json-render 核心库演进指南:从 SpecStream 流式渲染到全能渲染生态

原创2026-09-20 16:08:371,902 阅读
文章标签:人工智能AI 应用前端UI组件跨平台开发工具

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 整理的关键迁移信号:

  1. 0.6.0(大版本破坏):表达式改名($path→$state 等)、repeat.path→repeat.statePath、actionHandlers→handlers、移除遗留 catalog API、codegen 的 traverseTree→traverseSpec。升级前对照 packages/core/CHANGELOG.md 的 Breaking Changes 清单逐一检查;
  2. 0.9.0:onStateChange 签名改为单次回调收到变更数组;schema 导入改用服务端安全的 @json-render/react/schema 子路径,避免 Next.js App Router API 路由中的 createContext 崩溃;
  3. 0.12.1:生成模式 "generate"/"chat" 重命名为 "standalone"/"inline"(旧名保留但弃用);
  4. 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、多端渲染"的完整链路。

登录后查看全文
json-render