dsh-structured 0.0.0-stage → 0.7.4

package/ACCEPTANCE.md

@@ -0,0 +1,3 @@
+[验收 1｜注入与开关] 开启：`session-206815c3-6b0d-442e-bd29-993d699c036e` 首轮 `system/message` 同时命中「结构化输出（本会话已启用」与「提醒：本轮最终回复第一句给结论」；`/structured off` 走插件真实 handler + 真实 `state.json`（headless 不派发 slash 命令，host invocation 由 `.tools/toggle.mjs` 模拟），同会话第 5 轮最新 `system/message` 命中 0 条（`node scripts/session-inspect.mjs --session ... --last-system --grep "结构化输出（本会话已启用"`）。
+[验收 2｜三轮稳定] 同会话连发第 2/3/4 轮均正常完成（`.tools/rounds.jsonl` 的 `turn_end` 为 completed、`.tools/rounds.err` 为空、`producer-owned` 命中 0）；边界单测 22/22 通过（`npm test`），覆盖无 `agent/pre-step`、无消息 append、无 `ctx.tools`、fail-open 与 lib/src 一致性。
+[验收 3｜卸载、desktop 兼容与指标] `node scripts/desktop-check.mjs` 全部 PASS（desktop bundle 栈含 dsh-base/dsh-web-app、files 含 cordis.patch.yml、main/exports 指向存在文件、运行时只 import `node:`、无 Electron 专有 API、无 profile 分支）；`dsh plugin --profile structured-test remove` + 手工删 bundle 行 + `node scripts/uninstall.mjs` 后，profile `node_modules`、`package.json`、`$DSH_HOME/dsh-structured` 均无残留，卸载后 headless 仍能正常回答（`.tools/post-uninstall-smoke.txt`）；散文率改前 38.7%（首屏口径，737 会话/5727 条）与 37.5%（人工 21/56），改后 12/12 会话注入、0/12 散文 = 0.0%（<10%，明细见 `docs/METRICS.md`）。

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.7.4 — 2026-10-21
+
+- 发布准备：加入 `assets/screenshots/`（4 张）、`screenshots.json`、README Screenshots 与 npm/市场/GitHub Release 安装说明。
+- `npm pack` 排除 `docs/RE-AUDIT-REPORT.md`、`docs/PUBLISH-READY.md` 与 `docs/RELEASE-NOTES-0.7.4.md`；打包内容 34 文件。
+- 不声明 `@deepseek-ai/*` peerDependencies：插件只使用 host service，不直接 import 官方包；README 明示 `engines.dsh`/`dsh.compatibility` 是 advisory，`evaluatePluginCompatibility` 的 peer 门禁不生效（P2 风险）。
+- 市场 YAML 与 fork/PR 命令放在 `marketplace/`，不提交。
+
+## 0.7.3 — 2026-10-21
+
+- 多段落首卡也识别为 statement：首段 `<strong>` 后带正文不再要求 `<strong>` 独占整段。
+- 文档数字对齐 0.7.x：标签 13px、标题 16px、状态列 68px；移除打包文档里对 `FULL-TEST-PROMPT.md` 的引用。
+
+## 0.7.2 — 2026-10-21
+
+- 一页段落（`<p><strong>title</strong><br>body</p>`）也能识别为 statement 卡，不再要求两个 `<p>`。
+- 删除 `blockquote[tone="info"]` 对主题 brand 的覆盖；卡片强调色固定为 `#2563eb`（暗色 `#60a5fa`）。
+- GenUI 只信 `clientModules` 实时图；不回退可能被继承污染的 profile env。
+- 打包文档清除本机绝对路径。
+
+## 0.7.1 — 2026-10-21
+
+- 首卡视觉：无标签标题卡标题 16px/700；模型只写普通 blockquote 时，client 把首段升级为 16.5px/600 的 lead 卡（图标 + 淡色表面 + 4px 强调边）。
+- 标题上限放宽到 ≤60 字，避免长结论被迫退化为普通引用；表格仍 ≤5 行，正文 ≤500 字。
+- 强调色固定为 `#2563eb`（暗色 `#60a5fa`），不再跟随主题的灰色 brand token。
+
+## 0.7.0 — 2026-10-21
+
+- P0: 首卡改为无标签标题卡（`> **一句标题**`），不再与 `~/.dsh/AGENTS.md` §7 的「No label」冲突；`statement` 卡片由 client 识别。
+- P1: `measure-prose` 首屏分类器计入卡片，修复 16.7% 假阴性。
+- P1: `state.json` 按 mtime 缓存热更新，外部编辑下一轮生效。
+- P1: `/structured` 明确只控制提示词注入；状态文本标注视觉层始终开启。
+- P1: 表格单元格 18px 留白、表头 11px/700、三列宽度 24/22/54、状态列 68px。
+- P1: GenUI 自动检测优先 `clientModules`，不再被继承的 `DSH_PROFILE_DIR` 污染。
+- P1: 标题 ≤24 字、表格 ≤5 行、正文 ≤500 字；可复制内容强制代码块。
+- P2: 增加 `.gitignore`、`repository` / `homepage` / `bugs` 元数据，准备 GitHub/npm 发布。
+
+## 0.6.3 — 2026-10-21
+
+- 表格单元格留白与表头字号修正。
+
+## 0.6.2 — 2026-10-21
+
+- 增加「可复制内容用代码块」规则；代码块右上角提供复制按钮。
+
+## 0.6.1 — 2026-10-21
+
+- 卡片标题 16px/700、标签 13px、正文 15.5px；修正表格留白。
+
+## 0.6.0 — 2026-10-21
+
+- 卡片 SVG 线图标、状态列软底、表格 lead、单列状态着色。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MYCAIGC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# dsh-structured
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 DSH 的每条实质回复默认结构化：**首句给结论，内容用表格 / 清单 / 步骤排出来**。按会话开关，默认开启；规则可用 `style.md` 整份覆盖。
+
+它解决的是一个实测问题：只靠 `~/.dsh/AGENTS.md` 第 7 节的提示词规则，56 条符合触发条件的回复里只有 21 条真的结构化（37.5%），长上下文下继续衰减。本插件把同一条规则放进**每次请求都会重新求值的 system prompt section**，并在末尾追加一句轻量提醒，不依赖模型记住历史。
+
+路线图：Phase 1 结构化已完成；Phase 2 做视觉热点规范引导与卡片系统，见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。
+
+## 判定优先级
+
+1. 老板读得快不快
+2. 会不会打断会话（稳定性）
+3. token 成本
+4. 实现优雅
+
+对应到实现：注入只有一条规则段（约 400 字）+ 一句尾部提醒（约 50 字）；任何异常都放行原请求；不接管 GenUI，不改 agent 循环。
+
+## 安装
+
+要求：DSH 0.2.x（`@deepseek-ai/cordis` 4.x），Node ≥ 22。
+
+**默认目标就是 desktop profile。** 插件只硬依赖 `systemPrompt`（desktop 由 `@deepseek-ai/dsh-base` 提供），`commands` 是可选服务；不依赖 Electron/headless 专有 API，也没有 profile 分支。安装前先跑一次预检：
+
+```powershell
+node scripts/desktop-check.mjs
+```
+
+`desktop` 由 Electron 独占只影响 **CLI 的 `--profile desktop` 子命令**，不影响插件本身；推荐走插件管理入口，或退出 Desktop 后手工 pnpm（方式二）。
+
+### 方式一：插件市场（发布后）
+
+在 DSH 插件管理里搜索 `dsh-structured` 安装；市场收录后可用。桌面端由应用侧加载 client，不需要浏览器刷新。
+
+### 方式二：npm（发布后）
+
+```powershell
+dsh plugin --profile <profile> add dsh-structured
+```
+
+desktop profile 由 Electron 独占，使用插件管理搜索/安装，不要跑 `--profile desktop`。
+
+### 方式三：GitHub Release（发布后）
+
+从 GitHub Releases 下载 `dsh-structured-0.7.4.tgz`，在插件管理里选择本地包；不使用 npm 时，市场 YAML 的 `tarball` 指向该 release。
+
+### 开发方式：本地 tgz / 手工 pnpm（desktop profile）
+
+本地包只用于开发验证：在 DSH 插件管理里选择 `dsh-structured-0.7.4.tgz`，或 `plugin_manager.install_bundle` 指向该文件。手工 pnpm 方式如下。
+
+`desktop` profile 由 Electron 独占：**全局 `dsh plugin --profile desktop ...` 会被 CLI 直接拒绝**（`profile "desktop" is managed exclusively by the Electron application`）。不要用那条命令。要先**完全退出 Desktop**，再在 profile 目录里手工 pnpm：
+
+```powershell
+$dir = Join-Path $env:DSH_HOME 'profiles\desktop'
+Copy-Item "$dir\package.json" "$dir\package.json.bak-before-dsh-structured"
+Copy-Item "$dir\pnpm-lock.yaml" "$dir\pnpm-lock.yaml.bak-before-dsh-structured"
+Copy-Item "$dir\cordis.patch.yml" "$dir\cordis.patch.yml.bak-before-dsh-structured"
+
+Set-Location $dir
+$tgz = "dsh-structured-0.7.4.tgz"   # 把 tgz 放到当前目录，或写成实际路径
+pnpm add $tgz
+```
+
+手工 pnpm **不会**自动改 bundle 列表，需要把 `dsh-structured` 加进 `$dir\package.json` 的 `dsh.profile.bundles`（只加一次，不要重复）：
+
+```json
+{
+  "dsh": { "profile": { "bundles": ["...", "dsh-structured"] } }
+}
+```
+
+启动 Desktop。
+
+开发期用独立测试 profile 时，`dsh plugin --profile <测试 profile> add <tgz>` 可以正常使用，并且会自动追加 bundle 行；新 profile 可用 `dsh <name> --from-default-profile headless "..."` 创建。
+
+### Desktop 兼容性依据
+
+- 预检：`node scripts/desktop-check.mjs` 全部 PASS —— desktop profile 已初始化、bundle 栈含 `dsh-base`/`dsh-web-app`、`files` 含 `cordis.patch.yml`、`main`/`exports` 指向存在文件、`dsh.client.platform: web` 与 `exports["./client"]` 就位、`engines.dsh`/`dsh.compatibility.dshReleases` 已声明、运行时只 import `node:`、无 Electron 专有 API、无 profile 分支、状态走 `DSH_HOME`。
+- **desktop 是主目标，Web 只做兼容。** 本会话本身运行在 desktop profile，`systemPrompt` 与 `commands` 由 live host 的 Service 查询确认；`dsh.client.platform: web` 是 DSH 客户端模块的格式（desktop 的 Web UI 也加载它），不代表 Web 优先。
+- desktop 实装实测：`plugin_manager install_bundle` 返回 `applied`（0.7.4），desktop `dependencies`/`bundles` 各一处；当前 desktop 会话最新 `system/message` 命中两段注入。
+- 视觉层由 desktop 应用侧加载，验收以应用内实际渲染为准；不要求用户手动刷新。
+
+### 兼容性门禁
+
+本包不声明 `@deepseek-ai/*` peerDependencies：插件只使用 host service，不直接 import 官方包。`engines.dsh` 与 `dsh.compatibility.dshReleases` 是 advisory；本机 `evaluatePluginCompatibility` 只读 peer，因此版本门禁不生效（P2 风险）。实测 DSH CLI `0.1.7-rc.2` 与 desktop `0.2.1-rc.2`。
+
+## 使用
+
+```text
+/structured            # 查看本会话状态
+/structured off        # 关闭本会话（下一轮生效）
+/structured on         # 重新开启
+/structured status     # 同 /structured
+```
+
+- 开关按会话独立，状态落在 `$DSH_HOME/dsh-structured/state.json`（tmp + rename 原子写）。
+- 新会话默认开启；`defaultEnabled: false` 可改默认值（见配置）。
+- 自定义规则：写 `$DSH_HOME/dsh-structured/style.md`，**非空即整份覆盖**内置文本，保存后下一轮生效；文件为空或删除时回落内置。
+- 内置文本与 `~/.dsh/AGENTS.md` 第 7 节同源：首句结论、组件化正文、禁过程叙事与复述、结构化不等于变长、500 字上限。
+
+### 视觉层（desktop 主目标；web 兼容）
+
+客户端半区会给对话 markdown 加一层排版：标题层级与图标方块、表头/细横线/状态列、代码块语言色与贴合 banner、风险/验收/结论三色卡片、结论/下一步卡、列表/链接/分隔线。强调色固定为 `#2563eb`（暗色 `#60a5fa`），其余 token 跟随明暗主题；只给宿主节点加 class/attribute，不改消息内容，headless / CLI 不加载 client 半区。
+
+视觉方向只做一套：**Linear 的秩序 + Notion 的卡片 + Stripe 的信息密度 + Vercel AI Elements 的回复结构**，见 [`docs/DESIGN-REFERENCES.md`](docs/DESIGN-REFERENCES.md)。卡片用图标方块 + 13px 标签 + 淡色表面；状态只在 68px 状态列着色，不再整行 pastel；表格结论用强调左规线。不做主题菜单。
+
+设计与分阶段计划见 [`docs/VISUAL-PLAN.md`](docs/VISUAL-PLAN.md)，视觉热点/层级诊断见 [`docs/VISUAL-CRITIQUE.md`](docs/VISUAL-CRITIQUE.md)，卡片类型与热点预算见 [`docs/CARD-SYSTEM.md`](docs/CARD-SYSTEM.md)。视觉层默认开启，**只提供一套「工程蓝图」方案，不做主题选择**；`/structured on|off` 是唯一开关。
+
+Phase 2 已落地 2.1–2.4：卡片类型（结论/判断/指标/风险/下一步/验收/重点）、`data-dsh-structured-card-type` 归属标记、GenUI 软联动（检测到才追加 `dsh-ui` 路由，未检测走纯 markdown fallback，不硬依赖）。
+
+## Screenshots
+
+![无标签标题卡](assets/screenshots/01-title-card.png)
+
+![状态表](assets/screenshots/06-status-table.png)
+
+![代码块](assets/screenshots/07-code-block.png)
+
+![窄窗](assets/screenshots/08-narrow.png)
+
+`screenshots.json` 列出全部 4 张，覆盖标题卡、表格 + 表格结论、状态列、代码块与 800px 窄窗；GenUI 截图因避免暴露工作区未收录。
+
+### 配置
+
+在 profile 的 `cordis.patch.yml` 里覆盖同一行（注意：config 是整份替换，不是深合并）：
+
+```yaml
+- id: dsh-structured
+  config:
+    defaultEnabled: true    # 新会话默认开启
+    tailReminder: true      # system prompt 末尾追加一句提醒
+    includeSubagents: false # 子代理会话不注入（它的产出不直接面向用户）
+    genui: auto             # auto | on | off；auto 检测到 GenUI 才追加 dsh-ui 路由
+```
+
+## 验证注入生效
+
+会话日志是 `$DSH_HOME/sessions/<cwd-group>/<session-id>/session.v4.jsonl.zstd`（独立 zstd 帧拼接，普通 grep 读不了）。仓库自带读取脚本：
+
+```powershell
+# 最近一个会话里搜注入文本（开启状态应命中 1 条）
+node scripts/session-inspect.mjs --grep "结构化输出（本会话已启用"
+
+# 指定会话
+node scripts/session-inspect.mjs --session session-xxxx --grep "结构化输出（本会话已启用"
+
+# 只看最新一条 system/message（验证「关掉后下一轮 0 命中」）
+node scripts/session-inspect.mjs --session session-xxxx --last-system --grep "结构化输出（本会话已启用"
+```
+
+开启时应看到：
+
+```text
+搜索："结构化输出（本会话已启用" → 命中 1 条 system/message
+```
+
+关闭后（`/structured off` 或把该会话在 `state.json` 里置为 `false`），同一个会话下一轮应看到 `命中 0 条`。视觉样式仍保留；`/structured` 只控制提示词注入，不关闭 client 视觉层。
+
+> 以上命令在仓库根执行。已装到 profile 时，脚本路径是 `<profile>\node_modules\dsh-structured\scripts\`；把命令里的 `scripts/` 换成 `node_modules/dsh-structured/scripts/` 即可。
+
+## 卸载 / 回滚
+
+一条命令（仓库根执行；已装到 profile 时用 `<profile>\\node_modules\\dsh-structured\\scripts\\uninstall.mjs`）：
+
+```powershell
+node scripts/uninstall.mjs --profile <profile> --dry-run
+node scripts/uninstall.mjs --profile <profile>
+```
+
+它会先执行 `dsh plugin --profile <profile> remove dsh-structured`（移除依赖、bundle 行和 `node_modules`），再删除 `$DSH_HOME/dsh-structured`（state.json / style.md）。只删这两个目标，不碰其他插件。
+
+手工 pnpm 回滚：退出 Desktop，按 `package.json` / `pnpm-lock.yaml` 备份恢复，或 `pnpm remove dsh-structured`；如果 `dsh.profile.bundles` 里还有这一行，手工删掉。重新打开 Desktop（应用重新加载，不是浏览器刷新）。
+
+卸载后检查：`node_modules` 下没有 `dsh-structured`，`package.json` 里没有依赖与 bundle 行，`$DSH_HOME/dsh-structured` 不存在。
+
+## 效果指标
+
+口径固定、可复跑：`scripts/measure-prose.mjs`。
+
+- **实质回复**：去掉代码块后可见字符 ≥ 120，且句子数 ≥ 2。
+- **结构化**：≥2 行表格 / ≥2 个清单项 / ≥2 个标题 / ≥1 个 `dsh-ui` 组件块。
+- **散文违规**：实质回复但没有结构化，且句子数 ≥ 3。
+- **散文率**：散文违规数 ÷ 实质回复数。
+
+```powershell
+# 最近 14 天的会话
+node scripts/measure-prose.mjs --since-days 14 --verbose
+
+# 指定会话（A/B 对照时最常用）
+node scripts/measure-prose.mjs --sessions session-a,session-b --json
+```
+
+同一测试 profile、同一模型、同一组 12 条 prompts 的配对采样结果见 [`docs/METRICS.md`](docs/METRICS.md)。核心数字：
+
+| 样本 | 口径 | 散文率 |
+| --- | --- | ---: |
+| 改前历史（737 会话 / 5727 条实质回复） | 首屏 300 字符 | **38.7%** |
+| 改前历史（同一批） | 整篇 | 16.8% |
+| 改后（12 个新会话） | 首屏 / 整篇 | **0.0%**（0/12） |
+
+任务书给定的人工基线是 37.5%（21/56），与首屏口径的 38.7% 基本一致。同 prompt 配对对照里 baseline 也是 0%，说明这批短问题本身就能被 AGENTS.md 覆盖；插件可证明的作用是 12/12 请求都带规则段与尾部提醒。完整的样本、命令、长上下文试点和局限都在 `docs/METRICS.md`。
+
+## 设计边界（这些是刻意不做）
+
+- **不用 `agent/pre-step` 往请求里 append 消息**。DSH v4 要求 `source.kind` 属于宿主注册的 producer，自造 kind 会让整回合失败：`format v4 message requires a producer-owned source kind`。
+- **不 append 消息、不改 agent 循环、不改工具权限、不接管 GenUI**。GenUI 负责组件渲染，本插件只负责「强制形状 + 注入规则」。
+- **fail-open 是红线**：section 求值、`style.md` 读取、状态读写、`/structured` 处理全程 try/catch；section 求值失败返回空串，本轮不结构化但请求照常放行。
+- `interpolate: false`：`style.md` 里出现 `{{...}}` 也不会触发严格变量插值而打断组装。
+- 子代理默认不注入：子代理产出由父代理消费，不是用户可见回复，注入只会浪费上下文。
+
+## 目录
+
+```text
+src/index.js                 host 入口（systemPrompt section + 会话开关 + 命令）
+src/client.js                client 模块（视觉层 + 结论卡 + 语义装饰）
+lib/index.js                 host 构建产物
+lib/client.js                client 构建产物
+cordis.patch.yml             bundle 装配清单
+scripts/build.mjs            构建
+scripts/uninstall.mjs        卸载后清理状态目录
+scripts/session-inspect.mjs  验证 system prompt 注入
+scripts/desktop-check.mjs    desktop 兼容性预检
+scripts/measure-prose.mjs    散文率统计（可复跑）
+scripts/lib/session-log.mjs  v4 会话日志 zstd 帧读取
+test/structured.test.mjs     单元测试 + 边界测试
+docs/METRICS.md              A/B 指标与原始明细
+docs/ROADMAP.md              Phase 1/2 路线图与 Phase 2 任务
+docs/CARD-SYSTEM.md          卡片类型、anatomy 与热点预算
+docs/DESIGN-REFERENCES.md    视觉引导参考与反例
+docs/VISUAL-PLAN.md          视觉排版方案与阶段计划
+docs/VISUAL-CRITIQUE.md      视觉诊断与热点预算
+ACCEPTANCE.md                3 行验收记录
+```
+
+## 已知限制
+
+- 注入是概率性约束，不是格式校验：模型仍可能忽略；指标文档记录了实测比例。
+- 状态目录按 `DSH_HOME` 共享，不区分 profile；测试 profile 的开关会落到同一个 `state.json`。
+- 视觉层是渐进增强，只在 desktop 客户端生效（Web 客户端作为同源兼容面，不单独验收）；headless / CLI 不加载 client 半区，host 注入不受影响。
+- 视觉层依赖宿主内部 class 名（`[class*="_markdown_"]`、`.md-code-block`）；宿主升级后若改名，会自动退化为原生 markdown，需要按 `docs/VISUAL-PLAN.md` 跑一次视觉回归。
+- `style.md` 是整份覆盖，不做片段合并。

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# dsh-structured bundle 装配清单。
+# 列入 profile 的 dsh.profile.bundles 后，官方 boot 层按此清单插入插件。
+#
+# config 全部可选：
+#   defaultEnabled   新会话默认是否开启结构化（默认 true）
+#   tailReminder     是否在 system prompt 末尾追加一句提醒（默认 true）
+#   includeSubagents 是否也给子代理会话注入（默认 false，子代理产出不直接面向用户）
+#   genui            auto | on | off；auto 检测到 dsh-genui 才追加 dsh-ui 路由（默认 auto）
+#
+# 需要改默认值时，在 profile 的 cordis.patch.yml 里覆盖同一行（整份 config 替换，不是深合并）：
+#   - id: dsh-structured
+#     config: { defaultEnabled: false, tailReminder: true }
+- insert:
+    - id: dsh-structured
+      name: 'dsh-structured'
+      config:
+        defaultEnabled: true
+        tailReminder: true
+        includeSubagents: false
+        genui: auto

package/docs/CARD-SYSTEM.md

@@ -0,0 +1,62 @@
+# 卡片系统（Phase 2.1）
+
+## 原则
+
+1. **按内容选卡，不按好看选卡**：短答不套卡；没有证据的数字不做指标卡。
+2. **热点预算**：每条实质回复最多 **1 个主卡 + 1 个行动/风险卡**；全文强调块 ≤2。
+3. **卡片必须可回退**：没有 GenUI 时用原生 markdown + 我们的 CSS；有 GenUI 时交互/图表卡片走 `dsh-ui`，普通卡片仍走 fallback。
+4. **颜色不超过 3 个语义色**：品牌色（结论/判断/指标/下一步）、warn（风险）、success（验收）。不用第四种装饰色。
+
+## 卡片类型
+
+| 类型 | 何时用 | host 语法 | 客户端标记 | 图标 |
+| --- | --- | --- | --- | --- |
+| 标题卡（首卡） | 每条实质回复 1 个，第一段 | `> **一句标题**` + 下一行正文 | `card-type=statement` | ◆ |
+| 判断/决策卡 | 有取舍、需要拍板 | `> **判断**` + 标题/正文 | `card-type=decision` | ⇄ |
+| 指标卡 | 2–4 个关键数字 | `> **指标**` + 数字 | `card-type=metric` | ▦ |
+| 风险卡 | 风险/阻塞/未验证项 | `> **风险**` + 标题/正文 | `card-type=risk` + tone=warn | ⚠ |
+| 下一步卡 | 行动/待办 | `> **下一步**` + 动作 | `card-type=next` | → |
+| 验收卡 | 验收/通过/完成 | `> **验收**` + 结果 | `card-type=accept` + tone=success | ✓ |
+| 重点卡 | 单条关键提醒 | `> **重点**` + 一句话 | `card-type=key` | ★ |
+| 证据表 | 对比/清单/状态 | `**表格结论：** ...` + 表格 | 表格行/状态着色 | — |
+| 结果卡 | 工具输出、diff、文件变更 | 宿主工具卡 / `dsh-ui` | GenUI/宿主 | 由宿主 |
+
+## 卡片 anatomy
+
+```text
+[title]    一句短标题（≤60 字）           ← 16px/700，无「结论」标签
+[body]     1–2 行证据/动作               ← 15.5px，正文
+[footer]   来源/下一步（可选）            ← 仅在需要时出现
+```
+
+- 首卡不写「结论：」标签：标题本身就是结论；这与 `AGENTS.md §7` 的 no-label 一致。
+- 行动卡用 `风险` / `下一步` / `验收` 作为组件标签，不当作正文前缀。
+- 卡片内最多 3 行；超过就拆成卡片 + 表格/清单。
+- 风险卡必须写“影响 + 触发条件”；下一步卡必须写“动作 + 验收信号”。
+
+## 热点预算
+
+| 回复类型 | 主卡 | 次卡 | 表格 | 状态 glyph |
+| --- | --- | --- | --- | --- |
+| 短答（1–2 句） | 不用卡 | 不用 | 不用 | 不用 |
+| 结论 + 证据 | 标题卡（无标签） | 0–1 个风险/下一步 | 有表格结论 | 有状态就加 |
+| 决策/方案 | 判断卡 | 1 个风险或下一步 | 对比表 | 有状态就加 |
+| 事故/复盘 | 标题卡 | 1 个风险卡 | 时间线/证据表 | 有状态就加 |
+| 工具结果 | 标题卡 | 0–1 个下一步 | 结果表 | 有状态就加 |
+
+## GenUI 映射
+
+| 内容 | 无 GenUI | 有 GenUI |
+| --- | --- | --- |
+| 结论/判断/风险/下一步 | markdown 卡片 + 我们的 CSS | 仍用 markdown 卡片（避免每条回复都生成 JSON） |
+| 图表/可排序表格/表单/大表格 | markdown 表格或文字 | ` ```dsh-ui ` 组件 |
+| 工具 diff/文件变更 | 宿主工具卡 | 宿主工具卡 / GenUI diff |
+
+同一内容只渲染一次：有 `dsh-ui` fence 的区域不再套我们的卡片样式。
+
+## 验收
+
+- 12 条固定 prompt：首屏出现主卡/结论 ≥80%。
+- 每条回复强调块 ≤2；带表格的回复 100% 有表格结论。
+- 状态行/状态表 100% 有 ✅/⚠️/❌ 或文字标签。
+- 无 GenUI / 有 GenUI 两种环境都不报错；同一内容不重复渲染。

