docs-sync

文档同步

概述

通过将 main 分支的功能和配置选项与当前文档结构进行对比，找出文档覆盖缺口和不准确之处，然后提出有针对性的改进建议。

授权与范围

对于仅审计或仅提议的请求，只报告发现的问题，不进行编辑。当用户要求更新或已批准某个方案时，直接完成这些本地编辑和适用的检查，无需再次询问。仅就未决的范围、行为、发布时间或额外授权进行询问。保持生成的翻译内容不变。在将未发布的行为纳入 docs/ 之前，应遵循仓库的文档发布时间策略。

工作流程

1. 确认范围与基准分支

   • 确定当前分支和默认分支（通常为 main）。
   • 优先分析当前分支，以使工作与进行中的变更保持一致。
   • 仅在分支范围的请求中使用分支 diff。已请求的主题或已发布文档的更正即使与当前分支 diff 无关，仍属于范围之内。
   • 若切换分支会打断本地变更，则避免切换。优先进行只读检查，例如 git show main:<path>。如果确实需要单独的检出，请停止操作，并在创建或切换 worktree 之前，获取 AGENTS.md 所要求的明确批准。

2. 根据所选范围建立功能清单

   • 将清单限定在请求的主题或 diff 范围内。仅在明确要求全面审计时，才清点完整的功能表面。
   • 对于分支范围的工作，检查相对于预期基准的功能新增、变更和删除。
   • 关注面向用户的行为：公共导出、配置选项、环境变量、CLI 命令、默认值以及已文档化的运行时行为。
   • 为每一项记录证据（文件路径 + 符号/设置）。
   • 使用有针对性的搜索来查找选项类型和功能开关（例如：rg "Settings"、rg "Config"、rg "os.environ"、rg "OPENAI_"）。
   • 当主题涉及 OpenAI 平台功能时，调用 $openai-knowledge，从 OpenAI Developer Docs MCP 服务获取最新详情，而不是凭猜测；若出现不一致，以 SDK 源代码为准。

3. 文档优先检查：审阅现有页面

   • 遍历 docs/ 下每个相关页面（不包括 docs/ja、docs/ko 和 docs/zh）。
   • 找出缺失的重要且受支持的选项（可选启用的标志、环境变量）、自定义点，或来自 src/agents/ 和 examples/ 的新功能说明。
   • 对于用户合理预期能在该页面找到的内容，提出补充建议。

4. 代码优先检查：将功能映射到文档

   • 审阅 docs/ 和 mkdocs.yml 下当前的文档信息架构。
   • 基于现有模式以及 docs/ref 下的 API 参考结构，确定每项功能最合适的页面或章节。
   • 找出没有任何文档页面的功能，或有页面但缺少对应内容的功能。
   • 当结构调整能提升可发现性时予以说明。
   • 改进 docs/ref/* 页面时，以 src/ 中对应的文档字符串/注释为准。优先更新这些代码注释，以确保重新生成的参考文档保持正确，而不是手动编辑生成的页面。

5. 发现缺失与不准确之处

   • 缺失：main 中存在但文档中缺少的功能/配置。
   • 不正确/过时：名称、默认值或行为与 main 不一致之处。
   • 结构问题（可选）：页面过载、缺少概览，或主题分组不当。

6. 报告发现或继续已授权的更新

   • 对于仅审计的工作，提供证据、建议位置和拟议修改，然后停止。
   • 对于更新请求，依据发现的问题完成已授权的编辑。

7. 应用已授权的变更（仅限英文）

   • 仅编辑 docs/** 中的英文文档。
   • 不要编辑 docs/ja、docs/ko 或 docs/zh。
   • 保持变更与现有文档风格和导航一致。
   • 新增或重命名页面时，更新 mkdocs.yml。
   • 依据 AGENTS.md 中的文档验证等级对完整 diff 进行分类，并仅运行该等级所要求的检查。
   • 对于内容或结构变更，待编辑和必要审阅稳定后，运行一次 make build-docs。仅为编辑性质的变更则不运行。

输出格式

报告检查结果时使用以下模板:

Docs Sync Report

• 文档优先发现的问题
  • 页面 + 缺失内容 -> 证据 + 建议插入位置
• 代码优先发现的缺口
  • 功能 + 证据 -> 建议的文档页面/章节(或缺失的页面)
• 错误或过时的文档
  • 文档文件 + 问题 + 正确信息 + 证据
• 结构性建议(可选)
  • 建议的变更 + 理由
• 建议的编辑
  • 文档文件 -> 简要变更摘要
• 未解决的决定(仅在需要时)

参考资料

• references/doc-coverage-checklist.md