CopilotKit 预置 Sidebar 组件验收指南基于 CrewAI Conversational Flows 演示的端到端 QA 实战【免费下载链接】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 的预置CopilotSidebar组件可以让你的应用在数行代码内获得一个可开合、与主内容并排的 AI 助手侧边栏。本文以仓库中 CrewAI Conversational Flows 集成的prebuilt-sidebar演示为例完整拆解该组件的验收测试步骤、预期结果与底层实现原理读完你将掌握如何在真实部署环境中对侧边栏的默认展开、消息收发、开关切换与状态保持进行全面验证并理解其不卸载、仅切换可见性的工作方式。一、文档定位与验收前提本篇文章对应的验收文档位于 showcase/integrations/crewai-conversational-flows/qa/prebuilt-sidebar.md它是该集成仓库 QA 体系中的一份功能验收清单。其前置条件只有一条演示应用已部署、Agent 后端健康可用。这意味着验收的是真实链路——从浏览器里的侧边栏输入一路经过前端运行时、CopilotKit Runtime 路由最终抵达后端的 CrewAI Conversational Flows 代理而不是组件层的单元测试。后端健康检查的具体实现可以在 src/app/api/copilotkit/route.ts 中看到GET /api/copilotkit会以 3 秒超时探测AGENT_URL默认http://localhost:8000下的/health端点并返回agent_status: reachable或unreachable (...)。验收前可以通过该健康探测端点快速确认后端是否就绪。二、分步验收从页面加载到会话保持验收清单共六步覆盖了侧边栏组件的核心交互闭环。每一步都可以配合 tests/e2e/prebuilt-sidebar.spec.ts 中对应的 Playwright 自动化用例对照执行人工验收与自动化用例相互印证。步骤 1导航到演示路由并确认页面挂载在浏览器中访问/demos/prebuilt-sidebar路由。页面主内容区应展示标题Sidebar demo — click the launcher。这条路由的入口源码位于 src/app/demos/prebuilt-sidebar/page.tsx其标题实际渲染为 Sidebar demo完整文案见 main-content.tsx。E2E 用例通过page.getByRole(heading, { name: Sidebar demo })断言主内容标题可见以此确认路由挂载的是预期页面。步骤 2验证侧边栏默认展开页面加载后CopilotSidebar /应默认处于打开状态即聊天输入框在首帧即可见。默认展开是由defaultOpen{true}属性驱动的见 page.tsxCopilotSidebar agentIdprebuilt-sidebar defaultOpen{true} /在 v2 实现中defaultOpen通过isModalDefaultOpen传入CopilotChat最终反映为侧边栏视图中的isModalOpen状态并体现在aria-hidden属性上见 CopilotSidebarView.tsx 与 L214 的aria-hidden{!isSidebarOpen}。E2E 用例对应的断言是输入框占位符Type a message可见同时[data-testidcopilot-sidebar]的aria-hidden为false。因此自动化验收时aria-hidden属性是判断开关状态的权威信号比 CSS 动画状态更可靠。步骤 3确认存在启动按钮launcher侧边栏自带一个悬浮的开关按钮launcher。即使侧边栏处于打开状态该按钮依然存在它负责后续的折叠与重新展开操作。E2E 用例通过[data-testidcopilot-chat-toggle]定位它并断言其可见prebuilt-sidebar.spec.ts。步骤 4通过侧边栏发送 Say hi 并确认助手回复在侧边栏输入框中发送Say hi应出现一条助手assistant消息。该演示为侧边栏配置了三条建议快捷指令suggestion pills见 suggestions.tsuseConfigureSuggestions({ suggestions: [ { title: Say hi, message: Say hi! }, { title: Fun fact, message: Give me a fun fact. }, { title: Is 17 prime?, message: Walk me through whether 17 is prime. }, ], available: always, });available: always意味着这些建议在加载时即渲染在侧边栏内。E2E 用例点击Say hi药丸后断言[data-testidcopilot-assistant-message]出现超时 45 秒。因为该演示没有前端工具判定的信号就是出现了一条助手气泡而非校验回复文本。前端发送的消息会通过CopilotKit runtimeUrl/api/copilotkit进入后端路由层为prebuilt-sidebar这个 agent 名称注册了别名route.ts默认指向AGENT_URL/conversational_flows/chat的 CrewAI Conversational Flow。步骤 5通过启动按钮关闭侧边栏点击启动按钮launcher后侧边栏应折叠收起。E2E 用例的实现细节值得注意在较窄视口下打开的侧边栏会拦截指针事件因此自动化用例先通过 JS 级document.querySelector([data-testidcopilot-close-button]).click()从侧边栏内部关闭同时绕开 localhost 上自动启用的 dev-onlycpk-web-inspector覆盖层再断言aria-hidden变为trueprebuilt-sidebar.spec.ts。人工验收时无需如此繁琐直接点击启动按钮即可观察侧边栏滑出收起。步骤 6重新打开并验证消息持久化再次点击启动按钮侧边栏重新展开此前的对话消息应仍然保留。这正是launcher 切换侧边栏时不会卸载组件的直接体现。E2E 用例还额外断言了 URL 保持不变/demos/prebuilt-sidebar$证明开关切换是纯客户端状态变化不触发路由跳转prebuilt-sidebar.spec.ts。三、预期结果与判定标准验收文档给出了三条硬性预期结果它们是判定侧边栏实现是否合格的判据预期结果验证要点对应测试断言侧边栏默认打开首帧即可见输入框与欢迎界面aria-hiddenfalse、输入框可见启动按钮切换侧边栏且不卸载关闭后 DOM 仍挂载重新打开消息不丢失aria-hidden在true/false间切换URL 不变主内容保持可见侧边栏与主内容并排展示而非遮挡主标题 Sidebar demo 始终可见第三点在主内容源码中有明确说明CopilotSidebar /停靠在视口边缘将页面内容推开而不是叠加在其上main-content.tsx这就是Sidebar与CopilotPopup浮层式弹窗在设计上的核心差异。四、底层原理不卸载的开关是如何实现的v2 的CopilotSidebar实现位于 packages/react-core/src/v2/components/chat/CopilotSidebar.tsx其中几个关键设计直接支撑了上面的预期结果受控与不受控双模式defaultOpen让侧边栏自我管理开关状态而openonOpenChange构成受控模式宿主应用完全掌控开关CopilotSidebar.tsx。open/onOpenChange通过ModalOpenControlProvider以 context 传递而不是经由SidebarViewOverride传入避免每次切换都因组件身份变化而重建整个聊天子树CopilotSidebar.tsx——这正是开关不卸载、消息持久的结构性保证。开启/关闭的真实信号侧边栏视图根据isModalOpen状态写入aria-hidden属性CopilotSidebarView.tsx而关闭动画仅通过 CSS transform 将面板滑出DOM 始终挂载。这也解释了为什么验收清单强调re-open 后消息持久——消息状态存放在上层聊天上下文中与面板的视觉开关解耦。五、可配置项速览把验收扩展到自己的场景基于 v2 的CopilotSidebarPropsCopilotSidebar.tsx除了验收文档涉及的defaultOpen与agentId你还可以配置header/toggleButton自定义侧边栏头部与启动按钮的渲染width: number | string面板宽度position停靠位置对应CopilotSidebarViewProps[position]open/onOpenChange受控开关配合宿主应用状态其余继承自CopilotChatProps的聊天能力消息流、建议、工具渲染等。将这些参数组合进上文的分步验收流程即可形成一套可复用的侧边栏功能回归清单。如需将自动化验收跑进 CI可直接以 tests/e2e/prebuilt-sidebar.spec.ts 为模板它已经覆盖了默认展开 → 建议发送 → 手动输入 → 关闭/重开的完整路径是这套 QA 文档在代码层面的直接落地。【免费下载链接】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），仅供参考 
长河君 · 2026/9/12 19:23:40 · 阅读 1.2k CopilotKit 预置 Sidebar 组件验收指南：基于 CrewAI Conversational Flows 演示的端到端 QA 实战
CopilotKit 预置 Sidebar 组件验收指南基于 CrewAI Conversational Flows 演示的端到端 QA 实战【免费下载链接】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 的预置CopilotSidebar组件可以让你的应用在数行代码内获得一个可开合、与主内容并排的 AI 助手侧边栏。本文以仓库中 CrewAI Conversational Flows 集成的prebuilt-sidebar演示为例完整拆解该组件的验收测试步骤、预期结果与底层实现原理读完你将掌握如何在真实部署环境中对侧边栏的默认展开、消息收发、开关切换与状态保持进行全面验证并理解其不卸载、仅切换可见性的工作方式。一、文档定位与验收前提本篇文章对应的验收文档位于 showcase/integrations/crewai-conversational-flows/qa/prebuilt-sidebar.md它是该集成仓库 QA 体系中的一份功能验收清单。其前置条件只有一条演示应用已部署、Agent 后端健康可用。这意味着验收的是真实链路——从浏览器里的侧边栏输入一路经过前端运行时、CopilotKit Runtime 路由最终抵达后端的 CrewAI Conversational Flows 代理而不是组件层的单元测试。后端健康检查的具体实现可以在 src/app/api/copilotkit/route.ts 中看到GET /api/copilotkit会以 3 秒超时探测AGENT_URL默认http://localhost:8000下的/health端点并返回agent_status: reachable或unreachable (...)。验收前可以通过该健康探测端点快速确认后端是否就绪。二、分步验收从页面加载到会话保持验收清单共六步覆盖了侧边栏组件的核心交互闭环。每一步都可以配合 tests/e2e/prebuilt-sidebar.spec.ts 中对应的 Playwright 自动化用例对照执行人工验收与自动化用例相互印证。步骤 1导航到演示路由并确认页面挂载在浏览器中访问/demos/prebuilt-sidebar路由。页面主内容区应展示标题Sidebar demo — click the launcher。这条路由的入口源码位于 src/app/demos/prebuilt-sidebar/page.tsx其标题实际渲染为 Sidebar demo完整文案见 main-content.tsx。E2E 用例通过page.getByRole(heading, { name: Sidebar demo })断言主内容标题可见以此确认路由挂载的是预期页面。步骤 2验证侧边栏默认展开页面加载后CopilotSidebar /应默认处于打开状态即聊天输入框在首帧即可见。默认展开是由defaultOpen{true}属性驱动的见 page.tsxCopilotSidebar agentIdprebuilt-sidebar defaultOpen{true} /在 v2 实现中defaultOpen通过isModalDefaultOpen传入CopilotChat最终反映为侧边栏视图中的isModalOpen状态并体现在aria-hidden属性上见 CopilotSidebarView.tsx 与 L214 的aria-hidden{!isSidebarOpen}。E2E 用例对应的断言是输入框占位符Type a message可见同时[data-testidcopilot-sidebar]的aria-hidden为false。因此自动化验收时aria-hidden属性是判断开关状态的权威信号比 CSS 动画状态更可靠。步骤 3确认存在启动按钮launcher侧边栏自带一个悬浮的开关按钮launcher。即使侧边栏处于打开状态该按钮依然存在它负责后续的折叠与重新展开操作。E2E 用例通过[data-testidcopilot-chat-toggle]定位它并断言其可见prebuilt-sidebar.spec.ts。步骤 4通过侧边栏发送 Say hi 并确认助手回复在侧边栏输入框中发送Say hi应出现一条助手assistant消息。该演示为侧边栏配置了三条建议快捷指令suggestion pills见 suggestions.tsuseConfigureSuggestions({ suggestions: [ { title: Say hi, message: Say hi! }, { title: Fun fact, message: Give me a fun fact. }, { title: Is 17 prime?, message: Walk me through whether 17 is prime. }, ], available: always, });available: always意味着这些建议在加载时即渲染在侧边栏内。E2E 用例点击Say hi药丸后断言[data-testidcopilot-assistant-message]出现超时 45 秒。因为该演示没有前端工具判定的信号就是出现了一条助手气泡而非校验回复文本。前端发送的消息会通过CopilotKit runtimeUrl/api/copilotkit进入后端路由层为prebuilt-sidebar这个 agent 名称注册了别名route.ts默认指向AGENT_URL/conversational_flows/chat的 CrewAI Conversational Flow。步骤 5通过启动按钮关闭侧边栏点击启动按钮launcher后侧边栏应折叠收起。E2E 用例的实现细节值得注意在较窄视口下打开的侧边栏会拦截指针事件因此自动化用例先通过 JS 级document.querySelector([data-testidcopilot-close-button]).click()从侧边栏内部关闭同时绕开 localhost 上自动启用的 dev-onlycpk-web-inspector覆盖层再断言aria-hidden变为trueprebuilt-sidebar.spec.ts。人工验收时无需如此繁琐直接点击启动按钮即可观察侧边栏滑出收起。步骤 6重新打开并验证消息持久化再次点击启动按钮侧边栏重新展开此前的对话消息应仍然保留。这正是launcher 切换侧边栏时不会卸载组件的直接体现。E2E 用例还额外断言了 URL 保持不变/demos/prebuilt-sidebar$证明开关切换是纯客户端状态变化不触发路由跳转prebuilt-sidebar.spec.ts。三、预期结果与判定标准验收文档给出了三条硬性预期结果它们是判定侧边栏实现是否合格的判据预期结果验证要点对应测试断言侧边栏默认打开首帧即可见输入框与欢迎界面aria-hiddenfalse、输入框可见启动按钮切换侧边栏且不卸载关闭后 DOM 仍挂载重新打开消息不丢失aria-hidden在true/false间切换URL 不变主内容保持可见侧边栏与主内容并排展示而非遮挡主标题 Sidebar demo 始终可见第三点在主内容源码中有明确说明CopilotSidebar /停靠在视口边缘将页面内容推开而不是叠加在其上main-content.tsx这就是Sidebar与CopilotPopup浮层式弹窗在设计上的核心差异。四、底层原理不卸载的开关是如何实现的v2 的CopilotSidebar实现位于 packages/react-core/src/v2/components/chat/CopilotSidebar.tsx其中几个关键设计直接支撑了上面的预期结果受控与不受控双模式defaultOpen让侧边栏自我管理开关状态而openonOpenChange构成受控模式宿主应用完全掌控开关CopilotSidebar.tsx。open/onOpenChange通过ModalOpenControlProvider以 context 传递而不是经由SidebarViewOverride传入避免每次切换都因组件身份变化而重建整个聊天子树CopilotSidebar.tsx——这正是开关不卸载、消息持久的结构性保证。开启/关闭的真实信号侧边栏视图根据isModalOpen状态写入aria-hidden属性CopilotSidebarView.tsx而关闭动画仅通过 CSS transform 将面板滑出DOM 始终挂载。这也解释了为什么验收清单强调re-open 后消息持久——消息状态存放在上层聊天上下文中与面板的视觉开关解耦。五、可配置项速览把验收扩展到自己的场景基于 v2 的CopilotSidebarPropsCopilotSidebar.tsx除了验收文档涉及的defaultOpen与agentId你还可以配置header/toggleButton自定义侧边栏头部与启动按钮的渲染width: number | string面板宽度position停靠位置对应CopilotSidebarViewProps[position]open/onOpenChange受控开关配合宿主应用状态其余继承自CopilotChatProps的聊天能力消息流、建议、工具渲染等。将这些参数组合进上文的分步验收流程即可形成一套可复用的侧边栏功能回归清单。如需将自动化验收跑进 CI可直接以 tests/e2e/prebuilt-sidebar.spec.ts 为模板它已经覆盖了默认展开 → 建议发送 → 手动输入 → 关闭/重开的完整路径是这套 QA 文档在代码层面的直接落地。【免费下载链接】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），仅供参考