pr

在为此仓库的变更创建 GitHub 拉取请求，或编辑现有 PR 的标题或描述时，使用此技能。

gh CLI

此技能全程使用 gh CLI。如果 gh 命令因未安装或未通过身份验证而失败，请改为清楚地提供 PR 标题和正文，方便用户复制粘贴，并附上相关 GitHub URL：

• 新建 PR：https://github.com/cloudflare/cloudflare-docs/compare/production...<branch>（通过 git branch --show-current 获取分支）
• 编辑现有 PR：https://github.com/cloudflare/cloudflare-docs/pull/<number> — 指示用户在描述中选择 Edit。

编辑现有 PR

当被要求更新或编辑现有 PR 的描述（或标题）时，严格遵循以下规则，然后停止。不要继续执行下面的“创建新 PR”步骤。

1. 始终先读取当前 PR 描述，使用 gh pr view <number> --json title,body，然后再进行任何更改。
2. 如果描述为空，将其视为新 PR 正文，并遵循下面“创建新 PR”部分中的模板和指南。
3. 遵循现有格式 — 如果作者以特定方式组织了描述，请保留其结构。不要重新格式化、调整顺序或重组他们编写的部分。
4. 只修改用户要求的内容 — 仅进行满足请求所需的最小改动。不要“改进”无关措辞、修正其他地方的语法、重写摘要，或修改用户未提及的核对清单项。
5. 应用修改：
   • 标题：gh pr edit <number> --title "..."
   • 正文：使用 Write 工具将更新后的正文写入临时文件，然后运行 gh pr edit <number> --body-file /tmp/pr-body.md，并使用 rm /tmp/pr-body.md 清理。不要使用 --body "..." — shell 引号处理会破坏反引号和其他 Markdown 格式。

推送到有开放 PR 的分支之后

每当你向已有开放 PR 的分支推送新提交时，检查 PR 标题和描述是否仍能准确说明该分支当前的内容。新提交经常会引入原描述未涵盖的范围。

1. 检查该分支是否有开放 PR：gh pr view --json number,title,body。
2. 将标题和正文与完整分支差异进行比较（git diff production...HEAD --stat），而不只是查看最新提交。
3. 如果描述已不准确或不完整，请遵循“编辑现有 PR”中的规则进行更新 — 保留作者的结构，并只做反映新变更所需的最小修改。如果描述仍能正确说明分支内容，则保持不变。

推送后主动执行此操作；无需用户另行提出要求来保持 PR 信息同步。

创建新 PR

仅在创建新 PR 时（或现有 PR 的描述为空时）执行以下步骤 1–4。

步骤 1 — 收集上下文

先运行 --stat，了解变更范围，避免一次性载入过多内容：

git log --oneline production..HEAD
git diff production...HEAD --stat
git status

如果 git status 显示有未跟踪或已修改的文件，请停止并询问用户是否应将这些文件作为 PR 的一部分提交。不要默默忽略它们 — 它们可能是此次提交工作不可或缺的内容。

如果 stat 输出显示变更文件超过约 20 个，请勿运行完整差异。改为阅读 stat 输出中不明确的特定文件。对于较小的变更集（少于约 20 个文件），可以查看完整差异：

git diff production...HEAD

步骤 2 — 撰写 PR 标题

分支：production

此仓库使用 production 作为默认分支，而非 main。创建 PR 时始终使用 --base production。其他仓库的贡献者通常会认为默认分支是 main — 这是有意为之。

除非用户要求使用其他基准分支，否则应从最新的 production 提交创建功能分支（运行 git fetch origin，然后从 origin/production 创建分支）。

格式

对于内容更改，主要采用产品方括号格式：

[Product] Short description

对于涉及多个产品的更改：

[Product1, Product2] Short description

对于非内容更改（工具、CI、配置、组件、worker 代码、仓库维护），请改用 Conventional Commits 前缀：

chore: Short description
fix: Short description
feat: Short description

根据文件路径推断产品方括号

不要询问作者该使用哪个产品方括号——应根据已更改的文件路径推断。

• src/content/docs/{slug}/ 和 src/content/partials/{slug}/ 直接对应一个产品。读取 src/content/docs/{slug}/index.mdx 中的 title 字段以获取显示名称，然后去掉任何 "Cloudflare " 前缀，作为方括号内容（例如，标题 "Cloudflare Workers" → [Workers]）。
• src/content/changelog/{slug}/ 的处理方式相同——使用产品方括号，而不是 [Changelog]。只有当 PR 仅新增或更新多个产品的变更日志条目时，才使用 [Changelog]。
• 如果更改涉及的产品超过 3 个，请选用其中最主要的 2–3 个。

规则

• 产品名称在方括号内使用标题式大小写：[Workers]、[AI Search]、[Zero Trust]
• 描述控制在约 60 个字符以内
• 使用祈使语气：添加、修复、更新、移除、记录、更正
• 末尾不要加句号
• 方括号内使用常见缩写：Durable Objects 用 [DO]，以及 [KV]、Zero Trust 用 [ZT]、[R2]、[D1]

标题示例（来自真实 PR）

[AI Search] Add hybrid search and boosting configuration docs
[Hyperdrive, Workers VPC] Document TCP services, TLS cert verification
[Browser Rendering] Add Wrangler CLI commands documentation
[Billing] Restructure billing docs into intent-based sections
[DMARC Management] ELI5
[Client-side security] ELI5 updates
[DNS, Fundamentals] Onboarding review and add video
[Style Guide] Adding products frontmatter to all visible examples
[Workers] Document Durable Object Facets
[Changelog] CDP + WebMCP changelog entries

