pr-review-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

请求复审后持续跟进至收敛。处理完一轮后保持对最新审查意见与检查状态的监听；一轮返回不代表任务已完成。

## 跟进入口

1. 先读取当前 PR 的最新评论、审查结果和最新 HEAD 的检查状态，恢复工作树外的跨轮账本。快照与每一轮都核对最新 headRefOid，旧提交上的通过不能代替最新提交的检查与审查。读评论/意见列表记得带 `--paginate`——不带只回最旧 30 条，评论多的 PR 新意见永远不可见。
2. 等齐本轮意见：本轮请求的和推送自动触发的审查者（上轮已超时的不算），都在最新 HEAD 上给出结论（或按第 6 步放弃等待）后，才开始归桶和修改；只到了一部分就继续监听，不边到边改。
3. 按「收敛规则」归桶 → 更新跨轮账本 → 判断是否触发方向审计。触发时先完成审计、确定收敛路径，再恢复修复；路径按「方向取舍」自行裁决，只有产品决策按「暂停」交回用户。
4. 按确定的路径修复 → 核验或补跑相关检查 → 在已有提交/推送授权范围内提交推送 → 回复。每次请求复审或继续等待自动复审前，必须把本轮处置及升级判断写回账本，向用户简短说明各子系统的连续轮数和下一步，再按「审查者现状」重新触发本轮未通过的审查者。需要额外授权时先完成可审阅的修复，再交回用户。

   推送含可见 UI 改动的提交前：先重拍受影响界面、上传、`gh pr edit` 更新 PR 描述中的截图链接，再推送。push 时自动触发的审查者读的是当时的描述——先推后改，它按旧图审，会对已修问题再开一轮。上传前先打开图片，确认不是过渡帧或旧布局。
5. 本轮处理完后继续监听最新审查意见与检查状态，新事件到达即回到第 1 步做快照。
6. 审查者超过「审查者现状」里的等待上限仍无结果时，按其下的「等待上限只花一次」处理。

结束跟进、因产品决策暂停、用户停止或交回用户前，撤掉仍在运行的监听。

## 审查者现状

当前接入的审查者与触发方式，名单变化时更新这里：

| 审查者 | 触发 | 等待上限 |
| --- | --- | --- |
| Codex | 每轮发一条顶层评论 `@codex review`；推送不会触发它 | 触发后 40 分钟 |

**等待上限只花一次。**某审查者超过等待上限仍无结果，本轮跳过它，结束时说明，并把超时记进账本；此后各轮不再为它等待，到齐判定不含它——云端审查者不一定一直在线，一轮缺席说明它当下不在，同一个上限不该每轮重付。手动触发的审查者照常发请求，只是不为它等待；它之后自己出了结论就按「意见识别不看作者」正常回收，并恢复为正常等待。

## 收敛规则

**意见识别不看作者。**人类同事可能用任意账号评论，其他 agent 也可能借本账号 token 发结论——所有非空评论都会进新意见列表；只有自己带 `<!-- pr-review-loop:reply -->` 标记的评论被排除（见「回复」）。

处理本轮新意见之前，先把它们归并分桶，再按桶回复：

| 桶 | 含义 | 回复动作 |
| --- | --- | --- |
| Act on | 影响正确性、安全或可维护性的真实问题 | 先判断方向审计 → 按确定的路径修复、核验和回复 → 更新账本后重新请求这个审查者 |
| Consider | 说得对，但属于本 PR 需求目标之外的另一件事 | 回复「有道理，本 PR 不做，理由 X」，**不**重新请求 |
| Noted | 技术上成立但不可行动（依赖上下文、过早优化） | 简短确认，不改 |
| Dismissed | 错的、吹毛求疵的、缺上下文的 | 回复驳回理由并给依据 |

**云端 bot 的一致性要降权。**多个审查者独立提出同一件事通常是高信号，但前提是它们看了同一份输入。PR 上的云端 bot 输入并不相同——有的读了 PR 描述，有的只看 diff——所以「两个 bot 都提了 X」的置信度低于同输入的多模型审查。记录每条意见是谁提的，但不要让提的条数直接决定它进哪个桶。

**跨轮账本。**复审是多轮的，账本必须跨轮累积。写成一个 TSV，放在工作树之外（仓库约定不允许把临时文件留在工作树里），列为：`轮次 / 受审 HEAD / 子系统 / 审查者 / 意见摘要 / 桶 / 理由 / 回复链接 / 本轮状态`。每轮快照与最新评论对账，记录各子系统连续出现 Act on 的轮数，以及方向审计结论或未触发理由。账本缺失或停在旧轮次时，先从 PR 历史补齐，再继续修复或复审。