package/docs/DESIGN-REFERENCES.md

@@ -0,0 +1,51 @@
+# 视觉引导参考（单一方向）
+
+## 方向
+
+不做主题菜单，只做一套：**Linear 的秩序 + Notion 的卡片 + Stripe 的信息密度 + Vercel AI Elements 的 AI 回复结构**。
+
+## 参考项目
+
+官方入口：[Linear](https://linear.app) · [Notion](https://www.notion.so) · [Stripe Docs](https://docs.stripe.com) · [Vercel AI Elements](https://ai-sdk.dev/elements) · [GitHub Primer](https://primer.style) · [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) · [Material 3](https://m3.material.io) · [IBM Carbon](https://carbondesignsystem.com) · [Attio](https://attio.com) · [Height](https://height.app) · [Raycast](https://raycast.com) · [assistant-ui](https://www.assistant-ui.com) · [prompt-kit](https://www.prompt-kit.com)。
+
+| 参考 | 借什么 | 不借什么 |
+| --- | --- | --- |
+| **Linear** | 8px 网格、1px 低对比边框、11px 大写字距标签、强调色只给主操作、克制的 hover | 深色单色调、键盘优先的交互密度 |
+| **Notion** | callout 结构：图标方块 + 淡色底 + 标题/正文；8–10px 圆角；页面留白 | emoji 当图标、过软的粉彩 |
+| **Stripe Docs** | 信息密度、等宽小标签、清晰的表头/正文层级、inline code chip | 营销页渐变、过多品牌色 |
+| **Vercel AI Elements** | AI 回复的 `Message / Response / CodeBlock / Tool / Sources / Actions` 组件划分；代码块 header；状态/来源 | 开发者暗色审美、全量组件库 |
+| **GitHub Primer** | design token、状态 label、AA 对比度、可访问的语义色 | 开发者工具的密集 chrome |
+| **Apple HIG** | Clarity / Deference / Depth：卡片轻 elevation、内容优先、克制装饰 | iOS 专用控件 |
+| **Material 3** | tonal surface + state layer：卡片用「表面色 + 强调色 5–10%」而不是重边框 | 重阴影、动态色大面积铺 |
+| **IBM Carbon** | 2x grid、数据表规格、行高/对齐 | 企业级高密度 |
+| **Attio / Height / Raycast** | 低对比边框 + 高对比文字 + 单一强调色；小圆角；细分隔线 | 复杂命令面板布局 |
+| **assistant-ui / prompt-kit** | AI 聊天气泡、Markdown、CodeBlock、Tool 卡片的组件边界 | 整套框架依赖 |
+
+## 从参考里抽出的 6 条规则
+
+1. **一个焦点**：每条回复只有 1 个结论卡 + 最多 1 个行动/风险卡；强调色只出现在这两个焦点和关键数字上。
+2. **卡片不是边框盒子**：图标方块（26px，强调色 12% 底）+ 13px 大写标签 + 12px 圆角 + 淡色表面 + 1px 低对比边；禁止灰底灰边的大方块。
+3. **状态用 badge，不用整行染色**：状态列 68px，emoji/符号居中；整行 pastel 底是 Excel 感的主要来源，改成只给状态单元格 10–12% 色底。
+4. **表格去竖线**：表头 11px 大写、44px 行高、1px 横线、无竖线；表格前一行 lead（表格结论）用 2px 强调左规线。
+5. **文字层级**：正文 15.5/1.7；标签 13/700 + letter-spacing；H2 21/700；数字用 tabular-nums；等宽只给标签/数字，不全文等宽。
+6. **动效克制**：150–200ms opacity/translate；`prefers-reduced-motion` 关闭；不用弹跳/发光/大面积渐变。
+
+## 反例（当前廉价感来源）
+
+- 结论卡是白底 + 1px 灰边 + 小蓝字，像普通 blockquote；
+- 表格整行 pastel 绿/黄，像 Excel 条件格式，且状态列占 30% 宽；
+- 表格无「表格结论」lead 样式，只是一行粗体；
+- 结论卡、下一步卡外观几乎一样，卡片类型没有视觉差异；
+- 强调蓝同时出现在标题条、表头、标签、链接，10% 强调被摊成 50%；
+- emoji 直接当状态图标，缺少 badge 容器和统一尺寸。
+
+## 落地映射
+
+| 规则 | CSS/DOM |
+| --- | --- |
+| 卡片图标方块 | `blockquote[data-card-type] > p:first-child > strong:first-child::before` 22px 方块 |
+| 卡片表面 | 1px 强调 16% 边 + 强调 6% 渐变底 + `0 8px 24px -16px` 阴影 + 12px 圆角 |
+| 状态 badge | `table[data-dsh-structured-status-table] td:first-child` 68px、居中、10% 语义色底；不再整行染色 |
+| 表格 lead | `p[data-dsh-structured-lead="table"]` 2px 强调左规线 + 14px |
+| 去竖线 | `border-collapse:separate` + 只有 `border-bottom` |
+| 单一强调 | H2 左条保留但变细；表头不用蓝底，用中性 surface |

package/docs/METRICS.md

@@ -0,0 +1,89 @@
+# 指标与实测记录
+
+统计口径、原始命令、样本量、结论和局限都在这里。所有数字都可以用仓库里的 `scripts/measure-prose.mjs` 复跑。
+
+## 口径
+
+- **实质回复**：去掉代码块后可见字符 ≥ 120，且句子数 ≥ 2。
+- **首屏结构化（主口径）**：回复前 300 个字符内出现 ≥2 行表格、≥2 个清单项、≥2 个标题，或 ≥1 个 `dsh-ui` 组件块。首屏在**原文**上截取；`dsh-ui` 计入结构，普通代码块内容不计（避免代码里的 `|` / `-` 误判）。
+- **散文违规**：实质回复、首屏不结构化、且句子数 ≥ 3。
+- **散文率**：散文违规数 ÷ 实质回复数。
+- **整篇口径（对照）**：只要回复任意位置出现上述结构就算结构化。两个口径同时输出，避免只挑好看的数。
+- **口径细节**：句子按 `。！？!?;；\n` 与 `. ` 切分后、长度 ≥6 字符的片段计数；表格按行计数（含表头与分隔行）；`--since-days` 是相对时间窗，`--before` 按会话文件 mtime 过滤，因此 737/6159/5727 这组数只在窗口不变时可复现。
+- **与人工基线的差异**：37.5% 是人工抽检 56 条的结果，38.7% 是全量脚本口径，相差 1.2 个百分点，视为同一量级。
+
+为什么用首屏：需求是「老板点开就能扫到结论和组件」。结构埋在 800 字之后，整篇口径会算它合规，但阅读体验没有改善。首屏口径在历史语料上复现出接近人工审计的基线（见下）。
+
+## 1. 改前基线（历史会话，插件未安装）
+
+- 时间窗：最近 30 天，写入时间早于 `2026-10-20T21:35:00+08:00`（插件首次安装时刻）。
+- 样本：737 个会话 / 6159 条最终回复 / 5727 条实质回复。
+- 命令：
+
+```powershell
+node scripts/measure-prose.mjs --since-days 30 --before "2026-10-20T21:35:00+08:00"
+node scripts/measure-prose.mjs --since-days 30 --before "2026-10-20T21:35:00+08:00" --whole
+```
+
+| 口径 | 结构化 | 散文 | 散文率 |
+| --- | ---: | ---: | ---: |
+| 首屏（主） | 3494 | 2216 | **38.7%** |
+| 整篇（对照） | 4746 | 964 | 16.8% |
+
+与任务书给定的人工审计基线 **37.5%（21/56）** 基本一致。差异来自样本不同（人工只挑「符合触发条件」的 56 条，脚本覆盖全部实质回复）。
+
+## 2. 改后样本（插件开启，测试 profile）
+
+- profile：`structured-test`（`dsh-base` + `dsh-headless` + `dsh-structured@0.1.2`）。测试构建是 0.1.2；交付的 0.7.4 为发布准备（截图/README/市场 YAML/npm 包），host 注入与统计口径未变。
+- 模型：headless 默认 `deepseek-flash`。
+- 样本：12 个新会话，同一组 12 条问题；**12/12 会话的 `system/message` 都同时命中主规则段与尾部提醒**。
+- 命令：
+
+```powershell
+node scripts/measure-prose.mjs --sessions "<12 个会话 id，逗号分隔>"
+node scripts/session-inspect.mjs --session <id> --grep "结构化输出（本会话已启用"
+```
+
+| 口径 | 结构化 | 散文 | 散文率 |
+| --- | ---: | ---: | ---: |
+| 首屏（主） | 12 | 0 | **0.0%** |
+| 整篇（对照） | 12 | 0 | 0.0% |
+
+**结论：改后 0/12，达到 <10% 的目标。**
+
+## 3. 同 prompt 配对对照（诚实披露）
+
+同一测试 profile、同一组 12 条问题：
+
+| 组 | 插件 | 实质回复 | 结构化 | 散文率 |
+| --- | --- | ---: | ---: | ---: |
+| baseline | 未安装 | 12 | 12 | 0.0% |
+| after | 0.1.2 开启 | 12 | 12 | 0.0% |
+
+这批问题是短问题（如「pnpm 和 npm 该怎么定」），`~/.dsh/AGENTS.md` 第 7 节本身已经足以让模型输出表格/清单，所以 **同 prompt 的增量为 0**。插件在这批样本上可证明的作用是「请求级保证」：12/12 请求的 system prompt 里都有规则段和尾部提醒，不依赖模型记得住 AGENTS.md。
+
+真正需要插件兜底的是长上下文/复杂会话——那正是 38.7% 历史基线的来源。单轮 headless 压测无法稳定复现这种衰减，因此不把配对增量当作主要证据。
+
+## 4. 长上下文试点（未复现衰减）
+
+- 构造约 9.9k 字符的周报记录，末尾问「现在什么情况？我该先处理哪一件？」。
+- 对照组：插件仍安装，但用 `--patch` 把 `defaultEnabled` 覆盖为 `false`。
+- 结果：两组都输出了首屏表格（control 664 字符，treatment 664 字符），按脚本口径都是 0% 违规。
+
+结论：在当前模型/单轮 harness 下，长上下文本身没有把「结构化」压成散文，因此没有可报告的配对增量；这一点如实记录，不用合成数据凑效果。
+
+## 5. 复跑
+
+```powershell
+# 全量历史（注意 --before 选插件安装前的时刻）
+node scripts/measure-prose.mjs --since-days 30 --before "2026-10-20T21:35:00+08:00" --verbose
+
+# 某个会话
+node scripts/measure-prose.mjs --sessions session-xxxx
+
+# 换首屏阈值 / 换整篇口径
+node scripts/measure-prose.mjs --first-screen 500
+node scripts/measure-prose.mjs --whole
+```
+
+脚本只读 `$DSH_HOME/sessions`，不写任何状态；没有第三方依赖，Node ≥ 22（用内置 zstd）。