docs-review

检查文档变更的正确性、风格和结构。

主要风格参考： .agents/references/style-guide.md——审查前请先阅读。该文件包含 MDX 语法、前置元数据、写作风格、格式、链接、代码块和提示框的权威规则。如需深入了解某个主题，可查阅 src/content/docs/style-guide/ 中的完整风格指南。

何时提出建议，何时直接修改

决策逻辑

1. 明确指示优先。 如果用户说“提出建议”“只提出建议”或“不要进行修改”，请通过 gh CLI 发布建议，切勿推送提交。如果用户说“修复”“处理此问题”或“更新”，请直接编辑文件并提交。
2. 操作者不同，则提出建议。 如果发起审查的人不是 PR 作者（且没有明确要求修复），请发布建议，让作者自行决定。
3. 操作者相同或不明确，则默认修复。 如果发起者是 PR 作者（或无法确定），默认直接编辑文件。MDX 语法错误、代码错误、无效的前置元数据、组件用法错误及其他明显错误都应直接修复，而非仅提出建议。

快速参考

指示	操作
“审查”、“建议修改”、“提供建议”	仅通过 gh CLI 发布建议，不要推送提交
“只提出建议”、“不要进行修改”	仅提出建议——绝不编辑文件或推送
“修复”、“处理此问题”、“更新”	始终直接编辑文件并提交变更
“审查并修复”	直接修复低严重性问题；对高影响变更提出建议
发起者不是 PR 作者	除非明确要求修复，否则发布建议
发起者是 PR 作者（或无法确定）	直接修复，尤其是 MDX 语法、代码错误和构建阻断问题

如有疑问，修复明显错误（构建阻断问题、MDX 语法错误、错误的导入、代码错误），并对主观性修改（措辞、结构调整、风格偏好）提出建议。

发布 GitHub 建议

使用 GitHub REST API，通过 gh api 在 PR 上发布针对具体行的建议。处于仅提出建议的模式时，这是唯一允许提出修改建议的方式。

前提条件

发布建议前，先确定 PR 编号和最新提交 SHA：

PR_NUMBER=$(gh pr view --json number -q '.number')
COMMIT_SHA=$(gh pr view --json commits -q '.commits[-1].oid')

单行建议

替换差异中的一行。使用 subject_type: "line"。

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='Tighten the phrasing:

```suggestion
Workers use an event-driven architecture. Each incoming request triggers a `fetch` handler.
```' \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/get-started/index.mdx" \
  -F line=42 \
  -f side="RIGHT" \
  -f subject_type="line"

多行建议

替换一段行。添加 start_line 和 start_side。

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='Simplify this paragraph:

```suggestion
Bindings provide direct, in-process access to Cloudflare services like R2, KV, and D1.
They require no network hop, no authentication token, and add no extra latency.
```' \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/runtime-apis/bindings.mdx" \
  -F start_line=18 \
  -F line=22 \
  -f start_side="RIGHT" \
  -f side="RIGHT" \
  -f subject_type="line"

不附带建议的评论

对于无法对应到具体替换内容的反馈，发布普通审查评论（不包含建议块）：

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body="This claim needs a source. Link to the relevant API reference or remove it." \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/observability/index.mdx" \
  -F line=55 \
  -f side="RIGHT" \
  -f subject_type="line"

建议块规则

• suggestion 围栏块中的内容会精确替换目标行。请提供完整的替换文本，并使用正确的缩进。
• 单行建议：将 line 设为差异中的行号。不要设置 start_line。
• 多行建议：将 start_line 设为待替换范围的第一行，将 line 设为最后一行。
• side 始终设为 "RIGHT"（差异中新文件的一侧）。
• subject_type 始终设为 "line"。
• 行号指差异中新文件的行号（右侧），而不是旧文件的行号。
• 数值字段（line、start_line）请使用 -F（而非 -f），以便 gh 将其作为整数发送。
• 建议块前的说明文字仅限一句。不要过度解释。

使用 review 对象进行批量处理

发布 3 条或更多建议时，请使用包含多条评论的单个 review，避免通知过多：

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/reviews \
  --input - <<EOF
{
  "event": "COMMENT",
  "body": "A few suggestions for this PR.",
  "commit_id": "${COMMIT_SHA}",
  "comments": [
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 42,
      "side": "RIGHT",
      "body": "Tighten:\n\n\`\`\`suggestion\nWorkers use an event-driven model.\n\`\`\`"
    },
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 58,
      "side": "RIGHT",
      "body": "Fix link:\n\n\`\`\`suggestion\nFor more information, refer to [Bindings](/workers/runtime-apis/bindings/).\n\`\`\`"
    }
  ]
}
EOF

使用 heredoc 配合 --input - 时，不要传入 -f/-F 标志——所有字段都放在 JSON 请求体中。JSON 必须包含 event、commit_id、body 和 comments。

Review 流程

1. 阅读完整 Diff

gh pr diff ${PR_NUMBER}

阅读完整文件以了解上下文——在 diff 中看似有问题的代码，结合上下文来看可能是正确的。检查更改所在的章节，以及前后的内容。

2. 对照规则检查

完整规则请参阅 .agents/references/style-guide.md。快速参考：