内容更改默认使用 [Product] 方括号格式。非内容更改使用 Conventional Commits 前缀。

第 3 步 — 编写 PR 正文

编写正文前，先从仓库中读取 PR 模板：

cat .github/pull_request_template.md

将该文件作为 PR 正文的准确基础。不要依赖任何硬编码的模板版本——每次都要从磁盘重新读取，以防模板有所更改。

如何填写各个部分

摘要

简要说明以下内容：

• 此次修改的文档类型（新页面、更新、修复、重构、变更日志条目）
• 为什么需要此项修改，或是什么促成了这项修改
• 相关公开背景信息的链接：GitHub issue、相关 PR 或公开文档页面。

这是一个公开的开源代码库。请勿在 PR 标题、描述或评论中包含 Cloudflare 的非公开信息、机密、凭据、环境变量值，或内部资源（工单、Wiki 页面、内部文档）的 URL 和标题。如果不确定某些内容是否适合公开，请暂停并询问用户。

请以事实为依据。不要复述清单中的内容。对于小型、聚焦的 PR，写 1-2 句话即可。对于涉及多个文件或多个领域的大型 PR，可以写更长的描述；如果表格、列表或代码块比段落更便于快速浏览，请优先使用它们。

优秀示例：

小型、聚焦的 PR：

为 SCIM 配置中的 active 属性映射行为添加了一条注意事项。

修复 https://github.com/cloudflare/cloudflare-docs/issues/1234

中型 PR：

更新 Access 策略索引，以反映新的策略分组 UI。修正过时的截图和不准确的步骤顺序。

涉及多个领域的大型 PR：

将账单文档重组为按用户意图划分的章节，方便用户查找定价和用量信息。

修改前	修改后
billing/usage.mdx	billing/usage-and-limits.mdx
billing/limits.mdx	(合并至上方文件)
billing/overview.mdx	billing/index.mdx

• 更新所有指向已移动页面的内部链接
• 为所有已重命名的文件添加重定向

截图（可选）

除非 PR 修改了可视内容（例如新增页面、调整导航、更新 UI 步骤或修改图片），否则请完全跳过此部分。如果不需要截图，请勿保留空的注释占位符。

如果 PR 确实修改了可视内容，请保留此部分并包含一个 `` 注释，以便提醒相关人员在 PR 准备好接受审核前填写。

文档检查清单

逐项检查并判断是否适用：

1. 变更日志条目 — 如果 PR 介绍了 Cloudflare 产品的新功能、增强功能或值得注意的变更，则必须包含此项。如果 PR 属于修复、拼写错误更正、内部重构或样式更新，请移除此项。

2. 遵循样式指南 — 检查 src/content/ 下的文件或编写的组件文件（.mdx、.astro、.css）是否有差异。只有新增或修改了至少一个此类文件时，才保留此项。如果 PR 只修改了源代码（.ts、.tsx、.js）、工具、CI、配置文件、Agent 技能或其他非内容资源，请移除此项，即使这些文件位于 src/ 下或恰好是 Markdown 文件。

3. 针对较大改动创建 issue — 如果 PR 新增页面、重构章节或修正已知错误，则保留此项。对于小型、聚焦的改动，请移除此项。

4. 为重命名或移动的文件添加重定向 — 如果有任何 .mdx 文件被重命名、移动或删除，则保留此项。如果没有文件更改位置，请移除此项。

移除确实不适用的单项清单。不要保留不相关的未勾选项，以免给审核人员造成干扰。只有当所有项目都不适用时，才移除整个“文档检查清单”部分（例如纯粹的 CI 或工具改动）。只要有一项适用，就保留此部分，并且只移除不相关的项目。

不要这样做

这些做法会增加评审阻力，并导致 PR 被退回：

• 缺少上下文的改写 — 如果 PR 大幅更改或重组了内容，摘要必须说明改了什么以及为什么改。没有说明的差异会迫使评审者反向推断意图。
• 逐条叙述差异 — 不要通过逐行列出改动来概述 PR（“将第 42 行的 X 改为 Y”“将标题从 A 更新为 B”）。请解释为什么要做这项更改，而不是描述机械的改动过程。
• 未作说明的跨产品更改 — 如果 PR 涉及多个产品领域的文件，请解释它们之间的关联。看似无关的更改若没有说明原因，会引起评审者警觉。
• 错误地删减检查清单 — 删除不适用的单项。除非所有项目都不相关，否则不要删除整个检查清单部分。评审者会利用保留的项目快速确认覆盖情况。

第 4 步 — 创建 PR

根据第 3 步读取的模板撰写 PR 正文：将摘要占位注释替换为实际摘要，删除不适用的检查清单项目，并按照上文的指引处理截图部分。

重要： 不要通过 --body "$BODY" 或 --body '...' 传递正文——Shell 引号会破坏反引号和其他 Markdown 格式。请改为将正文写入临时文件，并使用 --body-file：

# 1. Write the PR body to a temp file using the Write tool (not echo/cat)
# 2. Create the PR referencing that file
gh pr create --base production --draft --title "[Product] short description" --body-file /tmp/pr-body.md
# 3. Clean up
rm /tmp/pr-body.md

所有 PR 都必须创建为草稿。大多数贡献者不应直接进入评审队列——作者应先检查部署预览，并在确认无误后将 PR 标记为可评审。

输出

分享 PR URL，并告知用户该 PR 已创建为草稿——他们应检查更改和部署预览是否正确，满意后再将其标记为可评审。不要推送后续提交，不要请求评审者，也不要在未收到请求时进一步修改 PR。接下来由人工处理。