load-pr-comments

将未解决的 PR 审查评论加载为并行任务

仅加载仍处于开放／未解决状态的 PR 审查讨论串，并将其改写为 .specs/comments/*.md 下分组的 Markdown 任务文件，确保每个文件都适合由单独的并行 Agent 实现，且互不重叠。

关键指南

• 你必须仅加载已解决状态为 false 的讨论串。跳过已解决的讨论串。
• 你必须将每条评论改写为可执行的任务要求，而非摘要。原样保留实质内容（代码建议、确切指令）。
• 你不得在 GitHub 上发布、回复或修改任何内容。此技能仅以只读方式访问 API。
• 你必须对评论进行分组，使每个文件都可独立实现，且文件之间没有重复内容。

步骤 0：确认可用工具

1. 检查是否已安装并完成身份验证的 GitHub CLI：

   gh auth status
   

2. 检查 GitHub MCP 服务是否可用：

   mcp__MCP_DOCKER__pull_request_read
   

   或者，如果已直接安装，则使用不带 MCP_DOCKER 前缀的类似命令。

• 如果两者都可用，则使用对该仓库拥有足够访问权限的任一工具。
• 如果 GitHub MCP 服务可用但结构不同，则调整以符合预期结构。
• 如果两者都不可用，尝试通过 curl 直接加载，以防仓库是公开的。如果仓库是私有的，请让用户安装 GitHub CLI 或 GitHub MCP 服务。
• 如果尚未安装 MCP 服务，但已安装 GitHub CLI 且尚未完成身份验证，请让用户运行 gh auth login 进行身份验证。

步骤 1：确定目标 PR

• 明确指定的 PR 参数始终优先于当前分支解析。如果传入了 PR 编号或 URL，则使用它（例如 URL https://github.com/{owner}/{repo}/pull/{n} → 编号 {n}），不要查询当前分支。
• 否则，默认使用当前分支对应的 PR：

gh pr view --json number,url,headRefName   # current branch's PR

• 确定仓库所有者／名称：gh repo view --json owner,name。
• 如果该分支没有对应的 PR，gh pr view 会报错并显示 "no pull requests found" — 停止并说明该分支没有关联的 PR（请用户提供 PR 编号／URL）。

步骤 2：获取未解决的评论

已解决／未解决是 GraphQL reviewThreads { isResolved } 的概念 — REST /pulls/{n}/comments 端点不会提供此信息。使用以下两种方法之一；如果首选方法不可用，则改用另一种。

首选：gh CLI（GraphQL）

直接在 jq 中筛选 isResolved == false：

gh api graphql -f query='
query($owner:String!,$repo:String!,$pr:Int!){
  repository(owner:$owner,name:$repo){
    pullRequest(number:$pr){
      reviewThreads(first:100){
        nodes {
          isResolved
          isOutdated
          path
          line
          startLine
          originalLine
          comments(first:50){
            nodes { author{login} body diffHunk url }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F repo=REPO -F pr=PR_NUMBER \
  --jq '[.data.repository.pullRequest.reviewThreads.nodes[]
         | select(.isResolved==false)
         | {path, isOutdated,
            line: (.line // .startLine // .originalLine),
            comments: [.comments.nodes[]
             | {author: .author.login, url, body, diffHunk}]}]'

这会返回每个未解决讨论串的文件 path、isOutdated 标志、可用的 line，以及按顺序排列的评论（作者、正文、永久链接 url、diffHunk）。

重要：对于过时的讨论串，line 为 null（差异位置已移动）。上述 jq 已通过 line // startLine // originalLine 进行回退，因此只要存在任一锚点，line 就不会为 null。当这三者全为 null 时，请在模板中省略 :<line> 部分 — 绝不要输出 path:null。

回退：GitHub MCP

如果 GitHub MCP 服务（MCP_DOCKER）可用，请使用 mcp__MCP_DOCKER__pull_request_read 工具，并设置 method: "get_review_comments"：

mcp__MCP_DOCKER__pull_request_read
  method: "get_review_comments"
  owner: "OWNER"
  repo: "REPO"
  pullNumber: PR_NUMBER
  perPage: 100

它会返回 review_threads[]，其中包含 is_resolved、is_outdated、is_collapsed（均为 snake_case — 已通过该工具的响应确认）以及 comments[]（body、path、author、html_url）。仅保留 is_resolved 为 false 的讨论串。注意，MCP 评论对象会提供 path，但不会提供行号，因此请使用 html_url 作为位置锚点。当 pageInfo.hasNextPage 为 true 时，使用 after: <endCursor> 翻页。

第 3 步：分组并改写为任务

将未解决的讨论串转化为聚焦的任务文件，供多个 Agent 并行处理。

先去重（分组前）：如果两个或多个讨论串在同一 path 的相同或重叠行请求相同变更，或提出完全相同的修复建议，就将它们合并为一条需求。不要针对重复的讨论串分别输出条目——这对于反复出现琐碎建议的 nitpick 文件尤其重要。

逐条改写规则：

• 删除对话背景和作者姓名。输出任务，而不是对话记录。
• 如果 HUMAN 审查者留下了反馈，就将其写为需求。
• 如果只有机器人或 AI 提出了建议（Claude、CodeRabbit、Copilot 等），就将该修复建议写为需求。
• 保留实质内容——不要省略代码块、建议的差异或精确措辞。
• 补充上下文：简短的问题描述，以及指向文件/行的链接（评论的 url/html_url，以及 path:line，如果有）。如果 line 为 null（过时/无法锚定的讨论串），只写 path，不加 :line，并注明该评论已过时。

前后示例（牢记“改写为任务，不要概括”）：

• 原始讨论串（机器人）：“commands is incorrect, real commands is more like /add-task /plan-task /implement-task”
• 任务需求：“- [ ] 将列出的命令替换为正确的命令：/add-task、/plan-task、/implement-task”（保留原建议，删除对话背景——而不是写成“修复命令”。）

分组规则：

• 按文件或功能分组，确保两个 Agent 不会修改同一区域 → 不产生冲突、不重复工作。
• 不要在多个文件中重复同一条评论。
• 将 nitpick / 琐碎的单行修改汇总到一个文件中（例如 nitpicks.md）。
• 总文件数不得超过 5 个。不要过度合并无关的变更——每个文件都必须是聚焦且可独立实施的工作单元。

第 4 步：处理 .gitignore

确保生成的评论文件已被忽略。此操作具有幂等性：仅在条目不存在时追加，且 >> 会在 .gitignore 不存在时创建该文件。

grep -qF '.specs/comments/*.md' .gitignore 2>/dev/null || printf '\n.specs/comments/*.md\n' >> .gitignore

第 5 步：写入文件

mkdir -p .specs/comments

将每个分组写入 .specs/comments/<kebab-topic>.md，并使用以下模板：

# Tasks: <focused topic, e.g. Fix incorrect command names in README-zh>

## <Topic 1>

File: `<path>:<line>` (omit `:<line>` when line is null; append " (outdated)" if isOutdated)
<Issue description for the change>

### Requirements

- [ ] <Reviewer requirement or bot fix suggestion, substance preserved>
- [ ] <Next requirement in this topic>

## <Topic 2>

File: `<path>:<line>` 
<Issue description for the change>

### Requirements

- [ ] <Reviewer requirement or bot fix suggestion, substance preserved>
- [ ] <Next requirement in this topic>

第 6 步：报告

汇总：目标 PR（编号 + URL）、已加载的未解决讨论串数量、创建的文件及其主题，以及跳过的讨论串（已解决）或遇到的限制（例如 MCP 不可用）。

边缘情况

情况	处理方式
当前分支没有 PR	gh pr view 报错 → 报告此情况并请求提供 PR 编号/URL
参数是 URL	提取 /pull/ 后面的末尾编号
未解决讨论串为零	不创建文件；报告“没有未解决评论”
超过 100 个讨论串	使用 GraphQL after 游标 / MCP after 分页
MCP 不可用	使用 gh GraphQL；如果两者都不可用，报告限制
只有已解决的讨论串	全部跳过；报告没有可处理项