CopilotKit 开放生成式 UI（Minimal）质量验证指南：Google ADK 沙箱渲染全流程检查

CopilotKit 开放生成式 UIMinimal质量验证指南Google ADK 沙箱渲染全流程检查【免费下载链接】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 与 Google ADK 集成演示中的Open-Ended Generative UI最小实现场景给出从环境就绪性检查、核心功能验证、特性级检查建议条目、流式占位、SVG 渲染、动画循环、错误处理到预期性能指标的一整套可执行 QA 清单。读完本文你将掌握如何验证 agent 流式输出generateSandboxedUi工具调用、运行时中间件将其转换为open-generative-ui活动事件、并在沙箱 iframe 中挂载渲染的完整链路同时理解每条检查项背后的源码依据。一、前置条件确认演示环境与运行时接线在执行任何验证步骤之前需要确认以下三项前提成立否则后续所有断言都会因环境问题而失真演示应用已部署且可访问确保/demos/open-gen-ui页面能够正常加载。Agent 后端健康访问/api/health确认 Google ADK agent 服务健康。该端点由 health/route.ts 提供异常时会直接反映在后续的对话请求上。OGUI 运行时已注册open_gen_uigraph在 copilotkit-ogui/route.ts 中openGenerativeUI.agents数组必须包含open-gen-ui本 demo 与open-gen-ui-advanced共用该路由两者通过CopilotKit agent...传入不同的 agent 名区分。第三点是整个演示成立的关键。查看该路由的源码可以看到运行时通过HttpAgent将open-gen-ui与open-gen-ui-advanced分别绑定到 Python 后端的/open_gen_ui与/open_gen_ui_advanced端点const runtime new CopilotRuntime({ agents: { open-gen-ui: new HttpAgent({ url: ${AGENT_URL}/open_gen_ui, headers, }), open-gen-ui-advanced: new HttpAgent({ url: ${AGENT_URL}/open_gen_ui_advanced, headers, }), }, openGenerativeUI: { agents: [open-gen-ui, open-gen-ui-advanced], }, });源码注释明确强调运行时中间件OpenGenerativeUIMiddleware只有在openGenerativeUI.agents列表命中 agent 名时才会将流式generateSandboxedUi工具调用转换为open-generative-ui活动事件若该列表缺失中间件永不触发demo 的 iframe 会保持空白。这是 QA 检查中“iframe 挂载”断言能通过的根本前提。二、基础功能验证页面布局、输入框与首轮对话前置条件满足后进入第一组验证导航到open-gen-uidemo 页面验证CopilotChat在居中的max-w-4xl容器内以全高渲染验证输入 composer输入框可见发送一条基础消息如 “Hi”验证 agent 调用了generateSandboxedUi且一个沙箱 iframe 被挂载到聊天记录transcript内部验证最终 UI 渲染前会出现流式占位消息placeholder message页面布局由 page.tsx 定义外层flex justify-center items-center h-screen w-full负责水平居中内层h-full w-full max-w-4xl flex flex-col p-3将聊天区域约束在最大宽度 4xl 的纵向容器中chat.tsx 则以flex-1 rounded-2xl的CopilotChat组件填满剩余高度。“流式占位消息”来自后端 agent 的输出契约详见第四节agent 先发射placeholderMessages数组如 “Sketching the scene…”、“Labelling axes…”、“Wiring up the animation…”随后才流式输出 HTML前端因此在最终 UI 就绪前先展示占位文案。这一点同时被 e2e 测试注释佐证运行时中间件将工具调用流转换为open-generative-ui活动事件由内置的OpenGenerativeUIActivityRenderer挂载到沙箱iframe sandboxallow-scripts中。三、特性级检查建议条目SuggestionsDemo 页面渲染四条预设建议suggestion pill定义于 suggestions.ts通过useConfigureSuggestions以available: always注入“3D axis visualization (model airplane)” 建议可见“How a neural network works” 建议可见“Quicksort visualization” 建议可见“Fourier: square wave from sines” 建议可见const minimalSuggestions [ { title: 3D axis visualization, message: 3D axis visualization (model airplane) }, { title: How a neural network works, message: How a neural network works }, { title: Quicksort visualization, message: Quicksort visualization }, { title: Fourier: square wave from sines, message: Fourier: square wave from sines }, ];值得注意的实现细节message字符串在 aimock 夹具体系中同时充当确定性的 fixture key。e2e 测试 open-gen-ui.spec.ts 的注释说明这些消息必须与showcase/aimock/d5-all.json中的高优先级条目逐字对齐——因为d5-all.json先于 feature-parity.json 加载其 first-match-wins 排序优先于后者中宽泛的userMessage: hi兜底条目从而保证点击每个 pill 都会产生稳定的generateSandboxedUi工具调用而不是被通用兜底夹具吸收成普通的问候回复。e2e 测试用以下断言验证了这一点const expected [ 3D axis visualization, How a neural network works, Quicksort visualization, Fourier: square wave from sines, ]; const suggestions page.locator([data-testidcopilot-suggestion]); for (const title of expected) { await expect(suggestions.filter({ hasText: title }).first()).toBeVisible(); }四、特性级检查神经网络提示具体渲染验证点击 “How a neural network works” 建议后逐项验证流式期间显示短占位行例如 “Sketching the scene…”、“Labelling axes…”、“Wiring up the animation…”assistant 回合内挂载一个沙箱 iframe 活动iframe 内渲染的是内联svg元素而不是堆叠的div可见三层节点输入约 4 个、隐藏约 5 个、输出约 2 个及连接线存在层标签如 “Input”、“Hidden”、“Output”以及 “Forward pass” 说明文字激活脉冲动画循环从输入层向前传播至输出层——indigo 表示激活态slate 表示静息态无需用户交互可视化持续循环这些渲染约束并非偶然而是由 design-skill.ts 中的VISUALIZATION_DESIGN_SKILL明确规定的。该技能通过前端 Provider 的openGenerativeUI.designSkill注入为 agent 上下文取代默认的 shadcn 风格设计技能其中对几何渲染的要求原文即“Use inline SVG (preferred) orcanvasfor geometric content — NEVER stack dozens ofdivs to draw shapes”。动画与配色同样有明确的实现依据动画优先使用 CSSkeyframes transitions而非setInterval循环性概念旋转、波周期、网络脉冲使用animation-iteration-count: infinite。这正是 QA 中“动画循环播放、无 jank”断言背后的设计意图。配色Accent / primary motion: indigo #6366f1Neutral axes...: slate #64748b。激活脉冲以 indigo 呈现、静息态以 slate 呈现与设计技能中的语义色定义一一对应。后端侧open_gen_ui_agents.py 中_OPEN_GEN_UI_INSTRUCTION与设计技能保持一致并额外强调“On every user turn you MUST call thegenerateSandboxedUifrontend tool exactly once”确保每一轮都会产生一次 UI 渲染。五、特性级检查Quicksort 提示二次渲染验证在全新的一轮对话中点击 “Quicksort visualization” 建议渲染新的沙箱 iframe内含约 10 个 SVG 矩形柱条排序过程中说明文字动态更新如 “Partition around pivot”、“Swap”、“Recurse left”枢轴pivot高亮使用琥珀色#f59e0b被比较元素使用 indigo#6366f1颜色要求与设计技能的调色板完全一致Warning / attention / active: amber #f59e0b与Accent / primary motion: indigo #6366f1。说明文字动态更新则对应设计技能中的“Add short text callouts ...如 Pivot”规则以及“Motion must teach——每个动画元素都应对应概念的一个步骤如 pivot 对数组进行分区”。与神经网络用例一样后端 agent 的系统提示通过stop_on_terminal_text回调与AGUIToolset工具集驱动generateSandboxedUi的输出。六、特性级检查设计技能注入的全局约束对任何渲染输出均应验证以下通用设计约束可视化遵守调色板indigo 强调色、emerald 成功色、amber 警告色、slate 中性色外层容器为白色背景、圆角、带内边距不溢出到视口边缘可视化顶部包含一行标题与一行副标题这些约束全部来自VISUALIZATION_DESIGN_SKILL的对应规则“Paletteindigo/emerald/amber/slate 语义色”、“Outer card: white background, 1px solid #e2e8f0 border, 10-12px border-radius, 20-24px padding”以及“Include a 1-line title 1-line subtitle at the top describing the concept”。QA 检查项实际上是设计技能可执行性的一次端到端验收——如果渲染输出违反这些约束说明 design skill 未被正确注入或 LLM 未遵循 agent 上下文中的规范。七、错误处理验证异常输入与沙箱隔离发送明显离题的提示如 “banana banana banana”验证 agent 仍会渲染沙箱 UI或给出得体的文本回复——不得出现未处理的异常验证渲染过程中主页面host page无控制台错误沙箱内部的警告可忽略验证沙箱 iframe不会尝试 fetch / XHR / localStorage网络面板中无来自 iframe 的 origin 泄漏请求发送空消息输入应被拒绝且不报错流式中途刷新页面验证不会残留损坏的 UI错误处理检查项的源码依据非常扎实“离题提示仍能渲染”源于后端系统提示的兜底机制_OPEN_GEN_UI_INSTRUCTION要求“every user turn you MUST callgenerateSandboxedUiexactly once”因此即使输入离题agent 也应产出一次 UI 渲染或回退到文本回复而不是抛出未处理异常。“无 fetch / XHR / localStorage”是设计技能与后端提示共同强调的硬性约束design-skill.ts中明确写明“Do NOT attempt fetch, XHR, localStorage, cookies, or Websandbox.connection.remote calls”因为该 minimal 场景没有宿主侧沙箱函数可视化必须自运行后端_OPEN_GEN_UI_INSTRUCTION同样声明“No fetch / XHR / localStorage — the sandbox has no same-origin access”。“刷新页面无残留”可结合 e2e 测试的断言边界理解测试只验证 iframe 存在且srcdoc/src非空并明确不通过contentFrame()内省 iframe DOM——因为sandboxallow-scripts无allow-same-origin会阻止宿主跨源访问 frame。这也解释了为何 QA 允许“sandbox-internal warnings”只要求主页面无错误。八、预期结果性能与渲染基准验证完成后应达到以下基准指标预期聊天加载时间3 秒内提交提示后首个可视化挂载约 15 秒内沙箱 iframe 内容渲染基于 SVG 的内容含标签化的轴 / 层 / 图例动画使用 CSS keyframes 平滑循环无 setInterval 造成的抖动UI 状态无 UI 错误或布局损坏“首个可视化约 15 秒内挂载”与 e2e 测试的超时设定吻合test.setTimeout(120_000)iframe 可见性断言超时为 60 秒srcdoc/src非空的轮询断言超时为 30 秒——这些数字为 QA 的 15 秒经验值提供了自动化侧的回旋余量。e2e 测试 open-gen-ui.spec.ts 对四个 pillFourier、3D axis、Neural network、Quicksort各执行一次“点击 pill → iframe 挂载 → 源非空”的断言可视为本 QA 文档中核心功能与特性级检查的自动化镜像。九、QA 文档与自动化测试的对应关系本 QA 文档qa/open-gen-ui.md与仓库中的 e2e 测试、源码三者构成“人工验收 → 自动化断言 → 实现依据”的闭环QA 检查项自动化镜像源码依据页面加载 4 个建议可见page loads with chat composer and 4 suggestion pillssuggestions.ts点击 pill 挂载沙箱 iframe{Fourier, 3D axis, Neural network, Quicksort} pill renders a sandboxed iframe...page.tsx、chat.tsx运行时将工具调用转为活动事件测试注释中描述open-generative-ui活动事件挂载于iframe sandboxallow-scriptscopilotkit-ogui/route.tsagent 每轮必须调用generateSandboxedUi—由后端提示保证open_gen_ui_agents.py渲染约束SVG、调色板、占位消息、动画仅断言 iframe 源非空不内省 DOMdesign-skill.tse2e 测试头部的注释还透露了一个重要的运维原则断言边界止于 iframe 是否被宿主成功填充。由于sandboxallow-scripts无allow-same-origin阻止了跨源 frame 访问且每次运行生成的内层 HTML 各不相同自动化无法也不应验证 iframe 内部 SVG 节点、层数或动画——这些更细致的渲染质量检查正是 QA 文档中“特性级检查”部分的人工职责所在。换言之本文档的第四至六节内容恰恰是自动化测试刻意留给人工 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），仅供参考