resolve-human-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 --humans-only --unanswered --expanded

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

这只会显示尚未回复的人工评论及其完整详情：完整评论正文（不截断）、差异块（代码上下文）和所有回复。每条评论都会在方括号中显示其 ID（例如，[12345678]）。

如果未返回任何评论，则打印“未找到尚未回复的人工评论”，并跳到阶段 2。

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

针对展开详情输出中的每条评论：

A. 评估反馈

阅读相关代码和审核者的评论。人工审核者通常比机器人更准确，也更了解上下文。请给予其反馈适当的重视。确定反馈属于以下哪种情况：

1. 可执行——审核者指出了实际问题或要求进行具体更改
2. 讨论——评论提出了合理观点，但尚不清楚正确的处理方式
3. 已处理——相关问题已经修复或不再适用

可能属于“可执行”：

• 审核者指出了缺陷或逻辑错误
• 审核者要求进行具体的代码更改
• 审核者指出了缺失的边界情况或错误处理
• 审核者指出了命名、API 或架构方面的问题，并给出了明确的修复方案
• 审核者有理有据地提出了更好的处理方式

可能属于“讨论”——请询问用户：

• 审核者建议进行架构更改，而你对此没有把握
• 评论涉及取舍（例如性能与可读性）
• 审核者的建议与代码库其他部分使用的模式冲突
• 反馈带有主观性（风格、命名偏好），且团队尚未达成共识
• 你不同意反馈意见，希望由作者决定

可能属于“已处理”：

• 评论发布后代码已有更改
• 另一个提交已经修复了问题
• 评论所指的代码已不存在

B. 根据评估采取行动

**如果属于“可执行”：**修复代码。记录评论 ID 和简要修复说明。

**如果属于“讨论”：**请用户咨询 PR 作者。根据作者的决定处理并记录结果。

**如果属于“已处理”：**记录评论 ID 并说明原因。

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

步骤 4：提交并推送

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

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

   git add -A
   git commit -m "fix: address PR review feedback
   
   {List of changes made, grouped by reviewer}"
   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 上将审查线程标记为已解决。仅在结束讨论时使用（讨论已结束、问题已处理），不要用于仍需审查者验证的新修复。

对于每条 ACTIONABLE（我们已修复；保持线程开启，以便审查者验证）：

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

对于每条 DISCUSSION（用户作出决定后）（该决定结束此线程）：

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

对于每条 ALREADY ADDRESSED（无需进一步处理）：

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

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

所有回复发布完毕前，不要开始 Phase 2。

---

Phase 2：轮询后续评论（循环直至无新评论）

发现新评论后，监视器会立即退出（并等待 5s，以捕获批量发布的评论）。因此，需要循环运行：启动监视器，处理它返回的评论，重新启动监视器，重复此过程，直到监视器超时且没有新评论。

第 6 步：启动监视循环

重复以下步骤，直到监视器退出且没有新评论：

6a. 在后台启动监视器：

将 npx agent-reviews --watch --humans-only --unanswered 作为后台任务运行。

启动时，将 EXISTING COMMENTS 与本次运行中已处理的 ID 以及 --detail 返回的最新回复进行核对；不要重复处理已记录结果的评论。基线可能包含在第 1 阶段与监视器启动之间提交、尚未处理的发现。如果有此类发现，请停止监视器，按照步骤 3-5 处理这些发现，然后重新启动监视器。记录本次运行中已跳过的不可加入评论线程的评论，避免因此陷入重启循环。基线核对完成后，处理监视器退出时通过 EXITING WITH NEW COMMENTS 报告的新 ID。

6b. 等待后台命令完成（默认 10 分钟；可通过 --timeout 覆盖）。

6c. 检查输出：

• 如果发现了新评论（输出包含 EXITING WITH NEW COMMENTS）：

  1. 使用 --detail <id> 读取每条新评论的完整详情
  2. 完全按照第 1 阶段的步骤 3-5 处理（评估、修复、提交、推送、回复）
  3. 返回第 6a 步，重新启动监视器

• 如果没有新评论（输出包含 WATCH COMPLETE）： 停止循环，转到总结报告。

---

总结报告

两个阶段都完成后，提供总结：

## PR Review Resolution Summary

### Results
- Fixed: X issues
- Already addressed: X
- Discussion resolved: X
- Skipped per user: X

### By Reviewer
#### @reviewer-name
- {description} - Fixed in {commit}
- {description} - Already addressed

### Status
All review comments addressed. Watch completed.

重要说明

回复政策

• 每条评论都要回复——不得默默忽略
• 回复可以让审查者了解进展，并推动审批继续进行
• 即使评论提到“已处理”，也值得给予确认

用户互动

• 如果不清楚正确做法，请询问用户
• 人工审查者通常掌握你没有的上下文——不确定时应听从作者的意见
• 与其做出作者可能不认可的更改，不如先询问

最佳实践

• 人工审查者通常比机器人更准确——默认相信他们的反馈
• 修复应尽量精简且聚焦——不要重构无关代码
• 提交前确保类型检查和 lint 通过
• 将相关修复归入同一次提交
• 如果审查者建议了具体的代码更改，除非会引入问题，否则优先采用其方案