pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create or update one GitHub pull request for the current branch. Treat the PR as durable knowledge transfer: explain the changed behavior and its reason, not a file inventory. Follow explicit user instructions first, then applicable repository guidance, before the defaults below. Write the title in English. Write the body in the language the user explicitly requests, or otherwise in the language of the user's request; this skill does not impose a fixed body language. Write the user-facing response in the user's language.

为当前分支创建或更新一个GitHub拉取请求（PR）。将PR视为持久化的知识传递载体：解释变更后的行为及其原因，而非仅罗列文件清单。优先遵循用户明确的指令，其次适用仓库的指导规范，最后才使用以下默认规则。PR标题需使用英文撰写。PR正文使用用户明确要求的语言，或采用用户请求时使用的语言；本技能不强制固定的正文语言。面向用户的回复需使用用户的语言。

1. Inspect and Guard

1. 检查与防护

Read applicable repository guidance and any pull request template before composing content.
Inspect the current branch and worktree:
bash
```
git branch --show-current
git status --short --branch
git symbolic-ref --quiet --short refs/remotes/origin/HEAD
```
Keep the symbolic-ref result only as the fallback base for a new PR. Derive its branch name by removing only the leading
```
origin/
```
; do not select the comparison ref until the PR lookup below is complete.
Refresh remote refs with
```
git fetch --prune origin
```
. If the fetch fails, show the error and stop; do not make publish decisions from stale remote state.
Find an open PR for the exact head branch:
bash
```
gh pr list --head <branch> --state open --limit 1 \
  --json number,title,url,body,isDraft,baseRefName,headRefName
```
If the command fails, show the error and stop. Save the result for later use; an empty array means create and one result means update.
Choose the effective base only after that lookup:
- For an existing PR, use its
```
baseRefName
```
  . If the user explicitly requested a different base, stop and clarify instead of comparing against either one silently.
- For a new PR, use the user-requested base when supplied; otherwise use the remote default branch. If neither is available, stop and ask for the base.
Normalize a supplied
```
origin/<base>
```
by removing only the leading
```
origin/
```
, then set
```
<comparison-ref>
```
to
```
origin/<base>
```
. Verify that ref exists after the fetch. Stop if the current branch equals the effective base or if
```
git log <comparison-ref>..HEAD --oneline
```
contains no commits.
If tracked or untracked changes are present, tell the user they are not part of the PR and ask whether to commit them first. Continue only after the user commits them or explicitly chooses to exclude them.
Determine the upstream with:
bash
```
git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'
```
- With no upstream, run
```
git push -u origin <branch>
```
  .
- With an upstream, compute
```
git rev-list --left-right --count <upstream>...HEAD
```
  . If the left count is nonzero, stop and report that the local branch must be synchronized; do not merge, rebase, or force-push implicitly. If only the right count is nonzero, run
```
git push
```
  .
- If a push fails, show the error and stop. Never retry with
```
--force
```
  .

在撰写内容前，先阅读适用的仓库指导规范及任何拉取请求模板。
检查当前分支和工作区：
bash
```
git branch --show-current
git status --short --branch
git symbolic-ref --quiet --short refs/remotes/origin/HEAD
```
仅将symbolic-ref的结果作为新建PR的备选基准分支。通过移除开头的
```
origin/
```
来提取分支名称；在完成下方的PR查找前，不要选择对比引用。
使用
```
git fetch --prune origin
```
刷新远程引用。若拉取失败，显示错误并终止操作；不要基于过时的远程状态做出发布决策。
查找针对当前头部分支的开放PR：
bash
```
gh pr list --head <branch> --state open --limit 1 \
  --json number,title,url,body,isDraft,baseRefName,headRefName
```
若命令执行失败，显示错误并终止操作。保存结果供后续使用；空数组表示需要创建PR，单个结果表示需要更新PR。
仅在完成上述查找后选择有效的基准分支：
- 对于现有PR，使用其
```
baseRefName
```
  。若用户明确要求使用不同的基准分支，需终止操作并进行确认，而非静默对比任意分支。
