address-review-bots

处理审查机器人评论

适用场景

创建 PR 或推送到 PR 后，如果用户要求等待 Claude、Devin 或类似审查机器人的反馈、处理机器人评论，或持续迭代直到机器人审查通过，请在此时使用。

这项流程是本地验证的补充，不会取代目标代码库的常规推送前或合并前检查。

核心流程

1. 确认当前分支有 PR：

gh pr view --json number,url,headRefOid,headRefName

如果不存在 PR，请停止并告知用户此技能需要已有的 PR。

2. 在推送前后立即记录审查时间窗口：

REVIEW_BOT_SINCE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

3. 等待审查机器人检查，并获取最新评论快照：

mkdir -p .context
node scripts/review-bot-snapshot.mjs \
  --wait \
  --since "$REVIEW_BOT_SINCE" \
  --json > .context/review-bot-snapshot.json

从此技能目录运行捆绑的 scripts/review-bot-snapshot.mjs。如果 Agent 无法相对于技能目录执行，请先解析包含此 SKILL.md 的目录，然后显式传入脚本路径。

如果要处理的是已发布的评论，且未记录推送时间戳，请省略 --since。

4. 对每条最新的机器人评论进行分类：

• valid_actionable：机器人发现了需要在合并前修复的真实问题。
• already_fixed_or_stale：当前头部版本中已不存在此问题，或评论针对的是旧头部版本。
• false_positive：机器人的判断有误；请收集具体代码证据。
• needs_user_decision：此项改动涉及产品、UX 或架构策略，并非显而易见的正确性修复。
• valid_low_risk_cleanup：机器人发现了真实、范围明确的改进。此改进不会阻碍合并，成本低、客观，且符合代码库规范。
• non_actionable：摘要、赞扬、进度更新或“未发现问题”等评论。

不要仅因评论使用了“非阻塞”“小问题”“没有值得内联修改的内容”或类似措辞，就自动将其归为 non_actionable。如果评论包含具体代码引用、合理的故障模式、一致性问题或可维护性问题，请检查引用的代码，并根据实际情况分类。

自动修复 valid_actionable 评论。如果 valid_low_risk_cleanup 评论涉及的改动范围明确，且不会以需要用户判断的方式影响产品、UX、架构策略或公开行为，也请自动修复。除非依据代码库规范可明显确定取舍，否则将产品、UX 和架构方面的权衡留给用户决定。

继续下一步前，请在笔记或最终答复中为每项实质性的机器人观察结果制作一份简明分类表：

permalink | isOutdated or n/a | claim | classification | evidence | reply/resolution action or why left open

5. 针对有效且需要处理的评论，进行范围明确的修复，并补充附近的测试。

6. 自行审查改动，然后使用代码库的最终验证命令进行验证。

如果用户设置了 REVIEW_BOT_VALIDATION_COMMAND，请原样使用。否则，按以下顺序确定验证方式：

1. 使用代码库说明或 CI 要求的命令。
2. 检查适用的包清单，从代码库根目录开始，并根据工作区配置检查有改动的包。先通过根目录清单中的 packageManager 字段确定包管理器，再检查锁文件（pnpm-lock.yaml、yarn.lock、package-lock.json 或 npm-shrinkwrap.json、bun.lock 或 bun.lockb）。不要仅因存在其他可执行文件就切换包管理器。
3. 如果存在 precommit 包脚本，请使用已确定的包管理器运行，例如 pnpm run precommit、yarn run precommit、npm run precommit 或 bun run precommit。
4. 如果不存在 precommit，请使用同一包管理器运行所有可用的 lint 和 test 包脚本。不要调用不存在的脚本，也不要将脚本缺失视为验证失败。
5. 如果这两个脚本都不存在，请使用代码库文档中列出的非 JavaScript 检查或 CI 等效检查。如果找不到此类检查，请说明当前没有可用的验证覆盖，而不要自行编造命令。

迭代期间可以使用范围更小的检查，但在最后一次代码改动后，必须运行所有已确定的最终验证命令，然后才能提交或推送审查机器人修复。

7. 如果进行了修复，请提交并推送：

git add <fixed-files>
git commit -m "fix: address review bot feedback"
git push

8. 从步骤 2 开始重复，直到不再有新的有效且可执行的评论或有效的低风险清理机器人评论，剩余评论均已过时／不可执行／误报／需要用户决策，或进一步更改会沦为猜测。

9. 在每个稳定的当前头版本上，扫描未解决且属于范围内的审查线程，并在宣布机器人循环已清理干净之前，按照下方的审查线程清理政策进行处理。

除非用户明确要求继续，否则默认最多进行 8 轮修复并推送。

审查判断

将审查机器人视为信息来源，而非权威。在代码、测试、生成的构件或仓库惯例中有具体依据，评论才算有效。修复或驳回实质性意见之前，请检查所提及的文件及其周边代码。

