cmd-pr-description

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quick PR Description

快速PR描述生成

Generate a concise PR description by analyzing the diff against a base branch.

Output the result in a markdown file named

PR_DESCRIPTION.md

Copy to clipboard:

cat PR_DESCRIPTION.md | pbcopy

Instructions
Output Format
Section Rules
Example Output

通过分析与基准分支的差异生成简洁的PR描述。

将结果输出到名为

PR_DESCRIPTION.md

的markdown文件中。

复制到剪贴板：

cat PR_DESCRIPTION.md | pbcopy

使用说明
输出格式
章节规则
示例输出

Instructions

使用说明

1. Determine the base branch

1. 确定基准分支

First, determine the base branch using the repository's default branch.

Try these methods in order until one succeeds:

Method 1 - GitHub CLI

bash

BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null)

Method 2 - Git remote

bash

BASE_BRANCH=$(git remote show origin 2>/dev/null | grep "HEAD branch" | cut -d: -f2 | xargs)

Method 3 - Git symbolic-ref

bash

BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

IMPORTANT: Do NOT assume

master

main

as a fallback. If all methods fail, ask the user which branch to use as the base.

首先，使用仓库的默认分支确定基准分支。

按顺序尝试以下方法，直到成功获取为止：

方法1 - GitHub CLI

bash

BASE_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null)

方法2 - Git remote

bash

BASE_BRANCH=$(git remote show origin 2>/dev/null | grep "HEAD branch" | cut -d: -f2 | xargs)

方法3 - Git symbolic-ref

bash

BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

重要提示： 不要默认假设使用

master

或

main

作为回退分支。如果所有方法都失败，请询问用户要使用哪个分支作为基准。

2. Analyze the changes against the default branch

2. 分析与默认分支的差异

bash

git diff $BASE_BRANCH --stat -- ":(exclude)*.lock" ":(exclude)package-lock.json" ":(exclude)pnpm-lock.yaml" ":(exclude)package.json"
git log $BASE_BRANCH..HEAD --oneline

bash

git diff $BASE_BRANCH --stat -- ":(exclude)*.lock" ":(exclude)package-lock.json" ":(exclude)pnpm-lock.yaml" ":(exclude)package.json"
git log $BASE_BRANCH..HEAD --oneline

3. Generate the description using the format below

3. 使用下方格式生成描述

4. Offer to update the GitHub PR

4. 提供更新GitHub PR的选项

After writing

PR_DESCRIPTION.md

, use

AskUserQuestion

to ask the user if they want to update the GitHub PR description automatically.

If yes, run:

bash

gh pr edit --body "$(cat PR_DESCRIPTION.md)"

写入

PR_DESCRIPTION.md

后，使用

AskUserQuestion

询问用户是否要自动更新GitHub PR描述。

如果用户选择是，运行：

bash

gh pr edit --body "$(cat PR_DESCRIPTION.md)"

Output Format

输出格式

markdown

_tl;dr This is a single sentence summarizing the most important outcome of this PR in 100-200 characters._

markdown

_tl;dr 用100-200字符的单句话总结本次PR最重要的变更结果。_

Summary

概述

Subject/topic: < 100 character explanation
...
...

主题: 不超过100字符的说明
...
...

Feature Diff

功能差异

Component	Before	After
1-3 words describing the component	1 sentence describing how it worked before	1 sentence describing how it works after
...	...	...
...	...	...

组件	之前的状态	之后的状态
用1-3个词描述变更的组件	一句话描述之前的运行逻辑	一句话描述现在的运行逻辑
...	...	...
...	...	...

Details

详细信息

<details> <summary>Technical Details</summary>

Subsection Title

子章节标题

Subject/topic: < 100 character explanation
...

主题: 不超过100字符的说明
...

Another Subsection

其他子章节

Subject/topic: < 100 character explanation
...

</details> ```

主题: 不超过100字符的说明
...

</details> ```

Section Rules

章节规则

tl;dr

Single sentence, max ~120 characters
Product-level: what does the user/operator/developer get?
No implementation details, no file names

单句，最多约120字符
产品层面描述：说明用户/运营/开发者能获得什么收益
不要包含实现细节、文件名

Summary

概述

2-5 bullets, one per meaningful change (not per file)
Min (2) and max (5) are hard floors and ceilings per section
Bold phrase answers "what does the user/operator get?"
Plain language after the dash: one sentence, no jargon
No implementation details: reviewers will read the diff for that
No fluff: skip "minor cleanup", "refactor", "update docs" unless they deliver real value
Start from the most impactful change and work down

2-5个要点，每个要点对应一项有意义的变更（不是每个文件对应一个要点）
数量严格控制在2到5个之间
加粗的短语需要回答「用户/运营能获得什么？」这个问题
破折号后使用平实语言：单句描述，无专业行话
不要包含实现细节：评审人员会通过diff查看具体实现
不要冗余内容：跳过「小型清理」、「重构」、「更新文档」这类描述，除非它们能带来实际价值
按变更影响从大到小排序

Feature Diff

功能差异

