# 视觉诊断：从“有结构”到“有视觉热点”

## 结论

当前输出不是没有结构，而是**没有唯一焦点**：H1、表格、蓝色提示卡、文件 diff 卡在抢注意力，主结论却是普通正文；强调色被 H2 左边条、表头、链接分摊，视觉上等于没有强调。修法不是再加装饰，而是建立一条**热点预算**：每条回复最多 1 个主结论卡 + 1 个行动/风险卡；表格只做证据，表格前必须有一句“表格结论”。

## 对截图的具体诊断

| 现象 | 问题 | 理论 |
| --- | --- | --- |
| 主结论是普通正文，蓝色“它问的四件事”反而最抢眼 | 焦点错位：装饰块比结论更重 | 视觉层级 / 信号噪声比 |
| H1、H2、表头、链接都用同一强调蓝 | 强调色平摊，10% 强调变成 50% | 60-30-10 色彩法则 |
| 表格没有“表格结论”，读者要自己总结 | 证据与结论没有分组 | 格式塔「接近性 / 共同区域」 |
| 状态词 active / in-sync / gap 是普通文本 | 状态不可扫读，没有 chips/行底色 | 前注意加工 / F 型扫读 |
| 代码块语言 banner 像独立浮条 | banner 与代码体分离，形成两个对象 | 格式塔「接近性」 |
| H1 26px、H2 21px、正文 15px，但 H2 与 H1 差距小 | 层级靠字号不足，缺少 eyebrow/lead | 模数比例 / 字体层级 |
| 表格全边框、表头与正文对比弱 | 非数据墨水过多，表头不突出 | Tufte 数据墨水比 |
| 蓝色组件卡、文件 diff 卡与我们的 markdown 样式混在一起 | 来源不可辨，无法判断谁负责 | 可观测性 / 归属标记 |

## 设计理论映射

1. **视觉层级（Visual Hierarchy）**：每屏一个主焦点，2 个次级焦点，其余三级。主焦点用「结论卡」；次级用「风险/下一步」；表格、正文退到三级。
2. **格式塔（Gestalt）**：结论与证据用接近性/共同区域分组；代码 banner 与代码体必须贴合成一个对象；同一主题的内容间距小于不同主题。
3. **F 型扫读（Nielsen）**：左上先落结论卡；表格第一列做标签，关键行加底色；每段首句承载信息。
4. **数据墨水比（Tufte）**：表格去竖线、减边框、表头轻底色、斑马纹极淡；让数字和文字成为墨水主体。
5. **60-30-10 色彩**：60% 中性底、30% 次级灰、10% 强调色。强调色只给结论卡、关键数字、风险/成功状态，不给每个 H2。
6. **信号噪声比**：每条回复最多 2 个强调块、每段最多 1 个加粗重点；图标只给语义标题，不做装饰。
7. **字体模数**：15 → 18.5 → 23 → 28（约 1.25 比例）；正文 1.6–1.75 行高，表格 13.5px，代码 13px；中文字距 0.01em。
8. **无障碍（WCAG AA）**：状态不能只靠颜色，必须同时有 ✅/⚠️/❌ 或文字标签；对比度 ≥4.5:1；`prefers-reduced-motion` 关闭动效。

## 热点预算（v0.3.1 的规则）

| 层级 | 元素 | 规则 |
| --- | --- | --- |
| 主焦点 | `> **结论：** ...` | 每条回复 1 个，放第一段；客户端渲染成强调卡；不得再用普通段落重复 |
| 证据 | 表格 | 表格前一行 `**表格结论：** ...`；表头轻底色；状态行按 ✅/⚠️/❌ 着色；最多 5–7 行 |
| 行动 | `> **风险：**` / `> **下一步：**` / `> **验收：**` | 每条回复最多 1 个，颜色区分 warn/success/info |
| 状态 | 行首 ✅/⚠️/❌ | 行级浅底色；状态表整行着色；不单靠颜色，保留符号 |
| 其余 | 正文 / 列表 / 链接 | 中性色，不加第二个强调色 |

## 归属：哪些是插件，哪些是 GenUI

- **本插件**：只给原生 markdown 节点加 CSS/属性。可验证标记：`<html data-dsh-structured="active">`，节点上的 `data-dsh-structured-card/icon/tone/status/row/lang`；浏览器控制台 `[dsh-structured] visual layer active`。
- **GenUI**：只渲染 ` ```dsh-ui ` fence 成 React 组件；它有自己的 root/类名，不带 `data-dsh-structured-*`。
- 截图里的蓝色「它问的四件事」标题卡、底部「已编辑 2 个文件」diff 卡，形态上不是我们的 CSS（我们不创建标题卡/文件卡），更可能是 GenUI 或宿主工具呈现。要确认，复制该回复原文看是否含 ` ```dsh-ui ` fence，或看 DevTools 里是否有 `data-dsh-structured-*` 属性。

## 本次落地（0.3.1）

- host 规则：首段强制 `> **结论：**`；表格前 `**表格结论：**`；状态行 ✅/⚠️/❌；全文最多两个强调块。
- client：结论卡加强（4px 强调边 + 渐变 + 标签图标）、callout 标签图标、状态行/表格行着色、代码 banner 贴合、表格去竖线/表头轻底色、根标记 + console 日志。
- 验收：desktop 应用内下一条回复应看到 1 个结论卡 + 1 个表格结论 + 0–1 个行动卡；DevTools 里 `document.documentElement.dataset.dshStructured === 'active'`。

## 下一步

- P1：单一「工程蓝图」视觉定稿、关键数字高亮、明暗/密度回归；0.9.x 提供 theme 三选一（deepseek/codex/anthropic）。
- P2：代码块复制/行号、表格横向滚动与复制、标题锚点。
- P3：GenUI 软联动（检测到才加 `dsh-ui` 路由规则），不硬依赖。