mcpField
D
docs-sync

docs-sync

github.com/openai开发4.0k149 次安装今天更新
代码仓库

关于 docs-sync

docs-sync 是用于依据实现证据审查文档并执行授权修改的仓库 Skill，支持按主题或差异范围检查，并纳入发布时机与验证要求。

主要功能

  1. 01按主题或差异范围审查
  2. 02基于证据整理功能清单
  3. 03检查文档缺漏与准确性
  4. 04按授权修改英文文档
  5. 05划分验证等级

适用场景

  1. 01审查指定功能的文档
  2. 02查找与实现不符的文档
  3. 03执行已批准的文档更新

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/openai/openai-agents-js --skill docs-sync

安装后在 Claude Code 中输入/docs-sync确认已加载。

附带文件agents/openai.yamlreferences/doc-coverage-checklist.md

详细介绍

文档同步

概述

根据实现证据，找出指定主题或差异中的文档缺漏和不准确之处。

范围与授权

对于仅要求审查或提出建议的请求，报告发现的问题，不要编辑。用户要求更新或已批准计划时，完成指定范围内的编辑和验证，无需再次询问。仅针对尚未明确的行为、范围、发布时机或额外授权进行询问。将未发布行为加入 docs/ 前，遵循仓库的文档发布时机政策。

工作流程

  1. 确认范围和基础分支

    • 确认当前分支和默认分支（通常为 main）。
    • 优先分析当前分支，使工作与正在进行的更改保持一致。
    • 仅在请求针对分支时使用分支差异。指定主题或已发布文档的修正即使与当前分支差异无关，也仍在范围内。
    • 避免切换分支，以免影响本地更改。优先使用只读检查，例如 git show main:<path>。如果确实需要单独检出，则在创建或切换工作树前，先停止并取得 AGENTS.md 要求的明确批准。

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

    • 将清单限制在指定主题或差异范围内。只有明确要求全面审查时，才盘点完整功能面。
    • 对于针对分支的工作，检查相对于预期基础分支的新增、更改和删除内容。
    • 重点关注面向用户的行为：公共导出项、配置选项、环境变量、CLI 命令、默认值和文档中描述的运行时行为。
    • 为每项记录证据（文件路径 + 符号/设置）。
    • 使用定向搜索查找选项类型和功能标志（例如：rg "Options"、rg "process.env"、rg "export"）。
    • 当主题涉及 OpenAI 平台功能时，调用 $openai-knowledge，从 OpenAI Developer Docs MCP 服务获取最新信息，而不要凭猜测作答；若出现差异，则以 SDK 源代码为准。
    • 对于 MCP SDK（modelcontextprotocol/typescript-sdk）或 Vercel AI SDK（@ai-sdk/*）相关主题，可选用 Deepwiki MCP 快速查询，但仍以 SDK 源代码为准。

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

    • 遍历 docs/src/content/docs 下的每个相关页面（不包括 docs/src/content/docs/openai）。
    • 找出重要且受支持的选项（选择启用标志、环境变量）、自定义点或 packages/ 中新功能的遗漏说明。
    • 在用户通常会查找这些信息的页面中提出补充建议。

  4. 先审查代码：将功能对应到文档

    • 检查 docs/src/content/docs 下当前的文档信息架构。
    • 根据现有模式和包的边界，为每项功能确定最合适的页面/章节。
    • 找出完全没有文档页面的功能，或虽有页面但缺少对应内容的功能。
    • 指出有助于提升内容可发现性的结构调整。

  5. 检查缺漏和不准确之处

    • 缺失：main 中存在但文档未提及的功能/配置。
    • 错误/过时：名称、默认值或行为与 main 不一致。
    • 结构问题（可选）：页面内容过载、缺少概述或主题分组不当。

  6. 对拟议的完整差异进行分类

    • 将 AGENTS.md 中的文档更改验证层级作为唯一依据。
    • 编辑前，按适用的最高级别，将拟议的完整差异归为编辑、内容或结构层级。
    • 将该层级所需的验证与 $implementation-final-review、$code-change-verification、$changeset-validation 和 $pr-draft-summary 现有的适用性规则分开处理。

  7. 报告发现的问题或继续执行已授权的更新

    • 对于仅审计的工作，提供证据、建议位置、拟议修改和所需验证，然后停止。
    • 对于更新请求，根据发现的问题和选定的验证级别完成已授权的修改。

  8. 应用已授权的更改（仅限英文）

    • 仅编辑 docs/src/content/docs/** 中的英文文档。
    • 审查和更新时排除 docs/src/content/docs/openai。
    • 不要编辑 docs/src/content/docs/ja、docs/src/content/docs/ko 或 docs/src/content/docs/zh。
    • 确保更改符合现有文档风格和导航结构。
    • 不要直接在 MDX 中添加 TypeScript 或 TSX 围栏代码块。将每个 TypeScript 或 TSX 代码片段放入 examples/docs/<doc-area>/ 下可编译的源文件中，在 MDX 中使用 ?raw 导入，并按照现有文档模式渲染导入的源代码。
    • 如果代码不够实用，不值得作为完整示例维护，请用文字说明其行为，而不要添加未经验证的代码片段。
    • 按照 AGENTS.md 中最高适用的「文档更改验证级别」运行所需的定向验证。如果完整差异修改了渲染的 TypeScript 或 TSX 代码片段源文件，或其 MDX 导入／渲染方式，请运行 pnpm -F docs-code build-check，并在交付前修复问题。

输出格式

报告发现的问题时使用此模板：

文档同步报告

  • 先看文档的发现
    • 页面 + 缺失内容 → 证据 + 建议插入位置
  • 先看代码的差距
    • 功能 + 证据 → 建议的文档页面／章节（或缺失页面）
  • 不正确或过时的文档
    • 文档文件 + 问题 + 正确信息 + 证据
  • 结构建议（可选）
    • 拟议更改 + 理由
  • 拟议修改
    • 文档文件 → 简要的更改摘要
  • 未解决的决策（仅在需要时列出）

参考资料

  • references/doc-coverage-checklist.md

评论

支持 Markdown