Storybook 版本升级指南基于 Claude Code Plugin 的 storybook-upgrade 技能将 Storybook 升级至 10.6【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本指南以 Storybook 官方 Claude Code Plugin 中storybook-upgrade技能code/lib/claude-plugin/skills/storybook-upgrade/SKILL.md为核心讲解在 Storybook 已存在但版本过旧时如何驱动 AI 代理完成版本升级包括目标版本 10.6 的判定规则、next预发布与 canary 构建的适用范围、底层storybook upgrade命令的完整执行流程以及升级失败时回退到预发布版本的策略。读完本文你将能够手动复现该技能的全部判定逻辑并结合仓库源码理解升级命令的每一步内部机制。一、技能定位何时触发 storybook-upgrade在 Claude Code / Claude Desktop 中安装 Storybook 插件后代理会获得一组可被提示词显式引用的技能skills。其中storybook-upgrade的定位非常明确——它的 frontmatter 声明如下--- name: storybook-upgrade description: Use this skill when Storybook exists but needs an upgrade. ---触发条件是Storybook 已经存在但需要升级。这与同目录下的其他技能形成互补storybook-init项目中没有 Storybook需要全新初始化storybook-setupStorybook 已存在需要为代理工作流配置环境storybook-upgradeStorybook 已存在但版本过旧需要升级。从仓库中其他技能的交叉引用可以看出这种先升级、后使用的依赖关系。例如 stories 技能 和 setup 技能 都声明了硬性前提Storybook must be at least 10.6。当版本不满足时代理会被指示切换到/storybook-upgrade——但仅限用户明确批准升级的情况下。也就是说升级属于需要用户授权的破坏性操作代理不能擅自执行。1.1 在提示词中调用该技能该技能既可以被代理在工作过程中间接触发也可以被用户显式调用。在 Claude Code 中输入/upgrade即可让代理执行与运行npx storybook upgrade等价的操作参见 README.md 中关于upgrade技能的说明。二、目标版本判定为什么是 10.6技能正文的第一条硬性约束是版本目标Storybook must end up at version 10.6 or later.随后给出了版本判定规则的精确展开——这一点对理解整个技能至关重要最终状态Storybook 必须处于 10.6 或更高版本预发布通道在 10.6 正式发布之前next标签指向的预发布版本同样满足条件即10.6.0-alpha.x这类 alpha 版本canary 构建任何形如0.0.0-pr-*的 canary 构建也符合要求。这条规则的背后是插件生态的版本兼容性约束storybook/addon-mcp以及插件提供的一系列工具都要求 Storybook 达到 10.6。可以推断10.6 是 MCP 工具集mcp 插件目录正常运行的最低版本门槛因此升级技能把10.6含等价的预发布/canary 通道定义为成功终点而不是简单追求最新稳定版。三、执行路径完整阅读官方升级文档技能正文第二条指令要求代理Read https://storybook.js.org/docs/releases/upgrading.md in itsentiretyto get the latest Storybook upgrade instructions.即代理在动手升级前必须通篇阅读官方升级文档获取最新升级指引。仓库中这份文档的对应源码版本位于 docs/releases/upgrading.mdx其核心内容值得展开升级脚本Storybook 提供 CLI 升级命令可自动检测仓库中所有的 Storybook 项目含 monorepo 场景版本指定storybooklatest upgrade升级到最新版storybook9 upgrade升级到最新的 9.x也可以精确指定storybook8.6.1 upgrade跨大版本限制upgrade命令设计为一次跨越一个大版本8→9 可以7→9 不可以需先升到 8 再升到 96→8 是唯一例外自动健康检查升级完成后自动运行storybook doctor验证结果。这段读文档的指令不是形式主义——官方升级策略尤其是跨大版本的限制与预发布通道的使用方式直接影响代理选择正确的命令参数。四、预发布回退策略npx storybooknext upgrade技能正文的最后一条指令是整个决策逻辑的关键分支If the latest stable release is still below 10.6, upgrade to the prerelease instead withnpx storybooknext upgrade.判定逻辑可以形式化为检查当前最新稳定版是否 10.6若是升级到最新稳定版若否最新稳定版仍低于 10.6则改用npx storybooknext upgrade升级到next预发布通道。这与仓库中预发布版本的处理方式完全一致。官方文档 upgrading.mdx 中说明storybooknext upgrade会升级到最新的预发布版本例如storybook8.0.0-beta.1 upgrade可精确指定 beta 版本。而本技能将这一能力与10.6 未发布的现实情况结合当稳定通道尚未到达 10.6 时next通道10.6.0-alpha.x和任何0.0.0-pr-*canary 构建都是被认可的合格终点。从仓库版本演进看当前 package.json 等处的技能文件均已将 10.6 作为插件运行的前提这解释了为什么升级技能宁可接受预发布也不接受停留在 10.5 稳定版。五、底层实现upgrade 命令在 CLI 中的完整定义npx storybooknext upgrade等价于npx storybook upgrade最终调用的是 Storybook CLI 中注册的upgrade命令其定义位于 code/lib/cli-storybook/src/bin/run.tscommand(upgrade) .description(Upgrade your Storybook packages to v${versions.storybook}) .addOption( new Option(--package-manager type, Force package manager for installing deps).choices( Object.values(PackageManagerName) ) ) .option(-y --yes, Skip prompting the user) .addOption( new Option( --features list, Comma-separated list of experimental feature flags to enable during the upgrade ).argParser((value) { try { resolveRequestedFeatures(value); } catch (error) { throw new InvalidArgumentError(error instanceof Error ? error.message : String(error)); } return value; }) ) .option(-f --force, force the upgrade, skipping autoblockers) .option(-n --dry-run, Only check for upgrades, do not install) .option(-s --skip-check, Skip postinstall version and automigration checks) .option( --skip-automigrations, Skip running automigrations entirely (only update package versions and install) ) .option( -c, --config-dir dir-name..., Directory(ies) where to load Storybook configurations from ) .action(async (options: UpgradeOptions) { await withTelemetry( upgrade, { cliOptions: { ...options, configDir: options.configDir?.[0] } }, async () { logger.intro(Storybook upgrade - v${versions.storybook}); await upgrade(options); logger.outro(Storybook upgrade completed!); } ).catch(handleCommandFailure(options.logfile)); });各选项的作用与适用场景总结如下选项说明典型使用场景--package-manager type强制指定包管理器npm / yarn / pnpm 等monorepo 中多种包管理器并存时-y, --yes跳过所有交互式提示CI 或代理驱动的无人值守升级--features list升级过程中启用逗号分隔的实验特性开关显式勾选experimentalReview等特性-f, --force强制升级跳过 autoblocker 阻塞检查已知阻塞项但不影响本次升级时-n, --dry-run仅检查可升级项不实际安装升级前的风险评估-s, --skip-check跳过安装后的版本与 automigration 检查只想改 package.json 版本号时--skip-automigrations完全跳过 automigration只更新版本并安装自定义迁移流程时-c, --config-dir dir...指定一个或多个 Storybook 配置目录配置目录非默认.storybook时注意--features与--skip-automigrations是互斥的——特性开关依赖 automigration 机制来写入配置upgrade.ts 会在二者同时出现时直接抛错if (options.features options.skipAutomigrations) { logger.error( The --features flag enables feature flags through automigrations, so it cannot be combined with --skip-automigrations. ); throw new HandledError(--features cannot be combined with --skip-automigrations); }六、升级主流程从项目检测到健康检查upgrade函数的实现位于 code/lib/cli-storybook/src/upgrade.ts其执行顺序与官方文档描述一致项目检测getProjects(options)自动发现仓库中所有 Storybook 项目支持 monorepo 多项目若未发现任何项目则直接返回项目清单输出多项目时逐一打印configDir: beforeVersion - currentCLIVersion中断处理注册SIGINT/SIGTERM处理器用户中断时记录遥测并抛出HandledErrorautoblocker 检查processAutoblockerResults检测升级前的阻塞项存在阻塞时抛出Blockers detected——--force可跳过此检查参见 code/lib/cli-storybook/src/autoblock/utils.ts 中的错误提示版本合法性校验拒绝降级安装UpgradeStorybookToLowerVersionError并拒绝无法确定当前版本的项目UpgradeStorybookUnknownCurrentVersionError依赖更新非--dry-run模式下通过各项目的 package manager 预检查安装可行性含MinimumReleaseAgeHandledError的最小发布时长检查再批量更新package.json中的依赖版本automigration 执行根据新旧版本之间的破坏性变更运行相应迁移例如跨入 10.5 时会提示启用experimentalReview、experimentalDocgenServer等实验特性且默认不勾选、绝不擅自启用doctor 健康检查升级后对每个项目自动运行doctor验证是否存在重复依赖、不兼容插件、版本不匹配等常见问题。升级过程全程受遥测包裹withTelemetry(upgrade, ...)多项目场景会发送multi-upgrade遥测事件。遇到问题时仓库根目录会生成debug-storybook.log记录完整日志。七、技能约束与测试保障值得注意的是该技能文件本身刻意保持极简——只有版本目标、文档阅读指令和回退策略三条核心规则。这种设计在 plugin.test.ts 中有明确的测试约束技能 description 的 UTF-8 字节数必须低于 350 字节MAX_SKILL_DESCRIPTION_BYTES否则 Claude Code 会在技能列表中静默丢弃描述导致代理不再触发该技能。这也是为什么升级技能把大量细节委托给官方文档与 CLI 命令而不是内联到技能正文中——这是代理插件场景下的工程权衡。八、端到端实战手动复现该技能的决策在不借助代理的情况下你可以手动执行与storybook-upgrade技能完全一致的步骤步骤 1判断当前最新稳定版是否达到 10.6npm view storybook dist-tags查看latest标签对应的版本号。步骤 2A稳定版已 10.6 → 升级到最新稳定版在仓库根目录执行npx storybooklatest upgrade步骤 2B稳定版仍 10.6 → 升级到 next 预发布通道npx storybooknext upgrade该命令会将 Storybook 升级到10.6.0-alpha.x等预发布版本或0.0.0-pr-*canary 构建两者均满足技能定义的 10.6 目标。步骤 3验证升级结果npx storybook doctor运行健康检查确认无重复依赖、插件不兼容或版本不匹配问题。补充参数按需组合# 只检查可升级内容不实际安装 npx storybooknext upgrade --dry-run # 指定非默认配置目录支持多个 npx storybooknext upgrade --config-dir .storybook-app .storybook-ui # 无人值守CI / 代理场景 npx storybooknext upgrade --yes九、总结storybook-upgrade技能是 Storybook Claude Code 插件中存量项目维护环节的关键一环它以10.6 为硬性版本目标以官方升级文档为操作依据以npx storybooknext upgrade为预发布回退手段并以--dry-run、--config-dir、--features、--force等 CLI 选项覆盖多种升级场景。其底层命令通过项目自动检测、autoblocker 校验、automigration 迁移与 doctor 健康检查四步闭环保证了从旧版本到 10.6 的升级过程可追溯、可验证。对于需要为 AI 代理准备 Storybook 环境的团队理解这条升级路径与版本判定规则是让后续setup、stories等技能正常工作的前提。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Storybook 版本升级指南：基于 Claude Code Plugin 的 storybook-upgrade 技能将 Storybook 升级至 10.6+
Storybook 版本升级指南基于 Claude Code Plugin 的 storybook-upgrade 技能将 Storybook 升级至 10.6【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本指南以 Storybook 官方 Claude Code Plugin 中storybook-upgrade技能code/lib/claude-plugin/skills/storybook-upgrade/SKILL.md为核心讲解在 Storybook 已存在但版本过旧时如何驱动 AI 代理完成版本升级包括目标版本 10.6 的判定规则、next预发布与 canary 构建的适用范围、底层storybook upgrade命令的完整执行流程以及升级失败时回退到预发布版本的策略。读完本文你将能够手动复现该技能的全部判定逻辑并结合仓库源码理解升级命令的每一步内部机制。一、技能定位何时触发 storybook-upgrade在 Claude Code / Claude Desktop 中安装 Storybook 插件后代理会获得一组可被提示词显式引用的技能skills。其中storybook-upgrade的定位非常明确——它的 frontmatter 声明如下--- name: storybook-upgrade description: Use this skill when Storybook exists but needs an upgrade. ---触发条件是Storybook 已经存在但需要升级。这与同目录下的其他技能形成互补storybook-init项目中没有 Storybook需要全新初始化storybook-setupStorybook 已存在需要为代理工作流配置环境storybook-upgradeStorybook 已存在但版本过旧需要升级。从仓库中其他技能的交叉引用可以看出这种先升级、后使用的依赖关系。例如 stories 技能 和 setup 技能 都声明了硬性前提Storybook must be at least 10.6。当版本不满足时代理会被指示切换到/storybook-upgrade——但仅限用户明确批准升级的情况下。也就是说升级属于需要用户授权的破坏性操作代理不能擅自执行。1.1 在提示词中调用该技能该技能既可以被代理在工作过程中间接触发也可以被用户显式调用。在 Claude Code 中输入/upgrade即可让代理执行与运行npx storybook upgrade等价的操作参见 README.md 中关于upgrade技能的说明。二、目标版本判定为什么是 10.6技能正文的第一条硬性约束是版本目标Storybook must end up at version 10.6 or later.随后给出了版本判定规则的精确展开——这一点对理解整个技能至关重要最终状态Storybook 必须处于 10.6 或更高版本预发布通道在 10.6 正式发布之前next标签指向的预发布版本同样满足条件即10.6.0-alpha.x这类 alpha 版本canary 构建任何形如0.0.0-pr-*的 canary 构建也符合要求。这条规则的背后是插件生态的版本兼容性约束storybook/addon-mcp以及插件提供的一系列工具都要求 Storybook 达到 10.6。可以推断10.6 是 MCP 工具集mcp 插件目录正常运行的最低版本门槛因此升级技能把10.6含等价的预发布/canary 通道定义为成功终点而不是简单追求最新稳定版。三、执行路径完整阅读官方升级文档技能正文第二条指令要求代理Read https://storybook.js.org/docs/releases/upgrading.md in itsentiretyto get the latest Storybook upgrade instructions.即代理在动手升级前必须通篇阅读官方升级文档获取最新升级指引。仓库中这份文档的对应源码版本位于 docs/releases/upgrading.mdx其核心内容值得展开升级脚本Storybook 提供 CLI 升级命令可自动检测仓库中所有的 Storybook 项目含 monorepo 场景版本指定storybooklatest upgrade升级到最新版storybook9 upgrade升级到最新的 9.x也可以精确指定storybook8.6.1 upgrade跨大版本限制upgrade命令设计为一次跨越一个大版本8→9 可以7→9 不可以需先升到 8 再升到 96→8 是唯一例外自动健康检查升级完成后自动运行storybook doctor验证结果。这段读文档的指令不是形式主义——官方升级策略尤其是跨大版本的限制与预发布通道的使用方式直接影响代理选择正确的命令参数。四、预发布回退策略npx storybooknext upgrade技能正文的最后一条指令是整个决策逻辑的关键分支If the latest stable release is still below 10.6, upgrade to the prerelease instead withnpx storybooknext upgrade.判定逻辑可以形式化为检查当前最新稳定版是否 10.6若是升级到最新稳定版若否最新稳定版仍低于 10.6则改用npx storybooknext upgrade升级到next预发布通道。这与仓库中预发布版本的处理方式完全一致。官方文档 upgrading.mdx 中说明storybooknext upgrade会升级到最新的预发布版本例如storybook8.0.0-beta.1 upgrade可精确指定 beta 版本。而本技能将这一能力与10.6 未发布的现实情况结合当稳定通道尚未到达 10.6 时next通道10.6.0-alpha.x和任何0.0.0-pr-*canary 构建都是被认可的合格终点。从仓库版本演进看当前 package.json 等处的技能文件均已将 10.6 作为插件运行的前提这解释了为什么升级技能宁可接受预发布也不接受停留在 10.5 稳定版。五、底层实现upgrade 命令在 CLI 中的完整定义npx storybooknext upgrade等价于npx storybook upgrade最终调用的是 Storybook CLI 中注册的upgrade命令其定义位于 code/lib/cli-storybook/src/bin/run.tscommand(upgrade) .description(Upgrade your Storybook packages to v${versions.storybook}) .addOption( new Option(--package-manager type, Force package manager for installing deps).choices( Object.values(PackageManagerName) ) ) .option(-y --yes, Skip prompting the user) .addOption( new Option( --features list, Comma-separated list of experimental feature flags to enable during the upgrade ).argParser((value) { try { resolveRequestedFeatures(value); } catch (error) { throw new InvalidArgumentError(error instanceof Error ? error.message : String(error)); } return value; }) ) .option(-f --force, force the upgrade, skipping autoblockers) .option(-n --dry-run, Only check for upgrades, do not install) .option(-s --skip-check, Skip postinstall version and automigration checks) .option( --skip-automigrations, Skip running automigrations entirely (only update package versions and install) ) .option( -c, --config-dir dir-name..., Directory(ies) where to load Storybook configurations from ) .action(async (options: UpgradeOptions) { await withTelemetry( upgrade, { cliOptions: { ...options, configDir: options.configDir?.[0] } }, async () { logger.intro(Storybook upgrade - v${versions.storybook}); await upgrade(options); logger.outro(Storybook upgrade completed!); } ).catch(handleCommandFailure(options.logfile)); });各选项的作用与适用场景总结如下选项说明典型使用场景--package-manager type强制指定包管理器npm / yarn / pnpm 等monorepo 中多种包管理器并存时-y, --yes跳过所有交互式提示CI 或代理驱动的无人值守升级--features list升级过程中启用逗号分隔的实验特性开关显式勾选experimentalReview等特性-f, --force强制升级跳过 autoblocker 阻塞检查已知阻塞项但不影响本次升级时-n, --dry-run仅检查可升级项不实际安装升级前的风险评估-s, --skip-check跳过安装后的版本与 automigration 检查只想改 package.json 版本号时--skip-automigrations完全跳过 automigration只更新版本并安装自定义迁移流程时-c, --config-dir dir...指定一个或多个 Storybook 配置目录配置目录非默认.storybook时注意--features与--skip-automigrations是互斥的——特性开关依赖 automigration 机制来写入配置upgrade.ts 会在二者同时出现时直接抛错if (options.features options.skipAutomigrations) { logger.error( The --features flag enables feature flags through automigrations, so it cannot be combined with --skip-automigrations. ); throw new HandledError(--features cannot be combined with --skip-automigrations); }六、升级主流程从项目检测到健康检查upgrade函数的实现位于 code/lib/cli-storybook/src/upgrade.ts其执行顺序与官方文档描述一致项目检测getProjects(options)自动发现仓库中所有 Storybook 项目支持 monorepo 多项目若未发现任何项目则直接返回项目清单输出多项目时逐一打印configDir: beforeVersion - currentCLIVersion中断处理注册SIGINT/SIGTERM处理器用户中断时记录遥测并抛出HandledErrorautoblocker 检查processAutoblockerResults检测升级前的阻塞项存在阻塞时抛出Blockers detected——--force可跳过此检查参见 code/lib/cli-storybook/src/autoblock/utils.ts 中的错误提示版本合法性校验拒绝降级安装UpgradeStorybookToLowerVersionError并拒绝无法确定当前版本的项目UpgradeStorybookUnknownCurrentVersionError依赖更新非--dry-run模式下通过各项目的 package manager 预检查安装可行性含MinimumReleaseAgeHandledError的最小发布时长检查再批量更新package.json中的依赖版本automigration 执行根据新旧版本之间的破坏性变更运行相应迁移例如跨入 10.5 时会提示启用experimentalReview、experimentalDocgenServer等实验特性且默认不勾选、绝不擅自启用doctor 健康检查升级后对每个项目自动运行doctor验证是否存在重复依赖、不兼容插件、版本不匹配等常见问题。升级过程全程受遥测包裹withTelemetry(upgrade, ...)多项目场景会发送multi-upgrade遥测事件。遇到问题时仓库根目录会生成debug-storybook.log记录完整日志。七、技能约束与测试保障值得注意的是该技能文件本身刻意保持极简——只有版本目标、文档阅读指令和回退策略三条核心规则。这种设计在 plugin.test.ts 中有明确的测试约束技能 description 的 UTF-8 字节数必须低于 350 字节MAX_SKILL_DESCRIPTION_BYTES否则 Claude Code 会在技能列表中静默丢弃描述导致代理不再触发该技能。这也是为什么升级技能把大量细节委托给官方文档与 CLI 命令而不是内联到技能正文中——这是代理插件场景下的工程权衡。八、端到端实战手动复现该技能的决策在不借助代理的情况下你可以手动执行与storybook-upgrade技能完全一致的步骤步骤 1判断当前最新稳定版是否达到 10.6npm view storybook dist-tags查看latest标签对应的版本号。步骤 2A稳定版已 10.6 → 升级到最新稳定版在仓库根目录执行npx storybooklatest upgrade步骤 2B稳定版仍 10.6 → 升级到 next 预发布通道npx storybooknext upgrade该命令会将 Storybook 升级到10.6.0-alpha.x等预发布版本或0.0.0-pr-*canary 构建两者均满足技能定义的 10.6 目标。步骤 3验证升级结果npx storybook doctor运行健康检查确认无重复依赖、插件不兼容或版本不匹配问题。补充参数按需组合# 只检查可升级内容不实际安装 npx storybooknext upgrade --dry-run # 指定非默认配置目录支持多个 npx storybooknext upgrade --config-dir .storybook-app .storybook-ui # 无人值守CI / 代理场景 npx storybooknext upgrade --yes九、总结storybook-upgrade技能是 Storybook Claude Code 插件中存量项目维护环节的关键一环它以10.6 为硬性版本目标以官方升级文档为操作依据以npx storybooknext upgrade为预发布回退手段并以--dry-run、--config-dir、--features、--force等 CLI 选项覆盖多种升级场景。其底层命令通过项目自动检测、autoblocker 校验、automigration 迁移与 doctor 健康检查四步闭环保证了从旧版本到 10.6 的升级过程可追溯、可验证。对于需要为 AI 代理准备 Storybook 环境的团队理解这条升级路径与版本判定规则是让后续setup、stories等技能正常工作的前提。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