**轮次按受审提交计。**同一 HEAD 上多个审查者的意见合为一轮；通知重放、已修复的旧意见和同一意见的重复报告不另计轮次。旧提交的迟到意见先核对当前 HEAD 是否仍成立。重启会话、rebase 或补发复审请求都沿用账本中的连续轮数。

**不追目标分支。**审查只回答本 PR 的改动是否成立；与目标分支的整合留到用户收尾时一次完成。跟进与等待收尾期间，提交只为处理审查意见；目标分支前进、GitHub 显示冲突或被冲突事件唤醒都只记录，留给收尾。例外：本 PR 必须用到目标分支上的新改动才能通过审查或验证时，提前整合并在账本写明理由。

**Dismissed 跨轮复用。**一条意见在上一轮已被 Dismissed，下一轮另一个审查者又提同样的，引用上一轮的驳回理由和那条回复的链接，不要重新辩论一遍。

**三轮未收敛先做方向审计。**同一子系统连续 3 轮仍有有效的 Act on 意见，无论 bot 标为 P0、P1、P2 或未标级别，收到第三轮意见后先停下逐条修补与复审循环，调 `$code-review-panel` 对整份 diff 做方向审计：实现方向是否成立、反复出现的问题是否有共同根因、剩余修复能否沿当前方向收敛。审计结论与选定路径写入账本后，才恢复修复；审计有分歧或修法互相冲突时按「方向取舍」裁决。只有完成方向审计并确定路径，或该子系统一轮审查结束且没有有效 Act on 意见，才重置连续轮数。

## 方向取舍

方向审计后的路径、修在本 PR 还是另立需求、补不补回归与夹具，由你自己定，默认**根治**：选长期更干净正确的方案——在本 PR 内修掉共同根因、换掉反复生边界的模型、补上能变异验证的回归。PR 已经很大、审查轮次已经很多，都不是延后的理由；「另立需求」「记档不修」只留给本 PR 需求目标之外的事。拿不准时请两个不同模型的顾问各自独立裁决（编排环境下用其实现顾问，否则用 `$code-review-panel`），一致照办，仍分歧按根治取向自选；结论与依据写进账本后直接继续。

## 回复

回复正文先写进 UTF-8 无 BOM 的临时文件，不要把中文内联在命令里。

- 行内意见：`gh api repos/<repo>/pulls/<n>/comments -X POST -F in_reply_to=<线程第一条评论的 id> -f body="$(cat '<回复文件>'; printf '\n\n<!-- pr-review-loop:reply -->')"`
- 顶层评论、审查总结和 bot 结论：`gh api repos/<repo>/issues/<n>/comments -X POST -f body="$(cat '<回复文件>'; printf '\n\n<!-- pr-review-loop:reply -->')"`，正文开头引用被回复的意见或附上它的链接。

**自己发的每条评论末尾都要带 `<!-- pr-review-loop:reply -->` 标记**（HTML 注释，渲染后不可见）——回复、处置总结、更正都一样。不带标记的自己评论会在下一轮被当作新意见回收一次。Windows 下 `$(cat …)` 不可用时把标记写进回复文件末尾，再用 `-F body=@<回复文件>` 提交。

不要对任何评论执行 `PATCH` 或 `DELETE`，自己账号发的也不行——有仓库写权限时 GitHub 不会拦，改错了就会覆盖审查结论。回复发错了就再发一条更正，不要改原评论。修改 PR 描述用 `gh pr edit`，不受这条限制。

## 暂停

只有需要产品决策的意见（用户可见行为、文案或交互语义要变，需求与项目文档都没给答案）才停下来问用户：先撤掉监听，汇总问题、可选路径及推荐项，收到选择后再恢复循环。技术方向、范围与修法的分歧按「方向取舍」处理。

## 结束

所有审查者已回应（或已按上面的规则放弃等待），最新提交上没有未处理的有效意见，CI 通过：

1. 撤掉仍在运行的监听。
2. 勾选 PR 描述中「审查意见处理」的待办项。
3. 向用户简短汇报：共几轮；修了什么；哪些意见没改、理由是什么；哪个审查者无响应。
4. 不要合并 PR，等用户的收尾指令。

From gitbobobo/skills, MIT.

More from gitbobobo/skills