thesysdev/openui · 上手攻略

• 仓库：thesysdev/openui
• 链接：https://github.com/thesysdev/openui
• 分类：engineering / app（Generative UI 框架）
• 作者：spark
• 更新：2026-10-22

一句话结论

如果你的 LLM 助手需要「回一段 UI 而不是回一段话」，OpenUI 值得认真评估——它的流式渲染和 token 效率是真优势；但上线前务必按本文坑 1 把「服务端 prompt 包 + 客户端运行时」一起钉版本，这是最容易翻车的地方。

它是什么

OpenUI 叫自己 "The Open Standard for Generative UI"，实际是一个全栈、框架无关的 Generative UI 框架。它的核心是一门叫 OpenUI Lang 的紧凑型、流式优先语言：模型输出的不再是纯文本，而是可被逐块解析并即时渲染的结构化 UI。

整体链路是五步闭环：

1. 定义或复用一套组件库（component library）
2. 从这套组件库自动生成系统提示词
3. 把提示词发给模型
4. 把 OpenUI Lang 的流式输出返回客户端
5. 用 Renderer 渐进渲染

依官网技术博客补充，OpenUI Lang 是行式 DSL，每条语句形如 id = Component(args)，利用前向引用让渲染器能为尚未流入的 id 先显示骨架，从而实现自上而下的逐步展开（top-down reveal）。

⚠️ 版本状态（2026-10-22 查证）：2026-10-12 有两个包发到 1.0.0——@openuidev/lang-core 和 @openuidev/react-lang（同一个 PR #1348），10-15 跟进 1.0.1。但 Vue / Svelte / Angular 运行时仍停留在 0.x。npm 上 @openuidev/react-ui 最新为 0.18.1（peer 依赖要求 @openuidev/react-lang >=1.0.0 <2.0.0），@openuidev/a2ui、@openuidev/svelte-lang 等近期发布为 0.4.1 档。许可 MIT，仓库约 12.9k stars。

解决什么问题

传统做法里，LLM 助手只能吐 markdown 或纯文本。想展示一张图表、一个表单、一张表格，你得自己写 tool calling schema、自己解析、自己拼 React 树——而且一旦流式输出，边解析边渲染的复杂度会陡增。

OpenUI 把这件事下沉到语言层：模型直接输出「我要用哪个组件、传什么参数」，渲染器按你的组件库逐块兑现。附带三个好处：

• token 效率：README 称比 JSON 少用至多 67% token
• 受控渲染：模型只能在你注册的组件范围内输出，不会凭空造标签
• 类型契约：用 Zod schema 预先定义 props 和结构

快速安装

# 最快路径：直接脚手架一个完整可跑的 chat app
npx @openuidev/cli@latest create --name genui-chat-app

然后按需装包（官方给的常见起点）：

# React + 预置组件库
npm install @openuidev/react-lang @openuidev/react-ui

# 框架无关后端 / Edge 侧生成 prompt
npm install @openuidev/lang-core

# LangChain / LangGraph agent 集成
npm install @openuidev/langchain @langchain/langgraph

# Vue / Svelte / Angular 运行时（三选一）
npm install @openuidev/vue-lang
npm install @openuidev/svelte-lang
npm install @openuidev/angular-lang

# A2UI 协议 + OpenUI Lang 组件载荷
npm install @openuidev/a2ui zod

React 侧的 peer 依赖（据 npm）：react >=19.0.0、react-dom >=19.0.0、zustand ^4.5.5、zod ^3.25.0 || ^4.0.0。⚠️ 注意 react-ui 的样式必须手动引入，否则组件没样式：

import "@openuidev/react-ui/styles/index.css";

不想装包构建的话，用 @openuidev/browser-bundle（CDN / iframe / 无构建场景）。

核心用法

定义组件并建库（React）：

import { defineComponent, createLibrary } from "@openuidev/react-lang";
import { z } from "zod/v4";

const Alert = defineComponent({
  name: "Alert",
  description: "An alert component that conveys important information to the user",
  props: z.object({
    level: z.enum(["info", "warn", "error"]),
    title: z.string(),
    message: z.string(),
  }),
});

export const library = createLibrary([Alert]);

生成系统提示词：用 @openuidev/cli 从 library 定义导出 system prompt 或 JSON schema，喂给模型。这一步是「你的组件库决定模型能生成什么」的落地点。

接收与渲染：把模型返回的 OpenUI Lang 流喂给 Renderer（React 下由 @openuidev/react-lang 提供），前向引用会先渲染骨架再填充内容。

不想自己写聊天界面：用 @openuidev/react-ui 的 AgentInterface 聊天界面，或 @openuidev/react-headless 提供 headless 状态让你自带 UI。

接 agent 框架：@openuidev/langchain 提供 agent transformer 和 server helpers，通过 AG-UI 流式传输。已有 assistant-ui 项目的用 @openuidev/assistant-ui 的 Tool UI renderer。

让 AI 助手帮你写：项目附带官方 Agent Skill（AgentSkills 规范）：

npx skills add thesysdev/skills --skill openui

覆盖组件库设计、OpenUI Lang 语法、system prompt 生成、Renderer、SDK 各包，以及「调试 LLM 输出的畸形内容」。

免构建环境：@openuidev/browser-bundle 把 renderer、UI 库、React 和样式打成 script + stylesheet，直接 CDN / iframe / script 标签引入。

反馈：

npx @openuidev/cli feedback "Describe the problem or idea"