规则	详情
未转义的 MDX 字符	正文中的 {、}、<、> 必须转义或放在反引号中
组件导入	使用的每个组件都必须从 ~/components 导入
Workers 代码	必须使用 TypeScriptExample，不能使用裸 js/ts 代码围栏
配置代码块	必须使用带 TOML 输入的 WranglerConfig；compatibility_date 使用 $today
软件包安装命令	必须使用 PackageManagers，不能使用裸 sh 代码围栏
代码块语言	使用支持列表中的小写语言标识符——参见 .agents/references/style-guide.md
内部链接	使用根相对路径，末尾带斜杠，不带文件扩展名，不使用完整的 developers.cloudflare.com URL
Frontmatter	必须包含 title 和 description；pcx_content_type 必须是有效值
写作风格	参阅 .agents/references/style-guide.md——其中涵盖语气、缩写、术语、标题等内容
代码正确性	如需检查类型、API 用法和绑定模式，请加载 code-review 技能
准确性	必须有依据支持相关声明——链接到权威来源，不要重复解释其他页面已涵盖的内容

3. 判断需要标记的问题

标记	不要标记
技术内容错误	风格指南中未规定的风格偏好
MDX 损坏（导致构建失败）	未更改行中原本就存在的问题
API 用法或类型错误	代码正确但“可以写得更简洁”
缺少组件用法（TypeScriptExample、WranglerConfig）	没有证据支持的理论性担忧
声明不准确或缺乏依据	PR 范围之外缺少的功能
示例中存在安全问题	不影响含义的细微措辞差异
范围蔓延（更改超出 PR 意图的文件）

4. 确定优先级

按严重程度排序：

1. 导致构建失败的问题——未转义的 MDX、缺少导入、无效的 frontmatter
2. 内容错误——API 错误、行为描述错误、示例损坏
3. 缺少最佳实践——未使用 TypeScriptExample、兼容日期硬编码、使用裸代码围栏
4. 风格与结构——标题级别、链接格式、正文质量

内容审查原则

这些原则总结自本仓库反复出现的审查反馈：

• 链接到权威来源。 不要重复解释已有专属文档页面的概念，而应链接到规范页面。例如，不要在正文中解释 HTTP 错误 522，而应链接到 /support/troubleshooting/http-status-codes/。
• 为主张提供依据。 如果文档声称“X 的行为是这样的”，请核实。引用源代码、API 文档或配置架构。标记未经核实的主张。
• 明确提出建议。 “连接远程 PostgreSQL 数据库时，始终使用 Hyperdrive”比“直接连接会增加延迟；可以考虑使用 Hyperdrive”更好。
• 明确适用范围。 “绑定可直接访问 R2、KV 和 D1 等 Cloudflare 服务”比“绑定可直接访问 Cloudflare 服务”更好，后者会让人误以为涵盖所有服务。
• 代码示例必须可安全复制。 将每个代码块都视为开发者会粘贴到生产环境中的内容。示例必须处理错误、使用正确的类型，并遵循当前最佳实践。
• 使用合适的组件。 Workers 代码应使用 TypeScriptExample。配置应使用 WranglerConfig，并用 $today 设置兼容性日期。软件包安装命令应使用 PackageManagers。
• 修改内容应限定在当前范围内。 如果审查发现 PR 以外文件中的问题，请指出，但不要在同一个 PR 中修复。
• 断言前先调查。 如果不确定某个 API、标志或行为是否正确，请先查阅类型定义、架构或文档，再提出问题。

输出格式

<response_format> 你的回复会以 GitHub 评论的形式显示。审查者阅读的每条评论都会占用注意力。请直截了当、言简意赅，绝不重复内容。

组织回复

发布行内建议时，在建议代码块前只写一句评论。不要过度解释。

发布总结评论时，使用以下结构：

1. 一句话结论 — 说明你做了什么（例如：“修复了 2 个问题，发布了 3 条建议。”）或给出评估（例如：“未发现问题。”或“有 2 个问题需要在合并前修复。”）。
2. 问题列表 — 只列出需要处理的事项，并按严重程度分组。使用严重程度标签：CRITICAL（构建中断、安全问题）| HIGH（内容错误、API 使用错误）| MEDIUM（缺少组件、模式过时）| LOW（轻微风格或措辞问题）。每项都注明文件路径和行号。
3. 范围外备注（可选）— 指出值得后续修复的既有问题，最多一两句话。

评论中仅包含以上内容。不要添加其他内容。

省略的内容

• 不要列出审查通过的项目。如果审查发现 2 个问题，就只提及这 2 个问题，不要再列出 15 个正常项目。
• 不要以赞扬或对 PR 的定性评价开头（例如“写得很好”“很扎实的 PR”“技术上很可靠”）。从结论开始。
• 不要重复信息。如果你发布了行内建议，总结评论应简要提及（“发布了 3 条行内建议”），而不是逐条重述。
• 少于 4 项时不要创建表格。请使用普通列表。
• 不要叙述审查过程（例如“我逐节进行了比较”“我核实了全部 37 处更改”）。直接说明结论，而不是审查方法。
• 不要向作者复述 PR 的更改。他们知道自己做了什么。

后续回复

在同一讨论串中回应后续请求时（例如“修复构建”“处理审查意见”）：

1. 说明你修改了什么，并注明文件路径和行号。
2. 到此为止。

不要重新进行完整审查。不要重新总结 PR。不要重复之前评论中的指导。讨论串中的每条评论都应只包含新信息。 </response_format>