AI 文档审查：事实自动核验，承诺明确归属

AI 写文档，最麻烦的错误有两类：一类是参数、默认值写错，另一类是替团队许下了没人批准的承诺。作者的核心主张是，把前者交给程序校验，把后者交给明确的负责人，别让人工逐行审稿承担所有责任。

这套方案用代码生成「事实包」，限制模型能写的内容，再用检查器拦截错误。方向值得借鉴，但原文给出的实现比它宣称的保障范围窄。读懂这层差距，才能把示例改成真正有用的文档检查流程。

先确定谁能负责，再决定模型能写什么

不存在的参数，可以拿代码核对；「这个版本提供多久的安全修复」，却未必能从代码里找到答案。后者需要团队先作出决定，再由具体的人确认。

作者因此要求，生成文档之前先给内容块分类。模型只允许起草 reference 和 procedure，也就是参考资料和操作步骤。支持期限、设计理由、安全表述等内容则由人负责，不能混进模型生成的文件。

下面这段标记，用来让责任归属跟着文档一起进入版本管理：

<!-- owner: model | class: reference -->
| Flag | Default | Notes |
|---|---|---|
| `--timeout` | 10 | seconds |

<!-- owner: avery.lin | class: commitment -->
Version 2.x receives security fixes for 12 months from release.

要看的是第二个 owner：Version 2.x 发布后提供 12 months 安全修复，是需要负责人确认的承诺。这里的名字只是示例，并不代表这项承诺已经得到验证。

事实是否正确，与谁有权作出承诺，需要两套检查。

不过，原文提供的分类规则并不完整。作者说有两类可以起草、四类不能起草，却没有展示所指的完整分类表；后面的代码只列出 commitment、rationale、security 三类人工负责内容。团队采用时，需要先补齐规则。

事实包的作用，是缩小模型可以发挥的范围

作者把 docsgen/facts.json 设为起草阶段唯一允许使用的事实来源。它不是另一份手工维护的说明书，而是从代码提取出来的结构化数据。

示例脚本通过 Python argparse 的 parser._actions 读取参数，记录 dest、default、choices、required 和 takes_value。默认值除 None 外转成字符串，选项值排序；action.nargs != 0 用来判断参数是否接收值。

模块部分通过抽象语法树（AST）提取名称：用 ast.parse 解析 Python 文件，只收集顶层 ast.FunctionDef 和 ast.ClassDef，并排除下划线开头的名字。输出格式标为 docfacts/1。

运行时，先执行 mkdir -p docsgen，再执行 python tools/docsgen/fact_bundle.py > docsgen/facts.json。示例中的 mypkg.cli、build_parser 和 Path('mypkg') 都需要按项目入口替换。事实包提交到仓库，和代码一起评审，并在 CI 中重新生成。

模型的约束则直接写成一份起草契约：

You draft only blocks of class `reference` or `procedure`.
The only permitted facts are in docsgen/facts.json. Quote flags, defaults, choices,
and paths exactly as they appear there. If a needed fact is absent, emit TODO(fact)
and stop that block.
Never write: dates, support windows, benchmarks, cost, security posture,
comparisons with other tools, or the words fast, secure, scales, best.
One `<!-- owner: model | class: ... -->` header per block. No prose outside blocks.

这里最有用的是 TODO(fact)：缺少事实就停止当前块，把资料缺口显露出来。相比补出一段流畅但无依据的说明，这种失败方式更方便后续处理。

作者称，自己在 MonkeyCode 免费模型档位上，为一个小型 CLI 参考文档目录跑过起草流程。原文也披露，这是 MonkeyCode 产品推广合作内容。运营方声称免费额度包含 10M-token，作者要求使用前核对条款，并自行统计每次 token 消耗。它不能直接作为今天的容量承诺，更不是质量验证结果。

检查器能拦住什么，要看代码实际检查了什么

作者提供的检查器读取事实包，再遍历 docs 下的 Markdown。执行命令是 python tools/docsgen/check_docs.py docsgen/facts.json。

它输出格式为 doccheck/1 的 JSON 报告，发现问题退出码为 1，否则为 0。检查规则包括：

• 文档出现事实包之外的长参数，报告 unknown-flag。
• --flag=value 中的值与已记录默认值不同，报告 default-mismatch。
• owner: model 的块属于指定人工分类，报告 class-not-draftable。

这些规则能演示流程，但还不能兑现原文描述的全部保障。

最直接的问题是，前面的表格把 --timeout 和默认值 10 放在两个单元格里。检查器能找到参数，却不会读取默认值所在列。把表格里的 10 改错，它也未必报错。

反过来，示例命令中的 --timeout=30 可能只是用户主动设置超时，并没有声称默认值为 30。检查器却会把等号后的值当作默认值比较，产生误报。

它也没有强制每个块都带责任标记，没有全面拒绝未知分类，更没有校验 choices、路径和模块名称。提取器只保存 action.option_strings[0]，同一参数的其他别名可能被遗漏；异步函数和类方法也不在上述名称提取范围内。

作者要求先跑失败样例，确认检查器确实会拦截错误，但提供的原文没有附上这组样例。CI 重新生成事实包之后，如何比较仓库版本并使任务失败，也没有给出配置。

退出码为零，只能说明现有规则没有发现问题。

我的判断

我认同把人工审查集中到责任和语义上。参数是否存在，可以自动核对；支持期限是否合理、安全表述是否成立，需要负责人判断。让两类问题各有去处，比要求审稿人记住所有细节更容易执行。

但这是一套有价值的流程草案，还不是经过充分验证的方案。作者没有提供错误检出率、误报率、节省审稿时间，或与普通人工审稿的对照数据。「第一次参数改名就能回本」属于经验判断，原文没有证明。

对于 CLI 参考资料，确定性的模板生成也是一个直接替代方案。既然参数、默认值和选项已经结构化，表格可以直接渲染。模型更适合承担需要组织语言的部分；即便是操作步骤，也可能依赖事实包尚未覆盖的环境条件和执行顺序。

原文建议把检查部署到 MonkeyCode 免费服务器，通过定时任务或 pre-receive 检查运行。短 Python 脚本的资源要求确实不高，但「放在应用流水线之外才能长期启用」没有对照证据。独立任务若不能及时关联文档变更，反馈也可能滞后。

它适合受版本管理的技术参考资料。以叙事、营销为主的文档，无法在 CI 重建事实包的项目，以及缺少负责人制度的团队，都很难直接套用。作者也明确要求：草稿发布前，仍需具名负责人确认。

能拿来做什么

• 从仓库里一页 CLI 参数表开始，先提取参数和默认值，验证代码修改后事实包能否同步变化，并在 CI 中比较差异。
• 如果维护 Node CLI，先围绕项目实际使用的参数解析器编写提取器。原文只覆盖 Python argparse，不能原样迁移。
• 按文档结构校验默认值，区分「默认值表格」和「命令示例」，并加入未知参数、错误默认值、合法自定义值的正反样例。
• 在日常 AI 文档任务中采用 TODO(fact) 和责任标记，把缺少依据的内容留给补充资料，把支持期限、安全承诺交给具名负责人确认。