Appearance
4.5 不变式、测试与文档规范
本章概览：DSH 如何用"运行时不变量 + 测试梯队 + 文档分层"三套纪律保证 200+ 包的正确性。理解它们，才能理解 DSH 的代码为什么长这样，以及贡献时被要求做什么。
运行时不变量：ctx.invariants
ctx.invariants（runtime-diagnostics/invariants）是包拥有的不变量注册表。各包的 ./invariant 伴生子路径注册归属自己的检查：
| 伴生 | 检查什么 |
|---|---|
dsh-session/invariant | 单调序列号、轮次/步骤包裹、同步骤工具调用/结果配对 |
dsh-agent/invariant | agent 状态转换关系 |
dsh-agent-loop/invariant | 请求重建：要求活会话并独立重建消息边界与折叠请求头 |
dsh-goal/invariant | goal 变更 revision 连续、生命周期合法迁移、时间戳不倒退、轮次非降 |
关键纪律（AGENTS.md）："运行时不变式断言拥有的关系——检查权威事件流或可变数据，而非服务/方法存在、插件元数据或固定纯示例。没有合理关系时，给出解释的空伴生是正确的。"
出处：
packages/runtime-diagnostics/invariants/README.md与docs/subsystems/invariants.md
测试梯队（testing tiers）
仓库测试策略把测试按表面（surface）分层（docs/testing.md）：
| 层级 | 命令 | 要点 |
|---|---|---|
| 单元测试 | pnpm run test | vitest 单元测试；CI 覆盖率门是 test:coverage（每个源文件 100% 覆盖） |
| 真实 API e2e | pnpm run test:e2e | 无 DEEPSEEK_API_KEY 时自行跳过 |
| 快照测试 | pnpm run test:snapshot | 免 key 的 ACP/headless 回放对比预期输出；test:snapshot:record 重录 |
| 组合 e2e/快照 | 计划单元、e2e、快照覆盖 | 能力缝、生命周期路径与 transcript 输出 |
纪律要点：
- 偏好真实实现而非 mock（Prefer the real implementation over a mock）；
- 验证世界而非自述（Verify the world, not the self-report）；
- 测试真实入口路径（Test the real entry path）；
- fixtures 必须在 macOS/Linux 上可回放：修 fixtures，不修 normalizer；
- 行为测试描述行为而非正确性：行为变化要改测试，并在 PR 里解释原因。
文档分层：一个事实一个家
docs/AGENTS.md 定义了文档分级（tier taxonomy），每个事实只有一个家：
| 层级 | 职责 |
|---|---|
| 根 AGENTS.md | 常驻命令：每条 1~3 行、链接其家 |
| architecture.md | 有序地图：组合、核心包、loop、seam、扩展点 |
| subsystems/ | 每子系统一页参考：类型定义、语义、生成的 Cordis API |
| Agent Notes | 活跃决策记录：为什么、放弃了什么、需要什么验证 |
| cookbook/ | 带编号验证步骤的实操手册 |
| user/ | 产品向指南（发布到文档网站） |
| package README | 每包契约：配置、语义、限制、扩展点、Model Experience |
| 生成目录 | tool-catalog、config-catalog、persistence-catalog、module-graph |
"查找某事实"的规则：类型定义 → subsystems；决策理由 → Agent Notes；步骤 → cookbook；包契约 → README；常驻命令 → AGENTS.md。
生成目录：防漂移机制
DSH 大量文档是从源码生成的并带新鲜度门（doc-sync）：
docs/tool-catalog.md：启动每个工具插件、收割 schema 生成；docs/config-catalog.md：逐字粘贴 config 声明 + 校验 schemastery schema 与声明类型一一对应；docs/persistence-catalog.md：持久会话事件目录；docs/module-graph.md/docs/capability-seams.md：包依赖与能力图。
贡献时的强制项
- 非平凡改动必须在同一 PR 含至少一篇 Agent Note（.agents/notes/README.md）；
- 每个非平凡模型/产品用户可见行为变化，添加或更新免 key 快照（真实可运行示例）；
- 改文档化类型时同步更新所属 subsystems 页（
verify-type-equiv捕获粘贴漂移）。
小结
三套纪律互相咬合：不变式在运行时断言"日志是真相"，测试梯队验证行为与世界一致，文档分层让"每个事实只有一个家"并由生成器防漂移。这是 DSH 能支撑 200+ 包快速迭代的工程底座。
参考资料
- packages/runtime-diagnostics/invariants/README.md — 不变式注册表（
deepseek-harness-src/packages/runtime-diagnostics/invariants/README.md） - docs/testing.md — 测试策略（
deepseek-harness-src/docs/testing.md） - docs/AGENTS.md — 文档标准（
deepseek-harness-src/docs/AGENTS.md） - AGENTS.md — 仓库约定（
deepseek-harness-src/AGENTS.md）