docs-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review documentation changes for correctness, style, and structure. Use AGENTS.md and the style guide at

src/content/docs/style-guide/

as primary references.

审核文档变更的正确性、样式与结构。请以AGENTS.md和位于

src/content/docs/style-guide/

的样式指南作为主要参考依据。

When to Suggest vs. When to Edit

何时提出建议 vs 何时直接编辑

Decision logic

决策逻辑

Explicit instruction wins. If the user says "suggest", "only make suggestions", or "do not make changes" — post suggestions via
```
gh
```
CLI, never push commits. If they say "fix", "address this", or "update" — edit files directly and commit.
Different actor = suggest. If the person invoking the review is not the PR author (and no explicit fix instruction was given), post suggestions so the author retains control.
Same actor or ambiguous = fix by default. When the invoker is the PR author (or it is unclear), default to editing files directly. MDX syntax errors, broken code, invalid frontmatter, wrong component usage, and other obvious errors should always be fixed, not suggested.

明确指令优先：如果用户要求“提出建议”“仅提供建议”或“不要修改”，请通过
```
gh
```
CLI发布建议，切勿推送提交。如果用户要求“修复”“处理此问题”或“更新”，请直接编辑文件并提交。
操作人非PR作者 = 提出建议：如果发起审核请求的人不是PR作者（且未明确要求修复），请发布建议，让作者保留控制权。
操作人是PR作者或指令模糊 = 默认修复：当发起者是PR作者（或身份不明确）时，默认直接编辑文件。MDX语法错误、代码损坏、无效前置元数据、组件使用错误及其他明显错误应始终直接修复，而非仅提出建议。

Quick reference

快速参考

Instruction	Action
"review", "suggest changes", "provide suggestions"	Post suggestions only via `gh` CLI — do not push commits
"only make suggestions", "do not make changes"	Post suggestions only — never edit files or push
"fix", "address this", "update"	Always edit files directly and commit changes
"review and fix"	Fix low-severity issues directly; suggest high-impact changes
Invoked by someone other than PR author	Post suggestions unless explicitly told to fix
Invoked by PR author (or unclear)	Fix directly — especially MDX syntax, code errors, and build breakers

When in doubt, fix obvious errors (build breakers, MDX syntax, wrong imports, broken code) and suggest subjective changes (wording, restructuring, style preferences).

指令内容	对应操作
"审核"、"提出修改建议"、"提供建议"	仅通过 `gh` CLI发布建议 — 切勿推送提交
"仅提出建议"、"不要修改"	仅发布建议 — 绝不编辑文件或推送提交
"修复"、"处理此问题"、"更新"	始终直接编辑文件并提交变更
"审核并修复"	直接修复低严重性问题；对高影响变更提出建议
由PR作者以外的人发起请求	除非明确要求修复，否则发布建议
由PR作者发起（或发起者身份不明）	直接修复 — 尤其是MDX语法、代码错误和会导致构建失败的问题

若存在疑问，直接修复明显错误（构建失败问题、MDX语法错误、导入错误、代码损坏），并对主观性变更提出建议（措辞、结构调整、样式偏好）。

Posting GitHub Suggestions

发布GitHub建议

Use the GitHub REST API via

gh api

to post line-level suggestions on PRs. This is the only way to propose changes when operating in suggestion-only mode.

通过

gh api

调用GitHub REST API在PR上发布行级建议。这是仅建议模式下提出变更的唯一方式。

Prerequisites

前置条件

Determine the PR number and the latest commit SHA before posting:

bash

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

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

bash

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

Single-line suggestion

单行建议

Replace one line in the diff. Use

subject_type: "line"

bash

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"

替换差异中的某一行。使用

subject_type: "line"

。

bash

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='优化措辞：

```suggestion
Workers采用事件驱动架构。每个入站请求都会触发一个`fetch`处理器。
```' \
  -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"

Multi-line suggestion

多行建议

Replace a range of lines. Add

start_line

and

start_side

bash

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"

替换连续多行。需添加

start_line

和

start_side

。

bash

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body='简化本段内容：

```suggestion
Bindings提供对R2、KV和D1等Cloudflare服务的直接进程内访问。
无需网络跳转、无需身份验证令牌，也不会增加额外延迟。
```' \
  -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"

Comment without suggestion

无建议的评论

For feedback that does not map to a specific replacement, post a plain review comment (no suggestion block):

bash

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"

对于无需提供具体替代内容的反馈，发布普通审核评论（不带建议块）：

bash

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \
  -f body="此声明需要来源。请链接到相关API参考文档或删除该内容。" \
  -f commit_id="${COMMIT_SHA}" \
  -f path="src/content/docs/workers/observability/index.mdx" \
  -F line=55 \
  -f side="RIGHT" \
  -f subject_type="line"

Rules for suggestion blocks

建议块规则

