Renderer 将其转换为真实的 React UI。
这种集成非常适合数据丰富的输出，如报告、仪表板和数据探索器，其中模型既是数据分析师又是 UI 设计师。
工作原理
- 生成系统提示词： 在启动时调用一次
openuiLibrary.prompt()；它会生成一个完整的 openui-lang 参考，模型使用它来编写有效的组件树 - 在第一条消息时注入： 在新对话开始时，将系统提示词作为初始系统消息发送
- 模型编写 openui-lang： 模型以类似
root = Stack([header, kpis, chart])的程序形式响应，而不是散文 - 使用
Renderer渲染： 将文本传递给 OpenUI 的Renderer和组件库；它会解析并渲染该树
安装
npm install @langchain/react @openuidev/react-ui @openuidev/react-headless @openuidev/react-lang
OpenUI 需要 React 19+ 和
zustand。前端代码仅限 React；LangGraph 代理后端可以用 TypeScript 或 Python 编写。导入组件样式
在你的 CSS 入口点或直接在根组件中导入 OpenUI 的捆绑样式：@import "@openuidev/react-ui/components.css";
@import "@openuidev/react-ui/styles/index.css";
生成系统提示词
OpenUI 提供了一个openuiLibrary.prompt() 函数，用于生成完整的 openui-lang 参考，包含所有组件签名、语法规则、流式传输提示和示例。在模块加载时调用一次：
import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui/genui-lib";
// 生成完整的 openui-lang 系统提示词。在启动时调用一次，
// 而不是在组件内部，以避免在每次渲染时重新计算。
const SYSTEM_PROMPT = openuiLibrary.prompt({
...openuiPromptOptions,
preamble:
"You are a report generator. When asked for a report, produce a detailed, " +
"data-rich report using openui-lang: executive summary, KPI cards, charts, " +
"tables, and multiple sections. Your ENTIRE response must be raw openui-lang " +
"— no code fences, no markdown, no prose.",
});
preamble 会覆盖默认的角色设定。添加 additionalRules 以注入特定任务的约束：
const SYSTEM_PROMPT = openuiLibrary.prompt({
...openuiPromptOptions,
preamble: "You are a report generator...",
additionalRules: [
...(openuiPromptOptions.additionalRules ?? []),
"Always end the report with 3–4 follow-up query buttons using " +
"Button({ type: 'continue_conversation' }, 'secondary') inside a " +
"Card([CardHeader('Explore Further'), Buttons([...])], 'sunk').",
],
});
通过 useStream 注入系统提示词
将系统提示词作为每个新线程的第一条消息发送。检查stream.messages.length === 0 以检测新线程，并在前面添加一条 system 消息：
import { useCallback } from "react";
import { useStream } from "@langchain/react";
const SYSTEM_PROMPT = openuiLibrary.prompt({ ... });
export function App() {
const stream = useStream({
apiUrl: import.meta.env.VITE_LANGGRAPH_API_URL ?? "/api/langgraph",
assistantId: "my_agent",
reconnectOnMount: true,
fetchStateHistory: true,
});
const handleSubmit = useCallback(
(text: string) => {
// 仅在新线程的第一条消息时注入系统提示词。
// 后续消息在其持久化历史记录中已包含它。
const isNewThread = stream.messages.length === 0;
stream.submit({
messages: [
...(isNewThread
? [{ type: "system", content: SYSTEM_PROMPT }]
: []),
{ type: "human", content: text },
],
});
},
[stream],
);
// ...
}
使用 Renderer 渲染
将 AI 消息的文本内容直接传递给Renderer 以及 openuiLibrary：
import { Renderer } from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
import { AIMessage } from "langchain";
function MessageList({ messages, isLoading }) {
const lastAiIdx = messages.reduce(
(acc, msg, i) => (AIMessage.isInstance(msg) ? i : acc),
-1,
);
return messages.map((msg, i) => {
if (AIMessage.isInstance(msg)) {
const text = typeof msg.content === "string" ? msg.content : "";
return (
<Renderer
key={msg.id ?? i}
response={text}
library={openuiLibrary}
isStreaming={isLoading && i === lastAiIdx}
/>
);
}
// ... 人类消息气泡
});
}
isStreaming={true}，以便 Renderer 在定义到达时优雅地处理未解析的引用。
openui-lang 格式
模型编写的是一个程序，而不是 JSON 规范。每条语句都是一个赋值；root 是入口点。官方提示词会教模型这种格式，包括提升（hoisting）——先编写 root，这样 UI 外壳会立即显示：
root = Stack([header, execSummary, kpis, marketSection])
header = CardHeader("State of AI in 2025", "Comprehensive Analysis")
execSummary = MarkDownRenderer("## Executive Summary\n\nThe AI market reached...")
kpi1 = Card([CardHeader("$826B", "Global Market"), TextContent("42% YoY", "small")], "sunk")
kpi2 = Card([CardHeader("78%", "Adoption"), TextContent("Fortune 500", "small")], "sunk")
kpis = Stack([kpi1, kpi2], "row", "m", "stretch", "start", true)
col1 = Col("Segment", "string")
col2 = Col("Revenue ($B)", "number")
tbl = Table([col1, col2], [["Generative AI", 286], ["ML Infra", 198]])
s1 = Series("Revenue", [286, 198, 147])
ch1 = BarChart(["Gen AI", "ML Infra", "Vision"], [s1])
marketSection = Card([CardHeader("Market Breakdown"), tbl, ch1])
root 行会首先编写，这样页面结构会立即出现，并且每个部分会在模型定义它时逐步填充。
渐进式渲染工具
直接将useStream 连接到 Renderer 会导致在每个流式令牌上重新渲染，并且每个响应会产生数百次无操作的重新解析。这会导致图表组件在其数据尚未到达时崩溃。以下工具解决了这些问题：
| 问题 | 解决方案 |
|---|---|
| 部分字符串字面量 | truncateAtOpenString / closeOrTruncateOpenString — 在解析前丢弃或关闭不完整的字符串 |
| 令牌中间的抖动 | useStableText — 仅在完整语句边界（name = Expr(…)) 而非每个令牌时才允许 Renderer 更新 |
| 图表空数据崩溃 | chartDataRefsResolved — 在将图表包含在快照中之前，验证其 Series 和标签数组是否已定义 |
尚无 root / 回退 | buildProgressiveRoot — 当模型尚未编写 root 时，从顶级变量合成一个 root = Stack([…]) |
| 蛇形命名标识符 | sanitizeIdentifiers — 解析器仅接受驼峰命名法；转换模型发出的任何 snake_case 名称 |
stable 传递给 <Renderer>：
import {
useCallback,
useEffect,
useMemo,
useRef,
useState,
} from "react";
import {
type ActionEvent,
BuiltinActionType,
Renderer,
} from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
/** 去除模型可能发出的任何 markdown 代码围栏。 */
function stripCodeFence(text: string): string {
return text
.replace(/^```[a-z]*\r?\n?/i, "")
.replace(/\n?```\s*$/i, "")
.trim();
}
/**
* openui-lang 解析器仅接受驼峰命名标识符。
* 转换模型发出的任何蛇形命名变量名；字符串内容不受影响。
*/
function sanitizeIdentifiers(text: string): string {
const toCamel = (s: string) =>
s.replace(/_([a-zA-Z0-9])/g, (_, c: string) => c.toUpperCase());
const snakeVars: string[] = [];
for (const m of text.matchAll(/^([a-zA-Z][a-zA-Z0-9]*(?:_[a-zA-Z0-9]+)+)\s*=/gm)) {
if (!snakeVars.includes(m[1])) snakeVars.push(m[1]);
}
if (snakeVars.length === 0) return text;
let result = "";
let inStr = false;
let i = 0;
while (i < text.length) {
if (text[i] === "\\" && inStr) { result += text[i] + (text[i + 1] ?? ""); i += 2; continue; }
if (text[i] === '"') { inStr = !inStr; result += text[i++]; continue; }
if (!inStr) {
let replaced = false;
for (const v of snakeVars) {
if (text.startsWith(v, i) && !/[a-zA-Z0-9_]/.test(text[i + v.length] ?? "")) {
result += toCamel(v); i += v.length; replaced = true; break;
}
}
if (!replaced) result += text[i++];
} else {
result += text[i++];
}
}
return result;
}
/**
* 遍历文本，跟踪未关闭的字符串。如果文本在字符串中间结束，则截断到最后一个安全的换行符——
* 这可以防止部分字符串字面量消耗我们稍后合成的任何 `root = Stack(…)` 行。
*/
function truncateAtOpenString(text: string): string {
let inStr = false;
let lastSafeNewline = 0;
for (let i = 0; i < text.length; i++) {
const ch = text[i];
if (ch === "\\" && inStr) { i++; continue; }
if (ch === '"') { inStr = !inStr; continue; }
if (ch === "\n" && !inStr) lastSafeNewline = i;
}
return inStr ? text.slice(0, lastSafeNewline) : text;
}
/**
* 类似于 truncateAtOpenString，但当部分行是 TextContent 语句时，会合成一个闭合的 `")`。
* 这允许文本逐令牌渲染，而所有其他部分字符串行仍被截断。
*/
function closeOrTruncateOpenString(text: string): string {
let inStr = false;
let lastSafeNewline = 0;
for (let i = 0; i < text.length; i++) {
const ch = text[i];
if (ch === "\\" && inStr) { i++; continue; }
if (ch === '"') { inStr = !inStr; continue; }
if (ch === "\n" && !inStr) lastSafeNewline = i;
}
if (!inStr) return text;
const safeText = lastSafeNewline > 0 ? text.slice(0, lastSafeNewline) : "";
const partialLine = text.slice(lastSafeNewline > 0 ? lastSafeNewline + 1 : 0);
if (/^[a-zA-Z][a-zA-Z0-9]*\s*=\s*TextContent\(/.test(partialLine)) {
return (lastSafeNewline > 0 ? safeText + "\n" : "") + partialLine + '")';
}
return safeText;
}
/** 统计以 `)` 或 `]` 结尾的完整赋值语句的行数。 */
function countCompleteStatements(text: string): number {
let count = 0;
for (const line of text.split("\n")) {
const t = line.trimEnd();
if ((t.endsWith(")") || t.endsWith("]")) && /^[a-zA-Z]/.test(t)) count++;
}
return count;
}
const CHART_TYPES = new Set([
"BarChart", "LineChart", "AreaChart", "RadarChart",
"HorizontalBarChart", "PieChart", "RadialChart",
"SingleStackedBarChart", "ScatterChart",
]);
const OPENUI_KEYWORDS = new Set([
"true", "false", "null", "grouped", "stacked", "linear", "natural", "step",
"pie", "donut", "string", "number", "action", "row", "column", "card", "sunk",
"clear", "info", "warning", "error", "success", "neutral", "danger", "start",
"end", "center", "between", "around", "evenly", "stretch", "baseline",
"small", "default", "large", "none", "xs", "s", "m", "l", "xl",
"horizontal", "vertical",
]);
/**
* 图表组件（recharts）在标签或系列属性未解析时，会因 `.map() on null` 而崩溃。
* 在提交稳定快照之前，验证文本中的每个图表是否已定义其所有数据变量。
*/
function chartDataRefsResolved(text: string): boolean {
const lines = text.split("\n");
const complete = new Set<string>();
for (const line of lines) {
const t = line.trimEnd();
const m = t.match(/^([a-zA-Z][a-zA-Z0-9]*)\s*=/);
if (m && (t.endsWith(")") || t.endsWith("]"))) complete.add(m[1]);
}
for (const line of lines) {
const t = line.trimEnd();
const m = t.match(/^([a-zA-Z][a-zA-Z0-9]*)\s*=\s*([A-Z][a-zA-Z0-9]*)\(/);
if (!m || !CHART_TYPES.has(m[2]) || !t.endsWith(")")) continue;
const rhs = t.slice(t.indexOf("=") + 1).replace(/"(?:[^"\\]|\\.)*"/g, '""');
for (const [, name] of rhs.matchAll(/\b([a-zA-Z][a-zA-Z0-9]*)\b/g)) {
if (/^[a-z]/.test(name) && !OPENUI_KEYWORDS.has(name) && !complete.has(name))
return false;
}
}
return true;
}
/**
* 如果模型尚未编写 `root = Stack(…)`，则从顶级变量（那些已定义但未在任何其他表达式内部引用的变量）
* 合成一个。即使模型最后编写 root，这也能实现渐进式渲染。
*/
function buildProgressiveRoot(text: string): string {
if (!text) return text;
const safe = truncateAtOpenString(text);
if (/^root\s*=/m.test(safe)) return safe;
const defs: string[] = [];
const seen = new Set<string>();
for (const m of safe.matchAll(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=/gm)) {
if (!seen.has(m[1])) { defs.push(m[1]); seen.add(m[1]); }
}
if (defs.length === 0) return safe;
const referenced = new Set<string>();
for (const line of safe.split("\n")) {
const thisVar = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=/)?.[1];
const stripped = line.replace(/"(?:[^"\\]|\\.)*"/g, '""');
for (const v of defs) {
if (v !== thisVar && new RegExp(`\\b${v}\\b`).test(stripped)) referenced.add(v);
}
}
const topLevel = defs.filter((v) => !referenced.has(v));
const rootVars = topLevel.length > 0 ? topLevel : defs;
return `${safe.trimEnd()}\nroot = Stack([${rootVars.join(", ")}], "column", "l")`;
}
/**
* 仅在至少有一个新的*完整*语句到达时才允许 Renderer 更新。这消除了流式传输期间数百次无操作的重新解析。
*
* 特殊情况：TextContent 行逐令牌更新（通过 closeOrTruncate），因此文本可以渐进式渲染，而无需等待整行完成。
*/
function useStableText(raw: string, isStreaming: boolean): string {
const [stable, setStable] = useState<string>("");
const lastCount = useRef(0);
useEffect(() => {
const safe = truncateAtOpenString(raw); // 严格模式 — 仅用于计数
const enhanced = closeOrTruncateOpenString(raw); // 显示模式 — 关闭部分 TextContent
if (!isStreaming) { setStable(enhanced); return; }
const count = countCompleteStatements(safe);
const newComplete = count > lastCount.current && chartDataRefsResolved(safe);
const partialTextContent = enhanced !== safe;
if (newComplete || partialTextContent) {
if (newComplete) lastCount.current = count;
setStable(enhanced);
}
}, [raw, isStreaming]);
return stable;
}
function AIMessageView({
raw,
isStreaming,
onSubmit,
}: {
raw: string;
isStreaming: boolean;
onSubmit: (text: string) => void;
}) {
const stable = useStableText(raw, isStreaming);
const processed = useMemo(() => buildProgressiveRoot(stable), [stable]);
const handleAction = useCallback(
(event: ActionEvent) => {
if (event.type === BuiltinActionType.ContinueConversation) {
onSubmit(event.humanFriendlyMessage);
}
},
[onSubmit],
);
if (!processed) return null;
return (
<Renderer
response={processed}
library={openuiLibrary}
isStreaming={isStreaming}
onAction={handleAction}
/>
);
}
export function MessageList({ messages, isLoading, onSubmit }) {
const lastAiIdx = messages.reduce(
(acc, msg, i) => (msg.getType() === "ai" ? i : acc),
-1,
);
return messages.map((msg, i) => {
if (msg.getType() === "human") {
return (
<div key={msg.id ?? i} className="flex justify-end">
<div className="user-bubble">
{typeof msg.content === "string" ? msg.content : ""}
</div>
</div>
);
}
if (msg.getType() === "ai") {
const raw = sanitizeIdentifiers(
stripCodeFence(typeof msg.content === "string" ? msg.content : ""),
);
if (!raw) return null;
return (
<div key={msg.id ?? i}>
<AIMessageView
raw={raw}
isStreaming={isLoading && i === lastAiIdx}
onSubmit={onSubmit}
/>
</div>
);
}
return null;
});
}
后续查询
OpenUI 的Button 组件支持 continue_conversation 动作类型。当用户点击后续按钮时，Renderer 会触发 onAction，上面的 AIMessageView 会将按钮的标签作为下一条用户消息提交，这与在输入框中输入的代码路径完全相同。
通过系统提示词中的 additionalRules 为每个报告添加“进一步探索”部分：
followUp1 = Button("Compare AI leaders 2024 vs 2025", { type: "continue_conversation" }, "secondary")
followUp2 = Button("Global AI investment breakdown", { type: "continue_conversation" }, "secondary")
followUpBtns = Buttons([followUp1, followUp2], "row")
followUpCard = Card([CardHeader("Explore Further"), followUpBtns], "sunk")
root = Stack([..., followUpCard])
最佳实践
- 在模块加载时生成系统提示词： 不要在 React 组件内部；提示词有几千字节，应该只计算一次
- 仅在新线程时注入系统提示词： 检查
stream.messages.length === 0，并在后续轮次跳过注入，以避免在线程历史记录中重复提示词 - 使用提升顺序： 先编写
root = Stack([...])；UI 外壳会立即出现，并且各部分会在模型定义每个部分时逐步填充 - 仅在完整语句时更新： 避免在每个令牌上重新渲染 Renderer；仅在完整语句（
name = ComponentCall(...)）到达时更新 - 渲染前验证图表数据： 图表组件需要在包含在稳定快照中之前定义其
Series和标签数组 - 保持驼峰命名变量名： openui-lang 解析器仅接受驼峰命名标识符；在系统提示词的
additionalRules中强化这一点
将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。