把 token 当公开契约

这是全站最没法从别处学到的一节。

大多数 agent 项目把「模型看见了什么」当成实现细节：它散落在几十个拼 prompt 的地方，谁改了谁知道，review 时靠人肉记忆。dsh 把它提升成了每个包的公开契约，并且用 CI 卡住——一个包的 README 如果不交代它对模型上下文的影响，门禁就红。

这一节讲三件事：这份契约要求写什么、CI 怎么卡、以及为什么「模型读的」和「文档渲染的」在这个仓库里不可能分叉。

4.1　Model Experience 契约

先看它想解决什么问题。决策记录里的原话（.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md）：

三个字段，各自回答什么

零影响的包怎么写：审计过的短式

如果一个包对模型上下文没有影响，或者某条路径完全由别的包渲染，它用被验证器审计过的短式：一句以 None, as 或 Indirectly, through 开头的话，后面跟一个 KV Cache effect 小节和一段散文。

为什么不允许「零影响就直接省略」？决策记录给的理由很干净：「不受约束的缺席，在『审计过的零』和『忘了写文档』之间是有歧义的。」

只有模型无关的通用包才能整节省略，而且必须在验证器里登记理由。这份名单就写在门禁脚本源码里，是可 review 的审计证据：

/**
 * 公开契约与模型无关的通用包。它们的 README 完全省略 Model Experience；
 * 理由留在这里作为可 review 的审计证据，
 * 这样「缺一节」就不会被误当成「忘了写文档」。
 */
const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
  'packages/core/scope': '模型无关的注册与生命周期原语；上下文选择由面向模型的 consumer 拥有。',
  'packages/util/brand': '纯类型原语，编译后被擦除。',
  'packages/util/home-paths': '只解析 harness 自己的宿主路径。',
  'packages/util/launch-environment': '只解析宿主环境变量。',
}

代码 4.1　全仓 227 个包，能整节省略的只有四个。名单是硬编码的白名单，加一个包进去要过 review。（散文为便于阅读作了翻译，结构与键名照原文。）

4.2　CI 到底卡什么

verify-package-readme-model-experience 会自己发现所有包的 manifest，然后校验：

1. 三种分类是否成立（完整结构式 / 审计过的短式 / 整节省略）
2. 末尾小节的顺序——Model Experience 必须紧挨在 ## Known Limitations and Deferred Work 之前
3. 字段标题的层级与顺序精确匹配（H4，且必须是那三个、按那个顺序）
4. 每个字段下有非空的散文段落
5. 逐字文本块归属正确（H5 拥有）
6. 具体的字面证据存在——不能只写抽象描述
7. 工具 catalog 链接带锚点

它跑在 doc-sync 聚合门禁里。这个门禁一共 28 个叶子检查，Model Experience 只是其中一个。

4.3　生成式文档链：模型读的和文档渲染的不可能分叉

光有「必须写」还不够——写下来的东西会过期。dsh 的第二招是：凡是能从代码推出来的，一律生成，并且给生成物配一个新鲜度门禁。

这条链最有意思的地方在 tool-cordis 这个包。它给模型的 cordis_inspect 报告，渲染的是 src/api-catalog.ts——workspace 里所有 Cordis 声明的生成式投影：方法签名、JSDoc、事件与分发模式、以及签名引用到的类型。而这份投影和 docs/subsystems 用的是同一次 AST 遍历。

README 里那句话是这一整节的最好总结：

一个现场发现：手写散文确实会过期，生成物不会

4.4　KV cache 前缀稳定性：哪些操作会打掉缓存

把 KV cache 单列成一个字段，是因为它的失效规则很反直觉：请求前缀从第一个变动的 token 开始，后面全部作废。所以「在 system prompt 开头加一行」和「在对话末尾追加一句」的代价差着一整个数量级。

照着契约里那四种分类，可以整理出一张实操表：