文档 Review 不该只靠人工:我把小模型和 Codex 接进了审校流程

💡 导读：当技术文档全面采用 Doc-as-Code（文档即代码）并托管在 GitHub 之后，Review 流程也开始越来越像代码协作，面临着极高的质量压力。

过去半年里，我围绕“文档审查”做了一次比较完整的演进：先用本地轻量模型处理错别字和基础文本问题，再引入 Codex 的本地与云端 Code Review，最后通过 AGENTS.md 把审查规则逐步沉淀下来，最终形成了一套轻量、本地、云端三层配合的内容审查流程。

这篇文章想和大家分享的，不只是工具体验，更是这套流程为什么值得做、怎么设计，以及它的边界在哪里。

为什么要引入 AI 内容审查？

我们的技术文档采用 Doc-as-Code 的方式，全部托管在 GitHub 代码仓库里，和产品代码一样通过版本控制来管理。

这种方式的好处很明显：文档有历史、有分支、有评审，也能自然接入现有的研发流程。

但当文档规模开始变大之后，我们发现人工 Review 最先失守的，并不是那些特别复杂的技术错误，而是那些会反复出现、又很难靠人眼稳定抓住的小问题：

• • 错别字和明显的病句
• • 内部链接、锚点、图片、导航栏引用失效
• • 同一个术语在不同页面写法不一致
• • 产品核心能力描述慢慢和真实情况脱节

这些问题单个看都不算事故，但一旦积累起来，文档的整体质量就会慢慢变得不可靠。更麻烦的是，它们往往不会在一篇文档里集中爆发，而是散落在整个仓库的不同页面、不同版本、不同 PR 里。

这也是我后来开始认真思考引入更强 AI Review 的原因：不是因为我觉得它能完全取代人，而是因为它正好填补了一个极其关键的空缺——它比纠错小模型和死板的规则更懂上下文，又比人工逐页检查更稳定、更高效。

第一阶段：本地 AI 纠错小模型轻量校验

在引入 Codex 之前，我其实已经跑通了一轮更轻量的本地校验方式：基于开源模型配合垂直领域语料，持续训练专用的小模型，对技术内容进行批量审校。

这套方案的思路简单直接：我们不需要试图理解所有深度内容，而是优先去抓那些最基础、最高频、最容易规模化的问题，例如错别字、术语误写、明显病句，以及部分格式和表达异常。

它的优势很鲜明，即跑得快、成本低、适合整库扫描，而且规则完全可控。

实测下来，完成单个产品约 38 万字的整库扫描，耗时仅 60 多分钟，折算下来大约是每秒校验 100 字左右。

对于多产品多版本的文档仓库来说，这种方案的性价比极高。

但它的边界也很明显：小模型和轻量规则更擅长的是表面质量，而不是内容正确性。它可以告诉您一句话里有错别字，却不一定能判断这句话会不会误导用户；它可以发现术语写法不统一，却不一定能意识到某个功能表述已经和真实的系统实现发生了偏离。

这也促使我开始寻找更强大的解决方案。

💬 小贴士：由于本次主题不是本地 AI 小模型校验平台，如果您对这块平台的构建感兴趣，欢迎在文末留言，后面单独开一篇一起聊聊。

第二阶段：Codex 内容审校流程实践

什么是 Codex？为什么把它接入文档 Review？

在前面的实践里，我们已经有了一层本地轻量校验。但如果想进一步解决上下文一致性、能力描述偏差、图片内容识别这类更复杂的问题，仅靠小模型往往还不够。也正是在这个阶段，我开始把 Codex 接入到文档 Review 流程中。

简单来说，Codex 是 OpenAI 提供的一套面向开发工作流的 AI Agent 能力，既支持本地使用，也支持在云端接入 GitHub Review 流程。从使用形态上看，主要分为两类：

1. 1. 💻 Codex Local：运行在本地，覆盖 CLI、IDE 插件和桌面端工作流。
2. 2. ☁️ Codex Cloud：运行在云端，支持 GitHub 上的 Code Review。

对文档审查来说，这两类能力刚好对应两个不同阶段：本地阶段更适合作者在编辑过程中做预检，尽早发现问题；PR 阶段则适合作为统一的保底检查。

这样一来，即使部分贡献者本地没有安装 Codex，或者提交前忘了手动跑 Review，到了 PR 环节，仍然会有一层自动审查兜底。

最终的内容审校流程如上图所示：

• • 第一层：本地轻量校验，低成本清理基础问题。
• • 第二层：Codex AI Review，检查链接、锚点、上下文冲突等复杂问题。

