fusion-github-review-resolution

解决 GitHub 审查评论

使用时机

当拉取请求中有尚未解决的行内审查评论，并且你需要一套可重复、可审计的关闭流程时，使用此技能。

典型触发条件（此技能应在以下所有情况下启用）：

URL 模式 — 立即启用：

• https://github.com/<owner>/<repo>/pull/<number>#pullrequestreview-<id>
• https://github.com/<owner>/<repo>/pull/<number>（上下文表明需要处理审查时）

明确的用户请求：

• “修复审查评论”
• “处理此 PR 的审查反馈”
• “有尚未解决的审查评论——请修复”
• “解决此 PR 中的讨论”
• “处理此 PR 中所有尚未解决的评论”
• “针对每条审查评论：修复、测试、提交、回复并解决”
• “关闭未结束的审查讨论”
• “查看此审查，并在修复后解决讨论”
• “解决尚未处理的审查反馈”
• “此 PR 被要求修改——请修复”

隐含触发 / Agent 检测到的情况：

• PR 处于“要求修改”状态，且 Agent 被要求处理该 PR
• PR 中有尚未解决的审查讨论，且用户要求改进或合并该 PR
• Agent 处理 PR 时发现有未结束的审查讨论

不适用情形

• 没有尚未解决的审查评论
• 请求仅要求总结或描述反馈，不涉及代码更改
• 所有目标讨论都已解决，或已过时且得到确认
• 分支 / 工作树有意设为只读

必需输入

执行前收集：

• 仓库所有者 / 名称
• 拉取请求编号或 URL
• 可选的审查 ID，用于限定评论范围（例如 pullrequestreview-<id>）
• 分支 / 工作树选择（如果当前检出已位于 PR 的头部分支，则无需询问——见步骤 1）
• 仓库所需的验证命令

提供审查 URL 时（github.com/<owner>/<repo>/pull/<number>#pullrequestreview-<id>）， 自动从中提取所有者、仓库、PR 编号和审查 ID。 仍需确认的只有分支 / 工作树选择和验证命令。

可选：

• 关联问题的引用（例如 equinor/fusion-core-tasks#432）
• 当多条评论涉及同一文件时，对提交粒度的偏好

说明

除非用户明确要求采用不同顺序，否则请按以下阶段顺序执行：获取 → 分析 → 修复 → 验证 → 推送 → 回复 → 解决 → 核实。不要在代码编辑重试期间穿插修改 GitHub 讨论串。

1. 确定分支 / 工作树上下文

   • 首先将当前检出的分支与 PR 的头部分支进行比对。
   • 如果当前分支已与 PR 的头部分支匹配，直接在该分支上继续——不要询问是否使用工作树。
   • 否则（当前分支不同，或工作区位于 main / master 等共享的长期分支上），在询问其他工作流问题之前，先询问是否使用专用的 git 工作树。
   • 如果用户同意，则使用或创建该工作树，并在其中继续。

2. 收集未解决的评论并创建工作跟踪文档

   • 如果提供了带有 #pullrequestreview-<id> 的评审 URL，请在获取内容前从中解析所有者、仓库、PR 编号和评审 ID。
   • **复制或打开 assets/review-resolution-checklist.md——将其作为工作文档。**填写上下文部分，并在处理每个讨论串时更新评论跟踪表。
   • 获取该 PR 的评审讨论串，并筛选出未解决的讨论串。
   • 如果提供了特定的评审 ID 或评审 URL，则仅处理该评审中的评论。
   • 在目标评审中，收集与该评审 ID 关联的所有评论（除非明确要求，否则不包括其他评审的回复）。
   • 创建工作列表，包含：讨论串 ID、评论 ID、父评审 ID、文件路径、原始评论内容，以及该讨论串中的所有后续回复（包括贡献者的回复）。
   • 阅读每个讨论串的完整回复链——贡献者可能补充了澄清、限制条件或其他上下文；决定如何解决评论时，必须将这些内容考虑在内。
   • 在进行任何 GitHub 修改前，记录目标讨论串 ID 列表和未解决讨论串数量的基线。

3. 理解、调查并判断每条评论

   • 阅读相关文件及其附近的逻辑。
   • 根据当前代码、要求和上下文，判断反馈是正确、部分正确、已过时还是不正确。
   • 评审者的意见不一定正确；不要仅为了满足过时或错误的评论而改动代码。
   • 如果反馈正确，请核实根本原因并找出最小且安全的修复方案。
   • 如果反馈明显不正确或已过时，请准备简洁、基于证据的回复，而不是不必要地更改代码。
   • 如果不确定，请在编辑前检查相邻的测试和用法。
   • 如果经过本地调查后仍有疑问，请在更改代码或修改该评审讨论串前询问用户。

