Storybook 仓库内部开发流程：rebuild-restart-storybook 技能——重建并重启内部 Storybook 的标准化工作流
【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook
本文围绕 Storybook 开源仓库中的 Agent 技能定义文件 SKILL.md（实体内容位于 .agents/skills/rebuild-restart-storybook/SKILL.md），完整解析这套"改动内部 Storybook 代码后如何重建、重启并审查 UI"的五步工作流。读完后，你将掌握：如何确定被修改的 monorepo 包及其 Nx 项目名、如何在code/目录执行缓存清理、按需构建与后台启动内部 Storybook、如何处理端口占用，以及如何借助 MCP 的review-create工具为本次改动生成 UI 审查。
技能定位与触发条件
rebuild-restart-storybook是 Storybook 仓库为 AI 编码代理（Claude Code / Codex 等）定义的标准化操作技能。SKILL.md 的 frontmatter 声明了它的元信息：
name: rebuild-restart-storybook：技能标识名；description：用于在修改了内部 Storybook 代码（core、addons、frameworks、renderers、libs 等）之后，重建并重启内部 Storybook UI，并可选地展示一次 UI 审查（review）。触发时机是"编辑了code/目录下的任意包之后，或用户主动要求重建/重启 Storybook 时"；allowed-tools: Bash, Read：技能执行时仅允许使用 Bash 与 Read 工具，即整个流程只涉及"读代码 + 跑命令"，不需要额外的写文件能力。
需要说明的是，.claude/skills/rebuild-restart-storybook/SKILL.md 本身只是一个指向.agents/skills/rebuild-restart-storybook/SKILL.md的引用文件（内容为路径指针），真正的技能正文以.agents/下的文件为准。这也体现了该仓库的约定：技能定义统一维护在.agents/skills/下，.claude/skills/侧做引用分发。
第一步：与用户确认是否重建（交互护栏）
技能的第一步是一道交互确认：除非用户是显式执行/rebuild-restart-storybook命令触发的，代理都必须先询问用户是否要重建并重启 Storybook；如果用户拒绝，流程到此终止。
这一步的设计意图在于：重建 + 重启是一个重量级操作（涉及清理缓存、重新构建多个包、拉起 dev server），在代理"顺带"修改了代码之后，不应未经确认就自动执行。它把"是否重建"的决策权交还给人类，同时保留了用户显式斜杠命令时的免确认路径。
第二步：确定被修改的包并找到 Nx 项目名
流程要求构建一个"以空格分隔的 monorepo 包名列表"，列出本次会话中被修改过的所有包。关键规则是：每个包必须使用其目录内project.json文件里的name字段（即 Nx 项目名），而不是package.json里的name字段（即 npm 包名）。
技能给出的示例是：如果修改了code/addons/review和code/addons/vitest，得到的列表就是addon-review addon-vitest。这个规则可以在仓库中得到直接印证：
- code/addons/vitest/project.json 中
"name": "addon-vitest"，对应的 npm 包名则是@storybook/addon-vitest（见 code/package.json 的 dependencies）； - code/core/project.json 中
"name": "core"，而 npm 包名是@storybook/core。
从源码结构看，这一约定并非任意：构建入口 scripts/build-package.ts 在解析命令行参数时，是把 npm 包名去掉@storybook/前缀得到"后缀"来匹配的，并对@storybook/cli做了特判映射为sb-cli。也就是说，yarn build接受的包名标识与 Nx 项目名在绝大多数包上一致、在个别包（如 CLI）上以项目名为准，因此技能明确规定"查project.json而不是package.json"，可以避免代理拿 npm 包名去匹配导致构建失败。
第三步：按顺序执行构建与启动命令
确定包列表后，技能要求在code/目录下按顺序执行以下命令，其中<extra packages>替换为第二步得到的包名列表：
rm -rf node_modules/.cache yarn yarn build storybook <extra packages>随后在后台执行启动命令：
NODE_OPTIONS="--preserve-symlinks" yarn storybook:ui --no-open这两组命令在仓库中都有明确落点，可以逐条核对：
yarn build的来源。code/package.json 中定义了"build": "NODE_ENV=production yarn --cwd ../scripts build-package"，最终转入 scripts/build-package.ts。该脚本基于 commander 解析参数，支持--all、--watch、--prod等选项；当直接传入包名（如yarn build storybook addon-review addon-vitest）时会按后缀匹配，并对无效包名给出"Did you mean ..."的纠错提示后以退出码 1 终止。技能中的命令形式（无--watch/--prod）对应一次性的 production 环境构建。注意storybook本身也要出现在构建列表里——它是核心 CLI 包，code/package.json 中storybook:ui脚本依赖的正是构建产物core/dist/bin/dispatcher.js。storybook:ui脚本的真实展开。code/package.json 中该脚本为：NODE_OPTIONS="--max_old_space_size=4096 --trace-deprecation" core/dist/bin/dispatcher.js dev --port 6006 --config-dir ./.storybook即通过 core 的 dispatcher 入口以 dev 模式在6006 端口启动，配置目录指向 code/.storybook。技能外层追加的
NODE_OPTIONS="--preserve-symlinks"作用于 yarn 进程本身的模块解析，而脚本内部又为 dispatcher 进程设置了--max_old_space_size=4096 --trace-deprecation（大堆内存 + 弃用警告追踪）。--no-open则透传给 dev 命令，避免启动时自动打开浏览器。内部 Storybook 为何"重建后生效"。code/.storybook/main.ts 展示了内部 UI 的组织方式：stories 直接扫描
code/core/src、code/addons/*/src等源码目录，且viteFinal在 DEVELOPMENT 模式下把storybook/manager-api、storybook/preview-api、storybook/theming等模块别名直接指向code/core/src下的源码文件（如../core/src/preview-api/index.ts）。从源码结构看，这意味着 dev 模式下 manager 侧的变更可被 vite 直接热更新捕获；但对 core 的编译入口、addons 的构建产物等路径上的改动，仍需走"重建包 + 重启"这条技能流程，这正是该工作流存在的理由。此外refs中挂载了一个远端 Chromatic 图标库作为Icons参考，staticDirs暴露了/bundle-analyzer页面，便于在内部 UI 里做 bundle 分析。
处理端口占用
技能明确给出了端口冲突的处理预案：可能已经有一个 Storybook 实例在运行；如果发现端口被占用，应取消当前启动、杀掉旧进程以释放端口，然后重新启动。结合上面的脚本定义，内部 UI 默认监听 6006 端口，因此实际操作中要检查的就是 6006 是否被旧的 dispatcher 进程占用。
第四步：给出 URL 并询问是否需要 review
Storybook 启动成功后，技能要求代理把 URL 告知用户（默认即http://localhost:6006），随后询问用户是否需要展示一次 review（UI 审查）。这一步把"跑起来了"与"看得怎么样了"拆成两个独立决策点：URL 是每次必给的交付物，而 review 是有代价的可选动作。
第五步：用 review-create MCP 工具展示 UI review
如果用户选择查看 review，技能要求使用 Storybook 的review-createMCP 工具，针对与"整个会话迄今为止内容"相关的 stories 创建一次 UI review；如果本次改动没有触及任何 UI 元素、因此不存在相关 stories，则应反问用户希望审查什么内容，而不是自行编造审查对象。
这条指令在仓库源码中能得到完整的机制佐证：
- 工具注册与门控逻辑位于 code/addons/mcp/src/preset.ts，其中注释说明
stories-find-by-component、stories-changed、review-create等工具受特性开关门控，且review-create额外要求experimentalReview特性标志开启； - code/addons/mcp/src/mcp-handler.test.ts 中的用例验证了该门控行为：当
experimentalReview与changeDetection两个 feature flag 同时开启时才注册review-create，缺少任一条件则不注册； - 内部 Storybook 的 code/.storybook/main.ts 恰好同时启用了
features.experimentalReview: true与core.changeDetection: true（以及features.changeDetection: true），因此在该仓库内部运行这套技能时，review-create工具是可用的。
从源码结构看，changeDetection使 MCP 能够感知"哪些 stories 发生了变化"，与第二步"确定被修改的包"的思路一脉相承：先定位改动范围，再据此圈定 review 的 stories 集合。
流程要点小结
| 步骤 | 动作 | 依据 |
|---|---|---|
| 1 | 非显式命令触发时，先询问用户是否重建重启，拒绝即终止 | SKILL.md Step 1 |
| 2 | 汇总会话中修改过的包，取各自project.json的name（Nx 项目名），如addon-vitest、core | code/addons/vitest/project.json、code/core/project.json |
| 3 | 在code/目录依次执行rm -rf node_modules/.cache、yarn、yarn build storybook <extra packages>；后台执行NODE_OPTIONS="--preserve-symlinks" yarn storybook:ui --no-open；端口被占则杀旧进程后重启 | code/package.json、scripts/build-package.ts |
| 4 | 给出 URL（默认 6006 端口），并询问是否需要 review | SKILL.md Step 4 |
| 5 | 用review-createMCP 工具对与会话相关的 stories 建 review；无相关 stories 时询问用户想看什么 | code/addons/mcp/src/preset.ts、code/.storybook/main.ts |
适用前提：该工作流面向 Storybook 仓库自身的内部开发（monorepocode/目录），依赖 Yarn workspaces 与 Nx 工程结构，且内部 UI 使用@storybook/react-vite框架与./.storybook配置目录；对外部普通 Storybook 用户项目并不适用。整套技能的本质，是把"改内部代码 → 重建产物 → 重启内部 UI → 按改动范围做 UI 审查"这一高频动作固化为一套可被 AI 代理可靠执行、且每一步都有仓库内脚本与配置可核对的标准流程。
【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
