pr

PR

创建、更新和管理拉取请求，并自动生成描述。

操作路由

操作可以组合执行。如果用户在提出创建／更新意图的同时提供了审阅者、标签或其他元数据，则在需要时先创建 PR，再应用这些操作。

用户输入	操作
/pr（无文本）	创建或更新 PR（网页界面）
/pr this fixes the timeout bug	同上，并为描述添加上下文
/pr against release/v2.x	针对指定的基础分支创建 PR
/pr close	gh pr close --delete-branch
/pr merge	gh pr merge --squash --delete-branch
/pr checks	gh pr checks
/pr status	gh pr view
/pr reviewers alice bob	如有需要则创建 PR，然后添加审阅者
/pr labels bug fix	如有需要则创建 PR，然后添加标签
/pr web	gh pr view --web
/pr update	推送并重新生成描述
/pr rebase	gh pr update-branch
/pr context info, reviewers: alice, bob	根据上下文创建 PR，然后添加审阅者
/pr only swift files	将差异限制为匹配的路径
/pr ignore tests	从差异中排除匹配的路径
/pr publish / /pr commit and push	自动提交未暂存的更改，然后推送

如果意图不明确，请提问。

路径筛选器

用户可以使用包含／排除 glob 模式限定差异范围。将自然语言（“仅 swift”“忽略生成文件”）转换为 git 路径规范：

• 包含 → *<pattern>（例如，*.swift）
• 排除 → :!*<pattern>（例如，:!*_test.go）

在步骤 1 中每次调用 git diff／git log 时，都在 -- 分隔符后追加这些模式。在步骤 2 的摘要中说明当前启用的筛选器，以便用户确认。

核心工作流（创建／更新）

步骤 1 — 收集上下文

并行运行以下操作：

检测基础分支（按顺序进行，匹配后即停止）：

1. 用户输入中指定的基础分支
2. 现有 PR 的基础分支（更新时）
3. Git 历史记录 — 使用 git symbolic-ref refs/remotes/origin/HEAD 获取远程默认分支，或使用 git config init.defaultBranch
4. 最后备选方案：gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

然后计算合并基点：git merge-base HEAD <detected-base>

差异和日志：

git diff --stat <base>...HEAD
git log --oneline <base>..HEAD

检测现有 PR：

gh pr list --head "$(git branch --show-current)" --state open --json number,url,title,isDraft,body,baseRefName --jq '.[0]'

这也会获取现有描述和基础分支。

其他上下文：

• 分支名称 → 提取匹配 (?:^|[/_-])([A-Z]{3,}[A-Z0-9_]*-\d+) 的工单 ID。去重、排序，并以 , 连接。
• 仓库模板检测（采用首个匹配项）：
  1. .github/pull_request_template.md
  2. .github/PULL_REQUEST_TEMPLATE/（目录 — 选择最相关的文件）
  3. .gitlab/pull_request_template.md
  4. .gitlab/merge_request_templates/（目录）
• 工作区状态 → 使用 git status --porcelain 检测未提交／未推送的更改（在步骤 2 中说明）。

步骤 2 — 总结并确认

执行前先打印摘要：

• 提交： N 个提交，N 个文件已更改，+N/-N 行
• 工单： PROJ-123（或“未检测到”）
• 模板： 仓库模板 / 默认 / 精简（以及原因——见下方的自动选择）
• 筛选条件： include=*.swift，exclude=*_test.go（如果没有则省略此行）
• 操作： 针对 <base> 创建新 PR，或更新 PR #42
• 分支： 已推送 / 需要推送 / N 个未提交的文件 / 领先远程 N 个提交

如果有未提交或未推送的更改，请明确指出并列出文件（最多约 10 个）。询问用户是要：

1. 停止操作，由用户手动处理，还是
2. 自动提交并推送（仅当用户已说过 /pr publish 或类似指令，或现在确认时）。

然后询问：“继续吗？”

步骤 3 — 生成描述

撰写规则

• 原样遵循用户提供的任何上下文。
• 只关注重要更改。忽略注释、格式调整、年份更新和拼写错误。
• 一个 PR 可能包含多个问题——按重要性加权描述所有问题。
• 使用专业但清晰的语言。句子简短，优先使用项目符号。
• 不要逐行分析——只做高层级描述。
• 绝不偏离模板结构。
• 如果差异内容含糊，使用提交消息了解意图和上下文。
• 标题：简洁，5–10 个词，不超过 72 个字符。
• 不要啰嗦。

模板选择（按优先级排序）

1. 明确指定——用户提出了类似“使用精简模板”/“使用默认模板”/“使用仓库模板”的要求。

2. 按更改重要性自动分类（没有明确指定时的默认方式）：

   • 精简——拼写错误修复、格式调整、注释、小型单行错误修复（少于约 20 行，涉及 1–2 个文件）。
   • 默认（内置）——重构、依赖项升级、中等规模的错误修复。
   • 检测到的模板——步骤 1 中发现的仓库模板，用于重大更改、新功能和破坏性更改。

   根据差异和提交消息判断重要性。在步骤 2 的摘要中说明所选模板及原因。

3. 回退方案——内置 assets/default-template.md。

内置模板位于 assets/default-template.md 和 assets/minimal-template.md。

标题

• 生成简洁的标题（5–10 个词），概括主要更改。
• 如果在分支名称中找到工单 ID，则在标题前添加工单 ID： PROJ-123: <title>（多个工单时使用 PROJ-123,PROJ-456: <title>）。仅当未检测到工单时才省略前缀。
• 更新现有 PR 时，保留现有标题，除非用户要求重新生成。

正文

• 关注原因，而非内容。
• 按领域归类更改。
• 明确标注破坏性更改。
• 从输出中移除所有 `` 注释。

**更新时：**始终先阅读现有 PR 描述（在步骤 1 中获取）。保留用户添加的上下文、备注或章节。仅移除与当前差异明显无关的内容（例如，描述已不存在的文件或更改）。根据当前差异重新生成自动生成的部分。

**大型差异（超过 500 行）：**先使用 --stat，再选择性阅读最相关文件的差异，其余内容根据统计输出进行总结。

步骤 4 — 执行

1. 自动提交（如有请求） — 用户选择发布时：
   • 仅暂存相关文件（避免使用通用命令 git add -A；切勿暂存 .env、凭据或大型二进制文件）。
   • 根据已暂存的差异生成简短的 Conventional Commits 风格提交消息（feat:、fix:、docs: 等），长度不超过 72 个字符。
   • 提交，然后继续。
2. 如有需要，推送分支：git push -u origin HEAD
3. 创建或更新：
   • 新 PR： gh pr create --web — 仅打开浏览器。不要向 gh pr create 传入 --title 或 --body；这些标志会通过 CLI 创建 PR。将生成的标题和正文打印到控制台，供用户粘贴到浏览器中。只有用户明确要求通过 CLI 创建时，才使用 gh pr create --title "..." --body "..."
   • 现有 PR： gh pr edit --title "..." --body "..."
4. 应用用户输入中包含的组合操作（审阅者、标签）

**审阅者：**添加前，通过 gh api 检查其是否可用：

gh api repos/{owner}/{repo}/collaborators --jq '.[].login'

如果请求的审阅者不是协作者，请发出警告。

故障排除

• **未通过 gh 验证：**运行 gh auth login
• **处于分离 HEAD 状态：**先切换到一个分支
• 没有上游远程仓库：git remote add origin <url>
• **推送被拒绝：**可能需要变基——建议运行 git pull --rebase origin <base>