resolve-agent-reviews

自动解决当前 PR 中 PR 审查机器人（Copilot、Cursor Bugbot、CodeRabbit 等）发现的问题。采用两阶段工作流：先修复所有现有问题，然后持续轮询新问题，直到机器人不再发现问题。

前置条件

以下所有命令均使用 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 --bots-only --unanswered --expanded

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

此命令只显示尚未回复的机器人评论，并包含完整详细信息：完整评论正文（不截断）、diff 片段（代码上下文）以及所有回复。每条评论都会显示其 ID（方括号内，例如 [12345678]）。

如果没有返回评论，输出“No unanswered bot comments found”，然后跳至阶段 2。

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

对于展开输出中的每条评论：

A. 评估问题

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

1. 确实存在 — 需要修复的真实 Bug
2. 误报 — 实际上不是 Bug（符合预期的行为、机器人误解）
3. 不确定 — 无法确定；询问用户

可能确实存在：

• 代码明显违反了所述行为
• 对可能为 undefined 的值缺少 null 检查
• 类型不匹配或函数签名错误
• 条件判断中的逻辑错误
• 对文档中说明的失败情况缺少错误处理

可能是误报：

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

不确定时——询问用户：

• 修复需要进行架构更改
• 确实无法确定该行为是否有意为之
• “Bug”涉及你不完全了解的业务逻辑
• 存在多种合理解释
• 修复可能会产生意外副作用

B. 根据评估采取行动

如果确实存在： 修复代码。记录评论 ID 和简要的修复说明。

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

如果不确定： 询问用户。如果用户要求跳过，则记录为已跳过。

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

步骤 4：提交并推送

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

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

   git add -A
   git commit -m "fix: address PR review bot findings
   
   {List of bugs fixed, grouped by 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> "Skipped per user request" --resolve

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

---

在所有回复发布之前，不要开始第 2 阶段。

---

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

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

步骤 6：等待，然后处理报告

重复执行，直到某一轮以状态码 0 退出：

6a. 在后台任务中运行 npx agent-reviews --wait-checks --bots-only --unanswered，并在其结束前继续处理其他工作。切勿使用 gh pr checks --watch、循环休眠或重复列出状态来轮询。

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

6b. 阅读报告。第一行会列出提交和结果；其下是失败的检查及链接、未报告的预期检查、未回复的行内评论以及 PR 级评论。PR 级评论（issue 评论、审查摘要）没有可回复的讨论串，因此每次运行都会列出：只处理本轮中尚未处理过的 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 --bots-only --unanswered --timeout 180。如果发现问题，按照阶段 1 的步骤 3–5 处理，然后返回步骤 6a，以便新提交的检查也得到等待。

---

摘要报告

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

## PR Review Bot Resolution Summary

### Results
- Fixed: X bugs
- Already fixed: X bugs
- Won't fix (false positives): X
- Skipped per user: X

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

#### Copilot
- {description} - Fixed in {commit}

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

重要说明

回复策略

• 每个问题都要回复——不可默默忽略
• 回复有助于训练机器人并记录决策
• 回复“不会修复”可以防止同一误报再次出现

与用户沟通

• 对问题不确定时，询问用户
• 不要猜测架构或业务逻辑相关的问题
• 与其错误修复或错误驳回，不如先询问

最佳实践

• 修复前先核实问题——机器人可能会误报
• 修复应尽量精简且聚焦——不要重构无关代码
• 提交前确保类型检查和 lint 均通过
• 将相关修复归并到同一提交中
• Copilot 的 suggestion 代码块通常包含可直接使用的修复方案