⚠️ 官方说明：使用 OpenUI skill 的 coding agent 会在发送前移除个人信息和代码，并请求你批准——但请你自己复核一遍脱敏结果再放行。

典型适用场景

• 做客服 / 助手类产品，希望回答直接是一张对比表或一张表单，而不是让用户自己读文字。
• 需要渐进式 UI（先出骨架再填数据）的仪表盘类应用。
• 想让 LLM 生成的 UI 严格限制在自家设计系统的组件范围内（安全 + 一致性双重诉求）。
• 多端渲染：同一套 OpenUI Lang 可输出 Web、移动端、React Email（另有 @openuidev/react-email 支持邮件生成与 HTML 导出）。
• 想自建组件库并让模型自动按库生成 prompt，不想手写 tool schema。

坑与注意

1. 版本耦合是最硬的坑。现象：@openuidev/lang-core 和 @openuidev/react-lang 在 2026-10-12 发了 1.0（1.0.1 于 10-15），但 Vue / Svelte / Angular 运行时仍是 0.x。影响：用 1.0 语法配 0.x 渲染器会不匹配，或渲染不出一致结果；升级组件库升级变成跨四层的协同改动（含模型输出格式）。修复：把「服务端生成 prompt 的包 + 客户端渲染包 + 模型输出格式」当作一组一起钉版本，别单独升某一个。⚠️ 本文核查于 2026-10-22，具体版本号会随发布漂移，请以 npm 实际版本为准。
2. 漏引样式导致组件「看起来没生效」。现象：组件渲染出来了但完全没样式。影响：误判成渲染 bug。修复：import "@openuidev/react-ui/styles/index.css"（npm readme 明确要求）。
3. React 版本下限。现象：装完报 peer 冲突。影响：装不上或运行异常。修复：react / react-dom 需 >=19.0.0。
4. 模型输出畸形（malformed output）。现象：渲染器解析失败或界面卡在骨架。影响：用户看到坏 UI。修复：官方 Agent Skill 专门覆盖这一类调试；先检查组件是否注册、prompt 是否由与服务端匹配的包生成。
5. token 基准的口径要看清。现象：直接引用「省 67% token」做宣传。影响：数字容易被挑战。修复：README 的表格是用 tiktoken（GPT-5 encoder）在七个 UI 场景下测的，TOTAL 为 OpenUI Lang 4800 vs Vercel JSON-Render 10180（-52.8%）vs Thesys C1 JSON 9948（-51.7%）。-67% 是单场景最高值（contact-form），不是平均。完整方法在 benchmarks/ 目录，可自行复现。
6. 对比表的延迟数字有前提。现象：拿「4.9s vs 14.2s」直接对比。影响：换场景就不成立。修复：README 的对比表明确标注延迟是在 60 tok/s 条件下测的；且该表由项目方自维护，CopilotKit OpenGenUI 的「~20s」「Streaming: Partial」等项建议自行复核。
7. React 功能领先，其他框架是追赶。现象：Vue/Svelte/Angular 用户缺少 React 才有的预置组件库和现成 chat 界面。影响：非 React 栈要多自建。修复：非 React 栈直接用 @openuidev/lang-core（框架无关）+ 对应 *-lang 运行时，或改用 browser-bundle。
8. 有同名加密资产。现象：搜到用 OpenUI 名字的代币/币。影响：误投。修复：README 顶部明确声明项目没有任何官方加密货币、代币或币，任何同名资产都与项目无关、不被维护者认可。
9. 可观测性默认外发到厂商。现象：以为 observability 是本地行为。影响：事件离开你的环境。修复：@openuidev/observability-cloud 是「批量收集 OpenUI 事件并发往 OpenUI Gateway」的云端 sink；不想外发就别引入它，或只用框架无关的 @openuidev/observability 事件总线。
10. 反馈命令会外发内容。现象：npx @openuidev/cli feedback 把描述发出去。影响：可能带出内部信息。修复：发送前自查文本，别粘贴代码或内部 URL。

与同类对比

README 自带一张对比表（⚠️ 项目方自维护，建议交叉验证）：

真正的区分点有三条：一是渲染器广度（官网技术博客称除 React/Vue/Svelte/Angular 外还覆盖 Solid、React Native，以及 React Email、React PDF、R3F、Remotion、Ink、Satori——⚠️ 这份列表来自官方博客，README 的 packages 表未列出 Solid/React Native，实际可用范围请以 monorepo 现状为准）；二是 OpenUI Lang 的 token 优势在同等语义下确实显著；三是内置数据获取与开箱聊天界面。CopilotKit OpenGenUI 走的是工具调用路线（无组件层、输出不保证一致），如果你要的是「模型调工具」而非「模型描述 UI」，那不是同一类东西。

不确定处

• 版本号核查于 2026-10-22：lang-core / react-lang 1.0.1、react-ui 0.18.1、a2ui 与 svelte-lang 等 0.4.1 档；发布频繁，具体数值请以 npm 为准。
• 「1.0 只有两个包、其余仍 0.x」来自第三方技术博客 ibl.ai 的分析，非官方 README 声明；但 npm 上 react-ui 的 peer 约束（要求 react-lang >=1.0.0 <2.0.0）与之互证，可信度较高。
• 官方博客提到的 Solid / React Native / R3F / Remotion 等渲染目标未在 README packages 表中出现，未能核实是否已发布为独立包。
• 对比表中的竞品数据均由 OpenUI 方维护，未做第三方复现。
• 未 clone、未运行代码；未安装任何 npm 包。