OpenAI 把工程师的经验写进了仓库：docs-sync 是怎么让文档和代码不再脱节的

你有没有遇到过这种情况：翻遍官方文档，照着配置写好了代码，跑起来就是报错。排查了半小时才发现，文档里写的参数名早就不用了，代码里已经换成了新的。你气的不是代码写错了，是文档骗了你。

这件事不只你遇到过。OpenAI 的 Agents SDK 团队也在头疼。两个仓库、几千个 API 接口、每周几十个 PR，文档跟不上代码的节奏是常态。修 bug 时顺手改了个参数名，谁会记得去同步文档？这种“文档漂移”是每个开源项目迟早要面对的慢性病。

但他们没选择加人手。他们写了一个 Skill，让 AI 来做这件事。这个 Skill 叫 docs-sync，是 OpenAI 公开的 8 个工程 Skill 之一。已经在生产环境跑了三个月，撑住了 457 个 PR 的节奏，PR 吞吐量涨了 45%，文档质量却没滑坡，靠的就是这一个自动化检查。

说白了，这篇文章想跟你讲清楚一件事：docs-sync 不是又一个“自动写文档”的魔法工具。它是一个带着方法论的设计，用双向交叉验证的思路，把文档审计这件事从纯人力变成了半自动。更重要的是，它背后的设计哲学，比它本身的代码更有意思。

环境准备

docs-sync 不是一个需要独立安装的工具。它是 OpenAI Agents SDK 仓库内置的一个 Agent Skill，安静地放在 .agents/skills/docs-sync/ 目录下。

如果你用的 AI 编码工具支持 Agent Skills 规范，比如 OpenAI Codex、Claude Code 或 Cursor，只要克隆了 openai/openai-agents-python 仓库，这个 Skill 就已经在那里了。不需要额外装任何包或插件，它只是一个带 SKILL.md 说明文件、几个参考文档和配置的文件夹。

用之前有三件事需要确认。你的仓库根目录需要一个 AGENTS.md，里头定义了什么时候该触发哪个 Skill。docs-sync 依赖 openai-knowledge 这个配套 Skill，它通过 MCP 从 OpenAI 官方开发者文档拉取最新 API 信息做交叉验证。如果你只想分析当前分支而非 main 全量，确保本地没有未提交的改动，否则 git diff 会混入噪音。

验证环境是否就绪的方式很简单。在你的 AI 编码工具里说一句“check doc coverage”或“audit the docs”，如果它理解了并开始走 docs-sync 的流程，你就准备好了。

操作流程

docs-sync 的完整工作流是一套七步管线。每一步有明确的输入和输出，合在一起形成一个从代码到文档的完整交叉验证回路。

第一步，确认范围和基准分支。它先判断你当前在哪个分支。如果在 main 上，对整个仓库做全量文档审计。如果在功能分支上，只分析当前分支和 main 之间的 diff。这个设计的实际价值很高，没人想在修一个拼写错误的时候被拖进全仓库文档审计。

第二步，从代码中提取功能清单。这是整条流水线的数据来源。它用 ripgrep 在源码中搜索这些用户可见元素：

• 公开导出的类、函数和类型
• 配置对象
• 环境变量
• CLI 命令入口

每发现一项都记录下文件路径和符号名作为证据。涉及 OpenAI 平台的 API 时，还会调用 openai-knowledge Skill 拉取官方最新文档做交叉验证。

第三步和第四步是 docs-sync 最有意思的设计：双向交叉分析。

第三步叫“文档优先”。逐页检查 docs/ 下已有的英文文档，找出哪些页面漏掉了代码中已经支持的配置项、环境变量或功能开关。关注的点不是文档写得好不好，而是“用户读到这一页时，合理预期会看到什么，漏了什么”。

第四步叫“代码优先”，反过来检查代码中的每个功能模块在文档中是否有对应的页面或段落。它会读取 mkdocs.yml 的导航结构，理解文档的组织逻辑，然后把每个功能映射到最合适的页面。找不到合适位置的，就标注为覆盖缺口。

这两步合在一起，形成了一个完整的交叉验证矩阵。只看文档容易漏掉新功能，只看代码容易忽略已有文档的上下文偏差。双向交叉之后，缺口和偏差同时暴露。

第五步，分类标注发现的问题。分三类：缺失，代码里有但文档没提的功能或配置。错误或过时，文档的参数名、默认值或行为描述和代码不一致。结构性问题，文档页面组织不合理，比如新手引导和深度参考混在一起。

第六步，生成文档同步报告并请求批准。报告分五个板块：

• 文档优先发现的遗漏
• 代码优先发现的覆盖缺口
• 文档中已存在的错误
• 结构优化建议
• 具体的编辑方案

每一处都附上了代码证据，精确到文件路径和函数名。报告末尾有一个”Questions for the user”板块，留给你确认或追问。不批准就不改。

第七步是执行。人工批准后才动手编辑。有两条硬约束：只改英文文档，绝对不碰 docs/ja、docs/ko、docs/zh 等翻译版本。编辑完跑 make build-docs 验证文档站点能否正常构建。

关键设计

看完整条流水线之后，值得停下来想想里面的几个设计决策。不是它们有多复杂，而是这些选择的理由比选择本身更有价值。

第一个是“默认不改，先报告再请求批准”。很多自动化工具倾向于直接动手，但文档修改和代码修改的风险性质不一样。修错一个参数名是好事，但如果 AI 误解了配置项的语义、把正确的文档改错了，结果就是用户照着文档写出错的代码。docs-sync 把编辑权留给人，把审计权交给 AI，这个分工是经过考虑的。

