pr-description

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Description Generator

PR描述生成器

Help the user turn the work on their current branch into a clean PR subject and a concise description they can paste into GitHub. The job is to read the branch's commits and code changes, understand the intent behind them, and express that clearly for a reviewer.

This skill is read-only with respect to git and GitHub: it inspects history and prints a result. It does not commit, push, or create/update any PR.

帮助用户将当前分支的工作内容转化为清晰的PR 标题和简洁描述，以便粘贴到GitHub中。该工具会读取分支的提交记录和代码变更，理解背后的意图，并清晰地表达出来供评审人员查看。

此技能对git和GitHub仅具有只读权限：它仅检查历史记录并输出结果，不会执行提交、推送或创建/更新任何PR的操作。

Workflow

工作流程

1. Confirm you're in a usable repo

1. 确认处于可用的仓库中

Check that the working directory is a git repository and the current branch has commits. If

git rev-parse --is-inside-work-tree

fails, tell the user this isn't a git repo and stop. Note the current branch name with

git rev-parse --abbrev-ref HEAD

检查当前工作目录是否为git仓库，且当前分支存在提交记录。如果

git rev-parse --is-inside-work-tree

命令执行失败，告知用户当前目录不是git仓库并停止操作。使用

git rev-parse --abbrev-ref HEAD

命令获取当前分支名称。

2. Work out what to compare against, then confirm with the user

2. 确定对比基准，然后与用户确认

The description should cover only the commits unique to this branch, so you need the base branch it will merge into. Detect a sensible default rather than asking cold:

Try the remote's default branch:
```
git symbolic-ref refs/remotes/origin/HEAD
```
(gives something like
```
origin/main
```
).
If that isn't set, fall back to whichever of
```
origin/main
```
or
```
origin/master
```
exists (
```
git rev-parse --verify
```
). If neither exists, fall back to local
```
main
```
/
```
master
```
.
Compute the merge base so you compare from where the branch diverged:
```
git merge-base <base> HEAD
```
.

Then count the commits with

git rev-list --count <merge-base>..HEAD

and tell the user what you're about to do, and ask them to confirm before generating. For example:

I'll compare
feature/login-rework
against
origin/main
(5 commits since they diverged). Sound right, or do you want a different base branch?

This confirmation matters because guessing the wrong base produces a description that's either missing changes or padded with unrelated ones — and the user knows their branching model better than any heuristic does. If they give a different base, recompute the merge base from it. Only proceed once they're happy.

描述内容应仅涵盖当前分支独有的提交记录，因此需要确定它将合并到的基准分支。自动检测合理的默认基准，而非直接询问用户：

尝试获取远程仓库的默认分支：
```
git symbolic-ref refs/remotes/origin/HEAD
```
（返回结果类似
```
origin/main
```
）。
如果该命令未返回结果，退而求其次，检查
```
origin/main
```
或
```
origin/master
```
是否存在（使用
```
git rev-parse --verify
```
命令）。如果两者都不存在，则使用本地的
```
main
```
/
```
master
```
分支。
计算合并基准，以便从分支分叉的位置开始对比：
```
git merge-base <base> HEAD
```
。

然后使用

git rev-list --count <merge-base>..HEAD

命令统计提交数量，并告知用户即将执行的操作，请求用户确认后再生成描述。例如：

我将对比
feature/login-rework
与
origin/main
分支（两者分叉后已有5次提交）。是否正确？或者你想要使用其他基准分支？

确认步骤至关重要，因为如果基准猜测错误，生成的描述要么遗漏变更内容，要么包含无关内容——而用户比任何启发式规则都更了解自己的分支模型。如果用户指定了其他基准分支，重新计算合并基准。只有在用户确认无误后才继续执行。

3. Gather the material

3. 收集素材

With the confirmed base (use the merge base as

<from>

), collect both signals:

Commit messages — the author's own narration of intent:
```
git log <from>..HEAD --pretty=format:'%h %s%n%b'
```
A map of what changed —
```
git diff <from>...HEAD --stat
```
The actual diff —
```
git diff <from>...HEAD
```

