CopilotKit Vue Storybook 对等性Parity工程实践以 React Storybook 为规范源构建可对比的 Vue 组件库【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKitCopilotKit 将 Storybook 作为跨框架 UI 组件的可视化回归阵地Vue 侧的每个故事都需要与 examples/v2/react/storybook 逐一镜像以保证copilotkit/vue与copilotkit/react-core在视觉与交互上可并排对比、可逐文件 diff。本文以仓库中的 examples/v2/vue/storybook/AGENTS.md 为骨架结合 Vue/React 两侧真实的 Storybook 源码、配置与脚本完整拆解这份对等性Parity开发规范从范围界定、命名对齐、场景覆盖、插槽slot验证到最终的构建/开发双重校验读完即可上手维护或移植 Vue Storybook 故事。一、为什么 Vue Storybook 需要对等性规范CopilotKit 的定位是Agents Generative UI 的前端技术栈同时维护 React、Vue、Angular 等多套前端 SDK。其中 Vue 侧由 packages/vue 提供组件实现而组件行为是否符合预期、视觉与交互是否与 React 对齐需要一个统一的检验场——这就是 Storybook。仓库为 Vue 单独建立了 examples/v2/vue/storybook 工作区其核心目标写得很明确范围examples/v2/vue/storybook/**目标与examples/v2/react/storybook/**在视觉与故事结构上保持对等换句话说Vue Storybook 不是另起炉灶的自由创作空间而是一面精确映照 React 组件的镜子。AGENTS.md正是这份镜子规则的成文载体任何新增或修改 Vue 故事的贡献者都必须先读它。二、单一事实来源Source of Truth对等性实践的第一步是明确谁说了算。规范原文规定将 React 故事的**名称story names、分组grouping与场景意图scenario intent**视为规范标准canonical每移植一个等价的 Vue 组件就逐条镜像对应的 React 故事故事文件的所有权归属尽量贴近 React 侧让每个 Vue 故事都能直接映射回它的 React 对应物。这一原则在目录结构上得到了严格落地。对比两侧stories/目录可以看到几乎一一对应的文件名Vue 侧examples/v2/vue/storybook/storiesReact 侧examples/v2/react/storybook/storiesCopilotAssistantMessage.stories.tsCopilotAssistantMessage.stories.tsxCopilotChatInput.stories.tsCopilotChatInput.stories.tsxCopilotChatMessageView.stories.tsCopilotChatMessageView.stories.tsxCopilotChatSuggestionPill.stories.tsCopilotChatSuggestionPill.stories.tsxCopilotChatSuggestionView.stories.tsCopilotChatSuggestionView.stories.tsxCopilotChatToggleButton.stories.tsCopilotChatToggleButton.stories.tsxCopilotChatUserMessage.stories.tsCopilotChatUserMessage.stories.tsxCopilotChatView.stories.tsCopilotChatView.stories.tsxCopilotKitInspector.stories.tsCopilotKitInspector.stories.tsxCopilotSidebarView.stories.tsCopilotSidebarView.stories.tsx这套文件即映射表的做法让跨框架 diff 变得极低成本同一功能React 改了什么Vue 侧照着文件名就能找到对应位置。另有CopilotProviderParity.stories.ts、A2UIActivityParity.stories.ts两个以Parity命名的故事文件以及共享的 CopilotStoryLayout.ts /CopilotStoryLayout.vue由 CopilotStoryLayout.ts 导出封装了 Vue 侧的公共布局装饰器。三、对等性约束允许什么、禁止什么规范用三条硬约束框定了边界防止对等性在移植过程中悄悄退化允许 Vue-only 的对等桥接故事如果 React 侧没有为某个已发布的 Vue 对等特性提供 Storybook 示例允许在 Vue 侧单独建立一个对等故事但必须显式标记为 parity bridge对等桥接让读者知道它不是镜像自 React故事标题必须与 React 命名对齐保留对比清晰度是命名对齐的根本目的。例如两侧的CopilotChatView故事都统一使用title: UI/CopilotChatView见 Vue 侧与 React 侧Storybook 侧边栏中的分组位置因此完全一致禁止引入 Vue-only 的脚手架抽象避免那些会让 React↔Vue 故事 diff 变难理解的额外封装层——抽象一旦出现读者就无法再靠逐行对比来判断两个框架的实现是否等价。四、实施路径从占位故事到完整对等规范的 Implementation guidance 给出了一条渐进式路线很适合边移植组件边补故事的节奏组件存在但不完整时先用占位/最小化对等故事占住位置保证故事结构先行对齐对应的 Vue 原语primitive落地后再把故事升级到完整的行为对等始终优先使用稳定、确定性的 props/data确保视觉对比结果可复现、可并排比对。这条先占位、后升级的策略与仓库当前状态互相印证examples/v2/vue/storybook/README.md 明确说明 Vue Storybook 已 scaffold 并运行、默认的 Storybook starter 示例已被移除、Copilot 相关故事在stories/下will be filled to full parity incrementally将逐步补齐到完整对等。五、故事完成清单Blocking Checklist判定对等完成的唯一标准对每个已移植的、用户可见的 Vue 特性只有以下六项全部满足才算故事对等完成。这是AGENTS.md中最具操作性的部分也是 code review 时的检查表存在一个与 React 故事意图对应的 Vue 故事一一映射缺一不可故事标题/分组与 React 命名对齐保证侧边栏与文档顺序可比核心交互状态齐全默认态、激活/加载态、错误/回退态适用时防止只覆盖快乐路径插槽/定制行为有演示当该特性使用 Vue slots 时必须用故事证明 slot 定制可用故事数据确定且稳定保证 React↔Vue 并排对比时不会因随机数据产生视觉偏差storybook build与storybook dev均成功开发与产物构建双通道都不能挂。清单在真实故事中的体现以 CopilotChatView.stories.ts 为例可以逐条验证这份清单场景覆盖定义了Default、PinToSend、WithSuggestions三个故事与 React 侧同名故事一一对应命名对齐三处故事的title均为UI/CopilotChatViewparameters.docs.description文案也保持一致确定性数据storyMessages、pinToSendMessages、suggestionSamples全部是硬编码的静态数组suggestionSamples中第三个建议isLoading: true刻意同时覆盖了普通建议与加载中建议两种状态Slot 演示Vue 故事通过#message-view、#assistant-message命名插槽注入CopilotChatMessageView与CopilotChatAssistantMessage并把thumbsUp/thumbsDown事件接到window.alert上与 React 侧messageView.assistantMessage.onThumbsUp/onThumbsDown的 alert 行为对齐。值得注意的是为了让对比真正公平连测试数据都做了镜像pinToSendMessages中足够多轮来回以强制滚动、让 pin-to-send 模式下输入框上方的渐变区清晰可见这一设计意图在 Vue 侧注释中明确写明Mirrors the React story fixture inCopilotChatView.stories.tsx。六、验证命令有意义改动后的必跑动作规范要求在发生有意义的改动后执行两条命令可从仓库根目录直接运行# 1. 启动 Vue Storybook 开发服务器 pnpm -C examples/v2/vue/storybook dev # 2. 构建 Vue Storybook 静态产物 pnpm -C examples/v2/vue/storybook build从 package.json 可以看清这两条命令背后的真实工作流dev脚本先执行pnpm --filter copilotkit/vue run build:css编译 Vue 包样式sleep 1等待就绪后用concurrently并行拉起三件事——copilotkit/vue的开发构建、copilotkit/web-inspector的开发服务、以及storybook dev -p 6008 --no-openVue Storybook 固定在6008端口且不自动打开浏览器build脚本同样先跑build:css随后执行storybook build输出可部署的静态站点另有check-types通过pnpm --filter copilotkit/vue exec vue-tsc --noEmit做 Vue 类型检查是 CI 中与故事文件配套的类型防线。对比 React 侧 package.json 可以看到设计上的刻意对称React Storybook 使用storybook/nextjs React 19 storybook dev -p 6006端口 6006 vs 6008、copilotkit/react-corevscopilotkit/vue两侧脚本结构完全同构。这份脚本同构正是对等性文化从故事内容延伸到工程配置的体现。七、给维护者的落地建议结合AGENTS.md全文与仓库现状维护 Vue Storybook 时的实操要点可归纳如下新故事先找 React 对应物动手前先确认 React 侧 stories 是否存在同名故事不存在且确属 Vue 已发布特性时新建的故事务必显式标记为 parity bridge数据从 React 侧抄录并保持确定性把 React 故事的 props/fixture 原样镜像到 Vue不引入随机值、不改变标题与分组Slot 即 Vue 的定制面凡是组件文档中声明了 slot 的特性故事里必须有通过#slot-name注入内容的演示这与清单第 4 条一一对应提交前跑双通道校验pnpm -C examples/v2/vue/storybook dev与build必须同时通过清单第 6 条是 Blocking 级别改动涉及类型时再补check-types不要在 Vue 侧发明抽象任何为写起来更省事而引入的额外封装层都会破坏AGENTS.md第 3 条约束让 React↔Vue 的故事 diff 失去可比性。八、总结CopilotKit 的 Vue Storybook 对等性实践本质上是把跨框架一致性从口头约定变成了可执行、可检查的工程规范以 React 故事为单一事实来源用文件名、故事标题、测试数据、脚本结构四个维度全面镜像再用 Blocking 级完成清单和 dev/build 双通道验证兜底。对于正在为copilotkit/vue移植组件或补充故事的开发者这份 AGENTS.md 就是最短路径上的路线图——照章执行即可保证 Vue 故事与 React 侧始终并排可读、逐行可 diff。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考