用途
resolve-agent-reviews 用于自动解决当前 PR 上 PR 审查机器人（Copilot、Cursor Bugbot、CodeRabbit 等）提出的发现项。它采用两阶段工作流：先修复所有已存在的未回复评论，再轮询新评论，直到机器人不再产生新反馈。
主要能力
- 获取当前 PR 上未回复的机器人评论，并展示完整评论正文、diff hunk（代码上下文）及所有回复，每条评论带有 ID。
- 对每条发现项进行评估，分为三类：真实缺陷（TRUE POSITIVE）、误报（FALSE POSITIVE）、不确定（UNCERTAIN）。
- 对真实缺陷修复代码；对误报不改代码并记录原因；对不确定项询问用户。
- 修复完成后统一提交并推送，再逐条回复评论。回复时可使用 --resolve 标记线程为已解决（仅用于关闭对话的场景，如误报和用户跳过的发现项）。
- 第二阶段通过 watcher 循环轮询新评论，直到 watcher 超时且无新评论。
使用方式
所有命令使用 npx agent-reviews。若项目使用其他包管理器，可替换为对应运行器（如 pnpm dlx agent-reviews、yarn dlx agent-reviews、bunx agent-reviews）。
前置条件
- 云环境（如 Codespaces、远程代理）：需验证 git 作者身份，以便 CI 检查能将提交映射到用户。运行 git config --global --get user.email，若为空或占位符则手动设置。本地环境跳过此检查。
阶段一：获取与修复（同步）
-
获取所有机器人评论（展开）： npx agent-reviews --bots-only --unanswered --expanded CLI 自动检测当前分支、找到关联 PR，并通过 gh CLI 或环境变量认证。若失败（无 token、无 PR、CLI 未安装），会以清晰错误信息退出。若返回零条评论，输出“No unanswered bot comments found”并跳到阶段二。
-
处理每条未回复评论：
- 评估发现项：阅读相关代码，判断为真实缺陷、误报或不确定。
- 真实缺陷的典型特征：代码明显违反既定行为、缺少对可能未定义值的空值检查、类型不匹配或函数签名错误、条件逻辑错误、缺少对已记录失败情况的错误处理。
- 误报的典型特征：机器人不理解框架/库模式、代码有意如此结构（有注释说明原因）、机器人标记的是风格偏好而非缺陷、“缺陷”实际是特性或有意行为、机器人误读代码流程。
- 不确定时询问用户：修复需要架构变更、确实不确定行为是否有意、缺陷涉及不完全理解的业务逻辑、存在多种合理解释、修复可能产生意外副作用。
- 根据评估行动：真实缺陷则修复代码并记录评论 ID 和修复简述；误报则不改代码并记录评论 ID 和原因；不确定则询问用户，若用户说跳过则记为跳过。此时不要回复评论，回复在提交之后进行。
-
提交并推送： 在评估并修复所有未回复评论后，运行项目的 lint 和类型检查，然后： git add -A git commit -m "fix: address PR review bot findings
{List of bugs fixed, grouped by bot}" git push 从输出中捕获提交哈希。
-
回复所有评论： 在发布内联审查评论回复前，先获取 npx agent-reviews --detail <comment_id> 并检查最新回复。PR 级 issue 评论和审查摘要没有线程回复列表；这些类型返回空列表并不代表没有记录结果。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 级 issue 评论或审查摘要提交（而非针对特定行的内联审查评论），CLI 无法发布线程回复，会打印 ⊘ Skipped reply: comment is not part of a review thread。这是预期行为。在摘要中记录结果并继续；不要重试。
在所有回复发布之前，不要开始阶段二。
阶段二：轮询新评论（循环直到安静）
watcher 在发现新评论时立即退出（有 5 秒宽限期以捕获批量发布）。这意味着需要循环运行：启动 watcher，处理其返回的任何评论，重启 watcher，重复直到 watcher 超时且无新评论。
- 启动 watcher 循环：
重复以下步骤，直到 watcher 退出且无新评论：
- 6a. 在后台启动 watcher：运行 npx agent-reviews --watch --bots-only --unanswered 作为后台任务。启动时，将现有评论与本次运行中已处理的 ID 以及 --detail 的最新回复进行核对；不要重放已记录的结果。基线可能包含阶段一和 watcher 启动之间提交的确实未处理的发现项。若有，停止 watcher，通过步骤 3-5 处理这些发现项，然后重启。跟踪本次运行中已跳过的不可线程评论，以免它们导致重启循环。一旦基线核对完成，处理 watcher 以 EXITING WITH NEW COMMENTS 退出时报告的新 ID。
- 6b. 等待后台命令完成（默认 10 分钟；可用 --timeout 覆盖）。
- 6c. 检查输出：
- 若发现新评论（输出包含 EXITING WITH NEW COMMENTS）：使用 --detail <id> 读取每条新评论的完整详情，完全按照阶段一步骤 3-5 处理（评估、修复、提交、推送、回复），然后回到步骤 6a 重启 watcher。
- 若无新评论（输出包含 WATCH COMPLETE）：停止循环，进入摘要报告。
摘要报告
两个阶段完成后，提供摘要：
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. Watch completed.
适用场景
- 需要批量清理 PR 审查机器人反馈的开发工作流。
- 使用 Copilot、Cursor Bugbot、CodeRabbit 等机器人进行 PR 审查的项目。
- 希望自动评估、修复或驳回机器人发现项，并留下可追溯回复记录的团队。
限制
- 需要 gh CLI 或环境变量认证，且当前分支需关联 PR。
- 云环境需验证 git 作者身份，本地环境跳过。
- 不可线程回复的评论（PR 级 issue 评论或审查摘要）无法发布线程回复，CLI 会跳过。
- 对不确定的发现项需询问用户，不应猜测架构或业务逻辑问题。
- 修复应保持最小和聚焦，不要重构无关代码。
- 提交前需确保类型检查和 lint 通过。
- 相关修复应分组到单个提交中。
- Copilot 建议块通常包含可直接使用的修复。