33 lines
4.1 KiB
Markdown
33 lines
4.1 KiB
Markdown
|
# RFC：Doc-sync 强制
|
|||
|
|
|
|||
|
|
Status: implemented
|
|||
|
|
|
|||
|
|
[English](2026-06-11-doc-sync-enforcement.md) | 中文
|
|||
|
|
|
|||
|
|
## 问题
|
|||
|
|
|
|||
|
|
AGENTS.md 承诺文档与代码严格同步，但这一承诺此前只靠肉眼验证。评审曾两次发现漂移：一次是实操手册（cookbook）示例与类型策略矛盾，一次是 README 引用了错误的 `registerAdapter` 调用。失去同步的文档比没有文档更糟；而本代码库主要由 agent 构建，agent 对门禁的遵从远比对行文的遵从可靠（机械质量门禁）。有两类文档漂移可以被机械检查：不再能编译的代码块，以及重复了 `interface Events` 声明的事件分类体系表。
|
|||
|
|
|
|||
|
|
## 决策
|
|||
|
|
|
|||
|
|
两道门禁，沿用既有的 `scripts/` 风格（tsx ESM，每个脚本一项职责）：
|
|||
|
|
|
|||
|
|
1. **`doc-typecheck`** 从 `README.md`、`docs/**` 和 `packages/*/README.md` 中提取所有 ` ```ts ` 围栏代码块，写入一个继承根 `tsconfig.json` 的临时项目，然后用 `tsc -b` 编译。临时项目复用源码的 `paths` 映射和根 project references，因此文档示例能看到源码，而 vendor 代码仍在其自身的 tsconfig 设置下被检查。刻意作为草图的代码块可以用显式的 ` ```ts ignore-check ` 信息字符串退出检查；脚本会报告退出比例，超过一半则失败，防止逃生口悄悄变成常态。
|
|||
|
|
2. **`verify-event-taxonomy`** 从 `packages/*/src` 的 `interface Events` 块中提取事件名，再从 `docs/architecture.md` 的分类体系表中提取事件名，断言两个集合完全一致。只校验、不生成：表格保留手写的 Mode/Purpose 列，只检查名称集合。（落地此门禁时发现了表格缺失的三个事件：`tools/change`、`llm/adapter-change`、`system-prompt/change`。）**已被取代**：[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)取代了此门禁及其 `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 都调用它（[机械质量门禁](2026-06-11-quality-gates.md)：钩子和 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 黄金报告**（[已推迟的提案](../../proposed/process/2026-06-11-api-extractor-reports.md)）：有意推迟。对于评审者已经能看到源码 diff 的内部 monorepo 而言价值不高，且依赖笨重、配置繁琐。
|
|||
|
|
- **从源码生成分类体系表**而非校验名称：否决，机制比问题本身更重；表格保留手写的 Mode/Purpose 列，直到[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)完全取代了这项检查。
|
|||
|
|
|
|||
|
|
## 后果
|
|||
|
|
|
|||
|
|
- 可机械检查的文档漂移现在会让 pre-push 钩子和 CI 失败，而非等待评审者发现。这是「机械门禁优于行文约定」原则的一个实例。
|
|||
|
|
- 让文档代码片段可编译需要少量 stub import 或 `declare`；`ignore-check` 比例必须保持低位，否则门禁形同虚设（比例守卫强制执行这一点）。
|
|||
|
|
- 分类体系检查仅限名称：Mode 或 Purpose 列的错误仍需人工评审。
|
|||
|
|
- 如果这些包（package）将来对外发布，API 报告仍可重新考虑。
|