UI Building and Story Writing Workflow【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookBefore creating or editing components or stories, call{{GET_STORYBOOK_STORY_INSTRUCTIONS}}.Treat its output as the source of truth for imports, story patterns, and testing conventions.After editing anything that changes how the UI looks — components, stories, styles, themes, colors, design tokens — call{{PREVIEW_STORIES}}, no exceptions; a shared file has no stories of its own, so preview its consumers stories.Include every returned preview URL in your final response.其中两个占位符分别对应两类动态事实 - {{GET_STORYBOOK_STORY_INSTRUCTIONS}}获取「如何编写 Story」详细规范的入口——因为导入约定、Story 模式与测试规范**因项目框架而异**不能硬编码在模板里必须由 Agent 运行时向本项目的 dev-server 查询对应 storybook-story-instructions.md 的内容其中包含 Storybook 9 的包合并、initialGlobals、sb.mock、play function canvas 参数等完整规范 - {{PREVIEW_STORIES}}生成 Story 预览 URL 的工具用于让 Agent 在视觉改动后产出可供用户核验的链接。 ## 二、四条工作流规则逐条解读 这份模板虽然短却定义了 AI 助手处理 UI 任务的完整闭环 1. **先取规范再动手**第 3 行。创建或编辑组件/Story 之前Agent 必须先调用获取 Story 编写指令的工具而不是凭训练记忆写代码。这一条针对的是 LLM 的常见错误——按旧版本如 storybook/react 或 CSF2习惯生成代码。 2. **以工具输出为唯一事实来源**第 4 行。Treat its output as the source of truth 明确禁止 Agent 依据自身记忆推断导入路径与测试约定从而保证生成代码与当前项目的框架、版本约定一致。 3. **视觉改动必须预览无例外**第 5 行。凡是改动 UI 外观——组件、Story、样式、主题、颜色、设计令牌——都必须调用预览工具。值得注意的细节是括号里的补充*a shared file has no stories of its own, so preview its consumers stories*——共享文件如工具函数、公共样式本身没有 StoryAgent 应转而预览**消费方**的 Story这是对改了共享代码却找不到可预览对象这一实际场景的针对性约束。 4. **最终回复必须包含全部预览 URL**第 6 行。返回的每一个预览链接都要写进最终回答不允许遗漏确保用户能逐一目检改动结果。 这四条规则构成「查询规范 → 修改代码 → 预览验证 → 交付链接」的最小闭环与 Storybook 官方倡导的「组件—Story—交互测试」工作流在 Agent 侧形成映射。 ## 三、模板如何被渲染buildServerInstructions 的装配逻辑 模板的填充由 [build-server-instructions.ts](https://link.gitcode.com/i/61a21314b4bff5bbf4e0765869a1e274) 中的 buildServerInstructions 函数完成。它接收一个 ServerInstructionsInputs 配置对象#L11-L25 ts export type ServerInstructionsInputs { transport: SkillTransport; // mcp | cli devEnabled: boolean; // 是否包含 UI 开发工作流 testSupported: boolean; // 是否包含测试工作流 docsEnabled: boolean; // 是否包含文档工具工作流 changeDetectionEnabled?: boolean; moduleGraphSupported?: boolean; reviewEnabled?: boolean; // 默认 false走 legacy 路径 };选择 legacy 模板的核心分支在 #L68-L78if (options.devEnabled !reviewEnabled) { // Review is off (the default): use the pre-review instruction text verbatim, // as shipped in the latest release — the workflow we know works. sections.push( legacyDevInstructions .replaceAll({{GET_STORYBOOK_STORY_INSTRUCTIONS}}, skillRef(write-story)) .replaceAll({{PREVIEW_STORIES}}, ref(stories.preview)) .trim() ); }即只有当devEnabled为真且reviewEnabled为假默认值时才使用legacy-dev-instructions.md。源码注释解释了命名由来——legacy 指它原样沿用了上一稳定版发布时的指令文本是被验证过有效the workflow we know works的工作流而 Review flavored 的新文案只在experimentalReview特性开关迭代期间使用见 #L68-L72 与 #L79-L109 的对照分支。占位符按传输通道解析{{GET_STORYBOOK_STORY_INSTRUCTIONS}}的填充值来自 skill-refs.ts#L11-L22const MCP_SKILL_TOOL_NAMES: PartialRecordSkillId, string { write-story: get-storybook-story-instructions, }; export function getSkillRef(transport: SkillTransport) { return (id: SkillId): string (transport mcp MCP_SKILL_TOOL_NAMES[id]) || npx storybook skills get ${id}; }也就是说同一个模板在不同通道渲染出不同措辞占位符MCP 通道transport: mcpCLI 通道transport: cli{{GET_STORYBOOK_STORY_INSTRUCTIONS}}MCP 工具名get-storybook-story-instructionsnpx storybook skills get write-story{{PREVIEW_STORIES}}MCP 工具名stories-preview由getToolName解析stories.preview对应的 CLI 工具名值得注意的是MCP_SKILL_TOOL_NAMES上的注释#L7-L10工具名是冻结契约必须与 addon-mcp 中tools/tool-names.ts的GET_UI_BUILDING_INSTRUCTIONS_TOOL_NAME保持一致——这解释了为何 Skill 的 id 与 MCP 工具名要分两层维护。四、为什么 legacy 版本刻意保持极简2,048 字符截断限制legacy-dev-instructions.md的短小并非内容单薄而是受硬约束驱动。build-server-instructions.ts #L27-L39 的注释说明了原因MCP clients truncate server instructions (Claude Code cuts them at 2,048 chars), so anything beyond the workflow trigger must live in tool descriptions and tool results.即MCP 客户端会对 server instructions 做截断Claude Code 截断到 2,048 字符因此超出工作流触发点的细则例如最终链接该如何排版不能塞进 server instructions而必须放在工具描述与工具返回结果里。这正是getFinalLinksGuidance#L40-L48的职责完整的链接呈现规则通过get-storybook-story-instructions的输出下发而 server instructions 里只保留 legacy 模板中那条一句式的 Include every returned preview URL in your final response。这一约束有直接的测试保障。build-server-instructions.test.ts 中#L187 起的用例断言「默认review 关闭指令必须保持在 2,048 字符客户端截断限制之内」#L124-L148 的用例legacy dev instructions ignore the change-detection and module-graph flags验证 legacy 路径对changeDetectionEnabled/moduleGraphSupported标志不敏感——无论这两个标志如何组合渲染结果与基准 legacy 输出完全一致。第二条测试恰好印证了架构分工legacy 模板走的是改完直接stories-preview的旧链路而模块图/变更检测驱动的智能发现stories.find-by-component、stories.changed只属于 review 启用后的dev-instructions.md分支参见 build-server-instructions.ts #L86-L92 的三态分支change-detection → 依赖模块图 → 纯人工识别。五、与 dev-instructions.md 的对照同一工作流的两个形态把 dev-instructions.md 与 legacy 版并读可以看到两者的规则演进关系## UI Building and Story Writing Workflow - Before creating or editing components or stories, call **{{GET_STORYBOOK_STORY_INSTRUCTIONS}}**; its output is the source of truth for imports, story patterns, and testing conventions. - {{PREVIEW_STORIES_STEP}} - {{FINAL_LINKS_STEP}}{{DISPLAY_REVIEW_STEP}} - Only use story IDs returned by tools — never derive them from file names or memory. **{{GET_STORIES_BY_COMPONENT}}** maps any input to stories; its description covers the workflow. No matches means no stories exist yet — say so.区别在于legacy 版把预览与给出链接合并为一条硬性规则review 版则把{{PREVIEW_STORIES_STEP}}按能力分级填充stories-changed/stories-find-by-component/ 人工识别三选一并新增{{DISPLAY_REVIEW_STEP}}——以review.create为视觉工作的终态步骤注释#L80-L85特别指出这是为了避免预览链接抢先收尾、review 从未发布的 Agent 行为该问题曾在 Codex MCP 通道上被观察到。review 版新增只使用工具返回的 story ID、绝不从文件名或记忆推导的规则并引入{{GET_STORIES_BY_COMPONENT}}对应 MCP 工具stories-find-by-component作为输入到 Story 的映射入口。两者共同保留先取write-story规范再动手这一条说明无论特性开关如何演进「以运行时查询结果为准」是这套指令系统的不变量。六、Skill 体系与 CLI 入口这些指令如何被消费这些模板最终通过storybook skills体系对外提供。skills.ts#L7-L23定义了三个公开 Skill idexport const SKILL_IDS [stories, write-story, setup] as const; export const SKILLS: RecordSkillId, { blurb: string } { stories: { blurb: The mandatory, ordered workflow for UI changes: discover affected stories, test, and present results. }, write-story: { blurb: How to write, update, and test Storybook stories for this project: imports, patterns, and conventions. }, setup: { blurb: Setup instructions to write stories for the real components in this project. }, };注释明确提醒这些 id 是公开 CLI 词汇插件桩会引用重命名视为破坏性变更。在 CLI 通道run.ts #L99-L113 的assemble函数把stories这个 Skill 映射到buildServerInstructionstransport固定为cliif (id stories) { return buildServerInstructions({ transport: cli, devEnabled: true, testSupported: inputs.testSupported, docsEnabled: inputs.docsEnabledForCli, changeDetectionEnabled: inputs.changeDetectionEnabled, moduleGraphSupported: inputs.moduleGraphSupported, reviewEnabled, }); }于是终端用户/Agent 执行npx storybook skills get stories时默认review 关闭得到的输出正是 legacy 模板渲染结果加上若项目支持测试legacy-test-instructions.md 的 Validation Workflow 段落## Validation Workflow - After editing anything that changes how the UI looks, run **test-run** — never a package.json test script. - Use focused runs while iterating, then a broad pass before handoff when scope is unclear or wide. - Fix failing tests; never report completion while they are failing.【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/7 18:33:35 · 阅读 1.2k UI Building and Story Writing Workflow
UI Building and Story Writing Workflow【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookBefore creating or editing components or stories, call{{GET_STORYBOOK_STORY_INSTRUCTIONS}}.Treat its output as the source of truth for imports, story patterns, and testing conventions.After editing anything that changes how the UI looks — components, stories, styles, themes, colors, design tokens — call{{PREVIEW_STORIES}}, no exceptions; a shared file has no stories of its own, so preview its consumers stories.Include every returned preview URL in your final response.其中两个占位符分别对应两类动态事实 - {{GET_STORYBOOK_STORY_INSTRUCTIONS}}获取「如何编写 Story」详细规范的入口——因为导入约定、Story 模式与测试规范**因项目框架而异**不能硬编码在模板里必须由 Agent 运行时向本项目的 dev-server 查询对应 storybook-story-instructions.md 的内容其中包含 Storybook 9 的包合并、initialGlobals、sb.mock、play function canvas 参数等完整规范 - {{PREVIEW_STORIES}}生成 Story 预览 URL 的工具用于让 Agent 在视觉改动后产出可供用户核验的链接。 ## 二、四条工作流规则逐条解读 这份模板虽然短却定义了 AI 助手处理 UI 任务的完整闭环 1. **先取规范再动手**第 3 行。创建或编辑组件/Story 之前Agent 必须先调用获取 Story 编写指令的工具而不是凭训练记忆写代码。这一条针对的是 LLM 的常见错误——按旧版本如 storybook/react 或 CSF2习惯生成代码。 2. **以工具输出为唯一事实来源**第 4 行。Treat its output as the source of truth 明确禁止 Agent 依据自身记忆推断导入路径与测试约定从而保证生成代码与当前项目的框架、版本约定一致。 3. **视觉改动必须预览无例外**第 5 行。凡是改动 UI 外观——组件、Story、样式、主题、颜色、设计令牌——都必须调用预览工具。值得注意的细节是括号里的补充*a shared file has no stories of its own, so preview its consumers stories*——共享文件如工具函数、公共样式本身没有 StoryAgent 应转而预览**消费方**的 Story这是对改了共享代码却找不到可预览对象这一实际场景的针对性约束。 4. **最终回复必须包含全部预览 URL**第 6 行。返回的每一个预览链接都要写进最终回答不允许遗漏确保用户能逐一目检改动结果。 这四条规则构成「查询规范 → 修改代码 → 预览验证 → 交付链接」的最小闭环与 Storybook 官方倡导的「组件—Story—交互测试」工作流在 Agent 侧形成映射。 ## 三、模板如何被渲染buildServerInstructions 的装配逻辑 模板的填充由 [build-server-instructions.ts](https://link.gitcode.com/i/61a21314b4bff5bbf4e0765869a1e274) 中的 buildServerInstructions 函数完成。它接收一个 ServerInstructionsInputs 配置对象#L11-L25 ts export type ServerInstructionsInputs { transport: SkillTransport; // mcp | cli devEnabled: boolean; // 是否包含 UI 开发工作流 testSupported: boolean; // 是否包含测试工作流 docsEnabled: boolean; // 是否包含文档工具工作流 changeDetectionEnabled?: boolean; moduleGraphSupported?: boolean; reviewEnabled?: boolean; // 默认 false走 legacy 路径 };选择 legacy 模板的核心分支在 #L68-L78if (options.devEnabled !reviewEnabled) { // Review is off (the default): use the pre-review instruction text verbatim, // as shipped in the latest release — the workflow we know works. sections.push( legacyDevInstructions .replaceAll({{GET_STORYBOOK_STORY_INSTRUCTIONS}}, skillRef(write-story)) .replaceAll({{PREVIEW_STORIES}}, ref(stories.preview)) .trim() ); }即只有当devEnabled为真且reviewEnabled为假默认值时才使用legacy-dev-instructions.md。源码注释解释了命名由来——legacy 指它原样沿用了上一稳定版发布时的指令文本是被验证过有效the workflow we know works的工作流而 Review flavored 的新文案只在experimentalReview特性开关迭代期间使用见 #L68-L72 与 #L79-L109 的对照分支。占位符按传输通道解析{{GET_STORYBOOK_STORY_INSTRUCTIONS}}的填充值来自 skill-refs.ts#L11-L22const MCP_SKILL_TOOL_NAMES: PartialRecordSkillId, string { write-story: get-storybook-story-instructions, }; export function getSkillRef(transport: SkillTransport) { return (id: SkillId): string (transport mcp MCP_SKILL_TOOL_NAMES[id]) || npx storybook skills get ${id}; }也就是说同一个模板在不同通道渲染出不同措辞占位符MCP 通道transport: mcpCLI 通道transport: cli{{GET_STORYBOOK_STORY_INSTRUCTIONS}}MCP 工具名get-storybook-story-instructionsnpx storybook skills get write-story{{PREVIEW_STORIES}}MCP 工具名stories-preview由getToolName解析stories.preview对应的 CLI 工具名值得注意的是MCP_SKILL_TOOL_NAMES上的注释#L7-L10工具名是冻结契约必须与 addon-mcp 中tools/tool-names.ts的GET_UI_BUILDING_INSTRUCTIONS_TOOL_NAME保持一致——这解释了为何 Skill 的 id 与 MCP 工具名要分两层维护。四、为什么 legacy 版本刻意保持极简2,048 字符截断限制legacy-dev-instructions.md的短小并非内容单薄而是受硬约束驱动。build-server-instructions.ts #L27-L39 的注释说明了原因MCP clients truncate server instructions (Claude Code cuts them at 2,048 chars), so anything beyond the workflow trigger must live in tool descriptions and tool results.即MCP 客户端会对 server instructions 做截断Claude Code 截断到 2,048 字符因此超出工作流触发点的细则例如最终链接该如何排版不能塞进 server instructions而必须放在工具描述与工具返回结果里。这正是getFinalLinksGuidance#L40-L48的职责完整的链接呈现规则通过get-storybook-story-instructions的输出下发而 server instructions 里只保留 legacy 模板中那条一句式的 Include every returned preview URL in your final response。这一约束有直接的测试保障。build-server-instructions.test.ts 中#L187 起的用例断言「默认review 关闭指令必须保持在 2,048 字符客户端截断限制之内」#L124-L148 的用例legacy dev instructions ignore the change-detection and module-graph flags验证 legacy 路径对changeDetectionEnabled/moduleGraphSupported标志不敏感——无论这两个标志如何组合渲染结果与基准 legacy 输出完全一致。第二条测试恰好印证了架构分工legacy 模板走的是改完直接stories-preview的旧链路而模块图/变更检测驱动的智能发现stories.find-by-component、stories.changed只属于 review 启用后的dev-instructions.md分支参见 build-server-instructions.ts #L86-L92 的三态分支change-detection → 依赖模块图 → 纯人工识别。五、与 dev-instructions.md 的对照同一工作流的两个形态把 dev-instructions.md 与 legacy 版并读可以看到两者的规则演进关系## UI Building and Story Writing Workflow - Before creating or editing components or stories, call **{{GET_STORYBOOK_STORY_INSTRUCTIONS}}**; its output is the source of truth for imports, story patterns, and testing conventions. - {{PREVIEW_STORIES_STEP}} - {{FINAL_LINKS_STEP}}{{DISPLAY_REVIEW_STEP}} - Only use story IDs returned by tools — never derive them from file names or memory. **{{GET_STORIES_BY_COMPONENT}}** maps any input to stories; its description covers the workflow. No matches means no stories exist yet — say so.区别在于legacy 版把预览与给出链接合并为一条硬性规则review 版则把{{PREVIEW_STORIES_STEP}}按能力分级填充stories-changed/stories-find-by-component/ 人工识别三选一并新增{{DISPLAY_REVIEW_STEP}}——以review.create为视觉工作的终态步骤注释#L80-L85特别指出这是为了避免预览链接抢先收尾、review 从未发布的 Agent 行为该问题曾在 Codex MCP 通道上被观察到。review 版新增只使用工具返回的 story ID、绝不从文件名或记忆推导的规则并引入{{GET_STORIES_BY_COMPONENT}}对应 MCP 工具stories-find-by-component作为输入到 Story 的映射入口。两者共同保留先取write-story规范再动手这一条说明无论特性开关如何演进「以运行时查询结果为准」是这套指令系统的不变量。六、Skill 体系与 CLI 入口这些指令如何被消费这些模板最终通过storybook skills体系对外提供。skills.ts#L7-L23定义了三个公开 Skill idexport const SKILL_IDS [stories, write-story, setup] as const; export const SKILLS: RecordSkillId, { blurb: string } { stories: { blurb: The mandatory, ordered workflow for UI changes: discover affected stories, test, and present results. }, write-story: { blurb: How to write, update, and test Storybook stories for this project: imports, patterns, and conventions. }, setup: { blurb: Setup instructions to write stories for the real components in this project. }, };注释明确提醒这些 id 是公开 CLI 词汇插件桩会引用重命名视为破坏性变更。在 CLI 通道run.ts #L99-L113 的assemble函数把stories这个 Skill 映射到buildServerInstructionstransport固定为cliif (id stories) { return buildServerInstructions({ transport: cli, devEnabled: true, testSupported: inputs.testSupported, docsEnabled: inputs.docsEnabledForCli, changeDetectionEnabled: inputs.changeDetectionEnabled, moduleGraphSupported: inputs.moduleGraphSupported, reviewEnabled, }); }于是终端用户/Agent 执行npx storybook skills get stories时默认review 关闭得到的输出正是 legacy 模板渲染结果加上若项目支持测试legacy-test-instructions.md 的 Validation Workflow 段落## Validation Workflow - After editing anything that changes how the UI looks, run **test-run** — never a package.json test script. - Use focused runs while iterating, then a broad pass before handoff when scope is unclear or wide. - Fix failing tests; never report completion while they are failing.【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考