pr

为当前分支创建或更新一个 GitHub 拉取请求（PR）。将 PR 视为持久的知识传递：说明行为发生了什么变化以及原因，而不是罗列文件。优先遵循用户的明确指示，其次遵循适用的仓库指南，然后再采用以下默认规则。标题使用英文。正文使用用户明确要求的语言；否则使用用户请求所用的语言。此技能不强制规定正文语言。面向用户的回复使用用户的语言。

1. 检查与防护

1. 撰写内容前，阅读适用的仓库指南和任何 PR 模板。

2. 检查当前分支和工作区：

   git branch --show-current
   git status --short --branch
   git symbolic-ref --quiet --short refs/remotes/origin/HEAD
   

   仅将符号引用结果保留为新建 PR 时的备用基础分支。通过移除开头的 origin/ 来获取其分支名称；在完成下方的 PR 查询之前，不要选择比较引用。

3. 使用 git fetch --prune origin 刷新远程引用。如果获取失败，显示错误并停止；不要根据过时的远程状态决定是否发布。

4. 查找头部分支完全匹配的未关闭 PR：

   gh pr list --head <branch> --state open --limit 1 \
     --json number,title,url,body,isDraft,baseRefName,headRefName
   

   如果命令失败，显示错误并停止。保存结果以供后续使用；空数组表示创建，单个结果表示更新。

5. 仅在完成该查询后选择有效基础分支：

   • 对于现有 PR，使用其 baseRefName。如果用户明确要求使用其他基础分支，应停止并澄清，不要默默地以其中任意一个作为比较分支。
   • 对于新建 PR，使用用户指定的基础分支（如有）；否则使用远程默认分支。如果两者都不可用，应停止并询问基础分支。

   对用户提供的 origin/<base>，仅移除开头的 origin/ 进行规范化，然后将 <comparison-ref> 设置为 origin/<base>。确认获取完成后该引用存在。如果当前分支与有效基础分支相同，或者 git log <comparison-ref>..HEAD --oneline 没有任何提交，则停止。

6. 如果存在已跟踪或未跟踪的更改，告知用户这些更改不会包含在 PR 中，并询问是否要先提交。只有用户提交这些更改或明确选择排除后，才能继续。

7. 使用以下命令确定上游：

   git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'
   

   • 如果没有上游，运行 git push -u origin <branch>。
   • 如果存在上游，计算 git rev-list --left-right --count <upstream>...HEAD。如果左侧计数不为零，则停止并说明本地分支必须先同步；不要擅自合并、变基或强制推送。如果只有右侧计数不为零，则运行 git push。
   • 如果推送失败，显示错误并停止。绝不要使用 --force 重试。

2. 构建 PR 模型

使用已保存的 PR 查询结果和上文选定的有效 <comparison-ref>， 检查 PR 的每个提交以及完整 PR 差异：

git log <comparison-ref>..HEAD --format='%h%x09%s%n%b'
git diff --stat <comparison-ref>...HEAD
git diff <comparison-ref>...HEAD

选择正文详略、撰写说明、检查变更覆盖范围以及报告提交和文件数量时，只将这些输出视为 PR 变更集。后续步骤中的“分支提交”均严格指 git log <comparison-ref>..HEAD 返回的提交。可从 <comparison-ref> 访问的提交属于基础历史，不属于 PR 变更，即使它不在远程默认分支中；正文中不要包含其行为。

将提交历史作为证据，而不是叙述结构。综合各提交中最终实现的行为，忽略已被完整 PR 差异取代的中间状态。起草前，按不同工作流或组件拆分每项重要变更，并根据证据梳理其参与者、触发条件、输入和时间范围、状态或输出、下游交接、故障行为以及发布或迁移顺序（如适用）。在内部检查是否涵盖了每项重要的分支变更，但不要将覆盖情况写成按时间顺序排列的提交列表。

根据保留的证据，确定主要的前后行为变化。只有证据确实支持时，才说明原因、语义解释、影响、限制、权衡或风险之间的确切关联；不要根据相关变更自行推断，缺乏证据时就省略。使用已保存的空查询结果创建 PR，或使用仅有的一条查询结果更新 PR。

