企业官网建设流程全解析

Storybook 的 handle-pr-comments Agent Skill：逐条处理 GitHub PR 评审评论的完整工作流

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

本文以 Storybook 仓库中的 handle-pr-comments Skill 定义 为主体，完整拆解这个编码代理技能的触发条件、四步工作流（定位 PR、GraphQL 拉取未解决评审线程、逐条交互式处理、汇总报告）与处理原则，并结合仓库中 AGENTS.md 及同目录其他 Skill 的实现，说明该技能在 Storybook 开源协作流水线中的位置与落地方式。读完后你可以掌握如何把一个"评审意见处理"流程沉淀为可复用、可交互、可审计的 Agent Skill。

Skill 在 Storybook 仓库中的位置

Storybook 在仓库根目录维护了一套面向编码代理（coding agents）的指令资产，集中在.agents/目录下：

• .agents/guidelines/— 代码注释与 JSDoc 规范；
• .agents/skills/— 各个可触发的技能定义，每个技能是一个独立目录，内含SKILL.md；
• .agents/plugins/— 代理插件的市场清单（marketplace.json 指向code/lib/codex-plugin/plugins/storybook）。

其中.agents/skills/下已沉淀了十余个与研发流程强相关的技能，覆盖 PR 全生命周期：创建 PR（pr、open-pr）、修复 PR 上的 lint 与类型错误（fix-linting-types-on-pr）、更新 PR 描述（update-pr-description）、canary 发布（canary）、minor 版本发布（minor-release）等，而handle-pr-comments正是这条流水线中"评审反馈处理"环节的自动化实现。

按照 AGENTS.md 的约定，该文件是整个仓库"编码代理指令的规范来源（canonical instruction source）"，而CLAUDE.md等内容文件只以一行引用（@AGENTS.md）指向它、不复制指令——handle-pr-comments这类 Skill 文件正是遵循同样的"单一事实来源"思想：每个流程只在一处定义，其他入口引用它。

SKILL.md 的结构：frontmatter 定义触发语义

SKILL.md 采用 Markdown + YAML frontmatter 的结构。frontmatter 有两个关键字段：

name: handle-pr-comments description: Triage and resolve GitHub PR review comments one by one, interactively. Use when the user asks to handle, address, respond to, or resolve PR review comments, or mentions reviewer feedback on a pull request.

• name：技能标识，与所在目录名一致（.agents/skills/handle-pr-comments/）；
• description：承担"触发路由"的职责——它同时描述了技能做什么（逐条分诊并解决 PR 评审评论、交互式进行）和何时被触发（用户要求处理/回应/解决 PR 评审评论，或提及 PR 上的 reviewer feedback 时）。代理框架正是依据这段描述把自然语言请求路由到该技能。

正文先给出一句总述，再展开编号工作流与 Notes 补充原则，整体只有 20 余行，但每一步都对应一个可执行动作或一个明确的判定标准，没有冗余叙事。

工作流第一步：定位 PR

技能的第一步规则很简洁：

1. 如果用户给了 PR 编号或 URL，直接使用；
2. 否则从当前分支推导，使用gh pr view查询当前分支关联的 PR；
3. 若不存在 PR 则停止（Stop if no PR exists），不做任何猜测性操作。

这一"找不到就停"的设计与同目录 fix-linting-types-on-pr 的 Step 1 一致（没有 PR 编号就问用户），是 Storybook 各 PR 类技能共同遵循的防御式风格：前置条件不满足时立即收敛，而不是继续执行后续可能产生副作用的步骤。

工作流第二步：用 GraphQL 拉取未解决评审线程

这是整个技能中技术含量最高的一步，原文要求：

Fetch unresolved review threads via the GraphQLreviewThreadsfield on the pull request — request each thread'sid,isResolved,isOutdated,path, andline, and comments. Filter toisResolved == false. (Use GraphQL, not REST: only it exposes threadids and resolution state.)

要点拆解：

• 数据源：Pull Request 对象上的reviewThreads字段。GitHub 把同一文件位置下的一串往来评论聚合为一个"评审线程（review thread）"，因此处理单位是"线程"而非单条评论——一个线程里可能包含评审人意见与作者的多次回复；
• 必取字段：
  • id：线程的全局节点 ID，后续解析（resolve）操作必须依赖它；
  • isResolved：线程是否已被标记解决，过滤条件即isResolved == false；
  • isOutdated：线程是否已过期（对应代码被改动后评论锚点失效），帮助判断该评论是否仍需处理；
  • path/line：评论锚定的文件路径与行号，是第三步"阅读周边代码"的定位依据；
  • comments：线程内的评论列表本身；
• 为什么必须是 GraphQL 而非 REST：原文明确指出，只有 GraphQL API 暴露了线程的id与解析状态（resolution state）。GitHub REST 的 review comments 接口不返回 thread 粒度的 ID 和isResolved，也就无法执行"逐线程解决"的闭环。

从源码结构看，这一步拉到的path+line会在后续被代理用来读取仓库中的实际代码上下文，而 Storybook 这种大型 TypeScript monorepo（代码主体在code/，按addons/、builders/、renderers/、frameworks/分层，见 AGENTS.md 的 Repository Structure 一节）里，锚点定位准确与否直接决定了"摘要反馈"的质量。

工作流第三步：一次只处理一条评论的交互循环

技能的核心纪律是Loop one comment at a time——严格串行，一次只处理一个线程，每个线程走固定的 a→f 六小步：

其中两处设计值得强调：

