企业官网建设流程全解析

Storybook Agent 技能实战：用 github-qa-labels 规范 GitHub QA 问题的标签工作流

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

本文以 Storybook 官方仓库内置的 Agent 技能文件 github-qa-labels/SKILL.md 为核心，完整解读 Storybook 团队在版本升级 QA（Quality Assurance）测试中，如何借助ghCLI 对发现的 Issue 和 PR 施加统一的跟踪标签（upgrade:<version>）与严重等级标签（sev:S1–sev:S4），并结合仓库中真实的技能体系结构、canary 发布流程与升级命令，说明这套标签规范在 Storybook 研发流水线中的定位、适用边界与批量操作技巧。读完后，你可以直接复现一套可追溯的版本 QA 问题归档流程，并理解该技能在多 Agent 协作框架（Claude Code / Codex 插件）中是如何被装载和引用的。

技能文件的位置与加载机制

github-qa-labels是 Storybook 仓库为编码 Agent 预置的一组技能（Skills）之一。它的入口文件位于.claude/skills/github-qa-labels/SKILL.md，但打开该文件会发现它只有一行内容：

@../../../.agents/skills/github-qa-labels/SKILL.md

这是一个引用声明：.claude/skills/下的 12 个技能文件全部以同样的方式指向.agents/skills/目录下的同名技能。真正的技能内容定义在.agents/skills/github-qa-labels/SKILL.md。这种"一处定义、多处引用"的结构与仓库整体的 Agent 指令约定一致——CLAUDE.md也只有一行@AGENTS.md，而AGENTS.md明确声明自己是"编码 Agent 的规范指令来源，CLAUDE.md等文件应指向它而非重复指令"。技能体系遵循同样的去重原则，避免多份副本漂移。

技能文件本身采用 YAML frontmatter 声明元信息，github-qa-labels的定义为：

--- name: github-qa-labels description: Label GitHub issues and PRs found during QA testing. Use when organizing QA findings with proper labels. allowed-tools: Bash ---

其中description是 Agent 决定"何时触发该技能"的依据（描述里给出了明确的触发场景：整理 QA 发现时），allowed-tools: Bash则把该技能可用工具限定为 Bash——因为技能的全部操作都是gh命令。仓库中还有.agents/plugins/marketplace.json声明了 Storybook 的 Codex 插件来源（code/lib/codex-plugin/plugins/storybook），说明同一套技能既服务于仓库内置工作流，也会随插件分发到外部项目中使用。

与github-qa-labels并列的还有 canary、storybook-upgrade、minor-release、handle-pr-comments 等技能，共同构成"发布 → 升级 → QA → 归档问题"的完整链路，github-qa-labels处在 QA 收尾归档这一环。

核心主题：为 QA 发现打标签

技能正文的开篇即给出定位：

When creating or organizing issues/PRs found during QA testing, apply these labels. （在创建或整理 QA 测试中发现的 Issue/PR 时，应用这些标签。）

也就是说，该技能不是通用的 GitHub 标签指南，而是专为"版本升级 QA"这一场景定制的归档规范，包含三类规则：QA 跟踪标签、严重等级标签、以及批量打标操作。

一、QA 跟踪标签upgrade:<version>

每个版本升级 QA 周期，所有发现的问题都挂到一个按版本号命名的跟踪标签下，从而可以用一个 label 聚合出该版本 QA 的全部发现。

第一步，确保标签存在（若不存在则创建）：

# Create label if it doesn't exist gh label create "upgrade:10.2" --repo storybookjs/storybook --color "0E8A16" --description "Issues/PRs found during 10.2 upgrade QA"

各参数含义：

• "upgrade:10.2"：标签名，遵循upgrade:<major.minor>的命名约定，与 QA 目标版本一一对应；
• --repo storybookjs/storybook：显式指定目标仓库（技能默认操作 Storybook 官方仓库）；
• --color "0E8A16"：深绿色，让版本跟踪标签在 GitHub 列表中视觉可辨；
• --description：说明该标签的语义边界，防止被误用到非 QA 场景。

第二步，把标签加到具体的 Issue 或 PR 上：

# Add to issue/PR gh issue edit <NUMBER> --repo storybookjs/storybook --add-label "upgrade:10.2" gh pr edit <NUMBER> --repo storybookjs/storybook --add-label "upgrade:10.2"

<NUMBER>替换为 Issue/PR 编号。gh issue edit与gh pr edit都通过--add-label增量添加标签，不会覆盖已有标签，因此upgrade:10.2可以与其他标签（如严重等级、类型标签）共存。

二、严重等级标签sev:S1–sev:S4（仅限 Bug）

对于真正的缺陷，再叠加一个严重等级标签：

gh issue edit <NUMBER> --repo storybookjs/storybook --add-label "sev:S2"

技能正文给出四级严重度的精确定义：

判定标准的核心变量是"有无替代方案"与"影响面大小"，这使不同 QA 执行者对同一问题打出的等级趋于一致。

三、什么类型的问题该打严重等级标签

技能用一张判定表明确了sev:*的适用范围，这里完整保留：

也就是说：sev:*只用于 bug，文档类问题、feature request、enhancement 一律不打严重等级标签（但仍应挂upgrade:<version>跟踪标签）。值得注意的是表中专门列出"automigrate 问题"——这与 Storybook 大型版本升级时依赖 codemod/automigrate 工具链的现状直接相关：自动迁移脚本产生的破坏同样按 bug 定级。

四、批量打标