如何接入 Codex Cloud？

接入方式非常简单，首先，前往 Codex Connector 管理页面，连接 GitHub，并授权需要进行 Code Review 的仓库。

完成授权后，继续前往 Code review 设置页面，配置 Review 的触发方式（例如：是否自动对 PR 执行检查、是否对所有贡献者统一启用等）。到这里，Cloud 侧的接入就基本完成了！

灵魂核心：AGENTS.md 是什么？为什么要设计它？

如果仅仅把仓库接入 Codex，还不足以让它真正适合文档 Review。如果没有明确的规则，Codex 默认更像一个泛用的代码审查员。对文档仓库来说，这通常会带来两个头疼的问题：该报的问题没有被指出，不该报的问题却报了一大堆。

这时候，AGENTS.md 就该登场了。

您可以把 AGENTS.md 理解成一份提供给 Codex 的项目级说明文件（Review Contract）。它的作用不是写长篇大论的写作规范，而是明确告诉 Codex：在这个仓库里，什么问题值得重点关注？什么问题可以忽略？哪些目录需要更严格的检查？

在实际落地时，我通常会在 docs/AGENTS.md 中保留那些长期稳定、反复会遇到的规则。比如：

## Review 重点- 当前产品能力、默认值、限制条件、UI 名称以当前版本为准；不确定时应标明未验证，而不是猜测。- 操作步骤应写清前提、顺序和结果；涉及不可逆操作、权限、网络、费用或数据风险时，应有明确提示。- 站内链接、标题锚点、相对路径、图片引用、文档 `id`（默认为文件名）与 sidebar 引用关系应保持一致。- `docs/reuse-content/**` 中的内容可能被多页复用；review 这类改动时，要考虑下游页面是否也会受影响。- `docs/images/**` 中图片的路径、大小写、扩展名应与引用保持一致。

💡 进阶技巧：如果仓库中有历史版本目录（如 versioned_docs/），建议为它单独设计一份更保守的规则，防止 AI 把旧版本行为误改成当前版本行为。Codex 会按目录读取规则，优先使用离当前改动文件最近的那份说明文件。

当然，完整的 AGENTS.md 还包含更多内容，比如评审范围、仓库结构概览、Review 输出约定等，相关示例也可以点击文末的阅读全文，在对应博客文章的仓库根目录和 i18n/en/AGENTS.md 中找到。

落地实战：本地预检 + PR 保底

完成流程接入和规则设定后，这套流程就可以正式跑起来了。

1️⃣ 本地编辑阶段（预检）

我们可以通过 Codex 的桌面端或 CLI 先做一轮预检，对当前改动尽早发现问题。在桌面端可以通过 /code review 发起任务并选择检查范围。

评审效果示例：本地 review 的优势在于灵活，可以根据需求选择更快的模型做快速扫描，或者用更强的模型做深入审核。可以看到，评审非常深入，连中英文内容不一致，以及英文文章包含中文图片都能精准检查出来！

2️⃣ PR 提交阶段（保底）

当触发 PR 请求后，可以由 Codex Cloud 自动执行 Review；如果没有开启自动检查，也可以在 PR 评论区手动通过 @codex review 触发。

评审效果示例：

⚠️ 注意：Codex Cloud 当前使用 GPT-5.3-Codex，并且默认只标记 P0 和 P1 级别的问题。如果希望它连文档 Typo、术语漂移这类问题也认真报出来，必须提前在 AGENTS.md 中把这些检查定义清楚。

总结：让机器做机器擅长的事

回过头看，这套流程真正带来的变化，不只是多了一层 AI 工具，而是把文档审查这件事慢慢工程化了：

1. 1. 基础问题：先在本地低成本过滤。
2. 2. 复杂问题：交给更强的 Codex Review 能力。
3. 3. 经验沉淀：通过 AGENTS.md 固化成长期规则。

它当然还不完美，最终的业务判断依然离不开人。但也正因为这样，我越来越觉得：AI Review 最有价值的地方，从来不是替代人工，而是把人工从重复、琐碎的检查里解放出来，让我们的注意力回到真正值得判断、有创造性的内容上。

👇 互动时间

如果您也在探索 AI 增强的内容审核，欢迎在评论区交流您的做法！您更倾向于先用轻量规则做前置过滤，还是直接把更强的 AI Review 接进 PR 流程呢？ 期待您的分享！

阅读更多点击文末左下角的 “阅读全文”，即可前往我的个人博客，查看本文对应的完整配置示例，以及更多 AI 实践与 Doc-as-Code 的技术干货分享！