1. AskQuestion的交互闸门。c 步的四个选项（apply suggested fix / apply a different fix / reply only / skip）把"代理建议"与"人类决策"显式分离：代理负责分析并给出默认推荐，但每一个有副作用的动作（改代码、提交、在 PR 上回复）都要经过用户确认。同目录 open-pr 技能在 frontmatter 中用allowed-tools: Bash, Read, AskQuestion声明了类似的能力边界——交互能力是这类技能的一等公民。
2. resolveReviewThread作为闭环信号。f 步使用专门的 mutation（而非普通 REST 调用）来解析线程，保证 PR 上的评论状态与本地实际处理结果一致：处理完一条，线程就被正式标记 resolved，下次再运行该技能时它不会再出现在待办列表里。这让技能本身是幂等且可重入的——中途被打断后重新触发，它只会继续处理剩余未解决的线程。

"一次一条"还带来了审计上的好处：每个线程对应一次明确的用户决策和（可选的）一次提交，评审意见与代码变更之间可以一一追溯。

工作流第四步：汇总报告

循环结束后，技能要求输出一份总览报告（Report），覆盖四类结果：

• 实际修改了什么（what was changed）；
• 哪些改动被提交了（committed）；
• 哪些只是回复了评论（replied to）；
• 哪些被跳过、哪些线程被解析（skipped and resolved）。

并且必须附带链接（Include links）——通常指向具体线程或提交，让评审人可以点击核对。这与 Storybook 对 PR 类产出的整体风格一致：pr 技能 要求 PR 描述逐字复制官方模板、Manual testing 步骤必须可复制粘贴，open-pr 技能 在创建 PR 后要把 PR URL 明确分享出来——"可核对的引用链接"是这条技能链的通用验收标准。

Notes：三条处理原则的深意

SKILL.md 末尾的 Notes 给出了三条补充原则，每一条都针对多代理评审场景下的真实痛点：

1. 真人评论优先于 AI 代理评论（"Handle real-user comments before addressing AI agents' (Copilot, CodeRabbit)."）。当前大量 PR 会同时收到人工评审与 Copilot、CodeRabbit 等 AI 评审工具的评论。技能要求先消化真人意见再处理机器意见，因为真人反馈往往承载设计决策，AI 反馈更偏模式化提示；先处理后者的话，AI 意见可能基于已被真人否定的方向。
2. 重复合并处理（Group duplicate comments）。同一/相似问题被多次指出时，一次性统一处理并统一解决所有相关线程，避免对同一根因做 N 次重复改动。
3. 每个变更一个独立提交（Make a separate commit for each change）。这条与逐条处理循环天然咬合：一条线程 → 一次改动 → 一次 commit → 一次 resolve，使得评审线程与 commit 历史形成一一映射，回滚或 cherry-pick 时粒度清晰。

与仓库工程约定的衔接

handle-pr-comments并非孤立存在，它隐含依赖了 Storybook 仓库若干工程约定，这些约定都由 AGENTS.md 定义：

• 基础分支是next而非main：所有 PR 应指向next，技能从当前分支推导 PR 时，该分支必然基于next切出；
• 提交与格式化钩子：仓库的 pre-commit hook 会通过std-env自动检测 AI 代理身份，把格式化检查从 check-only 切换为 write 模式，由 oxfmt 自动修复格式（cd code && yarn fmt:write是手工路径）。因此技能 e 步"询问是否 commit"之后，提交的格式一致性由钩子保证，无需代理手动格式化；
• 验证手段：改动落到具体包后，代理可用yarn nx run-many -t check（TypeScript 检查）与聚焦的yarn test <pattern>验证修复是否成立——这正是步骤 b"给出具体修复方案"时判断方案可行性的依据；
• QA 标签约定：pr 技能 要求每个 PR 打上qa:needed/qa:skip标签告知发布团队是否需要人工 QA。处理完评审意见后的 PR 若触发了行为变化，该标签可能需要随之复核，这也说明评论处理环节与发布流程是耦合的。

从源码结构看，handle-pr-comments与update-pr-description（对照 PR 标题/描述与实际 diff 的偏差并迭代修订）、fix-linting-types-on-pr（checkout PR 后批量修复 lint/TS 错误并推回）三者恰好覆盖"评审意见 → 描述修正 → 质量门禁"三个相邻环节，且共享ghCLI + 交互式确认 + 独立 commit 的同一套模式，构成 Storybook 仓库中一个完整的 PR 协作技能族。

使用前提与运行方式

• 运行环境：技能面向能执行 shell 命令、读写文件并与用户交互式提问的编码代理运行，需要本机安装并登录ghCLI（GraphQL 查询与resolveReviewThreadmutation 均经 GitHub 认证接口执行）；
• 触发方式：在代理对话中直接表达意图即可，例如"处理一下这个 PR 的评审意见"或"回应并解决 PR #1234 上的 reviewer 反馈"——frontmatter 的 description 已把这些措辞列为触发词；
• 适用前提：当前分支已推送且存在关联 PR（否则按第一步规则直接停止）；操作者对该 PR 有权限回复与解决线程；
• 行为边界：技能全程不越权决策——每条评论的处置方式由用户在 AskQuestion 中四选一确定，提交与否由用户确认，最终状态以 PR 上的线程解析记录为准。

小结

handle-pr-comments展示了把一项高频、琐碎、强交互性的维护工作（处理 PR 评审评论）沉淀为 Agent Skill 的完整范式：frontmatter 的 description 承担触发路由；工作流拆成"定位 PR → GraphQL 拉取未解决线程 → 单条串行处理（摘要、建议、确认、执行、提交、resolveReviewThread）→ 汇总报告"四个可验证阶段；Notes 用真人优先、重复合并、独立 commit 三条原则处理多代理评审的现实复杂度。配合 AGENTS.md 的仓库级约定与.agents/skills/下其他 PR 技能，它使"评审反馈闭环"在 Storybook 这样的多人多代理协作仓库中成为可重复、可审计、可随时中断续跑的标准化流程。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook