CopilotKit Chat Slots 深度验证指南CrewAI 集成下的欢迎页、免责声明与消息气泡定制【免费下载链接】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导读本文围绕 CopilotKit 的 Chat Slots插槽覆盖机制以 CrewAI (Crews) 集成仓库 中的 chat-slots 演示页为对象完整梳理 QA 验证的目标、前置条件、测试步骤与预期结果并结合前端源码、共享辅助函数与 Playwright E2E 用例讲清 slot 覆盖为什么能生效、slot 路径如何命名 以及 如何自动化断言 三个层面的问题。读完本文你将掌握 CopilotChat 三大核心插槽——welcomeScreen、input.disclaimer、messageView.assistantMessage——的定制方法、标记方式与端到端验证手段。一、QA 目标三个 Slot 覆盖必须同时可见chat-slots演示页的本职工作是验证 CopilotChat 的插槽机制开发者可以把聊天界面的默认区块替换成自定义 React 组件且替换必须端到端生效——从欢迎屏到输入区再到消息气泡。QA 文档把验收收敛为一条可判定的断言welcomeScreen欢迎屏覆盖可见默认欢迎页被自定义组件替换input.disclaimer输入区免责声明覆盖可见输入框下方展示自定义声明文案messageView.assistantMessage助手消息气泡覆盖可见助手回复被自定义包裹组件渲染。对应关系可参考 chat-slots QA 文档 以及生产演示页 page.tsx 中的插槽注册代码。二、前置条件Demo 已部署且 Agent 后端健康执行 QA 之前必须满足Demo 已部署crewai-crews集成应用处于可访问状态/demos/chat-slots路由可正常打开Agent 后端健康CrewAI Flow 服务默认运行在8000端口已启动且响应正常。后端的健康状态可以借助 API 路由 暴露的GET /api/copilotkit健康探针确认——它返回agent_url与agent_statusreachable/unreachable同时透出OPENAI_API_KEY是否已设置。Agent 地址由环境变量AGENT_URL决定默认http://localhost:8000见 route.ts。值得一提的细节chat-slots这个 agent 名并没有独立后端而是被注册映射到中立的 chat Flow 端点/chat见 route.ts 的 agentNames 列表。这意味着它不会产生 AG-UI 的 reasoning 事件也不会夹带 CrewAI crew 默认的系统提示词自述——这正是该演示页能纯粹展示 UI 插槽的前提。三、测试步骤逐条拆解QA 文档给出的步骤是打开/demos/chat-slots确认自定义欢迎屏可见data-testidcustom-welcome-screen并带有靛蓝渐变卡片与 Custom Slot 标签确认 Write a sonnet 与 Tell me a joke 两个建议词可见点击 Write a sonnet或直接发送消息确认助手回复被自定义消息卡片包裹data-testidcustom-assistant-message带靛蓝边框与 slot 徽标确认输入框下方出现自定义免责声明data-testidcustom-disclaimer。3.1 欢迎屏WelcomeScreen与嵌套WelcomeMessage子插槽欢迎屏是展示插槽嵌套能力的典型区域。在 slot-wrappers.tsx 中CustomWelcomeScreen接收input与suggestionView两个 ReactElement自行排列布局并在内部又嵌入了CustomWelcomeMessage子插槽。QA 步骤中靛蓝渐变卡片 Custom Slot 标签指的就是这一层SlotMarkerindigo 色、虚线边框、可点击的 slot 路径徽标包裹出的视觉效果。从源码看欢迎屏同时暴露了两个data-testid外层custom-welcome-screen、内层custom-welcome-message。E2E 用例刻意同时断言这两者正是为了防止意外回退到默认欢迎页——详见 chat-slots.spec.ts。3.2 建议词由useConfigureSuggestions驱动Write a sonnet 与 Tell me a joke 并非写死在 JSX 里而是通过 suggestions.ts 中的useConfigureSuggestions钩子注册useConfigureSuggestions({ suggestions: [ { title: Write a sonnet, message: Write a short sonnet about AI. }, { title: Tell me a joke, message: Tell me a short joke. }, ], available: always, });available: always意味着两个建议词在欢迎屏上立即可见E2E 用copilot-suggestion这个 testid 过滤文本后断言可见超时 15 秒。点击建议词实际发送的是message字段对应的完整消息例如 Tell me a short joke.。3.3 助手消息MessageView.AssistantMessage插槽包裹助手回复气泡由CustomAssistantMessage包裹默认的CopilotChatAssistantMessage并在外层套上 emerald 色的SlotMarker其data-slot-labelMessageView.AssistantMessage属性是判断插槽是否真正生效的权威信号见 spec.ts 顶部注释。QA 步骤里靛蓝边框 slot 徽标对应的是该 Marker 的视觉形态。3.4 免责声明Input.Disclaimer插槽免责声明属于input插槽族注册方式为input.disclaimer见 page.tsx。它在欢迎屏状态下是隐藏的只有用户发送首条消息、进入聊天态后才可见——E2E 用例对此有专门断言见 spec.ts。四、插槽机制源码深挖从注册到标记4.1makeSlotOverride集中化的类型断言插槽 prop 的类型是名义类型nominally typed——它要求组件与默认组件完全同构。而一个结构上兼容的自定义包装组件虽然在运行时完全可用却过不了 TypeScript 的类型检查。为此项目提供了共享助手 slot-override.tsexport function makeSlotOverrideTDefault( component: ComponentTypeany, ): TDefault { return component as unknown as TDefault; }它把as unknown as断言集中到一处让读者一眼看出这是在满足插槽契约而非散落的类型体操。演示页正是通过它注册欢迎屏、文本域、发送按钮、免责声明等十余个插槽见 page.tsx。提示教学向的最小示例欢迎屏 / 助手消息 / 免责声明三件套单独整理在 slot-overrides.snippet.tsx 中该文件仅供文档展示、不参与运行适合快速对照理解插槽注册的最小形态。4.2SlotMarker可复用的插槽可视化外壳slot-marker.tsx 是整页演示的视觉核心它为每个插槽渲染虚线边框、配色徽标和可点击复制的 slot 路径按钮。几个关键实现点data-slot-label属性渲染在 Marker 外层 span 上是 E2E 判定插槽是否接线的规范信号静态类名查找表SLOT_COLORS由于 Tailwind v4 在构建期扫描源码动态拼接border-${color}-400会失效所以颜色表用完整的静态 class 字符串硬编码嵌套隔离Marker 之间会嵌套欢迎屏包着 input 与 suggestionView普通:hover会点亮所有层级的标签因此 CSS 借助:not(:has(.slot-marker:hover))谓词确保只高亮最内层被悬停的 Marker一键复制点击徽标可把WelcomeScreen、MessageView.AssistantMessage这类 slot 路径写入剪贴板方便开发者把路径带进自己的代码。4.3 input 插槽族与toolsMenu的联动演示页给input同时塞入插槽覆盖与普通 props见 page.tsx除textArea、sendButton、disclaimer、addMenuButton四个插槽外还传了toolsMenu: [{ label: Demo tool (no-op), action: () {} }]。这样做的意义是Input.AddMenuButton插槽只有在设置了onAddFile或toolsMenu时才会渲染见 slot-wrappers.tsx 中的注释种子化的toolsMenu让这个插槽有了出现的理由。4.4 完整的插槽全景如果把演示页所有插槽按路径列出便得到一张插槽地图插槽路径对应区块Marker 配色WelcomeScreen欢迎屏整体indigoWelcomeScreen.WelcomeMessage欢迎屏内嵌标语violetInput.TextArea输入文本框orangeInput.SendButton发送按钮redInput.Disclaimer输入区下方免责声明yellowInput.AddMenuButton添加菜单按钮pinkMessageView.AssistantMessage助手消息气泡emeraldMessageView.UserMessage用户消息气泡skyMessageView.ReasoningMessage推理过程消息roseMessageView.Cursor流式输出中的光标amberSuggestionView.Container建议词容器cyanSuggestionView.Suggestion单个建议词tealScrollView.ScrollToBottomButton回到底部按钮limeScrollView.Feather输入区上方渐隐遮罩fuchsia其中MessageView.ReasoningMessage属于挂载但不活跃的插槽chat-slots连的是不带 reasoning 配置的中立 Flow永远不产生 AG-UIREASONING_MESSAGE_*事件因此该插槽只为演示 Atlas 存在。需要看推理插槽真正点亮的效果应访问/demos/reasoning-default与/demos/reasoning-custom此说明来自 suggestions.ts 的注释。五、Playwright E2E把 QA 步骤固化为自动化断言QA 文档的每条人工步骤都能在 tests/e2e/chat-slots.spec.ts 中找到对应的自动化用例首次加载渲染自定义欢迎屏断言custom-welcome-screen与其嵌套的custom-welcome-message同时可见——双断言防止回退到默认欢迎页两个建议词逐字渲染用copilot-suggestion过滤 Write a sonnet / Tell me a joke各给 15 秒超时点击建议词后助手消息插槽生效点击 Tell me a joke 后等待MessageView.AssistantMessage的 slot-marker 出现45 秒超时覆盖流式首块到达时间发送首条消息后免责声明可见通过copilot-send-button显式点击发送注释说明 Enter 提交在此部署上偶发丢失随后断言custom-disclaimer可见第二轮对话仍被插槽包裹用expect.poll等待第一轮文本流稳定2 秒无新增内容视为完成再发第二句断言MessageView.AssistantMessage的计数 ≥ 2证明插槽作用于每一轮而非仅首条。其中 poll 等待流稳定 的技巧值得借鉴assistant 气泡在首个 chunk 到达时即可见但输入区要到整个流结束后才退出 responding 状态因此直接断言第二条消息可见容易产生竞态先等文本稳定再发第二轮是稳妥做法见 spec.ts。六、预期结果与验收判定QA 文档的最终判定标准只有一个三个插槽覆盖全部可见——welcomeScreen、input.disclaimer、messageView.assistantMessage。从工程实践角度可以再补两条隐性的判定参考运行时信号[data-slot-labelMessageView.AssistantMessage]出现在 DOM 中说明覆盖真正接线而非回退默认渲染失败模式若欢迎屏断言通过但助手气泡是裸的默认样式多半是插槽 prop 未正确传入或类型断言把组件注册成了错误的插槽路径若免责声明不出现先检查是否仍停留在欢迎屏状态。七、快速上手如何在你的页面里复刻这套插槽引入 V2 组件从copilotkit/react-core/v2导入CopilotKit、CopilotChat及其子组件CopilotChatView、CopilotChatInput、CopilotChatAssistantMessage等编写包装组件用SlotMarker或你自己的外壳包裹默认组件透传全部 props用makeSlotOverride注册把包装组件断言为对应插槽的类型组装 propswelcomeScreen、input、messageView、suggestionView、scrollView五个插槽组按需覆盖接上后端CopilotKit runtimeUrl/api/copilotkit agentchat-slots并由 runtime 路由把 agent 名映射到你的 AG-UI 端点自动化验证参照 E2E 用例用data-testid与data-slot-label双通道断言防止回退到默认 UI。需要注意的前置约束插槽覆盖作用于CopilotChat组件树需要配套 V2 版本依赖与健康的 agent 后端GET /api/copilotkit返回agent_status: reachable。完整可运行示例以 chat-slots 演示页 与 slot-wrappers.tsx 为准。【免费下载链接】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），仅供参考