ZiyaZhang
8ea5cdd894
146 篇 RFC 译文按 v4 基线（#348）重出：v4 模板+术语表、金标 few-shot、三段协议、切换行后处理；全量机械核对零异常（一处 task id 术语违规已修）。三篇超长 RFC（code-mode 已入，web-seam/ agent-scope/sandbox/cds-core 仍在长文档通道产出）随后补。
4.1 KiB
RFC：Doc-sync 强制
English | 中文
Status: implemented
问题
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信息字符串来 opt-out；脚本会报告 opt-out 比例，超过一半即失败，防止该豁免机制悄然成为常态。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新鲜度门禁。本 RFC 中的其他门禁（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 报告方案仍可重新考虑。