# 路线图：结构化 → 视觉热点

> Boss 2026-10-20 定调：**卡片样式是方向**；第一阶段先实现结构化，第二阶段在结构化基础上实现视觉热点的规范引导，用多样的呈现方式让输出美观的同时提升人类阅读效率。

## 阶段划分

| 阶段 | 目标 | 状态 |
| --- | --- | --- |
| Phase 1 | 结构化输出：首句结论 + 表格/清单/步骤 + 会话开关 + style.md + fail-open + desktop 实装 | ✅ 已完成（0.1–0.3.1 基线） |
| Phase 2 | 视觉热点规范引导：卡片系统、热点预算、多样呈现、GenUI 软联动、阅读效率验收 | 🚧 进行中（2.1–2.4 已落地，2.5–2.6 待做） |

## Phase 1（已完成，作为底座）

- host 每请求注入结构契约；`/structured on|off|status`；`style.md` 覆盖。
- desktop 实装，client 视觉层是 Phase 2 的 P0 预览，不是终点。
- 指标：历史首屏散文率 38.7% → 改后 0/12；22/22 测试；desktop live 注入已验证。

## Phase 2（明天开工）

### 2.1 卡片系统与设计 token

定义固定卡片类型，不让模型自由发明样式：

| 卡片 | 使用时机 | 无 GenUI 时的 fallback |
| --- | --- | --- |
| 结论卡 | 每条实质回复 1 个，第一段 | `> **结论：**` + client 卡片 |
| 判断/决策卡 | 有取舍、需要拍板 | `> **判断：**` + 两列对比 |
| 指标卡 | 2–4 个关键数字 | 加粗数字 + 紧凑 stat 行 |
| 风险卡 | 风险/阻塞/未验证项 | `> **风险：**` warn 色 |
| 下一步卡 | 行动/待办 | `> **下一步：**` + 编号步骤 |
| 证据表 | 对比、清单、状态 | markdown 表格 + 表格结论 |
| 结果卡 | 工具输出、diff、文件变更 | 宿主工具卡 / GenUI diff 卡 |

规则：每条回复 **最多 1 个主卡 + 1 个行动/风险卡**；卡片必须有 eyebrow / 标题 / 正文 / 来源或下一步；颜色不超过 3 个语义色。

### 2.2 host 契约：卡片选择与热点预算

- 首段必须是结论卡；表格前一行 `**表格结论：**`；状态行用 ✅/⚠️/❌。
- 模型按内容类型选择卡片，不按“好看”选择；短答不套卡。
- 全文最多两个强调块；没有证据的数字不单独做指标卡。

### 2.3 client：fallback 渲染与热点样式

- 不依赖 GenUI：用 CSS + 轻量 DOM 属性渲染结论/风险/下一步卡、状态行/行底色、表格/代码块。
- 增加 `data-dsh-structured-card-type` 等归属标记，便于和 GenUI 区分。
- 流式安全：只加属性/class，不搬 React 节点；MutationObserver + rAF 合批。

### 2.4 GenUI 软联动（可选，不硬依赖）

- 检测到 `dsh-genui` 已安装时，host 规则追加一句：交互/图表/大表格用 ` ```dsh-ui `；普通说明用 markdown。
- 检测失败/未安装：不出现任何 `dsh-ui` 指令，走 2.3 fallback。
- 同一内容只渲染一次：有 `dsh-ui` fence 的区域不再套我们的卡片样式；我们的 CSS 只作用于原生 markdown。
- 不新增 `peerDependencies`，不自动安装 GenUI；需要一键装两个时用独立 meta-package。

### 2.5 多样呈现与阅读效率

- 呈现方式按内容选：表格、卡片、时间线、步骤、对比网格、callout、状态 badges、代码块、diff 结果卡。
- 验收代理指标：
  - 首屏命中率：12 条固定 prompt 中，首屏出现主卡/结论的比例 ≥80%。
  - 热点预算：每条回复强调块 ≤2；无“全是重点”。
  - 表格结论覆盖率：带表格的回复 100% 有表格结论。
  - 状态可扫读：状态行/状态表 100% 有 ✅/⚠️/❌ 或文字标签。
  - 散文率：沿用 `measure-prose`，目标 <10%。
  - 用户体感：desktop 截图对比，至少 3 组 before/after。

### 2.6 单一视觉方案定稿与回归

- 锁定一套「工程蓝图」视觉：token、字号、间距、卡片样式；0.9.0 增加 deepseek/codex/anthropic 三套 token，`theme` 由 profile Config 控制，不做主题市场。
- `/structured on|off` 只控制按会话的提示词开关；`theme`/`visual` 在设置页。
- 验收：三套主题在明/暗、不同桌面宽度下不溢出、不遮挡；设置页可切换。

## 非目标

- 不替换宿主 markdown 渲染器。
- 不接管 GenUI，不重复渲染 `dsh-ui` 内容。
- 不引入 pre-step 消息 append、不改 agent 循环、不改工具权限。
- 不硬依赖 GenUI，不把卡片样式写死在 host 规则里。

## 明天开工顺序

1. 2.1 卡片 token/类型定稿（`docs/CARD-SYSTEM.md`）。
2. 2.2 host 契约改为“按内容选卡 + 热点预算”。
3. 2.3 client fallback 卡片与归属标记。
4. 2.4 GenUI 软联动检测与 fallback 分流。
5. 2.5 12 条 prompt 的 before/after 与阅读效率验收。