pr-review-loop

在预算内把 PR 审到可合并：blocker 已修复验证，其余意见都有书面处置。审查回答的是「本 PR 的意图是否交付」，不是「这段代码还能挑出什么」；守住范围和修 bug 同样是你的职责。合并另按已有授权执行。

测试失败时先执行「测试失败处置」，尚未开 PR 也适用；任务仅为处理测试失败时，完成该节即结束。

开 PR 之前

模版里的「创建 PR 前完成」就是交付门槛：缺项会先被审查者当意见提出来，白白多一轮。

1. 用仓库自己的模版：.github/PULL_REQUEST_TEMPLATE.md（含全小写与 .github/PULL_REQUEST_TEMPLATE/ 目录）、docs/ 下的模版、CONTRIBUTING.md 指定的模版。整份按它的结构填满，冲突时以仓库为准；HTML 注释只当填写说明，正文不带注释。
2. 仓库没有模版时用 references/pr-template.md：占位项换成仓库的真实入口，无关小节删掉。
3. 在描述里写清意图：必须交付的行为、必须保持的不变量、明确不做的范围。分级以它为准；已有 PR 先从原始需求恢复意图。
4. 写满「创建 PR 前完成」再创建：GitHub gh pr create --body-file '<文件>'，Forgejo fj pr create，其他宿主按仓库入口提交同一份正文。

测试失败处置

1. 分诊：保存提交、命令、失败签名（用例与断言）、日志和并发条件，区分代码缺陷、测试缺陷与基础设施故障；证据不足时保留未定。复跑通过只证明结果不稳定；隔离通过或本 PR 未改相关文件，都不能排除真实竞态。
2. 有目的地复跑：首次可复跑一次失败用例或 gate，写明要验证的假设；隔离运行只作对照。同签名再次阻塞，或没有新的假设、修复、环境变化时，转用 $diagnosing-bugs 建立复现并定位；重复全量门禁须能检验新假设或验证处置结果。次数与证据跨提交、会话和代理累计。
3. 处置：本次引入的回归、关键正确性问题立即修复。仅在证据确认是既有测试缺陷、且有其他可靠覆盖保护关键行为时，才可将具体用例临时移入独立运行并报告失败的非阻塞检查；同时关联问题、负责人、恢复期限与恢复条件。仓库没有隔离机制时先修复或建立该机制，原门禁仍保持阻塞。调度、工具链等基础设施故障修复或明确报告阻塞，缺失的验证记未完成。
4. 验证与记录：修复后在原失败条件下做有界重复验证，并确认断言仍能发现目标缺陷，再跑受影响的必需检查。沿用仓库的问题追踪与记录位置；同一问题的次数、证据汇总更新，随实质处置批量提交，不为计数单独推送。复用已有检查前核对最终源码、工具链与覆盖范围，只补失效或缺失的证据。

完成标准：最终提交的必需检查实际通过；临时隔离项单列失败证据、覆盖缺口与后续安排，不计为通过。仍有关键正确性风险或必需验证未完成时，保持阻塞并说明下一步。

预算

• 轮次按受审 HEAD 计：同一 HEAD 上各审查者的意见合为一轮；重启会话、rebase、补发请求、换 PR 都沿用账本里的轮数。
• **默认 3 轮。**第 1 轮全量；之后每轮只核对上轮以来改动的代码和仍未关闭的意见，新冒出的、落在未改动代码上的意见按 nit 处理，除非它是 blocker。
• 延长到 5 轮只限两种情况：安全、权限、数据丢失、并发/状态类 blocker 带证据仍未关闭；或用户要求。
• 提前停：某轮复核后只剩 nit、wrong 或已记录的 should，回复完直接进「结束」。
• 预算用完就停，预算耗尽不等于通过：仍有 blocker 时按「暂停」交回用户，双方依据各写 2–3 行；没有 blocker 就记录遗留进「结束」。

分级

每条意见按意图自己复核再定级；审查者的 P0/P1/P2/Note 只是线索，P2 常常只是 nit。

级别	含义	动作
blocker	意图内的场景出错；数据丢失或损坏、凭据泄露/越权、崩溃/死锁、公共契约破坏、本 PR 引入的大范围回归	修：最小修法，优先删除或收窄；需要时补一个没修就失败的测试
should	本 PR 引入、调用方会在常见路径上碰到的真实 bug，修法局部	第 1–2 轮随批修；第 3 轮起记录接受，除非证据把它升为 blocker
nit	其他路径、罕见边界、小的性能开销、额外兼容、意图不需要的测试或守卫、可维护性、所有 Note	不改代码：一行理由回复，列为后续
wrong	错的、缺上下文的	驳回并给依据（file:line、测试、输出）