Use commits and diff together. Commit messages tell you why; the diff tells you what actually changed and catches things the messages glossed over or omitted. If the diff is very large, lean on

--stat

plus reading the most significant hunks rather than dumping everything — you need enough to summarize accurately, not every line.

在确认基准后（使用合并基准作为

<from>

），收集两类信息：

提交信息——作者对变更意图的自述：
```
git log <from>..HEAD --pretty=format:'%h %s%n%b'
```
变更映射——
```
git diff <from>...HEAD --stat
```
实际diff内容——
```
git diff <from>...HEAD
```

同时使用提交信息和diff内容。提交信息告诉你变更的原因；diff内容告诉你实际发生了哪些变更，并能捕捉到提交信息中忽略或遗漏的内容。如果diff内容非常庞大，优先参考

--stat

输出并读取最重要的代码块，而非全部内容——你需要足够的信息来准确总结，而非每一行内容。

4. Write the subject and description

4. 撰写标题和描述

Subject — a single plain imperative line, like a good commit summary: "Add JWT-based login flow", "Fix race condition in cache eviction". No type prefixes (no

feat:

fix:

), no trailing period, roughly 50–70 characters. It should tell a reviewer the gist at a glance.

Description — keep it concise and narrative:

One short paragraph (2–4 sentences) explaining what the change accomplishes and why, at a level a reviewer skims before diving into the diff.
A short bulleted list of the key changes — the things worth a reviewer's attention. Group related edits into one bullet rather than mirroring the commit list one-for-one. Skip noise (formatting-only churn, generated files) unless it matters.

Aim for signal over completeness. A reviewer should finish the description knowing what to look for, not re-reading the whole diff in prose.

标题——单行祈使句，类似优秀的提交总结： "Add JWT-based login flow"、"Fix race condition in cache eviction"。不要添加类型前缀（如

feat:

fix:

），不要加结尾句号，长度约50-70字符。标题应让评审人员一眼就能了解核心内容。

描述——保持简洁且具有叙事性：

用一段简短的段落（2-4句话）解释变更实现的目标和原因，达到评审人员在查看diff前快速浏览就能理解的程度。
用简短的项目符号列表列出关键变更——值得评审人员关注的内容。将相关编辑归为一个项目符号，而非逐一对应提交记录。除非有必要，否则忽略无意义的内容（仅格式变更、生成文件等）。

优先传递关键信息而非追求全面性。评审人员看完描述后应知道需要关注哪些内容，而非在 prose 中重新阅读整个diff。

5. Output

5. 输出

Print the result in a copy-friendly block so the user can lift it straight into GitHub:

Subject:
<the subject line>

Description:
<summary paragraph>

- <key change>
- <key change>
- <key change>

Then it's the user's to paste wherever they like.

以方便复制的格式打印结果，让用户可以直接复制到GitHub中：

Subject:
<the subject line>

Description:
<summary paragraph>

- <key change>
- <key change>
- <key change>

之后用户可将其粘贴到任意需要的地方。

Example

示例

For a branch that adds rate limiting to an API:

Subject:
Add per-client rate limiting to the public API

Description:
Introduces a sliding-window rate limiter on all /api/v1 endpoints to protect
against abuse from individual clients. Limits are configurable per route and
return a 429 with a Retry-After header when exceeded.

- Add RateLimiter middleware backed by Redis sliding-window counters
- Wire configurable per-route limits into the API gateway config
- Return 429 + Retry-After on limit breach, with tests covering the boundary

针对为API添加速率限制的分支：

Subject:
Add per-client rate limiting to the public API

Description:
Introduces a sliding-window rate limiter on all /api/v1 endpoints to protect
against abuse from individual clients. Limits are configurable per route and
return a 429 with a Retry-After header when exceeded.

- Add RateLimiter middleware backed by Redis sliding-window counters
- Wire configurable per-route limits into the API gateway config
- Return 429 + Retry-After on limit breach, with tests covering the boundary