Storybook MCP 按文件路径预览 Story解析 914-preview-story-by-path 评测场景与 stories-preview 工具【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇围绕 Storybook 仓库中 agent-eval 评测套件里的914-preview-story-by-path场景展开它给 AI 编码 Agent 下达了一个两步任务——先阅读 stories 文件并说明其导入内容再调用 Storybook MCP 的 preview 工具按「文件路径 导出名」预览 Primary 与 Secondary 两个 Button story。读完本文你能理解 path-based story 选择器的参数契约、评测如何断言 Agent 的工具调用以及该场景与 storyId 选择方式915-preview-story-by-id之间的设计取舍。评测场景的定位Storybook 仓库在 agent-eval 目录下内置了一套 Agent 评测套件它在沙箱中运行编码 AgentClaude Code / Codex让 Agent 对着 fixture 项目执行 Storybook 工作流编写 story、预览或审阅 story、运行 story 测试然后断言 Agent 确实遵循了仓库提供的 MCP 工具或 plugin 技能所定义的工作流。每个评测场景是一个独立目录由三部分组成文件作用PROMPT.md直接投喂给 Agent 的任务提示词EVAL.tsvitest 测试解析 Agent 的调用记录并断言工作流结果package.json声明该评测使用的 fixture 模板本场景为reshaped-storybook914-preview-story-by-path属于 9xx 系列的「MCP 工具行为」评测其核心考察点是当用户以故事文件路径而非 storyId指代 story 时Agent 能否正确使用stories-preview工具的路径形态选择器。原始任务提示词PROMPT.mdPROMPT.md 全文如下仅两句话、两步操作Read the stories file for the button atstories/Button.stories.tsx, and tell me what that file imports.Then afterwards, show a preview of the Primary and Secondary button stories using the Storybook MCP preview tool.拆解这个任务它刻意包含两种不同性质的动作静态阅读读取stories/Button.stories.tsx向用户报告该文件导入了什么。这一步不依赖 MCP考察 Agent 的基础文件理解能力。工具调用使用 Storybook MCP 的 preview 工具预览Primary和Secondary两个 story。关键在于提示词给出的是文件路径 导出名stories/Button.stories.tsx中的Primary/Secondary而不是button--primary这类 storyId——因此 Agent 应当使用 preview 工具输入 schema 中的 path-based 形态。Fixture 项目任务中正确答案的来源评测目录自带的 fixture 代码即任务的全部上下文。stories/Button.stories.tsx 完整内容如下import type { Meta, StoryObj } from storybook/react; import Button from ../src/components/Button; const meta { title: Example/Button, component: Button, tags: [test], args: { label: Click me, disabled: false, }, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; export const Primary: Story { args: { label: Primary, }, }; export const Secondary: Story { args: { label: Secondary, }, };对照提示词第一步该文件共导入两处storybook/react的Meta、StoryObj类型type-only 导入以及相对路径../src/components/Button的默认导出 Button 组件。这个组件本身极简——一个受label/disabledprops 驱动的button带data-testidbutton-component属性供后续断言或测试定位使用type ButtonProps { label: string; disabled?: boolean; }; export default function Button({ label, disabled false }: ButtonProps) { return ( button typebutton disabled{disabled}>const previewCalls getWorkflowCalls(stories-preview); expectWorkflowCalls([stories-preview]); expect( previewCalls.some((call) workflowCallIncludesStory(call, { absoluteStoryPath: stories/Button.stories.tsx, exportName: Primary, }) ) ).toBe(true); expect( previewCalls.some((call) workflowCallIncludesStory(call, { absoluteStoryPath: stories/Button.stories.tsx, exportName: Secondary, }) ) ).toBe(true);其中三个关键点值得注意expectWorkflowCalls([stories-preview])要求 Agent 的完整工作流恰好是调用stories-preview这一个工作流——不允许额外调用find-story-ids之类的探测工具来回绕即提示词给的信息已足够Agent 应直达预览。逐 story 校验选择器形态workflowCallIncludesStory断言的期望对象同时携带absoluteStoryPath与exportName而非storyId。测试里的注释明确说明了原因Deliberately no storyId: this eval requires the path export strategy, and workflowCallIncludesStory would accept a storyId match on its own.也就是说如果 Agent 偷懒改用 storyId 形态预览该断言会失败——这正是by-path与姊妹评测915-preview-story-by-id的分工所在。some()语义Primary 和 Secondary 可以出现在同一次调用的 stories 数组里也可以分两次调用只要每个 story 都被 path export 形态覆盖即通过。断言所依赖的工具函数定义在 agent-eval/lib/test-utils.ts其中StoryInputExpectation类型精确刻画了两种可选的故事选择形态export type StoryInputExpectation { absoluteStoryPath?: string; exportName?: string; storyId?: string; };该文件同时负责从 Agent 的 shell 命令记录或 MCP 调用记录中提取StorybookWorkflowCall解析逻辑见 agent-eval/lib/shell-parse.ts并在plugin与mcp两种集成方式间做归一化——因此同一份 EVAL.ts 同时约束 MCP 工具和 CLI plugin 两条路径。工具侧实现stories-preview 的输入契约评测断言的标准答案来自 MCP 工具本身的 schema。核心定义在 code/core/src/shared/open-service/toolsets/stories/story-input.tsstoryInputSchema是一个 union提供两种互斥的故事选择形态。形态一路径 导出名本评测考察的形态v.object({ exportName: /* The export name of the story from the story file... */, explicitStoryName: v.optional(v.string()), absoluteStoryPath: /* Absolute path to the story file... */, ...storyInputProps, })各字段的用途结合 schema 中的描述文本absoluteStoryPath故事文件的绝对路径描述明确写道仅当已有 story 文件上下文时与 exportName 一起使用。exportNamestory 在文件中的导出名本例即Primary/Secondary。schema 描述特意引导 Agent只有当你已经在编辑某个 .stories.* 文件、知道其中的导出名时才用这种形态否则应优先 storyId。explicitStoryName可选当 story 通过name属性设置了与导出名不同的显示名时使用否则不设置。props可选覆盖 story 默认 args 的自定义 propsglobals可选预览时的全局参数如themedark/light、localeen/fr、backgrounds如{ value: #000 }等横切关注点。形态二storyIdv.object({ storyId: /* for example button--primary... */, ...storyInputProps, })描述建议不在具体 story 文件内工作时优先使用此形态并提示 ID 应从 docs 工具withStoryIdstrue或 show 操作中获取。这正是915-preview-story-by-id评测对应的路径。输出契约预览成功/失败的结构定义在 code/core/src/shared/open-service/toolsets/stories/definition.ts 中。成功项必须返回title、name和previewUrl三个字段其中previewUrl带有明确的 Agent 行为引导Direct URL to open the story preview. Include this URL in the final user-facing response so users can open it directly.失败项则返回原始input与error字符串保证 Agent 能定位是哪个 story 的预览请求失败。两种选择策略的对照914 vs 915914-preview-story-by-path与 agent-eval/evals/915-preview-story-by-id/PROMPT.md 构成一组对照实验。915 的提示词是Show a preview of two existing Button stories: Primary and Secondary.Do not modify any component or story files.两者的差异揭示了工具 schema 的设计意图维度914by path915by id提示词给的信息文件路径stories/Button.stories.tsx 导出名仅组件与 story 名不含文件路径期望选择器形态absoluteStoryPathexportNamestoryId隐含前置动作阅读 stories 文件顺带回答导入问题通常需先从 story 索引中解析出 storyId断言策略显式排斥 storyId 匹配期望 storyId 匹配从 schema 描述文本看官方对二者的使用边界是清晰的已持有 story 文件上下文时用路径形态否则优先 storyId。914 评测正是把 Agent 钉在已有文件上下文这一分支上验证它不会退化到先查索引、再按 ID 预览的绕路行为。如何本地运行该评测评测套件在仓库根目录以 yarn workspace 方式运行见 agent-eval/README.md# 预览将要运行的内容不产生 API 调用 yarn workspace agent-eval run eval:dry # 只调试这一个评测 EVAL_ONLY914-preview-story-by-path yarn workspace agent-eval run evalREADME 同时强调了两条工程约束一是默认只跑第一个核心评测需EVAL_EXTRA_EVALS1才跑完整工作流评测线EVAL_ONLY则用于单个评测的调试二是本地运行前需在仓库根目录重新编译沙箱注入的 MCP 构建yarn nx run-many -t compile --projects mcp,addon-mcp过期的dist会在 preset 加载时崩溃表面症状是沙箱就绪超时而非构建错误。此外评测按 AgentClaude Code / Codex× 集成方式mcp/plugin× 模型与推理档位组合成实验矩阵见 agent-eval/experiments 下的实验定义文件EVAL.ts会依据运行环境自动适配两种集成方式的调用记录解析。小结914-preview-story-by-path场景用一个三步链条完整刻画了按路径预览 story的工作流提示词以文件路径指代 storyPROMPT.md→ fixture 提供可静态核对的 stories 文件与组件Button.stories.tsx→ 断言强制stories-preview调用携带absoluteStoryPathexportName而非storyIdEVAL.ts。而该链条的最终语义锚点落在 MCP 工具的输入 schema 上story-input.tspath 形态要求调用方已持有故事文件上下文storyId 形态则是无文件上下文时的首选。理解了这组评测也就理解了 Storybook 为 Agent 设计的最小惊讶原则——用户以何种坐标指代 storyAgent 就应使用与之对应的选择器形态。【免费下载链接】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 19:57:23 · 阅读 1.2k Storybook MCP 按文件路径预览 Story：解析 914-preview-story-by-path 评测场景与 stories-preview 工具
Storybook MCP 按文件路径预览 Story解析 914-preview-story-by-path 评测场景与 stories-preview 工具【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇围绕 Storybook 仓库中 agent-eval 评测套件里的914-preview-story-by-path场景展开它给 AI 编码 Agent 下达了一个两步任务——先阅读 stories 文件并说明其导入内容再调用 Storybook MCP 的 preview 工具按「文件路径 导出名」预览 Primary 与 Secondary 两个 Button story。读完本文你能理解 path-based story 选择器的参数契约、评测如何断言 Agent 的工具调用以及该场景与 storyId 选择方式915-preview-story-by-id之间的设计取舍。评测场景的定位Storybook 仓库在 agent-eval 目录下内置了一套 Agent 评测套件它在沙箱中运行编码 AgentClaude Code / Codex让 Agent 对着 fixture 项目执行 Storybook 工作流编写 story、预览或审阅 story、运行 story 测试然后断言 Agent 确实遵循了仓库提供的 MCP 工具或 plugin 技能所定义的工作流。每个评测场景是一个独立目录由三部分组成文件作用PROMPT.md直接投喂给 Agent 的任务提示词EVAL.tsvitest 测试解析 Agent 的调用记录并断言工作流结果package.json声明该评测使用的 fixture 模板本场景为reshaped-storybook914-preview-story-by-path属于 9xx 系列的「MCP 工具行为」评测其核心考察点是当用户以故事文件路径而非 storyId指代 story 时Agent 能否正确使用stories-preview工具的路径形态选择器。原始任务提示词PROMPT.mdPROMPT.md 全文如下仅两句话、两步操作Read the stories file for the button atstories/Button.stories.tsx, and tell me what that file imports.Then afterwards, show a preview of the Primary and Secondary button stories using the Storybook MCP preview tool.拆解这个任务它刻意包含两种不同性质的动作静态阅读读取stories/Button.stories.tsx向用户报告该文件导入了什么。这一步不依赖 MCP考察 Agent 的基础文件理解能力。工具调用使用 Storybook MCP 的 preview 工具预览Primary和Secondary两个 story。关键在于提示词给出的是文件路径 导出名stories/Button.stories.tsx中的Primary/Secondary而不是button--primary这类 storyId——因此 Agent 应当使用 preview 工具输入 schema 中的 path-based 形态。Fixture 项目任务中正确答案的来源评测目录自带的 fixture 代码即任务的全部上下文。stories/Button.stories.tsx 完整内容如下import type { Meta, StoryObj } from storybook/react; import Button from ../src/components/Button; const meta { title: Example/Button, component: Button, tags: [test], args: { label: Click me, disabled: false, }, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; export const Primary: Story { args: { label: Primary, }, }; export const Secondary: Story { args: { label: Secondary, }, };对照提示词第一步该文件共导入两处storybook/react的Meta、StoryObj类型type-only 导入以及相对路径../src/components/Button的默认导出 Button 组件。这个组件本身极简——一个受label/disabledprops 驱动的button带data-testidbutton-component属性供后续断言或测试定位使用type ButtonProps { label: string; disabled?: boolean; }; export default function Button({ label, disabled false }: ButtonProps) { return ( button typebutton disabled{disabled}>const previewCalls getWorkflowCalls(stories-preview); expectWorkflowCalls([stories-preview]); expect( previewCalls.some((call) workflowCallIncludesStory(call, { absoluteStoryPath: stories/Button.stories.tsx, exportName: Primary, }) ) ).toBe(true); expect( previewCalls.some((call) workflowCallIncludesStory(call, { absoluteStoryPath: stories/Button.stories.tsx, exportName: Secondary, }) ) ).toBe(true);其中三个关键点值得注意expectWorkflowCalls([stories-preview])要求 Agent 的完整工作流恰好是调用stories-preview这一个工作流——不允许额外调用find-story-ids之类的探测工具来回绕即提示词给的信息已足够Agent 应直达预览。逐 story 校验选择器形态workflowCallIncludesStory断言的期望对象同时携带absoluteStoryPath与exportName而非storyId。测试里的注释明确说明了原因Deliberately no storyId: this eval requires the path export strategy, and workflowCallIncludesStory would accept a storyId match on its own.也就是说如果 Agent 偷懒改用 storyId 形态预览该断言会失败——这正是by-path与姊妹评测915-preview-story-by-id的分工所在。some()语义Primary 和 Secondary 可以出现在同一次调用的 stories 数组里也可以分两次调用只要每个 story 都被 path export 形态覆盖即通过。断言所依赖的工具函数定义在 agent-eval/lib/test-utils.ts其中StoryInputExpectation类型精确刻画了两种可选的故事选择形态export type StoryInputExpectation { absoluteStoryPath?: string; exportName?: string; storyId?: string; };该文件同时负责从 Agent 的 shell 命令记录或 MCP 调用记录中提取StorybookWorkflowCall解析逻辑见 agent-eval/lib/shell-parse.ts并在plugin与mcp两种集成方式间做归一化——因此同一份 EVAL.ts 同时约束 MCP 工具和 CLI plugin 两条路径。工具侧实现stories-preview 的输入契约评测断言的标准答案来自 MCP 工具本身的 schema。核心定义在 code/core/src/shared/open-service/toolsets/stories/story-input.tsstoryInputSchema是一个 union提供两种互斥的故事选择形态。形态一路径 导出名本评测考察的形态v.object({ exportName: /* The export name of the story from the story file... */, explicitStoryName: v.optional(v.string()), absoluteStoryPath: /* Absolute path to the story file... */, ...storyInputProps, })各字段的用途结合 schema 中的描述文本absoluteStoryPath故事文件的绝对路径描述明确写道仅当已有 story 文件上下文时与 exportName 一起使用。exportNamestory 在文件中的导出名本例即Primary/Secondary。schema 描述特意引导 Agent只有当你已经在编辑某个 .stories.* 文件、知道其中的导出名时才用这种形态否则应优先 storyId。explicitStoryName可选当 story 通过name属性设置了与导出名不同的显示名时使用否则不设置。props可选覆盖 story 默认 args 的自定义 propsglobals可选预览时的全局参数如themedark/light、localeen/fr、backgrounds如{ value: #000 }等横切关注点。形态二storyIdv.object({ storyId: /* for example button--primary... */, ...storyInputProps, })描述建议不在具体 story 文件内工作时优先使用此形态并提示 ID 应从 docs 工具withStoryIdstrue或 show 操作中获取。这正是915-preview-story-by-id评测对应的路径。输出契约预览成功/失败的结构定义在 code/core/src/shared/open-service/toolsets/stories/definition.ts 中。成功项必须返回title、name和previewUrl三个字段其中previewUrl带有明确的 Agent 行为引导Direct URL to open the story preview. Include this URL in the final user-facing response so users can open it directly.失败项则返回原始input与error字符串保证 Agent 能定位是哪个 story 的预览请求失败。两种选择策略的对照914 vs 915914-preview-story-by-path与 agent-eval/evals/915-preview-story-by-id/PROMPT.md 构成一组对照实验。915 的提示词是Show a preview of two existing Button stories: Primary and Secondary.Do not modify any component or story files.两者的差异揭示了工具 schema 的设计意图维度914by path915by id提示词给的信息文件路径stories/Button.stories.tsx 导出名仅组件与 story 名不含文件路径期望选择器形态absoluteStoryPathexportNamestoryId隐含前置动作阅读 stories 文件顺带回答导入问题通常需先从 story 索引中解析出 storyId断言策略显式排斥 storyId 匹配期望 storyId 匹配从 schema 描述文本看官方对二者的使用边界是清晰的已持有 story 文件上下文时用路径形态否则优先 storyId。914 评测正是把 Agent 钉在已有文件上下文这一分支上验证它不会退化到先查索引、再按 ID 预览的绕路行为。如何本地运行该评测评测套件在仓库根目录以 yarn workspace 方式运行见 agent-eval/README.md# 预览将要运行的内容不产生 API 调用 yarn workspace agent-eval run eval:dry # 只调试这一个评测 EVAL_ONLY914-preview-story-by-path yarn workspace agent-eval run evalREADME 同时强调了两条工程约束一是默认只跑第一个核心评测需EVAL_EXTRA_EVALS1才跑完整工作流评测线EVAL_ONLY则用于单个评测的调试二是本地运行前需在仓库根目录重新编译沙箱注入的 MCP 构建yarn nx run-many -t compile --projects mcp,addon-mcp过期的dist会在 preset 加载时崩溃表面症状是沙箱就绪超时而非构建错误。此外评测按 AgentClaude Code / Codex× 集成方式mcp/plugin× 模型与推理档位组合成实验矩阵见 agent-eval/experiments 下的实验定义文件EVAL.ts会依据运行环境自动适配两种集成方式的调用记录解析。小结914-preview-story-by-path场景用一个三步链条完整刻画了按路径预览 story的工作流提示词以文件路径指代 storyPROMPT.md→ fixture 提供可静态核对的 stories 文件与组件Button.stories.tsx→ 断言强制stories-preview调用携带absoluteStoryPathexportName而非storyIdEVAL.ts。而该链条的最终语义锚点落在 MCP 工具的输入 schema 上story-input.tspath 形态要求调用方已持有故事文件上下文storyId 形态则是无文件上下文时的首选。理解了这组评测也就理解了 Storybook 为 Agent 设计的最小惊讶原则——用户以何种坐标指代 storyAgent 就应使用与之对应的选择器形态。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考