git-workflow

Git 工作流

PR 生命周期自动化。创建 PR → 监控 CI 和评审 → 修复 → 处理意见 → 推送 → 重复，直到全部通过。

要查看完整的 bun gh-tool 命令参考，请运行 bun gh-tool --help 或 bun gh-tool pr --help。本技能描述的是工作流，而非工具接口。

有关推送、创建分支和同步分支的操作方法，请参阅 references/push-branch-sync.md。

PR 工作流

触发条件：用户说“pr”“pull request”“create PR”“CI failed”“address review comments”“merge when green”或类似内容。

整个 PR 生命周期作为一个连续、积极主动的循环运行。没有单独的“修复意见”步骤——这属于同一个工作流。

阶段 1：创建或更新 PR

首先检查 PR 是否已存在：

bun gh-tool pr status

如果 PR 不存在——依次创建分支、提交、推送并发起 PR：

git checkout -b <branch> && git add -A && git commit -m "<msg>" && git push -u origin HEAD && bun gh-tool pr create --base <base> --title "<title>" --body "<body>"

如果 PR 已存在——提交、推送并更新元数据：

git add -A && git commit -m "<msg>" && git push origin HEAD
bun gh-tool pr edit --pr <pr_number> --title "<title>" --body "<body>"

• 如果当前已在功能分支上，则跳过 git checkout -b。
• 基础分支：用户提供的参数（默认为 test）。
• 分支命名：根据更改使用 feat/、fix/、chore/。

本地评审关卡

对于任何非琐碎更改，在首次提交或推送之前，先对差异运行 code-review 技能，并解决所有 Critical 和 Major 级别的问题。这是 PR 前的硬性关卡， 不是可选的清理步骤——bun run check 只能证明你编写的代码路径能够通过， 不能证明逻辑正确（覆盖缺口会让真实 Bug 在绿色测试中悄然发布：逐项循环 即使错误地标记输出，单项测试仍会通过）。只有琐碎或机械性的差异可以跳过， 并说明原因。

不要把阶段 2 的 GitHub 评审/监控循环当作首次评审。此处发现的 Bug 只需本地 修改；若同一个 Bug 到 CI 才被发现，就要经历完整一轮（推送、等待、评审 机器人、修复、重新运行）。当你以评审者的视角读过差异，且没有尚未解决的 Critical/Major 级别问题时，关卡即算通过。

PR 正文格式

## Summary
<1-2 sentences>

## Changes
- <bullet list>

提交信息规范

每次提交都必须使用规范的 Conventional Commits 格式，描述实际更改，而不是“处理评审反馈”或“修复 CI”之类的元描述。

格式：<type>(<scope>): <what actually changed>

• type：fix、feat、refactor、perf、style、chore 等。
• scope：受影响的模块或领域（例如 auth、db、ui、api）
• message：描述具体更改，而非提交原因

正确示例：

• fix(auth): add null check for session token before redirect
• refactor(api): extract validation logic into shared middleware
• fix(db): correct JOIN condition in user query

错误示例（绝不可使用）：

• fix: address review feedback
• fix: resolve CI check failures
• chore: fix issues

如果单次提交要处理不同领域的多条评审意见，请按领域分别提交，不要用一个包罗万象的提交。

阶段 2：主动监控循环

创建或更新 PR 后立即进入主动监控循环。不要暂停，也不要等待用户输入。

告知用户：“PR 已创建/更新。正在进入主动监控循环——监控 CI 和评审。（说‘stop’即可退出）”

---

循环开始

步骤 1：获取快照并决定下一步

循环约定 — 强制行为，不是建议：

• 创建/更新 PR 后，请一直留在此循环中，直到 循环退出。
• 每次修复并推送后，都要立即返回 步骤 1。
• 每次回复/解决问题后，都要立即返回 步骤 1。
• 如果 CI 仍在运行，循环就尚未完成。
• 如果仍有可见的未解决审查反馈，循环就尚未完成。
• 不要因为某一类检查已通过，就只处理一轮后停止。
• 除非用户说了 stop 或达到最大迭代次数限制，否则不要询问用户是否继续。

始终从步骤 1 的快照开始：

bun gh-tool pr review-triage --pr <pr_number>

此命令会在一次调用中返回 info、unresolvedThreads、visibleOpenThreads、summary 和 checks。请将其作为分支判断的唯一信息来源。

获取快照后，立即选择分支：

• 检查失败 → 转到步骤 2
• 检查通过且存在可见的未解决反馈 → 转到步骤 3
• 检查通过且没有可见的未解决反馈 → 转到循环退出
• 检查仍在运行且存在可见的未解决反馈 → 转到步骤 3（CI 运行期间处理反馈）
• 检查仍在运行且没有反馈 → 等待 CI：

bun gh-tool pr checks --pr <pr_number> --watch

--watch 完成后，返回 步骤 1 获取新快照。

不要围绕 bun gh-tool 编写临时的 sleep 轮询循环。 如果还有工作要做，请先处理，然后明确重新进入 步骤 1。如果只剩 CI 仍在运行，请使用 --watch。

步骤 2：处理 CI 失败

