Open Generative UI

一个开源示例项目，展示如何使用 CopilotKit 和 LangChain Deep Agents 构建丰富、交互式的 AI 生成 UI（Generative UI）。你可以让智能体（agent）可视化算法、创建 3D 动画、渲染图表或生成交互式图表——所有内容都以实时 HTML/SVG 的形式在沙箱化的 iframe 中呈现。

https://github.com/user-attachments/assets/ed28c734-e54e-4412-873f-4801da544a7f

https://github.com/user-attachments/assets/ba7db70d-07c0-49af-b221-f962f30245e2

功能说明

该智能体生成的是 生成式 UI（Generative UI） —— 不仅仅是文本回复，而是完全可交互的视觉组件：

• 算法可视化 —— 二分查找、BFS vs DFS、排序算法等
• 3D 动画 —— 交互式 WebGL/CSS3D 场景
• 图表与图示 —— 饼图、柱状图、网络图等
• 交互式小部件 —— 表单、模拟器、数学绘图等

所有视觉内容均在沙箱化 iframe 中渲染，并自动支持亮色/暗色主题、渐进式揭示动画和响应式尺寸调整。

快速开始

make setup    # 安装依赖 + 创建 .env 模板
# 编辑 apps/agent/.env 文件，填入你真实的 OpenAI API 密钥
make dev      # 启动所有服务

需要强大的模型。 生成式 UI 要求模型具备高能力，能够在单次输出中生成结构良好且复杂的 HTML/SVG。请在 .env 文件中将 LLM_MODEL 设置为以下之一：

模型	提供商
gpt-5.4 / gpt-5.4-pro	OpenAI
claude-opus-4-6	Anthropic
gemini-3.1-pro	Google

较小或能力较弱的模型将导致布局错乱、缺少交互性或可视化不完整。

• 前端应用: http://localhost:3000
• 智能体服务: http://localhost:8123

可用命令

命令	说明
make setup	安装所有依赖并创建 .env 模板
make dev	启动所有服务（前端 + 智能体 + MCP）
make dev-app	仅启动 Next.js 前端
make dev-agent	仅启动 LangGraph 智能体
make dev-mcp	仅启动 MCP 服务器
make build	构建所有应用
make lint	对所有应用进行代码检查
make clean	清理构建产物
make help	显示所有可用命令

你也可以直接使用 pnpm（如 pnpm dev、pnpm dev:app、pnpm dev:agent 等）。

MCP 服务器（自托管）

本仓库包含一个独立的 Model Context Protocol (MCP) 服务器，向任何兼容 MCP 的客户端（包括 Claude Desktop、Claude Code 和 Cursor）提供设计系统、技能说明文档和 HTML 文档组装器。

提供的功能

• assemble_document 工具 —— 将 HTML 片段包裹完整的 CSS 设计系统和桥接 JS，返回可直接用于 iframe 的完整文档
• 技能资源 —— 浏览和读取技能说明文档（skills://list、skills://{name}）
• 提示模板 —— 预先组合好的提示词，用于小部件、SVG 图表和高级可视化

Claude Desktop（stdio 模式）

在你的 Claude Desktop 配置文件（claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "open-generative-ui": {
      "command": "node",
      "args": ["dist/stdio.js"],
      "cwd": "/path/to/apps/mcp"
    }
  }
}

Claude Code / HTTP 客户端

# 启动 HTTP 服务器
cd apps/mcp && pnpm dev

在 .mcp.json 中添加：

{
  "openGenerativeUI": {
    "url": "http://localhost:3100/mcp"
  }
}

完整配置、Docker 部署和 API 参考请见 apps/mcp/README.md。

架构

基于 Turborepo 的 monorepo，包含三个包：

apps/
├── app/       Next.js 16 前端（CopilotKit v2, React 19, Tailwind 4）
├── agent/     Deep Agent（deepagents + CopilotKit 中间件，基于技能）
└── mcp/       独立 MCP 服务器（设计系统 + 技能 + 文档组装器）

Deep Agent + 技能系统

智能体后端使用 LangChain Deep Agents（create_deep_agent），采用基于技能（skills-based）的架构。不同于将所有可视化指令注入系统提示词，技能被定义为 apps/agent/skills/ 目录下的 SKILL.md 文件，并通过渐进式披露（progressive disclosure）按需加载：

apps/agent/skills/
├── advanced-visualization/SKILL.md   # UI 原型、仪表盘、Chart.js、生成艺术
├── master-playbook/SKILL.md          # 回复理念、决策树、叙述模式
└── svg-diagrams/SKILL.md             # SVG 生成规则、组件模式、图表类型

