resolve-reviews

自动解决当前 PR 上的所有审核评论（包括人工评论和机器人评论）。采用两阶段工作流：先修复所有现有问题，再持续轮询新问题，直到没有新评论。

前提条件

以下所有命令都使用 npx agent-reviews。如果项目使用其他包管理器，请替换为相应的运行器（例如，pnpm 使用 pnpm dlx agent-reviews，Yarn 使用 yarn dlx agent-reviews，Bun 使用 bunx agent-reviews）。始终遵循用户对包管理器的偏好。

仅限云环境（例如 Codespaces、远程 Agent）：验证 git 作者身份，以便 CI 检查能将提交关联到用户。运行 git config --global --get user.email，如果结果为空或是占位符，请手动设置。在本地环境中跳过此检查。

阶段 1：获取并修复（同步）

步骤 1：获取所有评论（展开详情）

运行 npx agent-reviews --unanswered --expanded

CLI 会自动检测当前分支，查找关联的 PR，并通过 gh CLI 或环境变量进行身份验证。如果发生任何错误（没有令牌、没有 PR、未安装 CLI），它会退出并显示明确的错误信息。

此命令会显示所有未回复的评论（包括人工评论和机器人评论）的完整详情：完整的评论内容（不截断）、差异片段（代码上下文）以及所有回复。每条评论都会在方括号中显示其 ID（例如，[12345678]）。

如果没有返回评论，请输出“未找到未回复的评论”，然后跳至阶段 2。

步骤 3：处理每条未回复的评论

根据评论作者是机器人还是人工审核者，对展开输出中的每条评论进行相应评估。

对于机器人评论

阅读评论所引用的代码并判断：

1. 确实存在的问题 - 存在需要修复的真实 Bug
2. 误报 - 实际上不是 Bug（行为是有意为之，或机器人误解了代码）
3. 不确定 - 无法确定；询问用户

可能确实存在的问题：

• 代码明显违反了声明的行为
• 对可能未定义的值缺少空值检查
• 类型不匹配或函数签名不正确
• 条件语句中的逻辑错误
• 对已记录的失败情形缺少错误处理

可能是误报：

• 机器人不理解框架或库的常见模式
• 代码有意采用这种结构（并通过注释解释原因）
• 机器人指出的是风格偏好，而非 Bug
• 所谓的“Bug”实际上是功能或有意为之的行为
• 机器人误读了代码流程

对于人工评论

阅读所引用的代码和审核者的评论。人工审核者通常比机器人更准确，也更了解上下文。请判断：

1. 需要处理 - 审核者指出了真实问题或要求进行具体修改
2. 需要讨论 - 评论提出了合理的问题，但合适的处理方式尚不明确
3. 已处理 - 该问题已修复或不再相关

可能需要处理：

• 审核者指出了 Bug 或逻辑错误
• 审核者要求进行具体的代码修改
• 审核者指出缺少边缘情况处理或错误处理

可能需要讨论——询问用户：

• 审核者建议进行你不确定的架构变更
• 评论涉及权衡（例如性能与可读性）
• 反馈带有主观性，且团队尚未达成共识

不确定时——询问用户

对于机器人评论和人工评论，如果出现以下情况，请询问用户：

• 修复需要进行架构变更
• 你确实无法确定该行为是否有意为之
• 存在多种合理的解释
• 修复可能产生意料之外的副作用

根据评估采取行动

**如果确实存在问题／需要处理：**修复代码。记录评论 ID 和简要的修复说明。

**如果是误报：**不要修改代码。记录评论 ID 和说明其并非真实 Bug 的原因。

**如果需要讨论：**请用户咨询 PR 作者。根据用户的决定处理并记录。

**如果已处理：**记录评论 ID 并注明原因。

**如果不确定：**询问用户。如果用户表示跳过，则将其记录为已跳过。

暂时不要回复评论。请在提交之后再回复（步骤 5）。

第 4 步：提交并推送

评估并修复所有未回复的评论后：

1. 运行项目的 lint 和类型检查
2. 暂存、提交并推送：

   git add -A
   git commit -m "fix: address PR review findings
   
   {List of changes made, grouped by reviewer/bot}"
   git push
   

3. 从输出中记录提交哈希。

第 5 步：回复所有评论

回复行内审查评论之前，先运行 npx agent-reviews --detail <comment_id> 并检查最新回复。PR 级问题评论和审查摘要没有线程回复列表；这些类型的评论即使列表为空，也不能据此认定没有记录处理结果。CLI 会跳过对这些类型评论的回复。记录这一跳过情况，不要另发顶层评论，也不要使用其他工具绕过限制。如果已记录相同的处理结果，不要重复发布。在恢复的会话中，使用最新的未回复列表，而不是重放之前会话的工作队列。只有出现新讨论或用户提出要求时，才重新考虑某项决定。

对于多行或复杂回复，将确切的回复文本写入仓库外临时目录中一个名称唯一的 UTF-8 文件，然后使用 npx agent-reviews --reply <comment_id> --body-file <path_to_reply_file>（仅在下文适用时添加 --resolve）。CLI 接受绝对路径和相对路径；对于仓库外的临时文件，优先使用绝对路径。直接使用文件路径，不要使用 shell 命令替换。回复成功后删除临时文件；即使发布失败，也要将回复文件保留在仓库外，以免后续的 git add -A 命令将其提交。

现在已有提交哈希，请回复每条已处理的评论。--resolve 标志会在 GitHub 上将审查线程标记为已解决。仅在结束对话时使用（误报、讨论已结束、问题已处理、用户选择跳过），不要用于需要审查者继续验证的新修复。

对于每条确认为有效／需要处理的评论（我们已修复；保持线程未解决，以便审查者验证）：

