CopilotKit Chat Slots 全解析用 Slot 覆盖定制 CopilotChat 的欢迎屏、消息气泡与输入区【免费下载链接】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 在 CrewAI Conversational Flows 集成中提供的chat-slots演示QA 文档见 showcase/integrations/crewai-conversational-flows/qa/chat-slots.md系统讲解 CopilotChat 的 Slot插槽覆盖机制。读者将掌握welcomeScreen、input.disclaimer、messageView.assistantMessage三大核心插槽的注册方式、验证方法以及 SlotMarker 与makeSlotOverride等底层实现原理能够把同样思路迁移到自己的聊天界面定制中。一、前置条件Demo 已部署且 Agent 后端健康QA 文档给出的唯一前置条件是Demo 已部署且 Agent 后端健康原文 Demo deployed; agent backend healthy。这背后对应的是一条完整的前后端调用链前端CopilotKit组件通过runtimeUrl/api/copilotkit与agentchat-slots建立连接见 src/app/demos/chat-slots/page.tsx。Next.js 侧的路由 src/app/api/copilotkit/route.ts 把chat-slots注册为一个 agent 别名L52并通过HttpAgent将请求代理到独立的 Agent 后端进程const AGENT_URL process.env.AGENT_URL || http://localhost:8000L12。后端由 CrewAI Flow 承载。chat-slots复用中性聊天 FlowPromptedChatFlow见 src/agents/chat_flow.py它不挂载任何后端工具、不修改状态、不做子代理委托只负责以BASE_CHAT_PROMPT生成简洁回复——这正是 slot 演示需要的纯对话环境L29-L37。因此在开始任何 QA 验证前先确认两件事即可前端能访问/demos/chat-slots路由后端:8000上的 CrewAI Flow 健康可用route.ts的GET接口暴露了/health探活与AGENT_URL信息L185-L208。二、测试步骤逐条拆解从欢迎屏到免责声明QA 文档定义了一条从首屏渲染到多轮对话的完整验证路径。下面结合源码把每一步的验证对象、预期信号和背后的实现逐条展开。2.1 导航到/demos/chat-slots浏览器访问http://deploy-host/demos/chat-slots。页面主体由 page.tsx 渲染一个CopilotKitProvider 包裹一个居中、圆角、带边框的CopilotChatL100-L109。该 demo 在集成清单 manifest.yaml 中的注册名为 Chat Customization (Slots)id: chat-slotsroute 为/demos/chat-slots定位就是通过 Slot 系统定制 CopilotChat。2.2 验证自定义欢迎屏welcomeScreen SlotQA 第一项断言出现包含Welcome to the Slots demo文本的自定义欢迎屏信号为data-testidcustom-welcome-screen。对应实现位于 slot-wrappers.tsx 的CustomWelcomeScreen它接收input与suggestionView两个 React 元素作为参数把它们重新排版进自己的布局提示语 输入框 建议区三行结构并挂上data-testidcustom-welcome-screen。注册方式是把该组件通过makeSlotOverride赋给CopilotChat的welcomeScreen属性page.tsx L53-L54。值得注意的是插槽之间是可以嵌套的welcomeScreen内部还暴露了welcomeMessage子插槽CustomWelcomeMessageslot-wrappers.tsx L26-L40。QA 文档虽然没有单列它但 e2e 测试专门同时断言了欢迎屏与其内部子消息两个 testid用来防止意外回退到默认欢迎界面见 tests/e2e/chat-slots.spec.ts L15-L26。2.3 验证 indigo 渐变卡片与 Custom Slot 标签QA 要求验证欢迎屏区域出现indigo 渐变卡片和Custom Slot 标签。这是 SlotMarker 组件的可视特征CustomWelcomeScreen的 SlotMarker 使用colorindigoslot-wrappers.tsx L51对应SLOT_COLORS表中的border-indigo-400/bg-indigo-500配色slot-marker.tsx L27-L31。每个覆盖区域被包在一个虚线边框 色块 badge的容器中badge 默认透明、悬停时显示该区域的 Slot 路径如WelcomeScreen、MessageView.AssistantMessage点击 badge 还会把路径复制到剪贴板slot-marker.tsx L140-L160。这个设计使 demo 同时充当Slot 图谱Slot Atlas开发者在页面上悬停任意区域就能一眼看出哪里可定制、对应的 slot 路径是什么。QA 里 Custom Slot 标签的语义即指这类slot-labelbadge。2.4 验证建议按钮suggestionView useConfigureSuggestionsQA 要求页面上可见Write a sonnet与Tell me a joke两条建议。这两条建议不是硬编码在欢迎屏里的而是通过useConfigureSuggestions注册的见 suggestions.tsuseConfigureSuggestions({ 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保证两条建议 pill 在欢迎屏上立即可见而非仅在空闲时轮换。e2e 测试用[data-testidcopilot-suggestion]定位并逐一断言标题原文精确可见chat-slots.spec.ts L28-L44。在 slot 层面建议区同样被覆盖CustomSuggestionContainer与CustomSuggestion分别包住SuggestionView.Container和SuggestionView.Suggestion两个插槽slot-wrappers.tsx L196-L219。2.5 点击建议验证自定义助手消息卡片messageView.assistantMessageQA 要求点击Write a sonnet或发送任意消息后助手回复被包在data-testidcustom-assistant-message的自定义卡片中带 indigo 边框与 slot badge。实现层面CustomAssistantMessage将默认的CopilotChatAssistantMessage原样渲染并在外层套上SlotMarkercoloremeraldlabel 为MessageView.AssistantMessage见 slot-wrappers.tsx L67-L79。需要向读者澄清一个实现细节当前仓库的实际代码中这条自定义消息的规范化验证信号是data-slot-labelMessageView.AssistantMessage由SlotMarker在 slot-marker.tsx L142 统一输出e2e 测试正是以[data-slot-labelMessageView.AssistantMessage]作为slot 覆盖真正生效的规范断言chat-slots.spec.ts L8。QA 文档中提到的custom-assistant-message可作为人工验证时对自定义卡片的直观参照自动化的权威信号则来自data-slot-label。此外messageView还一并覆盖了用户消息CustomUserMessage、推理消息CustomReasoningMessage仅当消息流含推理内容时渲染和流式光标CustomCursorpage.tsx L78-L88。2.6 验证输入区下方的自定义免责声明input.disclaimerQA 最后要求输入框下方可见data-testidcustom-disclaimer。对应CustomDisclaimerslot-wrappers.tsx L161-L177以coloryellow的 SlotMarker 包裹data-testidcustom-disclaimer直接挂在内部 div 上。它在input覆盖对象中与textArea、sendButton、addMenuButton一起注册page.tsx L59-L76。e2e 测试特别验证了 disclaimer 的状态感知行为欢迎屏阶段它被隐藏发送第一条消息、助手回复并退出欢迎状态后才出现chat-slots.spec.ts L66-L88。三、预期结果三大 Slot 覆盖同时生效QA 文档给出的预期结果非常凝练welcomeScreen / input.disclaimer / messageView.assistantMessage 三个 Slot 覆盖全部可见。将它与完整测试步骤对照可以归纳为下面这张验证矩阵Slot 路径自定义组件人工验证信号自动化验证信号e2eWelcomeScreen含嵌套WelcomeScreen.WelcomeMessageCustomWelcomeScreendata-testidcustom-welcome-screen indigo 虚线卡片 Custom Slot badgecustom-welcome-screen及其子节点custom-welcome-message均可见SuggestionView.SuggestionCustomSuggestionWrite a sonnet / Tell me a joke 两条 pill[data-testidcopilot-suggestion]标题精确匹配MessageView.AssistantMessageCustomAssistantMessage自定义消息卡片indigo/emerald 边框 badge[data-slot-labelMessageView.AssistantMessage]可见Input.DisclaimerCustomDisclaimerdata-testidcustom-disclaimer首轮回复后custom-disclaimer可见只要这四条全部通过即证明 slot 覆盖链路从前端注册、React 渲染到 DOM 信号完整打通且没有回退到 CopilotChat 的默认实现。四、Slots 系统的源码级原理4.1 SlotMarker把覆盖是否生效变成可检测信号整个 demo 的验证哲学建立在SlotMarker上每个自定义组件外包一层 markermarker 输出data-slot-labelslot-path作为规范信号slot-marker.tsx L140-L143。它同时解决三个问题可测试性e2e 只需查询data-slot-label即可断言任意插槽覆盖生效无需依赖视觉回归。可视化虚线边框 悬停显示的路径 badge 让每个覆盖区域在页面上肉眼可见。嵌套隔离marker 会嵌套welcomeScreen 包着 welcomeMessage / input / suggestionView因此 label 默认opacity-0只有当前 marker 被悬停且其内部没有其它 marker 被悬停时才点亮——注释中明确说明这是为了避开普通:hover .slot-label会把所有嵌套标签一起点亮的问题slot-marker.tsx L99-L108。配色表SLOT_COLORS使用静态查表而不是border-${color}-400动态拼接原因在源码注释中写得很清楚Tailwind v4 的源码扫描器必须在构建期就能看到完整类名字符串slot-marker.tsx L21-L22。4.2 makeSlotOverride一次集中的类型断言slot 属性在copilotkit/react-core中是按**默认组件的精确身份nominal type**标注的而自定义 wrapper 返回的是结构兼容但身份不同的组件。为此 src/app/demos/_shared/slot-override.ts 提供export function makeSlotOverrideTDefault( component: ComponentTypeany, ): TDefault { return component as unknown as TDefault; }它把as unknown as typeof X这类断言收敛到一个具名 helper 中让读者一眼明白这里涉及的是 slot 契约而不是类型体操。源码注释也预告一旦 slot 属性类型改为接受结构兼容性这个 helper 就可以删除断言自动解除slot-override.ts L7-L9。同时仓库还保留了一份只读的教学片段 slot-overrides.snippet.tsx它用最小代码展示 welcomeScreen、assistantMessage、disclaimer 三个插槽的注册范式不参与生产渲染专供文档引用。4.3 e2e 测试如何锁定多轮行为chat-slots.spec.ts 用 5 个用例把 QA 文档固化成回归防线首屏欢迎屏及其嵌套子插槽同时可见防止回退默认欢迎界面两条建议 pill 标题逐字匹配点击 Tell me a joke 后出现MessageView.AssistantMessage包装超时 45s覆盖首条流式回复首轮消息后 disclaimer 出现第二轮对话同样被自定义 slot 包装用expect.poll先等首轮流稳定再断言自定义消息数量 ≥ 2确保覆盖不是只在第一条消息生效的偶发现象。测试注释还披露了两个实测细节textarea 上的 Enter 提交在该部署下偶发丢消息因此改用显式点击copilot-send-button助手消息在首个 chunk 到达时就会显示需要等待流稳定后再断言后续轮次。五、完整 Slot 全景这个 demo 到底覆盖了多少插槽QA 文档只验证三个插槽但生产页面实际注册了十余个覆盖这正是 Slot Atlas 的用意。完整清单见 slot-wrappers.tsxwelcomeScreenWelcomeScreen、嵌套WelcomeScreen.WelcomeMessageinputInput.TextArea、Input.SendButton、Input.Disclaimer、Input.AddMenuButtonmessageViewMessageView.AssistantMessage、MessageView.UserMessage、MessageView.ReasoningMessage、MessageView.CursorsuggestionViewSuggestionView.Container、SuggestionView.SuggestionscrollViewScrollView.ScrollToBottomButton、ScrollView.Feather两个值得注意的惰性插槽Input.AddMenuButton只有当CopilotChatInput传入了onAddFile或toolsMenu时才会渲染。因此 page.tsx L70-L75 特意塞了一个toolsMenu: [{ label: Demo tool (no-op), action: () {} }]给该插槽一个存在的理由。MessageView.ReasoningMessagechat-slots 后端是无推理的sample_agentPromptedChatFlow直接走openai/gpt-5.4流式补全不产生 AG-UI REASONING 事件所以该插槽虽然被包裹注册但在本 demo 中始终休眠——推理渲染的完整演示位于/demos/reasoning-default与/demos/reasoning-custom见 suggestions.ts L5-L10。六、QA 验证的常见坑与建议区分人工信号与自动化信号欢迎屏与免责声明同时暴露data-testid人工友好与data-slot-label统一规范建议自动化以data-slot-label为权威断言避免文档与实现措辞不一致如 QA 文档中的custom-assistant-message与实际的data-slot-labelMessageView.AssistantMessage。流式响应需要稳定窗口助手气泡在首个 chunk 到达即可见但输入框会一直处于响应中直到流结束。多轮断言前先做 2 秒无新增内容的稳定性轮询参考 chat-slots.spec.ts L108-L121。优先点击 send 按钮而非回车该部署下 textarea 回车提交偶发失效测试代码已明确切换为点击copilot-send-button。嵌套插槽的可见性语义welcome 阶段 disclaimer 刻意隐藏、assistant 包装只在对话开始后出现断言时需对齐这一状态机否则会出现时序性误报。后端健康是前提所有前端断言都建立在AGENT_URL默认http://localhost:8000上的 CrewAI Flow 可用之上GET /api/copilotkit的健康探活接口是排障的第一入口route.ts L185-L208。七、小结CopilotKit 的 Slot 系统把 CopilotChat 拆解为欢迎屏、输入区、消息视图、建议区、滚动视图五组可替换插槽chat-slots演示同时证明了它的三种用法覆盖结构welcomeScreen 重新布局、包装默认实现assistantMessage / userMessage 外包一层自定义样式、纯插值disclaimer 追加自定义内容。QA 文档 e2e 测试 SlotMarker 信号三者结合形成了一套人工可看、自动化可断、源码可查的完整验证闭环——这既是本 demo 的验收标准也是开发者在自有项目中落地 slot 定制时可以直接复用的方法论。【免费下载链接】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），仅供参考