4. 逐条评论修复、检查并提交

   • 仅针对你判定为有效或部分有效的评论，进行有针对性的代码或文档更改。
   • 先运行针对性检查，再运行仓库要求的检查。
   • 尽可能为每条评论创建一个提交。
   • 如果两条评论需要通过一个不可拆分的更改来解决，则使用一个提交，并在回复中将两条评论都关联到该提交。
   • 对于不予采纳的评论，在跟踪文档中记录理由，以便最终回复明确且可审计。

5. 所有修复完成后推送一次

   • 创建所有与评论相关的提交后，一次性推送分支更新。

6. 回复并解决每条审查评论

   • 在修改任何讨论串之前，优先按以下顺序使用结构化工具：
     1. 当前客户端会话中提供的专用 GitHub MCP 审查讨论串回复／解决工具，
     2. 随附的 GraphQL 资源或随附的 scripts/resolve-review-comments.sh，
     3. 绝不使用临时编写的 Python 脚本、一次性批处理辅助工具或盲目重试的 gh api 循环。
   • 发布任何内容之前，先根据清单／跟踪表为每个目标讨论串准备且仅准备一条计划回复。
   • 如果回复／解决尝试报错、超时或结果不确定，重试前重新获取当前讨论串状态。
   • 对每个讨论串，以下两个步骤都必须按顺序紧接着完成，除非讨论串仍不确定且正在等待用户输入：
     1. 在讨论串中发布回复：说明做了哪些更改并附上提交哈希，或解释为什么评论有误／已过时，因此没有修改代码。
     2. 发布回复后立即解决讨论串——绝不可先解决。
   • 每次运行中，每个讨论串最多尝试发布一次回复。
   • 如果已有内容等效的 Agent 回复，不要再发布回复；复用该回复，并仅在讨论串仍未解决时解决它。
   • 如果已有不同的 Agent 回复，停止操作并手动检查，不要叠加另一条评论。
   • 讨论串仍不确定时不要解决；应先升级给用户处理。
   • 绝不可在没有回复的情况下解决讨论串。发布回复后绝不可不解决讨论串。
   • 回复要具体：指出更改的文件／行以及提交，不要只说“已修复”。

7. 验证关闭状态

   • 重新检查审查讨论串，确认没有目标未解决讨论串残留。
   • 确认目标未解决讨论串数量已降至零，并且本次运行没有产生重复的 Agent 回复。
   • 如果工作流要求检查通过，重新检查最新 CI 状态。

8. 询问是否要邀请原审查者进行新一轮审查

   • 修复已推送且讨论串已解决后，询问用户是否要邀请审查评论的作者进行新一轮审查。
   • 如果用户同意，向该审查者的用户名发送审查请求，并报告请求已发送。

9. 可选的脚本执行

   • 使用 scripts/get-review-comments.sh 获取匹配的审查评论（包括与审查 ID 关联的子评论）。
   • 结果最多包含前 100 个审查讨论串，以及每个讨论串的前 100 条评论。
   • 测试示例：
     • skills/.experimental/fusion-github-review-resolution/scripts/get-review-comments.sh --owner equinor --repo fusion-skills --pr 27 --review-id 3837647674
   • 需要获取匹配的过时讨论串中的评论时，使用 --include-outdated。
   • 使用 scripts/resolve-review-comments.sh 回复并解决匹配的讨论串；该脚本会先执行试运行，并防止重复回复。
   • 保持默认的试运行行为；仅在修复已提交并推送后使用 --apply。
   • 默认情况下，如果讨论串中已有经身份验证的用户发布的回复，脚本会拒绝再添加一条；仅在手动检查后使用 --allow-additional-reply。
   • 试运行示例：
     • skills/.experimental/fusion-github-review-resolution/scripts/resolve-review-comments.sh --owner equinor --repo fusion-skills --pr 27 --review-id 3837647674 --include-resolved
   • 执行示例：
     • skills/.experimental/fusion-github-review-resolution/scripts/resolve-review-comments.sh --owner equinor --repo fusion-skills --pr 27 --review-id 3837647674 --apply --message "Addressed in <commit>: <what changed>."

工具使用指南（MCP 与 GraphQL）

使用 GitHub MCP 工具执行高级 PR 操作，以及当前客户端提供的专用审查线程变更操作。MCP 支持不足时，使用 GraphQL 执行线程级审查操作。