1. 首先判断：是偶发故障还是实际问题？

   • 如果失败看起来是偶发故障（超时、基础设施/网络问题、无关服务问题），请重新运行检查并返回步骤 1：

     bun gh-tool pr rerun-checks --pr <pr_number>
     

     → 返回循环开始处

   • 如果失败看起来是实际问题，请继续执行以下步骤。

2. 获取失败检查的详细信息：

   bun gh-tool pr checks-failed --pr <pr_number>
   

3. 如果输出中包含工作流运行和任务名称，请获取日志：

   bun gh-tool workflow job-logs --run <run_id> --job "<job_name>" --failed-steps-only
   

4. 分析错误，在本地修复——不要询问，直接修复。

5. 运行验证：

   bun run check
   

6. 提交并推送：

   git add -A && git commit -m "<type>(<scope>): <what changed>" && git push origin HEAD
   

7. → 返回循环开始处

步骤 3：检查审查并分类处理反馈

步骤 1 的快照已包含线程和摘要。请深入查看详情：

3.1 仍需处理的内联审查线程：

使用 --visible-open-only——它会包含未解决的线程，以及尚无回复的已解决线程：

bun gh-tool pr threads --pr <pr_number> --visible-open-only

3.2 AI 审查者的问题评论（Claude bot、Sentry Seer 等）：

bun gh-tool pr issue-comments --pr <pr_number> --author claude --body-contains "Claude Code Review"
bun gh-tool pr issue-comments --pr <pr_number> --author sentry-io --body-contains "Sentry"

AI 审查者会在 PR 的普通评论中发布发现，包含标注严重程度的条目（Critical、Major、Minor）、文件路径和行号。请解析每条评论的正文，提取可执行事项。

3.3 决策：

• 如果没有可见的未解决线程，且没有可执行的 AI 评论 → PR 已无问题。→ 转到循环退出
• 如果发现任何反馈 → 继续执行步骤 4

步骤 4：立即处理每条评论

修改代码前，为每条可执行的评论／发现创建一个待办事项（如果有待办列表工具，就使用该工具；否则在对话中维护一份明确编号的清单）。

• 一条评论／发现 = 一个跟踪事项。
• 使用能标明来源和问题的简短标签。
• 仅在主动处理该条评论时标记为 in_progress。
• 只有代码修改以及回复／解决均已完成后，才能标记为 completed。

对于每条评论／发现：

1. 读取所提及具体行所在的文件。

2. 理解建议——对方要求进行什么更改？

3. 评估并采取行动：

   • 自动应用（无需确认）：拼写错误、样式修正、缺少类型、导入清理、明显错误、性能改进，以及符合 CLAUDE.md 约定的安全修复。
   • 酌情应用：能提升清晰度的重构建议、错误处理改进、命名改进。
   • 先询问用户：删除功能、更改公共 API 签名、与现有模式相矛盾或含义不明确的建议。

4. 立即修复——跟踪记录所做的更改及其原因。

步骤 5：回复评论并解决讨论串

至关重要：每个讨论串都必须先回复，再解决。

对于行内讨论串：一步完成回复和解决：

bun gh-tool pr reply-and-resolve --pr <pr_number> --comment-id <comment_id> --thread-id <thread_id> --body "<response>"

对于一般 PR 评论：发布回复：

bun gh-tool pr comment --pr <pr_number> --body "<response>"

回复格式：

• 如果已修复："已处理 - [简要说明所做的更改]"
• 如果不适用："不适用 - [简要说明原因]"
• 如果是正面反馈："感谢反馈！"或类似的致谢
• 如果需要讨论："问题：[请求澄清]"

**如果回复因待提交审核验证错误而失败：**先使用 bun gh-tool pr submit-review --pr <pr_number> 提交待处理的审核，然后重试。如果必须弃审，请先在 GitHub 中弃审。

对于你提出问题的讨论串，不要解决。

步骤 6：验证并推送

bun run check

修复任何新问题。然后提交并推送：

git add -A && git commit -m "<type>(<scope>): <what changed>" && git push origin HEAD

→ 返回循环起点

---

退出循环

到达此处时（所有检查均通过，且没有尚未关闭的可见反馈）：

在最终成功消息之前，打印一份评论解决情况摘要列表。

使用编号列表，每条已处理的评论／发现对应一个条目，并采用以下固定结构：

1. Source: inline thread | general PR comment | AI review
   Identifier: <thread_id / comment_id / reviewer label>
   Problem: <short summary of the concern>
   Resolution: <what changed, or why it was not applicable>
   Changed files: <file A>, <file B> | none
   Replied: yes | no | n/a
   Resolved: yes | no | n/a
   Link: <comment or PR URL if available>

如果没有发现评论，请明确说明，而不要打印空结构。

告知用户："所有 CI 检查均已通过。所有审核评论均已处理。PR 已准备好供审核！"

退出循环的条件

在以下情况下退出观察循环：

• 所有检查均通过且没有尚未关闭的可见反馈——自然退出。
• **用户说“停止”**或要求退出。
• 达到最多 20 次迭代——询问用户是否要继续。