QA 一轮下来往往积累十几个问题，技能给出了用&&串联命令的批量操作示例：

gh issue edit 33524 --repo storybookjs/storybook --add-label "upgrade:10.2" && \ gh issue edit 33527 --repo storybookjs/storybook --add-label "upgrade:10.2" && \ gh pr edit 33526 --repo storybookjs/storybook --add-label "upgrade:10.2"

要点有三：

1. 用&&顺序串联，任一命令失败即停止，避免在错误仓库上继续误操作；
2. Issue 用gh issue edit、PR 用gh pr edit，二者不能混用；
3. 批量场景下编号是已确认的真实 Issue/PR 号（如技能示例中的 33524、33526、33527），执行前应先核对。

结合仓库上下文：这个技能在 QA 流水线中的位置

单看标签规则略显孤立，放进 Storybook 的发布流程里，github-qa-labels的职责就清晰了。

QA 测的是什么：canary 版本与升级命令

从.agents/skills/canary/SKILL.md可以看到，Storybook 的每个 PR 都可以通过 GitHub Actions 发布一个格式可预测的 canary 版本：

0.0.0-pr-<PR_NUMBER>-sha-<SHORT_SHA>

例如 PR #33526、commit 短 SHA 为a2e09fa2时，canary 版本即0.0.0-pr-33526-sha-a2e09fa2，并以canarydist-tag 发布到 npm，同时把版本号写回 PR 描述。随后 QA 的验证动作由.agents/skills/storybook-upgrade/SKILL.md定义：

npx storybook@<VERSION> upgrade

该命令会自动检测项目内所有@storybook/*包、统一升级到目标版本、处理 peer dependencies，并支持 npm/yarn/pnpm；技能还强调两条纪律——不要手动npm add单个 storybook 包（保证包间版本同步），以及一次只升一个主版本（如 8.x → 9.x → 10.x，不能从 8.x 直接跳 10.x）。github-qa-labels的批量示例中恰好出现了 PR #33526 与canary技能里的示例版本号0.0.0-pr-33526-sha-a2e09fa2，从源码结构看可以推断：QA 流程正是"用npx storybook@0.0.0-pr-33526-sha-a2e09fa2 upgrade在下游项目复测 → 发现回归问题 → 创建 Issue #33524/#33527 与修复 PR #33526 → 统一挂upgrade:<version>标签归档"。

标签名与当前仓库版本的对应

以仓库现状为例，code/core/package.json中storybook包的当前版本为10.6.0-beta.1，按技能的命名约定，该版本升级 QA 期间应创建并使用upgrade:10.6跟踪标签（10.2只是技能文档中的示意版本）。由于标签名直接编码版本号，gh issue list -L "upgrade:10.6"之类的查询即可随时盘点该版本 QA 的未关闭项，为 minor-release 技能在写CHANGELOG.md时提供问题清单输入。

与其他技能、指令文件的协作关系

从.agents/skills/目录结构看，Storybook 把 Agent 的工作流拆成了 12 个职责单一的 SKILL.md：

• canary：触发 PR 的 canary 发布，产出待测版本号；
• storybook-upgrade：在外部项目执行升级验证；
• github-qa-labels：把验证发现的问题规范化归档；
• handle-pr-comments：逐条处理 PR review 意见；
• minor-release：汇总 prerelease 条目写 minor/major 版本的 changelog；
• 其余如 open-pr、pr、rebuild-restart-storybook 等覆盖开 PR、重启本地实例等操作。

每个技能只声明自己的触发条件与工具白名单，github-qa-labels的allowed-tools: Bash意味着 Agent 执行它时只有命令执行权限，无法改写仓库文件——这与标签操作"只动 GitHub 侧元数据、不动代码"的性质吻合。而全局性的行为准则（base 分支为next、任务编排用 NX 与yarn task等）统一收口在AGENTS.md，技能文件不重复这些内容，保持单一事实来源。

实践要点小结

结合技能全文与仓库证据，落地这套规范时可按以下清单执行：

1. 建标签：QA 开始前先gh label create "upgrade:<version>"（带--color与--description），确保同版本所有发现聚合到一个可查询的标签下；
2. 区分两类标签：所有 QA 发现（Issue 和 PR）一律挂upgrade:<version>；仅 bug 类追加sev:S1–sev:S4，文档、feature request、enhancement 不打严重等级；
3. 按 workaround 定级：无 workaround 且阻断 → S1；可能有 workaround → S2；有 workaround → S3；边缘场景 → S4；
4. 批量操作：用&&串联gh issue edit/gh pr edit，注意 issue 与 pr 命令不可互换；
5. 保持包版本同步：QA 对象若是下游项目，升级必须走npx storybook@<version> upgrade而非手工安装，且一次只跨一个主版本；
6. 版本号格式：测 canary 时使用0.0.0-pr-<PR_NUMBER>-sha-<SHORT_SHA>格式，可从 PR 号与最新 commit SHA 自行推导，也可从 PR 描述中的发布提示获取。

这套看似简单的标签约定，实际上把"哪个版本的 QA、发现了什么级别的问题、由哪个 PR 修复"三个维度固化到了 GitHub 元数据里，使升级回归问题在整个版本生命周期内可聚合、可追溯、可交接——这也是 Storybook 这类拥有大量下游框架集成（React、Vue3、Angular、Svelte、Next.js 等，见.agents/skills/storybook-upgrade/SKILL.md与AGENTS.md中的 monorepo 结构说明）的大型项目做版本升级 QA 时，值得直接借用的工程实践。

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