第二个是双向交叉验证。单独做文档审查或代码审查都不难，但交叉之后，发现的问题质量明显更高。实际的情况往往是代码里有一个 retry_timeout 参数，文档里也提到了，看起来覆盖了。但文档写默认 30 秒，代码实际是 60 秒。单向审计很可能漏掉这个偏差，只有交叉才会暴露。

第三个是 diff 模式。全量审计一次可能跑很久，但日常开发中最需要的其实是“这轮改了三个文件，文档跟上了吗”。docs-sync 在非 main 分支上自动切到 diff 模式，把分析范围收敛到 git diff main...HEAD 的变化范围内。不是炫技，是真的用得上的务实设计。

第四个对 docs/ref/* 类页面的处理方式值得一提。这类页面通常是从代码注释自动生成的。如果发现 ref 页面的内容和代码不一致，docs-sync 不会直接编辑生成页面，而是回到源码的 docstring 中修正。下次重新生成时就不会再变回去。不是哪坏了修哪，是修源头。

还有一个隐含的设计是信任层级。涉及 API 规范时，它会优先拿 OpenAI 官方文档做交叉验证。但如果官方文档和代码有冲突，以代码为准。写这个 Skill 的人很清楚：文档平台更新有滞后，但代码不会撒谎。

使用场景

docs-sync 最直接的使用场景是开源项目的日常维护。

以 OpenAI Agents SDK 为例，每次有新功能合并到 main，对应的文档更新很容易遗漏。以前靠人检查，一次两次还行，PR 量上去之后就撑不住了。现在 AI 在改完代码后跑一次 docs-sync，几分钟出一份报告，该补的补、该改的改。效率提升不是靠 AI 写文档，而是靠 AI 把该做的审计做完了。

第二个场景是项目重构。重构通常会改大量 API，老的参数被重命名或移除，新的模块被引入。重构完之后跑一次 docs-sync，相当于一个自动化的“重构文档影响检查”。代码层面改了但文档没跟上的，一一标出来。比一份一份对 diff 靠谱得多。

第三个场景更隐蔽但也更常见：新人接手老项目。老项目最让人头疼的不是代码看不懂，是文档和代码对不上。新人按文档配置，跑不通，然后怀疑自己的环境有问题。docs-sync 可以作为 onboarding 的一个步骤，先跑一遍全量审计，把已知的文档偏差一次扫清。

适用边界也得说清楚。它目前主要面向 Python 项目，特征提取的模式针对 Python 代码结构设计。对 Type 或 Go 的项目也能用，但识别精度会打折扣。它依赖 MkDocs 的文档结构（mkdocs.yml 导航配置），如果你的项目用 Sphinx、Docusaurus 或其他工具，需要适配分析逻辑。另外，它只审计用户可见的 API、配置和命令行行为，不看内部实现细节。这是有意为之的设计约束，不是功能缺陷。

洞察与反思

看完整个 Skill 的设计之后，我最大的感受是：它在解决一个比“文档同步”更大的问题。

OpenAI 公开的这 8 个 Skill 合在一起，本质上是在把资深工程师的隐性知识编码化。这些判断标准以前只存在于在这类项目里泡了半年以上的老工程师脑子里：

• 什么时候该检查文档覆盖
• 怎么判断一个参数是”用户可见”的
• 文档审计应该先看文档还是先看代码
• 发现冲突时该信谁

现在被写进了 SKILL.md，AI 读完就能执行。

这跟丰田生产系统走的是同一条路。1950 年代，丰田的制造知识全在老工人脑子里，大野耐一花了十年把这些知识提炼成“标准作业”贴在工位上。再后来，标准作业被编码进了机器人的程序。OpenAI 在做一样的事：从工程师的脑子到 Wiki 文档，再到仓库里的 Skill 文件。区别在于，丰田的机器人只能执行固定动作，而 AI 在理解规则之后，能灵活判断。

我不是说它没有缺点。docs-sync 的报告格式虽然结构化，但对普通开发者来说阅读体验不够友好。输出的是接近 diff review 的风格，需要一定经验才能快速定位优先级。它高度依赖 MkDocs 生态和 Python 代码特征，适用范围不够通用，推广到多语言、多文档工具需要大量适配。

但这些局限不影响它在本职工作上的表现。三个月、457 个 PR、文档质量没有倒退。这就是最好的压力测试。开源项目维护者都知道，光靠人在 review 时顺带提醒“文档也改一下”，效果有多差。docs-sync 的价值不在它多智能，而在它把这件事变成了一个不可跳过的步骤。

把我打动的不只是这个 Skill 本身。是 OpenAI 把这个流程公开了，把 AGENTS.md 的标准开放了，把设计思路写进博客了。他们不是关起门来自己用，而是说“这是我们的做法，希望对你的项目也有帮助”。这种把工程经验变成可复用模块的思路，比任何一个单独的 Skill 都更有长期价值。

资源地址

总结

docs-sync 做的事情用一句话就能说清楚：把代码里实际存在的功能和文档里写的做一次交叉比对，找出缺口和偏差，生成报告，等人工确认后再改。但它背后的思路比这个描述深远得多。

它代表了一种新的工程管理方式。资深工程师花了半年才积累起来的判断力和经验直觉，现在被编码进了仓库里的 SKILL.md 文件。AI 读完就能按同一套标准执行。不管是 PR、重构还是发版，检查机制不再依赖人对人的提醒。

如果你正在维护一个文档滞后于代码的项目，从 docs-sync 开始试一下。不一定非要用它本身，至少可以参考它的设计思路：把检查流程自动化，把编辑权留给自己，让 AI 做它最擅长的事情。