代码改了文档没改？OpenAI 开源了这个文档同步 Skill

你有没有这种感觉——文档写着写着就跟代码脱节了？上线一个新参数，文档里没提；改了个默认值，README 还是老数字。这种”文档和代码不同步”的问题，几乎每个团队都有。

OpenAI 最近开源了一个叫 docs-sync 的 Skill，专门解决这个痛点。它的工作逻辑非常直接：先吃透代码里有哪些功能和配置项，再拿这些去对照现有文档，哪里对不上就标出来。

具体怎么跑？

第一步，确定分析范围。docs-sync 会先识别当前分支和主分支，然后决定是全量扫描还是只比对 diff。优先分析当前分支，保持工作和文档同步。

第二步，建立功能清单。它会扫描 src/agents/、examples/ 等目录，把所有用户可见的接口、配置项、环境变量、CLI 命令全部抓出来。每一个功能点都会标注文件路径和具体符号，方便后续定位。

第三步，文档优先审查。docs-sync 会逐页走 docs/ 目录下的英文文档，找出页面上遗漏的重要功能点或新加的配置项。

第四步，代码优先映射。这一步反过来——以代码为基准，查找哪些功能根本没有文档页面，或者有页面但内容是空的。

第五步，生成报告并请求确认。报告里会写清楚：哪一页缺了什么、哪个功能完全没有文档、哪段描述和代码实际行为不一致。全部列好后，它会问你”要不要动手改”。

确认后才会实际编辑，且只改英文文档，不碰 docs/ja、docs/ko、docs/zh 等翻译目录。改完后还支持用 make build-docs 验证文档站能否正常构建。

这个 Skill 特别适合两类人：一是维护开源项目的开发者，文档贡献者经常不知道代码里有哪些新东西；二是大型项目的维护者，功能多了以后文档覆盖面会自然退化。

GitHub 链接附上，感兴趣可以去研究一下源码和工作流设计：

https://github.com/openai/openai-agents-python/tree/main/.agents/skills/docs-sync

GitHub: https://github.com/openai/openai-agents-python/tree/main/.agents/skills/docs-sync