工作流操作	首选工具	说明
请求审查者／更新 PR 元数据	mcp_github_update_pull_request	适用于协作者审查者和标准 PR 更新。
创建或提交 PR 审查	mcp_github_pull_request_review_write	处理待处理审查的生命周期操作。
添加一般 PR 评论	mcp_github_add_issue_comment	在 PR 对话中添加 issue 式评论，而非内联线程回复。
列出审查线程和评论	assets/pull-request-review-threads.graphql	使用 gh api graphql -f query=@assets/pull-request-review-threads.graphql 获取线程级上下文。
统计特定审查 ID 的未解决线程	assets/unresolved-thread-count-for-review.graphql	对响应进行后处理（例如使用 jq），按审查 ID 和未解决状态筛选。
回复审查线程	Dedicated MCP review-thread reply tool，否则使用 assets/add-pull-request-review-thread-reply.graphql	如果有 MCP 工具，优先使用；否则使用随附的线程范围变更，而不要编写临时脚本。
解决审查线程	Dedicated MCP review-thread resolve tool，否则使用 assets/resolve-review-thread.graphql	使用与当前客户端／会话匹配的结构化工具。⚠️ GraphQL 注意事项：resolveReviewThread 使用 threadId，而非 pullRequestReviewThreadId。
列出 PR 审查（支持按审查 URL／ID 查找）	assets/pull-request-reviews.graphql	从审查 URL 上下文开始时很有用。

专业提示： 查看 assets 中的每个 .graphql 文件，了解完整的变更／查询语法和参数名称。

GraphQL 成本注意事项

解决审查的工作流会多次调用 GraphQL 变更（每个线程都要回复并解决）。请谨慎操作：

• 每次变更消耗 5 个次级速率限制点（读取查询为 1 点）。处理多个线程时请做好预算。
• 连续变更调用之间至少暂停 1 秒，以避免触发次级速率限制。
• 将连接参数 first／last 设得较小（仅在需要一次获取单页中的所有线程时，才优先使用 first: 100）。
• 如果返回次级速率限制错误或 retry-after 标头，请停止处理，并在重试前遵守指定的等待时间。
• 如果客户端提供专用 MCP 审查线程工具，始终优先使用该工具，而不是原始 GraphQL。

Token 预算指南

• 获取一次完整线程列表，并在所有逐线程操作中重复使用；回复和解决之间不要重新获取线程。
• 预算估算：对于 N 个未解决线程，预计需要约 1 次列表调用 + N 次回复变更 + N 次解决变更 = 1 + 2N 次调用。审查 10 个线程约需 21 次调用。
• 如果线程数超过 15 个，在开始变更前告知用户存在速率限制风险，并提议分小批处理。
• 从首次获取的数据中缓存 PR 元数据（标题、分支、CI 状态、已更改文件），并在提交消息和回复中重复使用。
• 避免在各步骤之间重复读取 PR 级信息；单次解决流程中这些数据不会变化。

预期输出

返回简明报告，包含：

• 已处理的评论数，
• 处置摘要（已修复、有理由地拒绝、已升级给用户），
• 已更改的文件，
• 提交列表（哈希 + 消息），
• 已运行的验证命令及其结果，
• 推送确认，
• 每个线程的回复／解决确认，
• 已完成的清单位置，
• 任何仍未解决的线程或阻碍。

关联 issue 的使用

提供 issue 时（例如 equinor/fusion-core-tasks#432）：

• 在进度／最终摘要中提及该 issue，
• 确保实现符合 issue 范围，
• 避免扩展到无关的 PR 自动化。

安全与约束

• 此技能具有修改能力。发生冲突时，仓库本地的工作流说明优先于内联指引。
• 切勿在日志或回复中暴露机密或令牌。
• 优先使用基于 argv 的进程执行方式，而非通过 Shell 插值的命令字符串。
• 保持差异精简，仅限于审查反馈相关内容。
• 不要假定审查反馈正确；应先结合代码和要求进行判断。
• 如果经过调查后意见仍有歧义，请询问用户，而不是自行猜测。
• 在发布具体的修复回复之前，不要解决讨论串。
• 除非确实运行过命令，否则不要声称检查已通过。
• 不要强制推送；使用常规提交，并在所有修复完成后一次性推送。
• 如果评论已过时但仍未解决，请：
  • 附上清晰说明和提交引用后解决；或
  • 保持未解决，并说明原因。
• 在脚本模式下，保留默认的试运行行为，并要求显式使用 --apply 才能进行修改。