Deep Agents 还内置了规划能力（write_todos）、文件系统工具和子智能体支持。

工作流程

1. 用户通过 CopilotKit 聊天界面发送提示
2. Deep Agent 决定 是返回文本、调用工具，还是渲染视觉组件——必要时查阅相关技能
3. widgetRenderer —— 前端的 useComponent Hook —— 接收智能体生成的 HTML，并在沙箱化 iframe 中渲染
4. 骨架屏加载 在 iframe 加载期间显示，随后内容平滑淡入
5. iframe 内部的 ResizeObserver 将内容高度回传给父页面，实现无缝自动调整尺寸

关键 CopilotKit 模式

模式	Hook	示例
生成式 UI	useComponent	饼图、柱状图、小部件渲染器
前端工具	useFrontendTool	主题切换
人在环路（Human-in-the-loop）	useHumanInTheLoop	会议调度器
默认工具渲染	useDefaultRenderTool	工具执行状态

决策矩阵 —— 选择合适的可视化方式

用户询问的内容……	输出类型	技术栈
X 的工作原理（物理层面）	示意图	SVG
X 的工作原理（抽象层面）	交互式讲解	HTML + 内联 SVG
流程 / 步骤	流程图	SVG
架构 / 包含关系	结构图	SVG
数据库模式 / 实体关系图（ERD）	关系图	Mermaid
随时间变化的趋势	折线图	Chart.js
类别对比	柱状图	Chart.js
整体中的部分	环形图（Doughnut chart）	Chart.js
关键绩效指标（KPI）/ 度量	仪表盘	HTML 指标卡片
设计用户界面（UI）	线框图（Mockup）	HTML
在多个选项间做选择	对比卡片	HTML 网格
循环流程	分步展示（Step-through）	HTML 步进器
物理 / 数学	仿真（Simulation）	Canvas + JS
函数 / 方程	绘图器（Plotter）	SVG + JS
数据探索	可排序表格	HTML + JS
创意 / 装饰性内容	艺术 / 插图	SVG
3D 可视化	3D 场景	Three.js
音乐 / 音频	合成器（Synthesizer）	Tone.js
网络 / 图结构	力导向布局（Force layout）	D3.js
快速的事实性回答	纯文本	无
代码解决方案	代码块	无
情感支持	温暖的文字	无

技术栈

Next.js 16、React 19、Tailwind CSS 4、LangChain Deep Agents、LangGraph、CopilotKit v2、Turborepo、Recharts

许可证

MIT

OpenGenerativeUI 快速上手指南

环境准备

• 操作系统：推荐 macOS / Linux（Windows WSL2 亦可）
• Node.js：v20 或更高版本
• 包管理器：推荐使用 pnpm（v8+）
• API 密钥：需准备以下任一 LLM 提供商的 API Key：
  • OpenAI（推荐 gpt-5.4 或 gpt-5.4-pro）
  • Anthropic（claude-opus-4-6）
  • Google（gemini-3.1-pro）

⚠️ 注意：生成式 UI 对模型能力要求较高，低性能模型可能导致布局错乱或交互缺失。

安装步骤

1. 克隆仓库：

   git clone https://github.com/user-attachments/assets/OpenGenerativeUI.git
   cd OpenGenerativeUI
   

2. 安装依赖并生成配置模板：

   make setup
   

3. 配置 API 密钥： 编辑 apps/agent/.env 文件，填入你的 OpenAI（或其他）API Key：

   OPENAI_API_KEY=your_api_key_here
   LLM_MODEL=gpt-5.4  # 或其他支持的模型
   

4. 启动开发服务：

   make dev
   

服务启动后，访问以下地址：

• 前端应用：http://localhost:3000
• Agent 服务：http://localhost:8123

💡 国内用户建议配置 npm/pnpm 镜像加速安装：

pnpm config set registry https://registry.npmmirror.com

基本使用

1. 打开 http://localhost:3000
2. 在聊天框中输入可视化请求，例如：
   • “用动画演示快速排序过程”
   • “画一个展示用户登录流程的流程图”
   • “创建一个可交互的饼图，显示各产品销量占比”
3. AI 将自动生成并渲染交互式 HTML/SVG 组件，嵌入在沙箱 iframe 中，支持自动亮暗色主题和响应式尺寸。

你也可以单独启动特定服务：

make dev-app      # 仅启动前端
make dev-agent    # 仅启动 Agent
make dev-mcp      # 仅启动 MCP 服务