运行 npx agent-reviews --reply <comment_id> "Fixed in {hash}. {Brief description of the fix}"

对于每条误报评论（结束对话）：

运行 npx agent-reviews --reply <comment_id> "Won't fix: {reason}. {Explanation of why this is intentional or not applicable}" --resolve

对于每条讨论评论（用户作出决定后）（该决定结束线程）：

运行 npx agent-reviews --reply <comment_id> "{Outcome}. {Explanation of the decision and any changes made}" --resolve

对于每条已处理的评论（无需进一步处理）：

运行 npx agent-reviews --reply <comment_id> "Already addressed. {Explanation of when/how this was fixed}" --resolve

对于每条跳过的评论（用户选择不处理）：

运行 npx agent-reviews --reply <comment_id> "Skipped per user request" --resolve

无法创建线程回复的评论： 如果评论是 PR 级问题评论或审查摘要提交（而非针对特定行的行内审查评论），CLI 无法发布线程回复，并会输出 ⊘ Skipped reply: comment is not part of a review thread。这是预期行为。在摘要中记录处理结果，然后继续；不要重试。

所有回复发布完毕之前，DO NOT 开始第 2 阶段。

---

第 2 阶段：等待 HEAD 提交的检查完成（循环直至检查通过）

大多数审查机器人（Greptile、Cursor Bugbot、CodeRabbit 等）会将审查结果作为提交检查报告，与 CI 并列显示，因此提交的检查完成后，审查也就完成了。--wait-checks 会等待这些检查全部完成，然后只输出需要你处理的内容。

步骤 6：等待报告，然后采取行动

重复此过程，直到某次运行以 0 退出：

6a. 在后台任务中运行 npx agent-reviews --wait-checks --unanswered，并在其完成前继续处理其他工作。绝不要使用 gh pr checks --watch、循环休眠或重复列出检查来轮询。

对于延迟注册检查的每位审查者（例如，只有在预览部署后才启动的审查者），添加 --expect "<check name>"，以免等待过程在其报告前结束。对于草稿 PR，不会等待预期检查，因为审查机器人通常会跳过草稿。

6b. 阅读报告。第一行会列出提交和结果；下方是失败的检查及其链接、尚未报告的预期检查、待回复的行内评论，以及 PR 级别的评论。PR 级别的评论（问题评论、审查摘要）没有可回复的讨论串，因此每次运行都会列出：只处理本轮尚未处理的 ID。退出代码说明接下来该怎么做：

• 0：所有检查均已通过，且没有待处理评论。转到“摘要报告”。
• 1：有检查失败、预期检查未报告，或有行内评论待处理。严格按照阶段 1 的步骤 3–5 处理评论（评估、修复、提交、推送）。失败的检查也算一项发现：读取其日志（对于 GitHub Actions，运行 gh run view <id> --log-failed；对于审查机器人或外部状态，打开其链接），修复后提交并推送。然后返回步骤 6a。如果唯一的问题是预期检查未报告，不要再次等待：在摘要报告中说明该检查，然后停止。
• 2：PR 与其基础分支存在冲突，因此 CI 不会运行。合并或变基基础分支，推送，然后返回步骤 6a。
• 3：等待超时，仍有检查在运行（默认 30 分钟；--timeout <seconds>）。报告哪些检查仍在等待。
• 4：没有检查注册到该提交。报告这一情况；该分支所在的仓库可能没有 CI。

如果你在等待期间推送，系统会自动跟踪新的头部提交。

轮次上限。 此阶段每次修复推送都算一轮，无论发现来自 6b 还是下方的评论监视器。如果新的发现不断出现在你先前修复提交所更改的代码行上，说明每次修复都引出了新的边界情况，继续打补丁也无法解决问题。经过第二轮此类修复后，停止：不要再推送修复。向用户报告剩余发现，并说明每轮修复做了哪些更改；建议在继续之前整体审查设计（例如，进行一次对抗式设计审查）。先前修复未触及的代码所出现的发现不计入上限。

未通过检查发布评论的审查者（例如 Copilot）是评论监视器唯一需要处理的情况。在 --wait-checks 干净结束后，运行一次 npx agent-reviews --watch --unanswered --timeout 180。如果有发现，按照阶段 1 的步骤 3–5 处理，然后返回步骤 6a，以便等待新提交的检查。

---

摘要报告

两个阶段完成后，提供摘要：

## PR Review Resolution Summary

### Results
- Fixed: X issues
- Already addressed: X
- Won't fix (false positives): X
- Discussion resolved: X
- Skipped per user: X

### By Reviewer/Bot
#### cursor[bot]
- {description} - Fixed in {commit}
- {description} - Won't fix: {reason}

#### @reviewer-name
- {description} - Fixed in {commit}

### Status
All findings addressed. Every check on the head commit passed.

重要说明

回复政策

• 每条评论都要回复——不得默默忽略
• 对于机器人：回复有助于训练它们，并防止错误提示再次出现
• 对于人类：回复能让审查者了解进展，并推动审批

与用户互动

• 对发现有疑问时，询问用户
• 不要猜测架构或业务逻辑方面的问题
• 与其错误修复或错误驳回，不如先询问
• 人类审查者通常掌握你不了解的背景；不确定时应听从作者的意见

最佳实践

• 修复前先验证发现——机器人可能误报，人类则很少误报
• 保持修复精简且聚焦——不要重构无关代码
• 提交前确保类型检查和 lint 均通过
• 将相关修复归入同一次提交
• Copilot 的 suggestion 代码块通常包含可直接使用的修复方案
• 如果人类审查者提出了具体代码更改，除非会引入问题，否则优先采用其版本