PR Pilot — PR 提交与生命周期管理

概述

提交专业级的 Pull Request，并全程管理其评审生命周期，直至合并（或关闭）。涵盖 PR 创建、CI 状态监控、评审响应、迭代更新及进度跟踪等环节。

适用场景：开源项目贡献、团队代码评审、跨仓库 PR 管理，以及任何代码提交工作流。

前提条件

必须完成 GitHub CLI 认证 —— PR 创建、评审状态监控和评论发布均依赖该认证：

gh auth status   # 输出中必须显示 "Logged in"

若尚未配置，请提示用户提供以下信息：

1. GitHub 用户名 — 用于 --head {username}:{branch} 参数及 PR 搜索
2. GitHub Token — 运行 gh auth login 或设置 export GH_TOKEN=

Token 是以下操作所必需的：创建 PR、发布评论、检查评审状态、推送迭代变更。

第一部分：提交 PR

步骤 1：暂存与提交（如尚未执行）

# 仅暂存指定文件 — 切勿使用 git add .
git add {specific files}
git diff --cached --stat   # 验证暂存内容

# 使用约定式提交信息进行提交
git commit -m "{type}({scope}): {description}"

步骤 2：推送到远程仓库

git push origin {branch-name}

# 若为新建分支：
git push -u origin {branch-name}

步骤 3：撰写 PR 描述

请使用如下结构化模板。根据 PR 类型与范围调整各部分内容。

## 概述

{用 1–2 句话简述本 PR 的功能及其目的}

Closes #{issue_number}.

## 问题

{被修复的 Bug/问题描述：}
- 用户实际遇到的现象
- 根本原因分析
- 影响范围 / 严重程度

## 解决方案

{技术实现方式说明：}
- 架构 / 设计决策
- 引入的关键抽象（如有）
- 为何选择该方案而非其他替代方案

## 变更列表

| 文件 | 变更类型 |
|------|----------|
| `path/to/file.py` | **New** — 描述 |
| `path/to/other.py` | Modified — 描述 |
| `tests/test_file.py` | **New** — 为该功能新增 N 个测试 |

## 测试

{粘贴测试输出}
N passed in X.XXs

{说明测试覆盖范围：}
- … 的单元测试
- 覆盖的边界情况：...

## 向后兼容性

- 无破坏性变更 / 在 … 中存在破坏性变更

按 PR 类型适配描述重点

步骤 4：创建 PR

# 将 PR 描述保存至临时文件
cat > /tmp/pr_body.md << 'EOF'
{pr description}
EOF

# 创建 PR
gh pr create 
    --repo {owner}/{repo} 
    --head {username}:{branch} 
    --base {default-branch} 
    --title "{type}({scope}): {description}" 
    --body-file /tmp/pr_body.md

步骤 5：验证

# 检查 PR 是否成功创建
gh pr view {number} --repo {owner}/{repo} --json url,state,statusCheckRollup

# 验证 CI 是否已启动运行
gh pr checks {number} --repo {owner}/{repo}

PR 描述质量检查清单

• 关联待修复的问题（含 Closes #N）
• 阐明根本原因，而非仅描述表象
• 描述解决方案思路与设计决策
• 包含测试结果
• 含文件变更汇总表格
• 说明向后兼容性影响

第二部分：管理 PR 生命周期

2a. 监控 PR 状态

定期检查 PR 状态：

# 单个 PR
gh pr view {number} --repo {owner}/{repo} 
    --json state,reviews,comments,mergeable,statusCheckRollup

# 查看您所有已开启的 PR
gh search prs --author={username} --state=open 
    --json repository,number,title,url,updatedAt

2b. 响应评审意见

当评审者给出反馈时，请分类并针对性响应：

模式 1：可操作的代码修复

评审者：“此处应处理 null 情况” / “请为 X 添加错误处理”

操作：修复代码 → 补充测试 → 推送 → 回复。

发现得很及时 —— 已在 {commit_sha} 中修复。新增了 null 检查及对应测试用例。

模式 2：架构层面的疑虑

评审者：“该方案存在根本性缺陷，因为……”

操作：若确属根本性问题，应考虑整体重构。

您完全正确 —— {明确指出具体关切点}。我已在 #{new_pr_number} 中对该方案进行了重构：

{新方案的简要说明}

本 PR 将关闭，后续以新方案为准。

重大重构操作步骤：

1. 从 upstream 创建新分支
2. 采用新方案重新实现
3. 创建新 PR 并引用旧 PR
4. 关闭旧 PR，评论中注明新 PR 链接
5. 在新 PR 下回复原评审者

模式 3：风格 / 规范类细节建议

评审者：“此处我们使用 camelCase” / “请补充 docstring”

操作：快速修复 → 推送 → 回复。

已在 {commit_sha} 中修正，感谢指出规范要求。

模式 4：提问 / 澄清请求

评审者：“为何选择 X 而非 Y？”

操作：清晰解释；若对方提出更优方案，则采纳之。

{直接回答}。{说明权衡取舍}。

模式 5：补充测试请求

评审者：“能否为 …… 这一边界情况添加测试？”

操作：编写测试 → 验证通过 → 推送 → 回复。

已在 {commit_sha} 中添加。新测试覆盖：
- {场景 1}
- {场景 2}

迭代工作流

cd ~/prs/{repo}
git checkout {branch}
git pull origin {branch}

# 根据评审意见修改代码
# ...

# 运行测试
python -m pytest --tb=short

# 提交并推送
git add {files}
git commit -m "address review: {description}"
git push origin {branch}

2c. 处理 CI 失败

gh pr checks {number} --repo {owner}/{repo}

2d. 进度跟踪

对于多 PR 协同管理，请维护 {workspace}/pr-tracker.md：

# PR Campaign Tracker

> 最后更新时间：{date}

| # | 仓库 | PR | 标题 | 状态 | Issue |
|---|------|-----|------|------|-------|
| 1 | owner/repo | [#N](url) | fix(x): desc | 🟢 Open | #N |
| 2 | ... | ... | ... | 🟣 Merged | #N |

状态图标说明：

• 🟢 Open — 等待评审
• 🟡 Changes Requested — 需要迭代
• 🔵 Approved — 已获批准，可合并
• 🟣 Merged
• 🔴 Closed (not merged)

每次 PR 发生关键事件（创建、收到评审、迭代、合并、关闭）后，请同步更新 tracker。

评审响应原则

1. 逐条回复每条评论 — 即使仅回复 “Done” 或 “Good point, fixed”
2. 首次回应一轮评审时致谢评审者
3. 不争辩 — 仅解释一次，之后尊重维护者决定
4. 表述具体 — 引用具体 commit、行号、测试名称等
5. 及时响应 — 建议在 24–48 小时内回复，以保持推进节奏
6. 若方案发生重大变更，请同步更新 PR 描述

输出物

• PR URL 及已验证的 CI 状态
• 评审响应记录与迭代历史
• 更新后的 pr-tracker.md

提示

• 在开发流水线中，本流程紧随 dev-test 阶段之后，是最终交付步骤。
• 若需管理多个 PR，建议定期运行状态检查（或配置自动化任务）。
• 面对架构层面的评审意见时，新建 PR（而非强制推送重写）可保留清晰的评审历史，降低评审者理解成本。
• 推送评审迭代前，务必先在本地运行完整测试。