Ziya
2565133af3
implemented（除 4 篇超长文档随后补）、proposed、rejected 全树配对； 同一流水线 + 二遍校验（paraphrase-back + 仓库上下文一致性）产出。 docs/rfc/implemented/AGENTS.md 与其 CLAUDE.md 符号链接列入排除 （agent 指令文件，与根 AGENTS.md 同策略）。
4.1 KiB
RFC：Doc-sync 强制
Status: implemented
English | 中文
问题
AGENTS.md 承诺文档与代码严格同步，但这一承诺此前只靠肉眼验证。评审曾两次发现漂移：一次是实操手册（cookbook）示例与类型策略矛盾，一次是 README 引用了错误的 registerAdapter 调用。失去同步的文档比没有文档更糟；而本代码库主要由 agent 构建，agent 对门禁的遵从远比对行文的遵从可靠（机械质量门禁）。有两类文档漂移可以被机械检查：不再能编译的代码块，以及重复了 interface Events 声明的事件分类体系表。
决策
两道门禁，沿用既有的 scripts/ 风格（tsx ESM，每个脚本一项职责）：
doc-typecheck从README.md、docs/**和packages/*/README.md中提取所有```ts围栏代码块，写入一个继承根tsconfig.json的临时项目，然后用tsc -b编译。临时项目复用源码的paths映射和根 project references，因此文档示例能看到源码，而 vendor 代码仍在其自身的 tsconfig 设置下被检查。刻意作为草图的代码块可以用显式的```ts ignore-check信息字符串退出检查；脚本会报告退出比例，超过一半则失败，防止逃生口悄悄变成常态。verify-event-taxonomy从packages/*/src的interface Events块中提取事件名，再从docs/architecture.md的分类体系表中提取事件名，断言两个集合完全一致。只校验、不生成：表格保留手写的 Mode/Purpose 列，只检查名称集合。（落地此门禁时发现了表格缺失的三个事件：tools/change、llm/adapter-change、system-prompt/change。）已被取代：生成式 Cordis 目录取代了此门禁及其architecture.md表格，改为完全生成的docs/cordis-catalog/events.md+docs/cordis-catalog/services.md及其verify-cordis-catalog新鲜度门禁。本文的其他门禁（doc-typecheck以及下文修订的verify-md-wrap）不受影响。
两者通过一个共享的 doc-sync package.json 脚本运行，lefthook pre-push 钩子和 CI 都调用它（机械质量门禁：钩子和 CI 调用相同的脚本，因此门禁在推送前就在本地触发，而不仅仅在推送后）。它们在 pnpm run typecheck 之后运行，后者校验 doc-typecheck 所引用的 package/vendor 构建图。
修订（2026-06-17）： 第三道门禁 verify-md-wrap 后来也被纳入 doc-sync。它用 mdast-util-from-markdown + GFM 解析范围内的每个 Markdown 文件（README.md、docs/**、packages/*/README.md，加上 AGENTS.md / packages/AGENTS.md），对任何跨越多行的 paragraph 节点报错，强制执行 docs/AGENTS.md 中「一个段落一个物理行」的写作规则。同样遵循只校验不生成的原则：它报告硬换行，从不重写，因此不会引入格式化噪音。doc-sync 现在包含三道门禁。
曾考虑的替代方案
- API-extractor 黄金报告（已推迟的提案）：有意推迟。对于评审者已经能看到源码 diff 的内部 monorepo 而言价值不高，且依赖笨重、配置繁琐。
- 从源码生成分类体系表而非校验名称：否决，机制比问题本身更重；表格保留手写的 Mode/Purpose 列，直到生成式 Cordis 目录完全取代了这项检查。
后果
- 可机械检查的文档漂移现在会让 pre-push 钩子和 CI 失败，而非等待评审者发现。这是「机械门禁优于行文约定」原则的一个实例。
- 让文档代码片段可编译需要少量 stub import 或
declare；ignore-check比例必须保持低位，否则门禁形同虚设（比例守卫强制执行这一点）。 - 分类体系检查仅限名称：Mode 或 Purpose 列的错误仍需人工评审。
- 如果这些包（package）将来对外发布，API 报告仍可重新考虑。