3. 撰写有据可依的内容

新 PR 的标题

• 以简洁的英文祈使动词开头，并点明核心行为。
• 标题最多 40 个字符，不包括工单前缀。
• 如果分支包含由字母或字母数字字符后接连字符和数字组成的标识符，则将其转为大写并用方括号括起，置于标题前。例如，feature/proj-42-fix-layout 变为 [PROJ-42] Fix layout。
• 不要更改现有 PR 的标题。

正文篇幅

统计提交数和变更文件数；如果这两个指标对应的级别不同，则采用较详细的级别：

级别	阈值	生成的章节
简单	1-2 次提交且最多 3 个文件	摘要、变更
标准	3-10 次提交或 4-10 个文件	摘要、关键变更、验证
复杂	11 次或以上提交或 11 个或以上文件	摘要、按主题组织的关键变更、验证、审查备注

即使仓库模板要求添加章节，也应确保正文篇幅与变更相称。应用以下内容规则：

• 先说明行为变化前后的情况，以及其重要性。
• 说明能解释 PR 大部分内容的核心思路，然后按行为或审查者关注点归纳相关变更。如果重要工作流没有共同且有证据支持的原因或结果，应分别说明其变化前后的情况，不要强行套用一个总括性叙述。不要按提交顺序组织正文、逐一叙述文件，也不要复述每处差异。
• 除非次要和机械性修改会改变认知模型或需要审查者采取行动，否则不要将其写入摘要和关键变更。在验证中报告测试命令和结果，不要把常规测试实现列为关键变更。
• 当具体输入、状态或输出能更快地说明不明显的规则时，使用一个简单示例。例如：请求 r1、r1、r2 过去会创建三个任务；现在会创建两个，因为请求 ID 决定身份。确保示例忠实反映行为，不要在文字说明更清楚时强行举例。
• 除非用户或仓库模板明确要求，否则不要写入提交哈希或逐次提交日志。
• 仅在有证据支持时报告验证结果。仅由提交历史报告的结果，应注明其来源；不要将变更的测试或静态检查描述为已通过的执行结果。说明已报告的检查未覆盖的任何重要运行时、集成、部署、迁移或外部服务边界。如果必需的验证章节没有已执行检查的证据，应写出相当于未运行的内容；切勿猜测。
• 仅在差异内容支持时，才添加迁移说明、风险或审查指引。

仅将生成的内容包在以下所有权标记中：

<generated sections>

更新时：

• 如果两个标记各出现一次且顺序正确，则仅替换标记内的内容，并逐字节保留标记外的所有文本。
• 如果正文没有标记，则逐字节保留整个现有正文，并在末尾追加一个带标记的生成内容块。
• 如果标记格式错误、重复或顺序不正确，请停止并询问用户如何继续。不要冒险删除作者撰写的内容。

如果用户要求创建草稿，或分支名称以draft/或wip/开头，则创建时添加--draft。更新正文时，必须保留现有草稿状态。

4. 验证、执行并确认

在执行任何gh pr create或gh pr edit之前，确认：

1. 创建标题符合语言、长度、动词和工单规则。
2. 正文符合所选篇幅，开篇阐明核心思路，并涵盖所有重要的分支变更，不依赖按时间顺序排列的提交列表。
3. 每项事实性陈述均有已检查的差异、历史记录、指引或模板作为依据。
4. 所有权标记之外的现有内容保持不变。

通过标准输入传递正文，避免 shell 插值更改正文：

gh pr create --title "<title>" --assignee @me --base "<base>" \
  --head "<branch>" [--draft] --body-file - <<'EOF'
<body>
EOF

gh pr edit "<number>" --body-file - <<'EOF'
<body>
EOF

不要原样包含方括号中的可选标志；应添加--draft或省略它。成功后，运行gh pr view <number-or-url> --json number,title,url,body,isDraft,commits,files，并核实已发布的标题、正文、草稿状态、提交数和文件数。如果创建、更新或验证失败，则显示错误并停止，不要声称操作成功。

报告 PR 编号和标题、URL、创建或更新状态、草稿状态、提交数和变更文件数。