审查机器人可能会更新已有的顶层摘要评论，而不是新建审查评论。如果新的机器人状态评论表明已发布或更新审查摘要，即使快照因其原始 createdAt 早于当前审查窗口而将其列为过时评论，也要检查该摘要。在这种情况下，应根据 updatedAt 和状态评论的内容，判断是否需要对该摘要进行分类。

对于过时的行内评论，请对比快照头 SHA、评论的提交 ID 和当前代码。

对于无法归入任何审查线程的评论，如果回复有助于后续审查者理解驳回理由，请简短回复 PR。对于审查线程，请遵循下方更严格的“回复后再解决”规则。

审查线程清理

使用能够提供线程 isResolved 和 isOutdated 字段的 GitHub 工具查询未解决的审查线程。快照辅助工具基于评论 SHA 和时间进行的新旧分类，不能替代 GitHub 的 isOutdated 值。更改任何线程之前，请确认 PR 头仍为预期的当前 SHA。

解决线程之前，请检查当前代码，并对每个属于范围内的未解决线程进行分类：

• 对于 isOutdated: true，请确认当前头版本上问题已修复或不再相关。确认后才解决线程。除非额外说明有助于理解，否则无需回复 PR。如果问题仍然相关、含义不明确或需要用户决策，请保持线程未解决。
• 对于 isOutdated: false，绝不能默默解决。如果问题已修复或已过时，请先在同一审查线程中简洁说明，并提供当前头版本上的具体证据，例如处理该问题的函数或行为，以及相关测试。只有 GitHub 确认回复已发布后，才能解决线程。如果回复失败，请保持线程未解决并报告失败。
• 如果发现仍然有效、正确的修复方案不明确、证据不足，或解决需要产品、UX、公共 API 或架构方面的判断，请保持线程未解决。报告其永久链接以及线程仍未解决的原因。

不要仅凭 false_positive 分类就认为可以解决未过时的线程。只有当前头版本上的具体证据能够证明该问题已过时或不再适用时，才能解决；并且必须先在该线程中发布这些证据。

回复示例：

已在当前头版本中解决：addOrReplaceNewerTarget 现在委托给 mergeReopenTargetFields，当聚焦窗口目标替换事件派生目标时，该函数会保留 bundleId。此行为由 tools.test.ts 覆盖。

推送前自我审查

应用审查机器人提出的修复后、提交或推送前，请退一步，像另一位工程师编写了这些更改一样进行审查。不要因为补丁是你写的，就假定它是正确的。

审查完整的 git diff、每个已编辑的文件、相关调用点或测试，确认修复解决的是根本问题，而不只是机器人的示例，并检查是否引入了新的边界情况或测试缺口。

目标不是用完全部 8 轮，而是推送那些无需审查机器人和 CI 再次纠正的修复。

如果推送后出现新的、有效且可操作的机器人发现，请在下一次自我审查中深入检查：先重点审查差异，然后检查相关文件和测试；如果仍有遗漏，再检查模块级假设和故障模式。反复遗漏意味着本地审查缺少上下文；再次推送前，请放慢速度，检查更广泛的子系统。

等待规则

有选择地等待 GitHub。此技能用于推送后自动化审查 PR；对于常规实现工作，仓库的本地验证命令通常是更快的关卡。辅助工具会等待与 Claude、Devin 或审查模式匹配的检查，不应无限期阻塞在无关的 CI 上。

辅助工具的默认等待上限为 35 分钟，长于 Claude 审查工作流的 30 分钟作业上限。更改任一上限时，请保持两者协调一致。

辅助脚本

使用 scripts/review-bot-snapshot.mjs，而不是重写 GitHub API 命令。默认机器人是 Claude 和 Devin；如有需要，可使用 --bot-logins 或 REVIEW_BOT_LOGINS 覆盖。

常用选项：

node scripts/review-bot-snapshot.mjs --help
node scripts/review-bot-snapshot.mjs --wait
node scripts/review-bot-snapshot.mjs --wait --json
node scripts/review-bot-snapshot.mjs --pr 123 --bot-logins "claude[bot],devin-ai-integration[bot]"

最终回复

报告：

• 运行了多少轮审查机器人循环，
• 修复了哪些机器人评论，
• 拒绝了哪些评论或留待用户决定，并附上永久链接，
• 每条实质性机器人观察的分类和理由，
• 推送的提交 SHA，
• 最终验证命令及结果，
• 已解决的审查讨论串数量，
• 因 GitHub 标记 isOutdated: true 而静默解决的数量，
• 发布解释性串内回复后解决的数量，
• 所有仍未解决、保持打开状态的讨论串及其永久链接和理由。

如果没有剩余的有效评论，只有在对每条实质性观察完成分类后，才能直接说明这一点。如果审查检查超时，请说明已检查的内容以及仍未知的事项。