• 潜在高后果、证据不足：先做最小复现；确认前按 blocker。
• 只为 blocker 和 should 提交推送；nit 与 wrong 只回复。
• 推送前看 git diff --shortstat <base>：审查让 diff 变大了，先砍再推。
• 上一轮驳回过的意见被别的审查者再提，引用上次回复链接，不重新辩论。
• 云端 bot 的输入不同（有的读描述，有的只看 diff），「两个 bot 都提了」不直接决定级别。

每轮

1. 快照：读最新评论、审查和最新 headRefOid 上的检查。评论列表带 --paginate（Forgejo 见「回复」）；bot 常原地改写评论，按 updated_at 判新。审查者账号下的评论是意见，自己账号下的是回复；同一账号被别的 agent 借用时，才靠 <!-- pr-review-loop:reply --> 标记区分。
2. 等齐：本轮请求的和推送自动触发的审查者都在最新 HEAD 上出了结论（或按等待上限放弃）再动手，不边到边改。
3. 处置：逐条分级 → 写账本 → 批量修 blocker/should 并跑覆盖改动的检查 → 一次推送 → 逐条回复。含可见 UI 改动时，先重拍截图、更新 PR 描述再推送：自动审查读的是推送那一刻的描述。
4. 没有推送时：回复完就按「结束」自检，不另起一轮。某审查者只因 nit/wrong 把状态判红：回复里写明处置。
5. 有推送时：按「审查者现状」触发需要手动触发的审查者，向用户简短说明「第 N/预算 轮、未关闭项、下一步」，然后登记监听并结束本轮。完成标准是监听调用成功返回（T3 下 PR 已关联、watch_pull_request 成功，兜底定时任务存在）。

结束跟进、暂停、用户叫停或交回用户前，撤掉仍在运行的监听。

审查者现状

名单变化时更新这里：

审查者	触发	等待上限
fast-ship-bot	PR 开启、每次推送自动触发；也可发顶层评论 @fast-ship-bot	推送或评论后 30 分钟

**等待上限只花一次。**某审查者超时未出结论，本轮跳过它并记进账本；此后各轮不为它等待，它之后自己出了结论再正常回收。超时可重试一次并记账；不用空提交催审。宿主元数据异常先核对远端引用与 API 的差异，作为外部阻塞处理。

账本

TSV 放在工作树之外，跨轮累积：轮次 / 受审 HEAD / 审查者 / 意见摘要 / 级别 / 处置理由 / 回复链接 / 状态。状态 用 待回报 标记已发出、结论未回的请求；这一行还在，「结束」就不成立。账本缺失或停在旧轮次时，先从 PR 历史补齐。

每位审查者的账本记录 HEAD、触发事件（评论 ID 或推送）、宿主时间、重试次数及结论。超时从该有效触发计时；重复请求先对账，只有按超时规则发出的那次才计重试，线程回复时间不替代触发时间。

不追目标分支

审查只回答本 PR 的改动是否成立；目标分支前进、冲突事件都只记录，留给 $pr-finish 一次整合。例外：本 PR 必须用到目标分支的新改动才能通过验证时，提前整合并在账本写明理由。

卡住时

同一 blocker 修了两轮仍复发、修法来回反转，或每轮都从同一机制冒出新 blocker：停止逐条修，读 references/direction-audit.md。审计不重置轮数。

回复

回复意见、更新 PR 描述或读取宿主评论与检查时，读 references/replies.md，按宿主用文件提交并带回复标记。

暂停

两类情况停下来问用户：意见要求改变用户可见行为、文案或交互语义而需求与文档都没答案；预算用完仍有 blocker。先撤监听，给出问题、选项和推荐项，收到选择后恢复。

结束

成立条件：最新 HEAD 上每个审查请求都有结论或已按上限放弃，没有未关闭的 blocker，其余意见都已回复，账本没有 待回报，CI 通过。修复还没推送就先推送再判断。

1. 撤掉仍在运行的监听。
2. 勾选 PR 描述中「审查意见处理」的待办项（接口见「回复」）。
3. 向用户简短汇报：用了几轮/预算；修了什么；哪些意见没改、理由；哪个审查者缺席。
4. 已有合并、收尾或端到端交付授权时直接执行 $pr-finish 到 MERGED；只审查或要求停在待合并时，交付可合并结果。