json-render 核心库演进指南:从 SpecStream 流式渲染到全能渲染生态
json-render 核心库演进指南:从 SpecStream 流式渲染到全能渲染生态
本指南以 @json-render/core 的版本变更日志(packages/core/CHANGELOG.md)为主线,系统梳理这个 Generative UI 框架核心库的能力演进史:SpecStream 流式协议、Schema/Catalog/Prompt 三层结构、动态表达式、外部状态存储、多轮编辑模式,以及它孵化出的 React / Vue / Svelte / Solid / React Native / React PDF / React Email / Ink / 3D / 图片 / Next.js 等渲染器生态。读完本文,你将掌握 core 包的核心概念、关键 API 的调用方式与底层实现原理,并理解每个版本演进的动机与破坏性变更。
一、core 包在 json-render 中的定位
@json-render/core 是整个 json-render 框架的公共基础库,负责四件核心事情(见 packages/core/README.md):
- Schema:定义 spec 与 catalog 的结构("语法");
- Catalog:把组件名/动作名映射到带 Zod props 的定义("词汇表");
- Spec:AI 产出的、符合 schema 的 JSON 输出;
- SpecStream:基于 JSONL 的流式格式,用于渐进式构建 spec。
官方安装方式:
npm install @json-render/core zod
zod 是 peer 依赖,因为 catalog 的组件 props 和校验逻辑都基于 Zod schema 构建。
二、SpecStream:以 RFC 6902 JSON Patch 为核心的数据协议
2.1 流式格式的设计动机
AI 生成 UI 的典型痛点是"等待完整 JSON 才能渲染"。SpecStream 的解法是:AI 逐行输出 RFC 6902 JSON Patch 操作,客户端每收到一行就应用到当前的 spec 对象上,从而让 UI 边生成边填充。这个协议从 0.4.4 版本起便强调"去除 flat spec 中的 key/parentKey、保证 RFC 6902 合规",一直是 core 的基石。
SpecStream 的每一行是一个 patch 操作(见 packages/core/README.md):
{"op":"add","path":"/root","value":"card-1"}
{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Hello"},"children":["btn-1"]}}
{"op":"add","path":"/elements/btn-1","value":{"type":"Button","props":{"label":"Click"},"children":[]}}
全部六种 RFC 6902 操作(add、remove、replace、move、copy、test)都被支持,对应类型 PatchOp 定义在 packages/core/src/types.ts。
2.2 流式编译器的使用方式
createSpecStreamCompiler<T>() 是处理流式输出的主要入口(见 packages/core/README.md):
import { createSpecStreamCompiler } from "@json-render/core";
// 为你的 spec 类型创建编译器
const compiler = createSpecStreamCompiler<MySpec>();
// 处理来自 AI 的流式 chunk
while (streaming) {
const chunk = await reader.read();
const { result, newPatches } = compiler.push(chunk);
if (newPatches.length > 0) {
// 用部分结果更新 UI
setSpec(result);
}
}
// 获取最终编译结果
const finalSpec = compiler.getResult();
编译器的 push() 内部会维护一个行缓冲:只处理完整行,把不完整的行留到下一 chunk(见 packages/core/src/types.ts)。getPatches() 返回所有已应用的 patch,reset() 可清空状态重新开始。每次有新 patch 应用时,result 会被浅拷贝成新引用,以触发 React 等框架的重渲染。
2.3 底层工具函数
core 同时导出一组低层工具(见 packages/core/README.md):
import {
parseSpecStreamLine,
applySpecStreamPatch,
compileSpecStream,
} from "@json-render/core";
// 解析单行
const patch = parseSpecStreamLine('{"op":"add","path":"/root","value":{}}');
// { op: "add", path: "/root", value: {} }
// 把 patch 应用到对象上(就地修改)
const obj = {};
applySpecStreamPatch(obj, patch);
// 一次性编译整个 JSONL 字符串
const spec = compileSpecStream<MySpec>(jsonlString);
其中 applySpecStreamPatch 在 packages/core/src/types.ts 中按操作分派到 addByPath / setByPath / removeByPath,move 与 copy 走"先取源值、再增删"的路径,test 则做深比较,不匹配时抛出错误。parseSpecStreamLine 只接受以 { 开头且含 op 与 path 的合法行,其余一律返回 null,这也为后续的混合流解析(chat + GenUI)打下了基础。
另外还有一个 nestedToFlat() 工具(见 packages/core/README.md),能把人类手写的树形嵌套 spec(每个节点内联 children 数组)转换为扁平 { root, elements, state } 格式,自动生成 el-0、el-1… 这样的元素键,并把根节点上的 state 提升到 spec 顶层。
三、Schema → Catalog → Prompt:三层 AI 驱动结构
3.1 defineSchema:定义 spec 与 catalog 的语法
schema 通过 defineSchema 定义,使用 builder API(s.object、s.array、s.map、s.ref、s.propsOf、s.zod 等原语,见 packages/core/src/schema.ts):
import { defineSchema } from "@json-render/core";
export const schema = defineSchema((s) => ({
spec: s.object({
root: s.object({
type: s.ref("catalog.components"),
props: s.propsOf("catalog.components"),
children: s.array(s.string()), // Element keys (flat spec format)
}),
}),
catalog: s.object({
components: s.map({
props: s.zod(),
description: s.string(),
}),
actions: s.map({
description: s.string(),
}),
}),
}), {
promptTemplate: myPromptTemplate, // 可选的自定义 AI prompt 生成器
});
schema 选项还包括 defaultRules(在自定义规则之前注入 prompt 的默认规则)和 builtInActions(运行时始终可用、自动注入 prompt 的动作,例如 setState)。
3.2 defineCatalog:定义组件的"词汇表"
catalog 把组件名映射到 Zod props,并附带给 AI 的描述文本:
import { defineCatalog } from "@json-render/core";
import { schema } from "./schema";
import { z } from "zod";
export const catalog = defineCatalog(schema, {
components: {
Card: {
props: z.object({
title: z.string(),
subtitle: z.string().nullable(),
}),
description: "A card container with title",
},
Button: {
props: z.object({
label: z.string(),
variant: z.enum(["primary", "secondary"]).nullable(),
}),
description: "A clickable button",
},
},
actions: {
submit: { description: "Submit the form" },
cancel: { description: "Cancel and close" },
},
});
3.3 catalog.prompt:生成系统提示词
// 生成 AI 系统提示词
const systemPrompt = catalog.prompt();
// 自定义系统描述与规则
const systemPrompt = catalog.prompt({
system: "You are a dashboard builder.",
customRules: [
"Always include a header",
"Use Card components for grouping",
],
});
从 0.5.2 版本开始,prompt 生成改为动态地根据用户的 catalog 生成示例,而不是硬编码组件名,以此减少 LLM 幻觉;ComponentDefinition 支持可选的 example 字段,并附带 Zod schema 内省回退。0.4.3 版本则把 remove 操作明确写进了系统提示词。
3.4 jsonSchema 导出与严格模式(0.13.0)
从 0.13.0 起,core 提供了 jsonSchema({ strict: true }):产出与 LLM 结构化输出 API(OpenAI、Google Gemini、Anthropic)兼容的 JSON Schema 子集——每个 object 都保证 additionalProperties: false,所有属性都列入 required(可选项用 nullable 类型表达)。该选项的实现细节与限制记录在 packages/core/src/schema.ts:Record 类型(动态键映射)无法在 strict JSON Schema 中表达(因为 additionalProperties 必须为 false),会被输出为空对象,但 prompt 仍会描述完整结构。
四、动态表达式体系:让 spec 活起来
4.1 表达式从字符串重写到结构化对象(0.6.0)
0.6.0 是一次关键演进:把原来的字符串 token 改写替换为结构化表达式对象,包括:
- Props:
{ $state: "/path" }、{ $item: "field" }、{ $index: true } - 可见性:
{ $state: "/path", eq: "value" }、{ $item: "active" }、{ $index: true, gt: 0 } - 逻辑:
{ $and: [...] }、{ $or: [...] },以及数组的隐式 AND - 比较操作符:
eq、neq、gt、gte、lt、lte、not
配套的破坏性变更包括:{ $path }/{ path } 改名为 { $state };{ and/or/not } 改为 { $and/$or } 且 not 成为操作符标志;repeat.path 改名为 repeat.statePath;actionHandlers 改名为 handlers;并移除了旧的 createCatalog、generateSystemPrompt 等遗留 API。类型定义集中在 packages/core/src/types.ts。
4.2 数据绑定($state / $bindState / $bindItem)
单向读取用 $state:
{
"color": { "$state": "/theme/primary" },
"label": { "$state": "/user/name" }
}
双向绑定用 $bindState(表单组件)或 $bindItem(repeat 作用域内的当前条目):
{
"type": "Input",
"props": {
"value": { "$bindState": "/form/email" },
"placeholder": "Email"
}
}
0.6.0 引入双向绑定后,渲染器会解析绑定并把一个 bindings 映射传给组件,组件据此把值写回状态。
4.3 条件、模板与计算表达式
条件三元($cond/$then/$else,语法与可见性条件一致,且 $then/$else 可递归嵌套表达式):
{
"color": {
"$cond": { "$state": "/activeTab", "eq": "home" },
"$then": "#007AFF",
"$else": "#8E8E93"
}
}
模板插值(0.10.0 引入 $template,${/path} 引用状态值,缺失路径解析为空字符串):
{
"label": { "$template": "Hello, ${/user/name}! You have ${/inbox/count} messages." }
}
计算函数(0.10.0 引入 $computed,调用 catalog 注册的命名函数,args 支持嵌套表达式):
{
"text": {
"$computed": "fullName",
"args": {
"first": { "$state": "/form/firstName" },
"last": { "$state": "/form/lastName" }
}
}
}
运行时通过渲染器的 functions prop 提供函数实现(ComputedFunction 类型从 core 导出):
import type { ComputedFunction } from "@json-render/core";
const functions: Record<string, ComputedFunction> = {
fullName: (args) => `${args.first} ${args.last}`,
};
4.4 编程式解析
import { resolvePropValue, resolveElementProps } from "@json-render/core";
// 解析单个值
const color = resolvePropValue(
{ $cond: { $state: "/active", eq: "yes" }, $then: "blue", $else: "gray" },
{ stateModel: myState }
);
// 解析元素上的全部 props
const resolved = resolveElementProps(element.props, { stateModel: myState });
可见性条件同样可以用 visibility helper 以类型安全的方式构造(visibility.when("/path")、visibility.eq("/path", val)、visibility.and(...)、visibility.or(...) 等,见 packages/core/README.md)。
五、状态管理:从内置 store 到可插拔外部 store
5.1 内置 StateStore(0.9.0 起)
core 导出框架无关的内存版 StateStore:
import { createStateStore, type StateStore } from "@json-render/core";
const store = createStateStore({ count: 0 });
store.get("/count"); // 0
store.set("/count", 1); // 更新并通知订阅者
store.getSnapshot(); // { count: 1 }
// 订阅变更(兼容 React 的 useSyncExternalStore)
const unsubscribe = store.subscribe(() => {
console.log("state changed:", store.getSnapshot());
});
StateStore 接口定义在 packages/core/src/types.ts,包含 get、set、update(批量更新、单次通知)、getSnapshot、getServerSnapshot(可选,用于 SSR)与 subscribe。0.9.0 起,StateProvider、JSONUIProvider、createRenderer 都接受可选的 store prop 进入受控模式:一旦传入 store,它就是唯一事实来源(initialState/onStateChange 被忽略);不传则完全向后兼容。
值得注意的破坏性变更:0.9.0 中 onStateChange 签名从"每个 path 回调一次"改为"一次收到变更数组":
// Before
onStateChange?: (path: string, value: unknown) => void
// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
5.2 官方适配器生态
0.9.0 同步推出了 @json-render/zustand、@json-render/redux、@json-render/jotai 三个适配器包,0.10.0 又加入 @json-render/xstate(要求 @xstate/store v3+,通过 xstateStoreStateStore({ atom }) 接入)。所有官方适配器都构建在 @json-render/core/store-utils 的 createStoreAdapter 之上(见 packages/core/src/state-store.ts),适配器作者只需提供三个回调:
import { createStoreAdapter } from "@json-render/core/store-utils";
const store = createStoreAdapter({
getSnapshot: () => myLib.getState(),
setSnapshot: (next) => myLib.setState(next),
subscribe: (listener) => myLib.subscribe(listener),
});
get/set/update/无操作检测/getServerSnapshot 均由适配层完成。同文件中的 immutableSetByPath 通过结构共享(只浅克隆路径上的对象)实现不可变写入,flattenToPointers 把嵌套对象展平为 JSON Pointer 键控条目(深度上限 20)。
5.3 状态观察器(watch)
0.10.0 引入状态观察器:元素上的 watch 顶层字段(与 type/props/children 平级,不在 props 内部)把状态路径映射到动作绑定,值变化时触发动作,支持级联依赖(如"国家 → 城市选项加载"),只在值变化时触发而非初始渲染:
{
"type": "Select",
"props": {
"label": "Country",
"value": { "$bindState": "/form/country" },
"options": ["US", "Canada", "UK"]
},
"watch": {
"/form/country": {
"action": "loadCities",
"params": { "country": { "$state": "/form/country" } }
}
},
"children": []
}
六、多轮编辑:三种 spec 精修模式(0.14.0)
0.14.0 为多轮对话式精修引入了通用编辑模式与 buildUserPrompt() 的 editModes 选项。三种策略的语义定义在 packages/core/src/edit-modes.ts:
| 模式 | 协议 | 适用场景 |
|---|---|---|
patch |
RFC 6902 JSON Patch,每行一个操作 | 精确、定向的单字段更新(默认模式) |
merge |
RFC 7396 JSON Merge Patch,部分对象深合并,null 删除 |
结构性变更(增删元素、改 props) |
diff |
针对序列化 spec 的 unified diff | 小规模的文本级修改 |
6.1 buildUserPrompt:一键构造用户提示词
import { buildUserPrompt } from "@json-render/core";
// 全新生成
const prompt = buildUserPrompt({ prompt: "create a todo app" });
// 带编辑模式的多轮精修(默认只开 patch)
const refinementPrompt = buildUserPrompt({
prompt: "add a dark mode toggle",
currentSpec: existingSpec,
editModes: ["patch", "merge"],
});
// 携带运行时状态上下文
const contextPrompt = buildUserPrompt({
prompt: "show my data",
state: { todos: [{ text: "Buy milk" }] },
});
buildUserPrompt 的实现(packages/core/src/prompt.ts)负责:截断用户 prompt(maxPromptLength)、当 currentSpec 非空时委托给 buildEditUserPrompt、追加 AVAILABLE STATE 状态上下文,并在全新生成模式下提醒模型"先输出 /root,再交错输出 /elements 与 /state patch,让 UI 渐进填充"。
6.2 每种模式的输出约定
buildEditInstructions(packages/core/src/edit-modes.ts)按启用模式生成 prompt 段。JSON 格式下的约定:
- patch:每行输出一个 JSON 对象,如
{"op":"add","path":"/elements/new-key","value":{...}}; - merge:单行输出一个带
__json_edit: true标记的 JSON 对象,只包含变更键,null表示删除:{"__json_edit":true,"elements":{"main":{"props":{"title":"New Title"}},"new-el":{"type":"Card","props":{},"children":[]}}} - diff:在
```diff代码围栏内输出针对当前 JSON spec 的 unified diff。
当启用多个模式时,会额外输出"模式选择指引"(patch 适合精确小改动、merge 适合结构改动、diff 适合能看到精确行的小改动),由 AI 每次自行选择。buildEditUserPrompt 在 diff 模式下会给序列化后的 spec 加上行号(1| ...、2| ...),供 diff 引用。
6.3 配套工具与 YAML 支持
isNonEmptySpec(spec):判断 spec 是否有 root 且至少一个元素(packages/core/src/edit-modes.ts),它决定了buildUserPrompt走"全新生成"还是"编辑模式"分支;deepMergeSpec(base, patch)(packages/core/src/merge.ts):RFC 7396 深合并,null删除键、数组整体替换、普通对象递归、不修改入参;diffToPatches(oldObj, newObj)(packages/core/src/diff.ts):生成 RFC 6902 patch 序列——新键add、变更标量/数组replace(数组浅比较、原子替换)、删除键remove;- 0.14.1 起,
buildUserPrompt接受format: "json" | "yaml"与serializer选项,YAML 成为与 JSON 并行的 wire format(YAML 下必须自备 serializer)。
6.4 生成模式命名演进(0.12.1)
0.12.1 把生成模式从 "generate" / "chat" 重命名为 "standalone" / "inline"。旧名称仍然可用但会打印弃用警告:
standalone(默认):模型只输出 JSONL patch,不输出散文;inline:模型先以对话方式回复,再内联输出 JSONL patch,用于聊天机器人与 copilot 体验。
七、Spec 结构校验与自动修复
AI 生成的 spec 常常有结构性问题,core 提供了 validateSpec / autoFixSpec / formatSpecIssues 三个工具(见 packages/core/README.md):
import { validateSpec, autoFixSpec, formatSpecIssues } from "@json-render/core";
// 校验 spec
const { valid, issues } = validateSpec(spec);
// 格式化问题为可读字符串(可回填给 AI 做修复提示)
console.log(formatSpecIssues(issues));
// 自动修复常见问题(返回修正副本)
const { spec: fixed, fixes, fixDetails } = autoFixSpec(spec);
7.1 validateSpec 检查清单
校验逻辑在 packages/core/src/spec-validator.ts,覆盖了 schema 之外的结构完整性检查:
- 缺失或空 root(
missing_root)、root 在 elements 中不存在(root_not_found)、spec 无元素(empty_spec); children与命名slots引用不存在的元素(missing_child);visible条件格式非法(invalid_visible)——未识别的形状在运行时会被静默当作隐藏,因此在这里以可修复的错误拦截;repeat容器没有子元素(repeat_without_children,运行时会产生静默空白区域);- 相对 repeat 路径出现在外层 repeat 作用域之外(
repeat_item_outside_scope); repeat.statePath未指向 spec 自身state中的数组(repeat_state_mismatch,可用getByPath取样检查);visible/on/repeat/watch被错误地放在props内部(visible_in_props等);- 可选开关
checkOrphans: true时,报告从 root 不可达的孤立元素(warning 级别)。
7.2 autoFixSpec 的无损/有损修复策略
autoFixSpec 把 visible/on/repeat/watch 从 props 提升到元素顶层(无损,只是位置纠正),以及修剪指向未定义元素的 children/slots 引用(有损,改变渲染内容)。每个修复记录在 fixDetails 中,带 { message, lossy } 标记。
对于带重试循环的调用方,官方推荐:重试期间先应用无损修复,用有损修复兜底:
const lastAttempt = retriesUsed >= maxRetries;
const { spec: fixed, fixDetails } = autoFixSpec(spec, { lossy: lastAttempt });
一个实现细节:如果修剪会让 repeat 容器失去全部子元素,则保留悬空引用(避免把 missing_child 错误换成 repeat_without_children),让修复循环针对真正的问题(缺失的模板元素)去重试。
八、表单验证:内置验证函数与跨字段校验
core 内置了一组声明式验证函数(定义见 packages/core/src/validation.ts,README 中有完整表格):
| 函数 | 说明 | 参数 |
|---|---|---|
required |
值不能为空 | — |
email |
必须是合法邮箱 | — |
url |
必须是合法 URL | — |
numeric |
必须是数字 | — |
minLength / maxLength |
字符串长度上下限 | { min/max: number } |
min / max |
数值上下限 | { min/max: number } |
pattern |
正则匹配 | { pattern: string } |
matches |
必须等于另一字段 | { other: { $state: "/path" } } |
equalTo |
matches 的别名(语义更清晰) |
同上 |
lessThan |
必须小于另一字段 | 同上 |
greaterThan |
必须大于另一字段 | 同上 |
requiredIf |
条件为真时必填 | { field: { $state: "/path" } } |
0.10.0 新增了 equalTo、lessThan、greaterThan、requiredIf 四个跨字段验证函数,并且验证参数统一走 resolvePropValue 以支持 $state 表达式。类型安全的 helper 如下:
import { check } from "@json-render/core";
check.required("Field is required");
check.matches("/form/password", "Passwords must match");
check.requiredIf("/form/enableNotifications", "Required when notifications enabled");
0.10.0 还在 React 侧新增了 validateForm 内置动作:同步执行 validateAll(),把 { valid, errors } 写入状态,默认路径为 /formValidation(可用 statePath 参数配置);为此 React Provider 树重排了嵌套顺序,让 ValidationProvider 包裹 ActionProvider,并新增非抛错的 useOptionalValidation hook。
九、事件系统与内置动作(0.7.0 起)
0.7.0 引入了若干对组件作者友好的能力:
- Event Handle(
on(event)):组件在emit(event)之外还收到on(event)函数,返回带元数据的EventHandle——emit()触发事件、shouldPreventDefault表示是否有绑定请求preventDefault、bound表示该事件是否有处理器; BaseComponentProps:与具体 catalog 解耦的组件渲染函数基类型,适合构建像@json-render/shadcn这样不绑定特定 catalog 的复用组件库;- 内置动作:schema 可声明
builtInActions,运行时始终可用且自动注入 prompt。React schema 内置了setState、pushState、removeState; preventDefault:ActionBinding新增布尔字段,让 LLM 可以请求阻止默认浏览器行为(如链接导航);- 流式文本块切分:
createJsonRenderTransform()会围绕 spec 数据输出text-end/text-start对,保证 AI SDK 在message.parts中生成独立的 text part,正确交错散文与 UI。
十、事件驱动生态:从 core 孵化出的渲染器矩阵
CHANGELOG 记录的不仅是 core 自身,还有它逐步孵化出的渲染器生态,每个渲染器共享"同一种 spec、不同平台"的哲学(自定义 schema 说明见 packages/core/README.md —— React 用扁平元素映射、Remotion 用时间线、你自己的渲染器可以用任何结构):
| 版本 | 新增包/能力 | 核心亮点 |
|---|---|---|
| 0.4.x | SpecStream 协议打磨 | RFC 6902 合规、defineRegistry、prompt 加入 remove 操作 |
| 0.5.x | React Native 渲染器 | 事件系统(emit 取代 onAction)、repeat 列表、user prompt 构建、spec 校验、StateProvider 改名 |
| 0.6.x | Chat 模式 + AI SDK 集成 | useChatUI、$bindState/$bindItem 双向绑定、结构化表达式、破坏性更名 |
| 0.7.x | @json-render/shadcn |
30+ 组件、event handles、内置动作、preventDefault |
| 0.8.x | @json-render/react-pdf |
renderToBuffer/renderToStream/renderToFile,完整上下文支持 |
| 0.9.x | 外部 StateStore + 适配器 | @json-render/zustand/redux/jotai、onStateChange 破坏性变更 |
| 0.10.x | Vue 渲染器、XState 适配器、计算/模板表达式、状态观察器、跨字段验证 | 与 React 全特性对齐 |
| 0.11.x | @json-render/image |
Satori 驱动,renderToSvg/renderToPng(PNG 需 @resvg/resvg-js),9 个标准组件 |
| 0.12.x | Svelte 渲染器、React Email、MCP Apps | Svelte 5 runes 响应式;renderToHtml/renderToPlainText;createMcpApp 服务工厂 |
| 0.13.x | SolidJS、React Three Fiber、严格 JSON Schema | 3D 场景渲染(19 个内置组件);jsonSchema({ strict: true }) |
| 0.14.x | @json-render/yaml + 通用编辑模式 |
流式 YAML 解析、yamlPrompt()、pipeYamlRender、四种围栏类型(yaml-spec/yaml-edit/yaml-patch/diff) |
| 0.15.x | @json-render/ink |
终端 UI 渲染器,20+ 标准组件,useUIStream 流式 |
| 0.16.x | @json-render/next、@json-render/shadcn-svelte |
Next.js 应用渲染器(路由、布局、SSR、metadata、静态生成);Svelte 5 + Tailwind 的 36 个组件库 |
其中 AI SDK 集成(0.6.0)包含 SpecDataPart 类型(data-spec 流式 part,支持 patch/flat/nested 载荷)、SPEC_DATA_PART/SPEC_DATA_PART_TYPE 常量、createMixedStreamParser() 混合流解析器,以及 React 侧的 useChatUI()、useJsonRenderMessage()、buildSpecFromParts()/getTextFromParts()、useBoundProp() 等 hook。完整的聊天示例在仓库的 examples/chat(含 AI agent、工具调用、主题切换与流式 UI 生成),后续还有 ink-chat 终端聊天示例与基于 react-three-fiber 的 game-engine 3D 示例。
十一、实验性能力:决策模型驱动的组合式生成
core 的 README 记录了两个实验性 API(experimental_ 前缀,任何版本都可能变更,升级前应锁定精确版本并阅读发布说明,见 packages/core/README.md):
experimental_composeSpec:在应用的原子元素候选集中"挑选"并组装出一个扁平 Spec;experimental_createEvaluator:通过 Vercel AI Gateway 连接一个选择评估模型(当前示例是typesafe-ai/jev,API 本身与模型无关)。
// Server only
import { experimental_composeSpec, experimental_createEvaluator } from "@json-render/core";
import { catalog } from "./catalog";
import { candidates } from "./candidates";
const evaluate = experimental_createEvaluator({
model: "typesafe-ai/jev",
apiKey: process.env.AI_GATEWAY_API_KEY!,
});
for await (const event of experimental_composeSpec({
catalog,
candidates,
prompt: "Create account preferences with a name field and Save button",
initialState: { name: "" },
evaluate,
maxSteps: 12,
maxElements: 24,
signal: AbortSignal.timeout(30_000),
})) {
if (event.type === "step") console.log(event.spec);
else console.log(event.stopReason, event.spec);
}
关键语义:候选包含 id、description 与原子 element(root: false 排除根选择、maxUses 默认 1、共享 resource 的候选互斥);新的组合默认 strategy: "batch"(一次评估同时选根与成员,第二次评估排列 slot 与兄弟顺序);后续编辑走 sequential 协议(可增候选、替换 recipe 但保留 ID 与子元素、删除非根子树、在合法 slot 间移动/重排子树)。stopReason 为 "finish" | "limit" | "unavailable"。实现位于 packages/core/src/experimental-compose.ts 与 packages/core/src/experimental-evaluator.ts,仓库 apps/web/lib/jev 展示了这些 API 的完整用法。
十二、版本演进速查与迁移要点
按 CHANGELOG 整理的关键迁移信号:
- 0.6.0(大版本破坏):表达式改名(
$path→$state等)、repeat.path→repeat.statePath、actionHandlers→handlers、移除遗留 catalog API、codegen 的traverseTree→traverseSpec。升级前对照 packages/core/CHANGELOG.md 的 Breaking Changes 清单逐一检查; - 0.9.0:
onStateChange签名改为单次回调收到变更数组;schema 导入改用服务端安全的@json-render/react/schema子路径,避免 Next.js App Router API 路由中的createContext崩溃; - 0.12.1:生成模式
"generate"/"chat"重命名为"standalone"/"inline"(旧名保留但弃用); - 0.14.0:多轮编辑通过
buildUserPrompt({ currentSpec, editModes })启用,YAML wire format 需在 0.14.1+ 配合format与serializer使用。
如果你想从源码继续深入研究,推荐按此顺序阅读:先看 packages/core/src/types.ts(Spec/SpecStream/表达式类型与实现)、再看 packages/core/src/schema.ts(schema/catalog/prompt 系统)、packages/core/src/spec-validator.ts(结构校验)、packages/core/src/edit-modes.ts(编辑模式),最后对照各渲染器包的实现理解"一份 spec、多端渲染"的完整链路。