- 对于新建PR，若用户指定了基准分支则使用该分支；否则使用远程默认分支。若两者都不可用，终止操作并询问用户基准分支。
将提供的
```
origin/<base>
```
标准化：仅移除开头的
```
origin/
```
，然后将
```
<comparison-ref>
```
设置为
```
origin/<base>
```
。验证该引用在拉取后是否存在。若当前分支与有效基准分支相同，或
```
git log <comparison-ref>..HEAD --oneline
```
无提交记录，则终止操作。
若存在已跟踪或未跟踪的变更，告知用户这些变更不会包含在PR中，并询问是否需要先提交。仅在用户提交变更或明确选择排除后，才可继续操作。
通过以下命令确定上游分支：
bash
```
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. Build the PR Model

2. 构建PR模型

Using the saved PR lookup and the effective

<comparison-ref>

selected above, inspect every PR commit and the complete PR diff:

bash

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

Treat these outputs as the exclusive PR change set when selecting body depth, composing claims, checking change coverage, and reporting commit and file counts. Throughout the remaining steps, “branch commits” means exactly the commits returned by

git log <comparison-ref>..HEAD

. A commit reachable from

<comparison-ref>

is base history, not a PR change, even when it is absent from the remote default branch; do not include its behavior in the body.

Use commit history as evidence, not as the narrative structure. Synthesize the final behavior across commits, ignoring intermediate states that the complete PR diff supersedes. Before drafting, separate each material workflow or component and map its evidenced actor, trigger, input and time scope, state or output, downstream handoffs and failure behavior, and rollout or migration ordering, as applicable. Check internally that every material branch change is covered, but do not expose that coverage as a chronological commit list.

From the retained evidence, identify the primary before-and-after behavior. Include a reason, semantic explanation, impact, constraint, tradeoff, or risk only when the evidence supports that exact connection; omit it rather than infer it from related changes. Use the saved empty lookup result to create, or its single result to update.

使用保存的PR查找结果及上述选择的有效

<comparison-ref>

，检查每个PR提交及完整的PR差异：

bash

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. Compose Grounded Content

3. 撰写有依据的内容

Title for a new PR

新建PR的标题

Start with a concise imperative English verb and name the core behavior.
Keep the title at most 40 characters, excluding a ticket prefix.
If the branch contains an identifier matching letters or alphanumerics followed by a hyphen and digits, uppercase it and prepend it in brackets. For example,
```
feature/proj-42-fix-layout
```
becomes
```
[PROJ-42] Fix layout
```
.
Do not change the title of an existing PR.

以简洁的英文祈使动词开头，并点明核心行为。
标题长度最多40字符，不含工单前缀。
若分支名称包含字母或字母数字组合后接连字符和数字的标识符，将其大写并放在方括号中前置。例如，
```
feature/proj-42-fix-layout
```
变为
```
[PROJ-42] Fix layout
```
。
不要修改现有PR的标题。

Body depth

正文详细程度

Count commits and changed files, then use the more detailed level when the two measures disagree:

Level	Threshold	Generated sections
Simple	1-2 commits and at most 3 files	Summary, Changes
Standard	3-10 commits or 4-10 files	Summary, Key Changes, Validation
Complex	11+ commits or 11+ files	Summary, themed Key Changes, Validation, Review Notes

Keep the body proportional even when a repository template adds required sections. Apply these content rules:

Lead with the behavioral before-and-after model and why it matters.
State the single core intuition that explains most of the PR, then group supporting changes by behavior or reviewer concern. When material workflows do not share one evidenced reason or outcome, keep their before-and-after explanations distinct instead of forcing an umbrella narrative. Do not organize the body by commit order, narrate files, or restate every diff hunk.
Omit secondary and mechanical edits from
```
Summary
```
and
```
Key Changes
```
unless they alter the mental model or require reviewer action. Report test commands and results in
```
Validation
```
instead of listing routine test implementation as a key change.
Use one minimal toy example when concrete input, state, or output makes a non-obvious rule faster to understand. For example:
```
Requests r1, r1, r2 used to create three jobs; they now create two because request ID defines identity.
```
Keep the behavior faithful to the diff, and do not force an example when prose is clearer.
Omit commit hashes and a commit-by-commit log unless the user or a repository template explicitly requires them.
Report validation only when supported by evidence. Attribute results reported only in commit history, and do not present changed tests or static inspection as passing execution results. Name any material runtime, integration, deployment, migration, or external-service boundaries the reported checks did not exercise. When a required validation section has no evidence of executed checks, state the language-equivalent of
```
Not run
```
; never guess.
Include migration notes, risks, or reviewer guidance only when the diff supports them.

Wrap only generated content in these exact ownership markers:

markdown

<!-- pr-skill:start -->
<generated sections>
<!-- pr-skill:end -->

When updating:

If both markers exist once and in order, replace only the marked block and preserve all text outside it byte-for-byte.
If the body has no markers, preserve the entire existing body byte-for-byte and append one marked generated block.
If markers are malformed, duplicated, or out of order, stop and ask the user how to proceed. Do not risk deleting authored content.

Add

--draft

when creating if the user requested a draft or the branch starts with

draft/

wip/

. Updating the body must preserve the existing draft state.

统计提交次数和变更文件数，若两个指标不一致，采用更详细的级别：

级别	阈值	生成的章节
简单	1-2次提交且最多3个文件	摘要、变更内容
标准	3-10次提交或4-10个文件	摘要、关键变更、验证
复杂	11+次提交或11+个文件	摘要、主题化关键变更、验证、评审说明

即使仓库模板添加了必填章节，也要保持正文比例协调。遵循以下内容规则：

以变更前后的行为模型及其重要性开篇。
先阐述解释PR大部分内容的核心逻辑，然后按行为或评审关注点分组整理配套变更。若关键工作流没有共同的可验证原因或结果，需保持各自的变更前后说明独立，不要强行构建统一叙事。不要按提交顺序组织正文、罗列文件或重述每个差异块。
除非次要和机械修改会改变认知模型或需要评审者采取行动，否则不要在“摘要”和“关键变更”中提及。在“验证”部分报告测试命令和结果，不要将常规测试实现列为关键变更。
当具体的输入、状态或输出能让非直观规则更易理解时，使用一个极简的示例。例如：
```
请求r1、r1、r2过去会创建3个任务；现在会创建2个，因为请求ID定义了唯一性。
```
确保示例行为与差异一致，若文字说明更清晰则无需强行添加示例。
除非用户或仓库模板明确要求，否则省略提交哈希和逐提交日志。
仅当有证据支持时才报告验证结果。仅在提交历史中报告结果，不要将变更后的测试或静态检查作为已通过的执行结果呈现。列出已报告的检查未覆盖的任何关键运行时、集成、部署、迁移或外部服务边界。若必填的验证章节没有已执行检查的证据，需说明“未执行”；切勿猜测。
仅当差异支持时，才包含迁移说明、风险或评审指导。

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

markdown

<!-- pr-skill:start -->
<generated sections>
<!-- pr-skill:end -->

更新PR时：

若标记存在且顺序正确，仅替换标记内的块，并逐字节保留标记外的所有文本。
若正文无标记，逐字节保留整个现有正文，并追加一个带标记的生成块。
若标记格式错误、重复或顺序颠倒，终止操作并询问用户如何处理。不要冒险删除用户撰写的内容。

创建PR时，若用户要求草稿模式，或分支以

draft/

或

wip/

开头，添加

--draft

参数。更新正文时必须保留现有草稿状态。

4. Verify, Execute, and Confirm

4. 验证、执行与确认

Before any

gh pr create

gh pr edit

, verify that:

The create title satisfies the language, length, verb, and ticket rules.
The body matches the chosen depth, leads with the core intuition, and covers every material branch change without relying on a chronological commit list.
Every factual claim is grounded in the inspected diff, history, guidance, or template.
Existing content outside the ownership markers is unchanged.

Pass the body through standard input so shell interpolation cannot alter it:

bash

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

Do not include the bracketed optional flag literally; either add

--draft

or omit it. After success, run

gh pr view <number-or-url> --json number,title,url,body,isDraft,commits,files

and verify the published title, body, draft state, commit count, and file count. If creation, update, or verification fails, show the error and stop without claiming success.

Report the PR number and title, URL, created or updated status, draft state, commit count, and changed-file count.

在执行任何

gh pr create

或

gh pr edit

命令前，验证：

新建PR的标题符合语言、长度、动词及工单规则。
正文符合所选的详细程度，以核心逻辑开篇，覆盖所有关键分支变更且不依赖按时间顺序的提交列表。
所有事实声明都基于已检查的差异、历史、指导规范或模板。
所有权标记外的现有内容未被修改。

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

bash

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、创建/更新状态、草稿状态、提交次数及变更文件数。