尧图网站建设 
Storybook 怎么通过 JSDoc 注释与 Story 写法让 AI Agent 有效复用组件【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook你希望 AI Agent 在生成 UI 时优先找到并正确使用项目里已有的组件而不是每次重新发明轮子。Storybook 通过 MCP server 向 Agent 提供一份manifest组件与文档的 JSON 清单Agent 靠它了解有哪些组件、API 是什么、每种用法示例该在什么场景使用。关键事实是这份 manifest 由 Storybook 对 CSF 文件和 MDX 文件做静态分析、并解析组件源码中的 prop 类型生成——你写在代码里的 JSDoc 注释和 Story 描述就是 Agent 能拿到的全部语义信息。注释写得含糊Agent 复用时就会选错组件或传错 props。适用前提Storybook 的 AI 能力目前处于 preview 阶段API 可能在未来版本中变化。components manifest 目前只有 React 各框架react-vite、react-webpack5、nextjs、nextjs-vite、tanstack-react、react-native-web-vite、storybook/angular-vite和storybook/vue3-vite会生成Webpack 版的storybook/angular及其他框架不生成 manifest本文方法对它们不适用。确认你的框架会生成 manifest并打开开关components manifest 默认关闭需要在.storybook/main.js|ts的features里显式启用// .storybook/main.ts export default { features: { componentsManifest: true, }, };不同框架的附加要求见 MCP server overviewReact 各框架只需componentsManifest。storybook/vue3-vite还需要experimentalDocgenServer两个键写在同一个features对象里// .storybook/main.tsvue3-vite 项目 export default { features: { componentsManifest: true, experimentalDocgenServer: true, }, };storybook/angular-vite只需componentsManifest它自行启用experimentalDocgenServer。对 React 项目manifest 生成会读取reactDocgen配置项指定的 prop 类型解析库未配置时装了storybook/react则默认react-docgen。官方推荐用react-docgen-typescript因为它给出的 props 信息更准确完整如果 manifest 生成太慢再换回更快的react-docgen// .storybook/main.tsReact 项目可选 export default { typescript: { reactDocgen: react-docgen-typescript, }, };给组件和 props 写 JSDocmanifest 里的组件描述、prop 说明都来自组件源码中的 JSDoc 注释。官方明确建议给组件和它们的 props 尽量多写 JSDoc 上下文见 Manifests。写法上有三个要点组件级注释在组件导出上方写描述说明组件用于什么场景。如果同时提供summaryAgent 收到的是 summary没有 summary 时收到的是 description 的截断版本// Button.tsx /** * Button is used for user interactions that do not navigate to another route. * For navigation, use Link instead. * * summary for user interactions that do not navigate to another route */ export const Button (props) { // ... };描述里可以使用 Markdown 语法来添加格式或链接上面的例子就是在告诉 Agent需要跳转时别用 Button去用 Link 组件。prop 级注释在 props 定义的每个字段上写清用途Agent 会据此决定如何传参export interface ButtonProps { /** The icon to render before the button text */ icon?: ReactNode; }Vue 项目的特殊位置在script setupSFC 中组件 docblock 必须挂在defineOptions()调用上单独写在块顶部的 docblock 不会被解析到script setup langts /** * Button is used for user interactions that do not navigate to another route. * For navigation, use Link instead. * * summary for user interactions that do not navigate to another route */ defineOptions({ name: Button }); defineProps{ /** Text on the button. */ label?: string; }(); /script让每个 Story 只演示一个概念并说明 whyStories 是 manifest 里给 Agent 的用法示例snippet 来自应用了 args、decorators 之后的最终渲染结果所以无需担心抽象层面的写法。Best practices 给出的规则是每个 Story 尽量只演示一个概念或用法并且描述重点放在为什么要这么用而不只是展示的是什么。官方示例ReactCSF 3// Button.stories.tsx import type { Meta, StoryObj } from storybook/react-vite; import { Button } from ./Button; const meta { component: Button, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; // ✅ Good to show the default state export const Basic: Story {}; // ✅ Good to demonstrate a specific use case export const Primary: Story { args: { primary: true }, }; // ✅ Good - even though this story renders more than one button, // they both demonstrate the same concept of a disabled button export const Disabled: Story { args: { disabled: true }, render: (args) ( Button {...args}Disabled Button/Button Button {...args} primary Disabled Primary Button /Button / ), }; // ❌ Bad - demonstrates too many concepts at once, making // it less clear and less useful as a reference for agents export const SizesAndVariants: Story { render: () ( Button sizesmallSmall Button/Button ButtonMedium Button/Button Button sizelargeLarge Button/Button Button variantoutlineOutline Button/Button Button varianttextText Button/Button / ), };Disabled虽然渲染了两个按钮但都服务于禁用态这同一个概念所以合格SizesAndVariants一次性演示尺寸和变体多种概念对 Agent 来说是噪声。再给每个 Story 加上 JSDoc 描述和组件一样支持summary。对 StoryAgent 收到的是 summary或描述的前 60 个字符——注意这不是截断组件描述的同一条规则story 有明确的 60 字符界限重要结论尽量写进 summary/** * Primary buttons are used for the main action in a view. * There should not be more than one primary button per view. * * summary for the main action in a view */ export const Primary: Story { args: { primary: true }, };注意不要只是复述 Story 展示了什么要说明为什么该场景要用这种用法。用 !manifest 标签裁剪清单给 Agent 的上下文不是越多越好缺关键信息时 Agent 用不好组件塞入与任务无关的信息反而拖累它。默认所有 story 和独立 docs 页都带manifesttag、都会进入清单对 Agent 不需要参考的内容反模式演示、已废弃组件、纯教学 story移除 tag 即可排除// my-component.stories.ts // This story will be included in the manifest because it has the implicit manifest tag export const Basic: Story {}; export const ForInstructionOnly: Story { tags: [!manifest], // Remove the manifest tag to exclude this story from the manifests };想排除整个组件在文件 metadefault export上移除manifesttag该文件下所有 story 都不会进清单。想排除整个 MDX docs 页在页面元数据上移除例如Meta titleDoc for Humans Only tags{[!manifest]} /。另外对不依附于组件的独立 MDX 页如 design token 说明可以在Metatag 上提供summary它会被写进 manifest 供 Agent 参考。但注意 docs manifest 完全基于 MDX 源文件的静态分析只存在于源文件中的信息才会进清单。例如Colors.mdx里用{colors.map(...)}从外部变量渲染的颜色manifest 里不会有这些色值——相关细节必须直接写在 MDX 文件里而不是引用外部来源。验证 manifest 内容写完注释和 Story 后启动 Storybookdev server 运行时即可访问端口可能不是 6006组件清单原始 JSONhttp://localhost:6006/manifests/components.json构建后的 Storybook 用/manifests/components.json路由。文档清单原始 JSONhttp://localhost:6006/manifests/docs.json。推荐用 manifest debuggerhttp://localhost:6006/manifests/components.html。它把 components 和 docs 两份清单合并成人可读格式页面顶部会列出清单生成过程中遇到的 errors 和 warnings点击可以过滤出相关条目方便定位我的 JSDoc 为什么没进去。在 JSON 或 debugger 里核对三件事组件条目里是否出现了你写的description、props 里是否带有你在 JSDoc 中写的description、stories数组里的 snippet 是否符合预期。两个已知限制会影响验证方式启用experimentalDocgenServer时dev server 对两个 JSON 路由都返回 404——清单改由 docgen service 按需组装而不落盘此时请从构建后的 Storybook 读取或使用 debugger两种模式都可用。这永远影响storybook/angular-vite和storybook/vue3-vite也影响开启了该特性的 React 项目。debugger 的 prop 表格只读 React docgen 数据Angular/Vue 组件在 debugger 中会不显示 prop 类型但 Agent 侧的docs-show工具仍会返回它们的 inputs/outputs两者不一致是已知行为不是清单生成失败。边界与限制以上能力处于 previewmanifest schema 尚未稳定官方明确说不要把它当作公共 API 依赖。框架不生成 components manifest 时如 Webpack 版storybook/angulardocs 工具集不可用但 MCP server 的 development 与 testing 工具集仍可用——此时 JSDoc/Story 写法对 Agent 复用组件没有增益。如果 story 文件声明了subcomponentscomponents manifest 也会包含对应子组件的补充 API 文档无需额外配置。确认清单内容符合预期后下一步是把 MCP server 接入你的 Agent让它在真实开发中读取 manifest、生成 story 并跑交互测试来验证复用效果。【免费下载链接】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 怎么通过 JSDoc 注释与 Story 写法让 AI Agent 有效复用组件
Storybook 怎么通过 JSDoc 注释与 Story 写法让 AI Agent 有效复用组件【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook你希望 AI Agent 在生成 UI 时优先找到并正确使用项目里已有的组件而不是每次重新发明轮子。Storybook 通过 MCP server 向 Agent 提供一份manifest组件与文档的 JSON 清单Agent 靠它了解有哪些组件、API 是什么、每种用法示例该在什么场景使用。关键事实是这份 manifest 由 Storybook 对 CSF 文件和 MDX 文件做静态分析、并解析组件源码中的 prop 类型生成——你写在代码里的 JSDoc 注释和 Story 描述就是 Agent 能拿到的全部语义信息。注释写得含糊Agent 复用时就会选错组件或传错 props。适用前提Storybook 的 AI 能力目前处于 preview 阶段API 可能在未来版本中变化。components manifest 目前只有 React 各框架react-vite、react-webpack5、nextjs、nextjs-vite、tanstack-react、react-native-web-vite、storybook/angular-vite和storybook/vue3-vite会生成Webpack 版的storybook/angular及其他框架不生成 manifest本文方法对它们不适用。确认你的框架会生成 manifest并打开开关components manifest 默认关闭需要在.storybook/main.js|ts的features里显式启用// .storybook/main.ts export default { features: { componentsManifest: true, }, };不同框架的附加要求见 MCP server overviewReact 各框架只需componentsManifest。storybook/vue3-vite还需要experimentalDocgenServer两个键写在同一个features对象里// .storybook/main.tsvue3-vite 项目 export default { features: { componentsManifest: true, experimentalDocgenServer: true, }, };storybook/angular-vite只需componentsManifest它自行启用experimentalDocgenServer。对 React 项目manifest 生成会读取reactDocgen配置项指定的 prop 类型解析库未配置时装了storybook/react则默认react-docgen。官方推荐用react-docgen-typescript因为它给出的 props 信息更准确完整如果 manifest 生成太慢再换回更快的react-docgen// .storybook/main.tsReact 项目可选 export default { typescript: { reactDocgen: react-docgen-typescript, }, };给组件和 props 写 JSDocmanifest 里的组件描述、prop 说明都来自组件源码中的 JSDoc 注释。官方明确建议给组件和它们的 props 尽量多写 JSDoc 上下文见 Manifests。写法上有三个要点组件级注释在组件导出上方写描述说明组件用于什么场景。如果同时提供summaryAgent 收到的是 summary没有 summary 时收到的是 description 的截断版本// Button.tsx /** * Button is used for user interactions that do not navigate to another route. * For navigation, use Link instead. * * summary for user interactions that do not navigate to another route */ export const Button (props) { // ... };描述里可以使用 Markdown 语法来添加格式或链接上面的例子就是在告诉 Agent需要跳转时别用 Button去用 Link 组件。prop 级注释在 props 定义的每个字段上写清用途Agent 会据此决定如何传参export interface ButtonProps { /** The icon to render before the button text */ icon?: ReactNode; }Vue 项目的特殊位置在script setupSFC 中组件 docblock 必须挂在defineOptions()调用上单独写在块顶部的 docblock 不会被解析到script setup langts /** * Button is used for user interactions that do not navigate to another route. * For navigation, use Link instead. * * summary for user interactions that do not navigate to another route */ defineOptions({ name: Button }); defineProps{ /** Text on the button. */ label?: string; }(); /script让每个 Story 只演示一个概念并说明 whyStories 是 manifest 里给 Agent 的用法示例snippet 来自应用了 args、decorators 之后的最终渲染结果所以无需担心抽象层面的写法。Best practices 给出的规则是每个 Story 尽量只演示一个概念或用法并且描述重点放在为什么要这么用而不只是展示的是什么。官方示例ReactCSF 3// Button.stories.tsx import type { Meta, StoryObj } from storybook/react-vite; import { Button } from ./Button; const meta { component: Button, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; // ✅ Good to show the default state export const Basic: Story {}; // ✅ Good to demonstrate a specific use case export const Primary: Story { args: { primary: true }, }; // ✅ Good - even though this story renders more than one button, // they both demonstrate the same concept of a disabled button export const Disabled: Story { args: { disabled: true }, render: (args) ( Button {...args}Disabled Button/Button Button {...args} primary Disabled Primary Button /Button / ), }; // ❌ Bad - demonstrates too many concepts at once, making // it less clear and less useful as a reference for agents export const SizesAndVariants: Story { render: () ( Button sizesmallSmall Button/Button ButtonMedium Button/Button Button sizelargeLarge Button/Button Button variantoutlineOutline Button/Button Button varianttextText Button/Button / ), };Disabled虽然渲染了两个按钮但都服务于禁用态这同一个概念所以合格SizesAndVariants一次性演示尺寸和变体多种概念对 Agent 来说是噪声。再给每个 Story 加上 JSDoc 描述和组件一样支持summary。对 StoryAgent 收到的是 summary或描述的前 60 个字符——注意这不是截断组件描述的同一条规则story 有明确的 60 字符界限重要结论尽量写进 summary/** * Primary buttons are used for the main action in a view. * There should not be more than one primary button per view. * * summary for the main action in a view */ export const Primary: Story { args: { primary: true }, };注意不要只是复述 Story 展示了什么要说明为什么该场景要用这种用法。用 !manifest 标签裁剪清单给 Agent 的上下文不是越多越好缺关键信息时 Agent 用不好组件塞入与任务无关的信息反而拖累它。默认所有 story 和独立 docs 页都带manifesttag、都会进入清单对 Agent 不需要参考的内容反模式演示、已废弃组件、纯教学 story移除 tag 即可排除// my-component.stories.ts // This story will be included in the manifest because it has the implicit manifest tag export const Basic: Story {}; export const ForInstructionOnly: Story { tags: [!manifest], // Remove the manifest tag to exclude this story from the manifests };想排除整个组件在文件 metadefault export上移除manifesttag该文件下所有 story 都不会进清单。想排除整个 MDX docs 页在页面元数据上移除例如Meta titleDoc for Humans Only tags{[!manifest]} /。另外对不依附于组件的独立 MDX 页如 design token 说明可以在Metatag 上提供summary它会被写进 manifest 供 Agent 参考。但注意 docs manifest 完全基于 MDX 源文件的静态分析只存在于源文件中的信息才会进清单。例如Colors.mdx里用{colors.map(...)}从外部变量渲染的颜色manifest 里不会有这些色值——相关细节必须直接写在 MDX 文件里而不是引用外部来源。验证 manifest 内容写完注释和 Story 后启动 Storybookdev server 运行时即可访问端口可能不是 6006组件清单原始 JSONhttp://localhost:6006/manifests/components.json构建后的 Storybook 用/manifests/components.json路由。文档清单原始 JSONhttp://localhost:6006/manifests/docs.json。推荐用 manifest debuggerhttp://localhost:6006/manifests/components.html。它把 components 和 docs 两份清单合并成人可读格式页面顶部会列出清单生成过程中遇到的 errors 和 warnings点击可以过滤出相关条目方便定位我的 JSDoc 为什么没进去。在 JSON 或 debugger 里核对三件事组件条目里是否出现了你写的description、props 里是否带有你在 JSDoc 中写的description、stories数组里的 snippet 是否符合预期。两个已知限制会影响验证方式启用experimentalDocgenServer时dev server 对两个 JSON 路由都返回 404——清单改由 docgen service 按需组装而不落盘此时请从构建后的 Storybook 读取或使用 debugger两种模式都可用。这永远影响storybook/angular-vite和storybook/vue3-vite也影响开启了该特性的 React 项目。debugger 的 prop 表格只读 React docgen 数据Angular/Vue 组件在 debugger 中会不显示 prop 类型但 Agent 侧的docs-show工具仍会返回它们的 inputs/outputs两者不一致是已知行为不是清单生成失败。边界与限制以上能力处于 previewmanifest schema 尚未稳定官方明确说不要把它当作公共 API 依赖。框架不生成 components manifest 时如 Webpack 版storybook/angulardocs 工具集不可用但 MCP server 的 development 与 testing 工具集仍可用——此时 JSDoc/Story 写法对 Agent 复用组件没有增益。如果 story 文件声明了subcomponentscomponents manifest 也会包含对应子组件的补充 API 文档无需额外配置。确认清单内容符合预期后下一步是把 MCP server 接入你的 Agent让它在真实开发中读取 manifest、生成 story 并跑交互测试来验证复用效果。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考