OpenUI 1.0 上手：用自然语言生成界面并接入本地智能体
工具概述
这里的 OpenUI 指 Thesys 维护的 thesysdev/openui，不是同名的旧式文本生成前端项目。它的核心是 OpenUI Lang：模型按紧凑、逐行可流式解析的语言描述界面，渲染器再把描述映射到开发者注册的真实组件。用户说生成一张带筛选器的销售图表时，模型决定怎样组合组件，但不能凭空执行未注册的浏览器能力。
截至 2026 年 10 月 15 日，@openuidev/lang-core 的仓库版本为 1.0.1，项目采用 MIT 许可。官方同时提供 React、Vue、Svelte、Angular 运行时，其中 React 具有更完整的现成组件库与聊天界面。它不是一个模型，也不会替你安装本地大模型；它负责组件约束、提示生成、流解析和渲染，可接云端模型或本地兼容后端。
环境准备
最短路径需要可用的 Node.js、npm 和 npx。首次试验建议新建空目录，不要把脚手架直接覆盖到已有前端。模型输出最终会进入页面，因此仍要启用 React 的默认转义，并把自定义动作限制在明确的函数集合内。正式接入前先完成本地冒烟。官方仓库地址为 https://github.com/thesysdev/openui，文档入口为 https://openui.com。
安装部署
三个桌面平台使用同一个官方 CLI，差别主要是终端语法。脚手架会创建带流式处理、内置组件和 OpenUI Lang 支持的可运行应用。
Windows
在 PowerShell 中执行：
npx @openuidev/cli@latest create --name genui-chat-appSet-Location genui-chat-appnpm installnpm run dev
macOS
在 Terminal 中执行：
npx @openuidev/cli@latest create --name genui-chat-appcd genui-chat-app npm install npm run dev
Linux
在 Bash 中执行相同流程；若 npx 不存在，应先通过发行版推荐方式安装 Node.js，而不是下载来源不明的二进制包。
npx @openuidev/cli@latest create --name genui-chat-appcd genui-chat-app npm install npm run dev
快速上手
先运行脚手架自带会话，再输入生成订单审核面板，包含金额、风险等级和批准按钮。观察网络流可以看到界面逐步出现，而不是等待完整 JSON 闭合后一次性渲染。若要把运行时嵌入已有 React 项目，可只安装渲染与预制组件包。
npm install @openuidev/react-lang @openuidev/react-ui
后端流程固定为四步：从允许的组件库生成系统提示，把提示与用户要求交给模型，持续接收 OpenUI Lang 流，最后交给 Renderer。自然语言只是用户入口，真正的安全边界是组件定义及其 Zod 参数约束。不要把模型字符串拼成任意 HTML，也不要用 eval 执行模型返回内容。
接入本地智能体
OpenUI 提供面向 Claude Code、Codex、Cursor 等编码智能体的 Skill。安装后，智能体能按当前 API 生成组件库、排查畸形输出并选择正确包，而不是依赖过时样例。
npx skills add thesysdev/skills --skill openui
若本地智能体以 LangGraph 编排，可安装官方适配包。它负责把智能体输出通过 AG-UI 流转换给 OpenUI，具体使用哪一个本地模型由你的后端决定。
npm install @openuidev/langchain @langchain/langgraph
本地模型接入时要验证三项能力：能稳定遵循组件语法、支持流式输出、在长组件列表下仍能正确闭合结构。OpenUI 声明模型无关，不代表所有小模型效果相同。建议先限制为五到十个简单组件，记录解析失败率，再逐步增加图表、表单和动作。
词元数据与选型判断
官方仓库用 GPT-5 编码器的 tiktoken 对七类界面做了复现实验。OpenUI Lang 合计使用 4800 个词元，Vercel JSON-Render 为 10180，Thesys C1 JSON 为 9948；相对前者减少 52.8%。单个联系表单场景从 893 降到 294，减少 67.1%。这组数据来自项目方基准，反映序列化紧凑度，不等同于端到端界面准确率。
OpenUI 适合输出结构随问题变化的助手、数据分析台和审批界面。若页面结构完全固定，普通 React 表单更简单、更可测试。生产使用还要为按钮动作增加权限检查、幂等键和审计日志，绝不能因为按钮是模型生成的就跳过服务端鉴权。
常见问题与排查
第一类问题是只升级一个包。1.0 的语言核心、React 渲染器和服务端提示生成器应同步升级，否则新提示可能生成旧客户端无法执行的动作。第二类问题是组件过多导致模型选择混乱，可按业务场景拆分组件库。第三类问题是流中断留下半成品，应显示可恢复状态，并允许重新请求而不是执行不完整动作。
选型时可以先用官方 CLI 完成端到端冒烟，再决定是否引入 Gateway、Autofix 或完全自托管模型。OpenUI 的价值不是让模型任意写前端，而是把可生成范围收敛到一组经过审核的组件和动作中，这也是它能接入本地智能体而不放弃工程控制力的关键。