The content inside a
```
suggestion
```
fenced block replaces the target line(s) exactly. Include the full replacement text with correct indentation.
For single-line: set
```
line
```
to the diff line number. Do not set
```
start_line
```
.
For multi-line: set
```
start_line
```
to the first line and
```
line
```
to the last line of the range being replaced.
Always set
```
side
```
to
```
"RIGHT"
```
(the new file side of the diff).
Always set
```
subject_type
```
to
```
"line"
```
.
Line numbers refer to the new file in the diff (the right side), not the old file.
Use
```
-F
```
(not
```
-f
```
) for numeric fields (
```
line
```
,
```
start_line
```
) so
```
gh
```
sends them as integers.
Keep the prose before the suggestion block to one sentence. Do not over-explain.

```
suggestion
```
围栏块内的内容将完全替换目标行。请包含完整的替换文本并确保缩进正确。
单行建议：将
```
line
```
设置为差异中的行号，无需设置
```
start_line
```
。
多行建议：将
```
start_line
```
设置为替换范围的第一行，
```
line
```
设置为最后一行。
始终将
```
side
```
设置为
```
"RIGHT"
```
（差异中的新文件侧）。
始终将
```
subject_type
```
设置为
```
"line"
```
。
行号指的是差异中的新文件（右侧），而非旧文件。
数字字段（
```
line
```
、
```
start_line
```
）请使用
```
-F
```
而非
```
-f
```
，确保
```
gh
```
以整数形式发送。
建议块前的说明性文字请控制在一句话以内，无需过度解释。

Batching with a review object

批量提交建议（使用审核对象）

When posting 3+ suggestions, use a single review with multiple comments to avoid notification spam:

bash

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

When using

--input -

with a heredoc, do not pass

-f

-F

flags — all fields go in the JSON body. The JSON must include

event

commit_id

body

, and

comments

当需要发布3条及以上建议时，请使用单个审核请求包含多条评论，避免通知轰炸：

bash

gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/reviews \
  --input - <<EOF
{
  "event": "COMMENT",
  "body": "针对此PR的一些建议。",
  "commit_id": "${COMMIT_SHA}",
  "comments": [
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 42,
      "side": "RIGHT",
      "body": "优化表述：\n\n\`\`\`suggestion\nWorkers采用事件驱动模型。\n\`\`\`"
    },
    {
      "path": "src/content/docs/workers/get-started/index.mdx",
      "line": 58,
      "side": "RIGHT",
      "body": "修复链接：\n\n\`\`\`suggestion\n如需了解更多信息，请参考[Bindings](/workers/runtime-apis/bindings/)。\n\`\`\`"
    }
  ]
}
EOF

使用

--input -

和 heredoc 时，请勿传递

-f

-F

参数 — 所有字段均需放在JSON主体中。JSON必须包含

event

、

commit_id

、

body

和

comments

。

Review Process

审核流程

1. Read the Full Diff

1. 查看完整差异

bash

gh pr diff ${PR_NUMBER}

Read full files for context — code that looks wrong in a diff may be correct in context. Check what section the change sits in and what comes before/after.

bash

gh pr diff ${PR_NUMBER}

查看完整文件以获取上下文 — 在差异中看似错误的代码可能在完整上下文下是正确的。请检查变更所在的章节及其前后内容。

2. Check Against Rules

2. 对照规则检查

See

references/content-rules.md

for the full checklist. Quick reference:

Rule	Detail
Unescaped MDX characters	`{` , `}` , `<` , `>` in prose must be escaped or in backticks
Component imports	Every component used must be imported from `~/components`
Code block languages	Must be lowercase and in the supported set (see AGENTS.md)
Internal links	Absolute paths, no file extensions, no `https://developers.cloudflare.com`
Heading hierarchy	Sequential: H2 then H3 then H4 — never skip
Frontmatter	`title` required; `pcx_content_type` must be a valid value
Style guide	Active voice, no contractions, "select" not "click", bold for UI elements
Workers code	Must use `TypeScriptExample` component, not bare `js` / `ts` fences
Config blocks	Must use `WranglerConfig` component with TOML input
Code correctness	For type checking, API usage, and binding patterns, load the `code-review` skill
Accuracy	Claims must be substantiated — link to sources of truth, do not explain inline what other docs cover

完整检查清单请参见

references/content-rules.md

。快速参考：

规则	详情
未转义的MDX字符	正文内容中的 `{` 、 `}` 、 `<` 、 `>` 必须转义或放在反引号内
组件导入	所有使用的组件必须从 `~/components` 导入
代码块语言标识	必须为小写且属于支持集合（参见AGENTS.md）
内部链接	使用绝对路径，不带文件扩展名，不包含 `https://developers.cloudflare.com`
标题层级	按顺序使用：H2 → H3 → H4 — 切勿跳过层级
前置元数据（frontmatter）	必须包含 `title` ； `pcx_content_type` 必须为有效值
样式指南	使用主动语态，避免缩写，用“选择”而非“点击”，UI元素使用粗体标注
Workers代码	必须使用 `TypeScriptExample` 组件，而非直接使用 `js` / `ts` 围栏块
配置块	必须使用 `WranglerConfig` 组件并传入TOML格式内容
代码正确性	如需检查类型、API使用和绑定模式，请加载 `code-review` 技能
内容准确性	声明必须有依据 — 链接到权威来源，勿在正文内重复解释其他文档已覆盖的内容

3. Assess What to Flag

3. 确定需标记的问题

