前言¶
Pull Request 合并前的 Code Review，往往是开发流程里最耗心力的一环。Reviewer 在 diff 上留下 inline 评论、在 Conversation 里补充说明、再发一条 Request changes——评论散落在 GitHub 网页的不同区域。开发者需要在浏览器和 IDE 之间来回切换，逐条对照「谁说了什么、改哪一行、是否已 resolved」，改完还要自己核对有没有漏掉某条 thread。
如果你已经在用 AI 编程 Agent 写代码、跑测试，PR 评论处理却仍是纯手工，上下文切换的成本就更高了。gh-address-comments 是 OpenAI 在 openai/skills 仓库 skills/.curated/ 目录下维护的精选 Skill，专门把「拉取 PR 评论 → 人工筛选 → Agent 改代码」这条链路标准化。它不是一键全自动吞掉所有 review，而是保留人工判断的同时，把机械部分交给 Agent 和 gh CLI 完成。
gh-address-comments 是什么¶
gh-address-comments 是一个基于通用 SKILL.md 格式的 Agent Skill，由 OpenAI 维护，归类为 Codex curated（精选）技能。其官方描述为：
Help address review/issue comments on the open GitHub PR for the current branch using gh CLI; verify gh auth first and prompt the user to authenticate if not logged in.
一句话定位：在当前 Git 分支关联的 open PR 上，借助 GitHub CLI（gh）拉取全部 review 与 issue 评论，经用户确认后再逐条修改代码。
它解决的核心痛点是：PR 评论来源多（Conversation 评论、Review 提交、inline review thread），手动汇总费时且易漏；Agent 若缺少固定流程，又可能误改需要人工裁决的反馈。该 Skill 用脚本统一抓取、用编号清单呈现、让用户勾选后再动手——属于典型的 human-in-the-loop 工作流设计。
说明：openai/skills 仓库 README 标注该仓库已 deprecated，后续 Codex 插件示例迁移至 openai/plugins。但
gh-address-comments仍可从原仓库获取，安装方式与SKILL.md内容以仓库内文件为准。
核心功能与工作流程¶
官方 SKILL.md 将执行流程分为三步，并附带一个 Python 辅助脚本。
第一步：检查待处理评论¶
Agent 运行 Skill 目录下的 scripts/fetch_comments.py，拉取当前分支关联 PR 上的全部评论数据。脚本通过 gh api graphql 发起 GraphQL 查询，分页抓取三类内容：
- Conversation comments：PR 顶层的 issue 式讨论评论
- Reviews：Approve / Request changes / Comment 等 review 提交及其正文
- Review threads：inline 行级评论线程，包含
isResolved、isOutdated、文件路径、行号等元数据
脚本会先调用 gh auth status 确认 CLI 已登录，再通过 gh pr view --json number,headRepositoryOwner,headRepository 解析当前分支对应的 PR（支持跨仓库 PR）。输出为 JSON，可重定向保存：
python scripts/fetch_comments.py > pr_comments.json
第二步：编号汇总，请用户选择¶
Agent 将所有 review thread 和 comment 逐条编号，并为每条附上一句「若要修复，需要做什么」的摘要，然后询问用户：哪些编号需要处理？
这一步是设计亮点：并非 Agent 自行决定改什么。涉及架构取舍、产品语义、是否接受建议等需要人拍板的评论，可以留在清单里不选；明确的技术修正（命名、边界检查、测试补充等）则勾选后交给 Agent。
第三步：按选择修改代码¶
用户确认编号后，Agent 根据评论上下文理解 diff 位置与意图，在本地仓库应用对应修改。具体改法依赖 Agent 的代码理解能力，Skill 本身不硬编码修复逻辑——它规范的是流程，而非某一种固定补丁模板。
认证与权限前置条件¶
Skill 要求在使用前完成 gh 认证，并建议以提升权限运行 gh auth status（包含 workflow / repo 等 scope），确保后续 gh api graphql 不被沙箱或权限不足阻断。运行中若遇到 auth 或 rate limit 问题，应提示用户重新执行 gh auth login 后重试。Codex 环境下，官方还注明所有 gh 命令需要 elevated network access（网络访问提升权限）。
目录结构¶
从 官方仓库目录 可见，该 Skill 包含：
| 路径 | 说明 |
|---|---|
SKILL.md |
技能定义与三步工作流 |
scripts/fetch_comments.py |
通过 gh api graphql 拉取 PR 评论的辅助脚本 |
agents/ |
Agent 相关配置目录 |
assets/ |
附加资源 |
LICENSE.txt |
许可证文件 |
fetch_comments.py 是整套 Skill 的技术核心：它不依赖额外 Python 包，仅通过 subprocess 调用 gh，GraphQL query 覆盖 comment、review、reviewThread 三类节点并支持 cursor 分页，适合评论较多的大型 PR。
安装与启用¶
在 OpenAI Codex 中安装¶
根据 openai/skills README 与 Codex Skills 文档，curated 技能可通过 Codex 内置安装器一键拉取：
$skill-installer gh-address-comments
也可指定 GitHub 目录 URL 安装：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/gh-address-comments
安装后若未出现在技能列表，重启 Codex。在 CLI 中也可输入 /skills 浏览并手动选用已安装技能。Codex 的全局技能目录为 ~/.agents/skills/，仓库级为 .agents/skills/。
在 Cursor 中使用¶
Cursor 支持通用 Agent Skills 格式。将 gh-address-comments 文件夹（含 SKILL.md 与 scripts/）放入以下任一目录即可被自动发现：
- 项目级：
.cursor/skills/gh-address-comments/或.agents/skills/gh-address-comments/ - 全局：
~/.cursor/skills/gh-address-comments/或~/.agents/skills/gh-address-comments/
常见做法是从官方仓库复制对应目录，或 sparse checkout 只拉取该 Skill 子路径。Cursor 启动时会扫描上述路径；也可在 Agent 对话中输入 /gh-address-comments 显式调用。
环境前置：GitHub CLI¶
无论在哪款 AI 编程工具中使用，都需要先安装并登录 GitHub CLI：
# 一次性登录
gh auth login
# 确认状态（Skill 要求运行前验证）
gh auth status
当前分支必须已关联一个 open 状态的 PR；若分支尚无 PR 或 PR 已合并关闭，脚本无法解析目标 PR。
典型用法示例¶
场景：PR 收到多条 inline 评论¶
假设你正在功能分支 feat/oauth-refresh 上开发，同事在 PR 上留了 8 条 inline 评论和 2 条 Conversation 说明。在 Codex 或 Cursor Agent 对话中可以这样触发：
请使用 gh-address-comments 技能，处理当前分支 PR 上的 review 评论。
先拉取全部评论并编号汇总，我再告诉你改哪几条。
Agent 按 Skill 流程执行后，可能返回类似下面的摘要（示意）：
1. [inline] src/auth/token.go:42 — 建议对 refresh token 做空值检查
2. [inline] src/auth/token.go:78 — 错误信息不应暴露内部 ID
3. [review] @reviewer — Request changes：补充单元测试覆盖过期场景
...
请选择需要处理的编号（如 1,2,3）。
你回复 1,2,3 后，Agent 在本地修改对应文件，并可继续协助跑测试、提交 commit。
单独运行抓取脚本¶
即使不通过 Agent，也可在 Skill 目录下手动查看 PR 评论全貌：
cd skills/.curated/gh-address-comments
python scripts/fetch_comments.py | jq '.pull_request, (.review_threads | length)'
这在调试「Agent 是否漏了某条 thread」时很实用——JSON 里包含 isResolved、path、line 等字段，便于与 GitHub 网页对照。
适用场景与注意事项¶
适合使用的场景：
- 当前分支已有 open PR，且 review 评论分布在多个 thread，需要系统化汇总
- 希望 Agent 协助改代码，但想保留「选哪些评论要改」的控制权
- 团队已统一使用
ghCLI，本地认证与仓库权限配置成熟 - 与 Codex 其他 GitHub 类 Skill（如
gh-fix-ci、yeet）组合，形成「改评论 → 修 CI → 提交 PR」的自动化链路
需要注意的限制：
- 非全自动：Skill 明确要求用户选择编号，不会静默修改所有 review 意见
- 依赖 open PR：脚本通过
gh pr view解析当前分支 PR，无 PR 或 PR 已关闭则无法工作 - 修复质量取决于 Agent：Skill 规范流程，具体 patch 是否正确仍需人工 review 或 CI 验证
- 网络与权限：Codex 沙箱下
gh可能需要提升权限；auth scope 不足会导致 GraphQL 查询失败 - 仓库迁移：
openai/skills已标记 deprecated，长期分发可能转向 plugin 形态，但 Skill 内容与安装命令仍以官方仓库为准
在同属 OpenAI curated 系列的 Skill 中，gh-fix-ci 侧重修复 GitHub Actions 失败检查，yeet 侧重一键 stage/commit/push/开 PR；gh-address-comments 则聚焦 review 评论消化，三者互补，覆盖 PR 生命周期不同阶段。
小结¶
PR Code Review 的难点从来不只是「改几行代码」，而是找全评论、理解上下文、决定改不改。gh-address-comments 用 fetch_comments.py + gh GraphQL 把评论抓取标准化，用编号清单把决策权留给开发者，再让 Agent 执行选定的修改——在自动化与可控之间取得了平衡。
若你使用 Codex，可直接 $skill-installer gh-address-comments 安装；若使用 Cursor，将 Skill 目录放入 .cursor/skills/ 即可。官方资料：
- Skill 目录：https://github.com/openai/skills/tree/main/skills/.curated/gh-address-comments
- Codex Skills 文档：https://developers.openai.com/codex/skills
- Agent Skills 开放标准：https://agentskills.io
