docs-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs Sync

文档同步

Overview

概述

Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements.

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

Workflow

工作流程

Confirm scope and base branch
- Identify the current branch and default branch (usually
```
main
```
  ).
- Prefer analyzing the current branch to keep work aligned with in-flight changes.
- If the current branch is not
```
main
```
  , analyze only the diff vs
```
main
```
  to scope doc updates.
- Avoid switching branches if it would disrupt local changes; use
```
git show main:<path>
```
  or
```
git worktree add
```
  when needed.
Build a feature inventory from the selected scope
- If on
```
main
```
  : inventory the full surface area and review docs comprehensively.
- If not on
```
main
```
  : inventory only changes vs
```
main
```
  (feature additions/changes/removals).
- Focus on user-facing behavior: public exports, configuration options, environment variables, CLI commands, default values, and documented runtime behaviors.
- Capture evidence for each item (file path + symbol/setting).
- Use targeted search to find option types and feature flags (for example:
```
rg "Options"
```
  ,
```
rg "process.env"
```
  ,
```
rg "export"
```
  ).
- When the topic involves OpenAI platform features, invoke
```
$openai-knowledge
```
  to pull current details from the OpenAI Developer Docs MCP server instead of guessing, while treating the SDK source code as the source of truth when discrepancies appear.
- For MCP SDK (
```
modelcontextprotocol/typescript-sdk
```
  ) or Vercel AI SDK (
```
@ai-sdk/*
```
  ) topics, optionally use Deepwiki MCP for quick lookups, and still treat the SDK source code as the source of truth.
Doc-first pass: review existing pages
- Walk each relevant page under
```
docs/src/content/docs
```
  (excluding
```
docs/src/content/docs/openai
```
  ).
- Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from
```
packages/
```
  .
- Propose additions where users would reasonably expect to find them on that page.
Code-first pass: map features to docs
- Review the current docs information architecture under
```
docs/src/content/docs
```
  .
- Determine the best page/section for each feature based on existing patterns and package boundaries.
- Identify features that lack any doc page or have a page but no corresponding content.
- Note when a structural adjustment would improve discoverability.
Detect gaps and inaccuracies
- Missing: features/configs present in main but absent in docs.
- Incorrect/outdated: names, defaults, or behaviors that diverge from main.
- Structural issues (optional): pages overloaded, missing overviews, or mis-grouped topics.
Produce a Docs Sync Report and ask for approval
- Provide a clear report with evidence, suggested doc locations, and proposed edits.
- Ask the user whether to proceed with doc updates.
If approved, apply changes (English only)
- Edit only English docs in
```
docs/src/content/docs/**
```
  .
- Exclude
```
docs/src/content/docs/openai
```
  from review and updates.
- Do not edit
```
docs/src/content/docs/ja
```
  ,
```
docs/src/content/docs/ko
```
  , or
```
docs/src/content/docs/zh
```
  .
- Keep changes aligned with the existing docs style and navigation.
- Place any code snippets under
```
examples/docs/<doc-filename>/
```
  so the directory name matches the target doc file, mirroring existing patterns.
- Verify doc code snippets build successfully with
```
pnpm -F docs-code build-check
```
  and fix issues before handoff.

确认范围与基准分支
- 确定当前分支和默认分支（通常为
```
main
```
  ）。
- 优先分析当前分支，确保工作与正在进行的变更保持一致。
- 如果当前分支不是
```
main
```
  ，仅分析与
```
main
```
  分支的差异，以此确定文档更新的范围。
- 若切换分支会破坏本地变更，则避免切换；必要时使用
```
git show main:<path>
```
  或
```
git worktree add
```
  命令。
从选定范围构建功能清单
- 若在
```
main
```
  分支上：梳理完整的功能面并全面审核文档。
- 若不在
```
main
```
  分支上：仅梳理与
```
main
```
  分支相比的变更（功能新增/修改/移除）。
- 聚焦用户可见的行为：公开导出项、配置选项、环境变量、CLI命令、默认值，以及已记录的运行时行为。
- 为每个条目收集证据（文件路径 + 符号/设置）。
- 使用定向搜索查找选项类型和功能标志（例如：
```
rg "Options"
```
  、
```
rg "process.env"
```
  、
```
rg "export"
```
  ）。
- 当涉及OpenAI平台功能时，调用
```
$openai-knowledge
```
  从OpenAI开发者文档MCP服务器获取最新详情，而非自行猜测；若出现差异，以SDK源代码为权威依据。
- 对于MCP SDK（
```
modelcontextprotocol/typescript-sdk
```
  ）或Vercel AI SDK（
```
@ai-sdk/*
```
  ）相关主题，可选择使用Deepwiki MCP快速查询，但仍以SDK源代码为权威依据。
文档初筛：审核现有页面
- 遍历
```
docs/src/content/docs
```
  下的所有相关页面（排除
```
docs/src/content/docs/openai
```
  ）。
- 找出重要的、受支持的选项（可选启用标志、环境变量）、自定义点，或
```
packages/
```
  中的新功能在文档中缺失的提及。
- 在用户合理预期会找到这些内容的页面上，提出添加建议。
代码导向排查：将功能映射到文档
- 审核
```
docs/src/content/docs
```
  下当前的文档信息架构。
- 根据现有模式和包边界，确定每个功能对应的最佳页面/章节。
- 找出没有对应文档页面，或有页面但无对应内容的功能。
- 记录可提升可发现性的结构调整建议。
检测缺口与不准确内容
- 缺失：主分支中存在但文档中未提及的功能/配置。
- 错误/过时：与主分支不符的名称、默认值或行为。
- 结构问题（可选）：页面内容过载、缺少概述，或主题分组不当。
生成文档同步报告并请求批准
- 提交包含证据、建议文档位置和拟编辑内容的清晰报告。
- 询问用户是否继续进行文档更新。
若获批准，应用变更（仅限英文文档）
- 仅编辑
```
docs/src/content/docs/**
```
  下的英文文档。
- 排除
```
docs/src/content/docs/openai
```
  的审核与更新。
- 切勿编辑
```
docs/src/content/docs/ja
```
  、
```
docs/src/content/docs/ko
```
  或
```
docs/src/content/docs/zh
```
  下的文档。
- 确保变更与现有文档的风格和导航保持一致。
- 将所有代码片段放在
```
examples/docs/<doc-filename>/
```
  目录下，使目录名称与目标文档文件名匹配，遵循现有模式。
- 使用
```
pnpm -F docs-code build-check
```
  验证文档中的代码片段能否成功构建，在交付前修复所有问题。

Output format

输出格式

Use this template when reporting findings:

Docs Sync Report

Doc-first findings
- Page + missing content → evidence + suggested insertion point
Code-first gaps
- Feature + evidence → suggested doc page/section (or missing page)
Incorrect or outdated docs
- Doc file + issue + correct info + evidence
Structural suggestions (optional)
- Proposed change + rationale
Proposed edits
- Doc file → concise change summary
Questions for the user

报告结果时请使用以下模板：

文档同步报告

文档初筛发现
- 页面 + 缺失内容 → 证据 + 建议插入位置
代码导向排查的缺口
- 功能 + 证据 → 建议文档页面/章节（或缺失的页面）
错误或过时的文档
- 文档文件 + 问题 + 正确信息 + 证据
结构建议（可选）
- 拟变更内容 + 理由
拟编辑内容
- 文档文件 → 简洁的变更摘要
向用户提出的问题

References

参考资料

```
references/doc-coverage-checklist.md
```

```
references/doc-coverage-checklist.md
```