在基于 @json-render/core 定义…

适用于为 json-render 构建 JSON UI/video 规格、组件目录、AI 提示词、流式补丁、状态绑定、可见性与校验的应用集成。

适用场景

解决思路

1. 从 `@json-render/core` 导入 `experimental_composeSpec` 与 `experimental_createEvaluator` 做决策模型组合；这些 API 未发布，先用 source build，发布后固定精确版本，并接受实验导出与 `Experimental_` 类型可能在任何 release 变化。
2. 在服务端运行 Gateway evaluator，参数为 `{ model: 'typesafe-ai/jev', apiKey: process.env.AI_GATEWAY_API_KEY! }`；必须使用纯模型标识符，Jev 是当前示例，不要导入 provider constructor。
3. 调用 `experimental_composeSpec({ catalog, candidates, prompt, evaluate, initialState, signal })`；它是 async generator，把 `step.spec` 快照流到现有 renderer，并检查 `complete.stopReason`（`finish`、`limit`、`unavailable`）。
4. 处理组合错误与取消：错误和取消会抛出；保留最后快照作为部分 UI。
5. 新树默认 `strategy: batch`：第一次评估选择 root/membership，第二次在需要时排列已选元素；第一个快照按 catalog 顺序将选中内容放在 root 默认/第一个 slot 下。
6. 处理 resource variants 与重复计数：resource variants 共享一个 exclusive question；重复计数包含 root；root selection 优先于该 recipe/resource 冲突的 speculative membership；相同 sibling positions 保留 catalog order。
7. 发布前验证组合布局：cycles 或 excessive depth 会抛出；`maxElements` 限制批量创建，默认 32；限制截断的选择或缺少必需 layout call 返回 `limit`。
8. 对 legacy `next`/`parent` adapters 或 sequential creation 使用 `strategy: sequential`；编辑保持 sequential。
9. Batched trace steps 使用 `choice: select` 或 `choice: layout` 和 `answers` 记录；每个 trace 计为一次 evaluation，并只计一次其 tokens 与 latency。
10. 自定义 evaluators 必须回答每个提供的问题；名称/choices 不透明，包括 `root`/`select_*`，然后 batches 的 `parent_*`/`order_*`。
11. 对后续编辑，将选定版本作为 `initialSpec` 传入；它会被克隆并验证，evaluator 可添加、替换、移除非 root 子树，或移动/重排它们；未变 IDs、bindings 和 state 保留。
12. 需要共享标识描述时传 `elementDescriptions`，避免暴露 raw props/state；用 `initialState` 覆盖 seed state；seed 必须是 catalog、expression subset 和 depth limit 内的有效树。
13. 处理 usage/resource limits：matching recipes 消耗 usage/resource limits；removals/replacements 释放它们；replacements/moves 使用两次 evaluations（选择 target，然后 recipe/destination），每次计入 budget；operation 与 position keys 视为不透明。
14. 提供原子 candidates：`{ id, description, element: { type, props, on?, visible? }, root?, maxUses?, resource? }`；仅 catalog 不够，应用必须提供值和 binding recipes；Jev 选择元素和 parent slots，绝不生成 free-form text 或 code，也从不执行 actions。
15. 将 candidates 构建为配置好的组件实例，而不是页面模板：从当前应用记录/操作构建，或将 props 绑定到 `initialState`；为 chart types、field configurations、layout variants 提供显式备选。
16. 让模型在 candidates 内选择分组和顺序；在 prompts 中命名必需 sections；记住结构有效不代表语义完整。
17. V1 支持 flat Spec catalogs、named slots、literals、`$state`、`$bindState` 和 state visibility；不支持 prebuilt children、repeat/watch、computed/template/conditional props 或 custom directives；success/error callbacks 必须引用允许的 actions；events 必须在 component catalog 中声明。
18. Props 与 action params 针对 initial state 验证，不应用 schema transforms/defaults；提供有效初始值，并在运行时验证/授权 action calls；没有 parameter schemas 的 built-ins 只做 name validation。
19. 设置默认值：`root` 默认 true，`maxUses` 默认 one，共享 `resource` 值使 alternatives 互斥；默认 32 evaluations（包括 terminal calls；batches 无额外 finish call）、depth 八、每次 Gateway 调用 10 秒超时；提供整体 abort signal。
20. 只发送 candidate descriptions、prompt、instructions、topology 和显式 `context` 给 evaluator；initial state 和 raw props/binding values 不会自动发送。
21. 对 custom providers 实现 `Experimental_CompositionEvaluator`：接受 `{ state, questions, signal }`，返回 `{ answers: { [question]: { choice, confidence? } }, usage?: { inputTokens? } }`；只返回提供 criteria keys。
22. 查看 `packages/core/README.md` 和 `/docs/jev` 获取 app 集成和 source-build 说明；Web playground 是示例消费者，不是 API 依赖。
23. 用 `defineSchema` 定义 Spec 与 Catalog 的结构；在 builder 中声明 `spec` 与 `catalog`，其中 `catalog.components` 可用 `s.map({ props: s.zod(), description: s.string() })`。
24. 在 `defineSchema` 的第二个参数中可选传入 `promptTemplate: myPromptTemplate`，以自定义 AI prompt 模板。
25. 用 `defineCatalog(schema, { components: { ... } })` 创建 catalog，将组件/动作名映射到 props Zod schema 与 description，例如 `Button` 的 `props` 和 `description`。
26. 用 `catalog.prompt()` 基于 schema 的 `promptTemplate` 生成 systemPrompt。
27. 用 `catalog.prompt({ customRules: [...] })` 追加自定义规则生成 systemPrompt。
28. 用 `createSpecStreamCompiler<MySpec>()` 创建编译器；对每个流式 chunk 调用 `compiler.push(chunk)`，取得 `result` 与 `newPatches`；最后用 `compiler.getResult()` 获取最终 Spec。
29. 用 `createJsonRenderTransform` 在混合流中分离文本与 JSONL；用 `parseSpecStreamLine` 解析单条 JSONL 行；用 `applySpecStreamPatch` 将 patch 应用到对象。
30. 把任何 prop 值写成渲染时解析的动态表达式：用 `$state` 读取 state model 中的值，单向读。
31. 在表单组件的自然值 prop（如 `value`、`checked`、`pressed`）上用 `$bindState` 做双向绑定；不要使用 `statePath` prop。
32. 在 repeat scope 内用 `$bindItem` 对重复项字段做双向绑定。
33. 用 `$cond` 搭配 `$then` 与 `$else` 评估可见性条件并选择分支；条件语法与 visibility conditions 相同（`$state`、`eq`、`neq`、`not`、数组表示 AND），且 `$then`、`$else` 可以是递归表达式。
34. 用 `$template` 插值 `${/path}` 引用，将 state 值插入字符串。
35. 用 `$computed` 指定注册函数名，并在 `args` 中为每个参数传入已解析的表达式，以调用注册函数。
36. 用 `resolvePropValue` 解析单个 prop 表达式；用 `resolveElementProps(element.props, { stateModel: myState })` 解析元素的所有 prop 表达式。
37. 在元素顶层（与 `type`、`props`、`children` 同级）声明 `watch`，将 state 路径映射到带 `action` 与 `params` 的动作；仅当值变化时触发，不在初始渲染触发。
38. 在 `watch` 的 `params` 中用 `$state` 表达式传入当前 state 值，例如 `country` 参数引用 `/form/country`。
39. 用内置 validation functions：`required`、`email`、`url`、`numeric`、`minLength`、`maxLength`、`min`、`max`、`pattern`、`matches`、`equalTo`、`lessThan`、`greaterThan`、`requiredIf`。
40. 跨字段 validation 在 args 中使用 `$state` 表达式；用 `check.required(...)`、`check.matches(...)`、`check.lessThan(...)`、`check.greaterThan(...)`、`check.requiredIf(...)` 创建校验。
41. 用 `buildUserPrompt({ prompt: ... })` 构建全新生成的用户 prompt。
42. 用 `buildUserPrompt({ prompt, currentSpec: spec, editModes: [...] })` 构建带修订的用户 prompt；默认 edit mode 为 patch-only。
43. 用 `buildUserPrompt({ prompt, state: ... })` 将运行时 state 上下文加入用户 prompt。
44. 可用 edit modes 包括 `patch`（RFC 6902 JSON Patch）、`merge`（RFC 7396 Merge Patch）、`diff`（unified diff）。
45. 用 `buildEditUserPrompt` 为编辑现有 Spec 构建用户 prompt；用 `buildEditInstructions` 生成可用 edit modes 的 prompt section。
46. 用 `validateSpec(spec)` 得到 `{ valid, issues }`；issues 包括 `missing_child`、`invalid_visible`、`repeat_without_children`、`repeat_item_outside_scope`、`repeat_state_mismatch`。
47. 用 `autoFixSpec(spec)` 自动修复常见 Spec 问题，得到 `{ spec: fixed, fixDetails }`；`fixDetails` 条目为 `{ message, lossy }`。
48. 区分修复类型：无损修复会重定位放错位置的字段；有损修复会剪除悬空 children 引用。
49. 在修复循环中，直到重试耗尽才启用有损修复：调用 `autoFixSpec(spec, { lossy: retriesExhausted })`。
50. 用 state-based conditions 控制元素可见性；`VisibilityContext` 为 `{ stateModel: StateModel }`。
51. 可见性语法：`$state` 表示 truthiness；`$state` 加 `not: true` 表示 falsy；`$state` 加 `eq` 表示相等；条件数组表示隐式 AND。
52. 用 `visibility.when`、`visibility.unless`、`visibility.eq`、`visibility.and`、`visibility.or`、`visibility.always`、`visibility.never` 创建可见性条件。
53. 在 schema 中声明 `builtInActions`，例如 `defineSchema(builder, { builtInActions: [{ name: 'setState', description: 'Update a value in the state model' }] })`；这些动作运行时始终可用并自动注入 prompts。
54. 内置动作在 prompts 中显示为 `[built-in]`，且不需要在 `defineRegistry` 中提供 handlers。
55. 用 `createStateStore({ count: 0 })` 创建框架无关的内存 `StateStore`。
56. 用 `store.get('/count')` 读取值；用 `store.set('/count', 1)` 更新并通知 subscribers；用 `store.update({ '/a': 1, '/b': 2 })` 批量更新。
57. 用 `store.subscribe(() => { console.log(store.getSnapshot()); })` 订阅变化并读取快照。
58. 实现或接入 `StateStore` 接口：`get(path)`、`set(path, value)`、`update(updates)`、`getSnapshot()`、`subscribe(listener)`，以插入 Redux、Zustand、XState 等外部状态管理库。
59. 使用 `defineSchema` 创建新 schema。
60. 使用 `defineCatalog` 从 schema 创建 catalog。
61. 使用 `createStateStore` 创建框架无关的内存 `StateStore`。
62. 使用 `resolvePropValue` 解析单个 prop 表达式。
63. 使用 `resolveElementProps` 解析元素中的所有 prop 表达式。
64. 使用 `buildUserPrompt` 构建带 refinement 和 state context 的用户 prompt。
65. 使用 `buildEditUserPrompt` 为编辑现有 Spec 构建用户 prompt。
66. 使用 `buildEditInstructions` 生成可用 edit modes 的 prompt section。
67. 使用 `isNonEmptySpec` 检查 Spec 是否有 root 且至少一个 element。
68. 使用 `deepMergeSpec` 做 RFC 7396 deep merge：null deletes、arrays replace、objects recurse。
69. 使用 `diffToPatches` 从对象 diff 生成 RFC 6902 JSON Patch operations。
70. 使用 `EditMode` 类型，取值为 `patch`、`merge`、`diff`。
71. 使用 `validateSpec` 验证 Spec 结构。
72. 使用 `autoFixSpec` 自动修复常见 Spec issues，分类 lossy/lossless，`{ lossy: false }` 阻止 pruning。
73. 使用 `createSpecStreamCompiler` 将 JSONL patches 流式编译为 Spec。
74. 使用 `createJsonRenderTransform` 在 mixed streams 中分离 text 与 JSONL。
75. 使用 `parseSpecStreamLine` 解析单条 JSONL line。
76. 使用 `applySpecStreamPatch` 将 patch 应用到 object。
77. 使用 `StateStore` 接口接入外部状态管理。
78. 使用 `ComputedFunction` 作为 `$computed` expressions 的函数签名。
79. 使用 `check` 作为创建 validation checks 的 TypeScript helpers。
80. 使用 `BuiltInAction` 类型定义内置 action（`name` + `description`）。
81. 使用 `ActionBinding` 类型表示 action binding（包含 `preventDefault` field）。

适用边界 · 注意事项

• 未安装或不想依赖 @json-render/core、Zod 或 AI Gateway/API key 时，不要使用本经验。
• 实验性决策模型组合 API 未发布，必须使用 source build 并固定精确版本；不能接受实验导出和 `Experimental_` 类型随版本变化时，不要用于生产。
• V1 实验组合不支持 prebuilt children、repeat/watch、computed/template/conditional props 或 custom directives，且不会自动发送 initial state 和 raw props/binding values；需要这些能力时不要用 V1 实验组合。