Always include this section
Should have anywhere from 1-10 rows depending on the size of the PR
One row per component, module, config, API, or behavior that changed
"Component" = the thing that changed (endpoint, table, config key, module, behavior, etc.)
"Before" = previous state, or
```
N/A
```
if new
"After" = new state, or
```
Removed
```
if deleted
Keep cells concise — short phrases, not sentences
Group related rows; aim for 3-10 rows
Good component examples: API endpoint, DB table/column, config key, env var, dependency version, CLI flag, permission, error behavior

必须包含该章节
根据PR大小设置1-10行内容
每个变更的组件、模块、配置、API或行为单独占一行
「组件」= 发生变更的对象（端点、数据表、配置键、模块、行为等）
「之前」= 变更前的状态，如果是新增功能则填
```
N/A
```
「之后」= 变更后的状态，如果是删除功能则填
```
Removed
```
保持单元格内容简洁——使用短短语，不要长句子
将相关行分组；尽量保持3-10行的数量
优质组件示例：API端点、数据库表/列、配置键、环境变量、依赖版本、CLI参数、权限、错误处理逻辑

Details

详细信息

Only include for larger PRs (5+ files changed or multiple logical groups)
Use collapsible
```
<details>
```
tags
Group by feature/concern, not by file
This is where implementation specifics go (file names, function names, migration details)
Use backticks for code references (
```
file.py
```
,
```
get_user()
```
,
```
/api/v1/users
```
)
1-3 subsections, each with 3-5 bullets

仅针对大型PR包含该章节（变更5个以上文件或包含多个逻辑变更组）
使用可折叠的
```
<details>
```
标签
按功能/关注点分组，不要按文件分组
该章节用于存放实现细节（文件名、函数名、迁移细节等）
代码引用使用反引号包裹（
```
file.py
```
、
```
get_user()
```
、
```
/api/v1/users
```
）
1-3个子章节，每个子章节包含3-5个要点

General Details

通用规则

Use backticks for code references (
```
file.py
```
,
```
get_user()
```
,
```
/api/v1/users
```
)
Italicize or bold keywords if it helps readability

代码引用使用反引号包裹（
```
file.py
```
、
```
get_user()
```
、
```
/api/v1/users
```
）
如果有助于提升可读性，可以将关键字设置为斜体或粗体

Example Output

示例输出

markdown

_tl;dr Users can now log in with email/password and stay authenticated across browser sessions._

markdown

_tl;dr 用户现在可以使用邮箱/密码登录，并且在多个浏览器会话中保持登录状态。_

Summary

概述

Session-based login: Users authenticate with email/password and maintain sessions across browser restarts
Faster auth checks: Session lookups use an indexed token column instead of scanning the full users table
Remember-me support: Users can opt into 30-day sessions instead of the default 24-hour expiry

基于会话的登录: 用户通过邮箱/密码完成身份验证，浏览器重启后仍能保持会话有效
更快的身份校验: 会话查找使用带索引的token列，无需扫描全量用户表
记住我支持: 用户可以选择30天有效期的会话，替代默认的24小时有效期

Feature Diff

功能差异

Component	Before	After
Auth method	API key only	Email/password + session cookie
Session duration	N/A	24 hours (default), 30 days (remember-me)
`sessions` table	N/A	New table with `user_id` , `token` , `expires_at`
Token lookup	Full table scan on `users`	Indexed lookup on `sessions.token`
`/auth/login`	N/A	New endpoint
`/auth/logout`	N/A	New endpoint

组件	之前的状态	之后的状态
身份验证方式	仅支持API密钥	邮箱/密码 + 会话cookie
会话有效期	N/A	24小时（默认），30天（记住我）
`sessions` 表	N/A	新增数据表，包含 `user_id` 、 `token` 、 `expires_at` 字段
Token查找	全表扫描 `users` 表	对 `sessions.token` 进行索引查找
`/auth/login`	N/A	新增端点
`/auth/logout`	N/A	新增端点

Details

详细信息

<details> <summary>Technical Details</summary>

Authentication Service

身份验证服务

New login service: Handles JWT issuance, session creation, and cookie management
Add
```
login_service.py
```
with session create/validate/revoke methods
Integrate
```
/auth/login
```
and
```
/auth/logout
```
endpoints in
```
routes/auth.py
```
Support
```
remember_me
```
flag to toggle 24h vs 30d expiry

新增登录服务: 处理JWT签发、会话创建和cookie管理
新增
```
login_service.py
```
文件，提供会话创建/验证/撤销方法
在
```
routes/auth.py
```
中集成
```
/auth/login
```
和
```
/auth/logout
```
端点
支持
```
remember_me
```
参数，切换24小时和30天的会话有效期

Database Schema

数据库Schema

New sessions table: Stores active sessions with automatic expiry
Add
```
sessions
```
table with
```
user_id
```
,
```
token
```
,
```
expires_at
```
columns
Add B-tree index on
```
token
```
for O(1) lookups
Add index on
```
expires_at
```
for cleanup job performance

</details> ```

新增会话表: 存储活跃会话，支持自动过期清理
新增
```
sessions
```
表，包含
```
user_id
```
、
```
token
```
、
```
expires_at
```
字段
为
```
token
```
字段添加B-tree索引，实现O(1)时间复杂度的查找
为
```
expires_at
```
字段添加索引，提升清理任务的运行性能

</details> ```