Flag	Do not flag
Incorrect technical content	Style preferences not in the style guide
Broken MDX (build will fail)	Pre-existing issues in unchanged lines
Wrong API usage or types	"Could be cleaner" when code is correct
Missing component usage ( `TypeScriptExample` , `WranglerConfig` )	Theoretical concerns without evidence
Inaccurate or unsubstantiated claims	Missing features outside the PR scope
Security or safety issues in examples	Minor wording differences that do not change meaning
Scope creep (changes to files outside the PR intent)

需标记的问题	无需标记的问题
技术内容错误	样式指南未规定的个人样式偏好
会导致构建失败的MDX问题	未变更行中已存在的问题
API使用错误或类型错误	代码正确但“可以更简洁”的情况
未使用指定组件（ `TypeScriptExample` 、 `WranglerConfig` ）	无证据的理论性问题
不准确或无依据的声明	PR范围外的缺失功能
示例中的安全问题	不改变语义的细微措辞差异
范围蔓延（修改PR意图外的文件）

4. Prioritize

4. 优先级排序

Review in severity order:

Build breakers — unescaped MDX, missing imports, invalid frontmatter
Incorrect content — wrong API, wrong behavior description, broken examples
Missing best practices — no
```
TypeScriptExample
```
, hardcoded compat dates, bare code fences
Style and structure — heading levels, link format, prose quality

按严重性顺序审核：

构建阻断问题 — 未转义的MDX字符、缺失的导入、无效前置元数据
内容错误 — API使用错误、行为描述错误、示例损坏
缺失最佳实践 — 未使用
```
TypeScriptExample
```
、硬编码兼容日期、直接使用代码围栏块
样式与结构 — 标题层级、链接格式、正文质量

Content Review Principles

内容审核原则

These principles are derived from recurring review feedback on this repo:

Link to sources of truth. Do not re-explain concepts that have their own docs page. Link to the canonical page instead. Example: do not explain HTTP error 522 inline — link to
```
/support/troubleshooting/http-status-codes/
```
.
Substantiate claims. If docs say "X behaves this way", verify it. Reference source code, API docs, or config schemas. Flag unverified claims.
Be direct about recommendations. "Always use Hyperdrive when connecting to a remote PostgreSQL database" is better than "Connecting directly adds latency; consider using Hyperdrive."
Qualify scope. "Bindings provide direct access to Cloudflare services like R2, KV, and D1" is better than "Bindings provide direct access to Cloudflare services" (which implies all services).
Code examples must be safe to copy. Treat every code block as something a developer will paste into production. Examples must handle errors, use correct types, and follow current best practices.
Use the right component. Workers code should use
```
TypeScriptExample
```
. Config should use
```
WranglerConfig
```
with
```
$today
```
for compatibility dates. Package install commands should use
```
PackageManagers
```
.
Keep changes in scope. If a review uncovers issues in files outside the PR, note them but do not fix them in the same PR.
Research before asserting. If uncertain whether an API, flag, or behavior is correct, look it up in the types, schema, or docs before flagging.

这些原则源自本仓库中反复出现的审核反馈：

链接到权威来源：勿重复解释已有独立文档页面的概念，而是链接到规范页面。例如：勿在正文内解释HTTP 522错误 — 链接到
```
/support/troubleshooting/http-status-codes/
```
。
声明需有依据：如果文档称“X的行为是这样”，请进行验证。参考源代码、API文档或配置模式。标记未经验证的声明。
建议需直接明确：“连接远程PostgreSQL数据库时请始终使用Hyperdrive”比“直接连接会增加延迟；考虑使用Hyperdrive”更清晰。
限定范围：“Bindings提供对R2、KV和D1等Cloudflare服务的直接访问”比“Bindings提供对所有Cloudflare服务的直接访问”更准确（后者暗示支持所有服务）。
代码示例需可安全复制：将每个代码块视为开发者会直接粘贴到生产环境的内容。示例必须处理错误、使用正确类型并遵循当前最佳实践。
使用正确组件：Workers代码应使用
```
TypeScriptExample
```
组件。配置应使用
```
WranglerConfig
```
组件并配合
```
$today
```
设置兼容日期。包安装命令应使用
```
PackageManagers
```
组件。
变更需在范围内：如果审核发现PR外文件的问题，请记录但勿在当前PR中修复。
先调研再断言：若不确定某API、标志或行为是否正确，请先在类型定义、模式或文档中查证，再标记问题。

Output Format

输出格式

When posting suggestions, keep commentary minimal. One sentence of context, then the suggestion block.

When posting a summary comment (not line-level), list issues by severity with file and line references. Severity levels: CRITICAL (build break, security) | HIGH (incorrect content, wrong API) | MEDIUM (missing component, outdated pattern) | LOW (minor style, wording)

发布建议时，请尽量简化评论。先写一句上下文说明，再附上建议块。

发布总结评论（非行级评论）时，请按严重性排序列出问题，并标注文件和行号。严重性等级：CRITICAL（构建阻断、安全问题）| HIGH（内容错误、API使用错误）| MEDIUM（缺失组件、过时模式）| LOW（细微样式、措辞问题）