结构化输出
返回一个你的系统可以直接使用的 JSON 对象,或一个由你的应用渲染的界面——由结果构建(不调用模型)或由 LLM 构建,在离开 Dcision 之前始终经过检查。
决策负责回答问题:result、confidence 和 action。结构化输出目的地(json)还会返回一个可直接用于你系统的对象——要创建的工单、要更新的订单、要新建的线索——并在它离开 Dcision 之前按你定义的字段进行检查。
它在响应的顶层 output 中返回:
{
"result": { "route": "support", "priority": "high" },
"action": "continue",
"output": { "awb": "1Z999AA10123456784", "team": "support", "priority": 3, "summary": "Package is 3 days late" },
"destinations": [
{ "key": "ticket", "type": "json", "mode": "template", "status": "completed", "output": { "awb": "1Z999AA10123456784", "team": "support", "priority": 3, "summary": "Package is 3 days late" } }
]
}两种填充方式
mode | 方式 | 成本与延迟 |
|---|---|---|
template(默认) | 一个带变量的 JSON 模板——状态、回答、加权级别、复合指标和参数。 | 免费、即时:不调用模型。 |
extract | 由 LLM 读取状态并填充字段,使用你的 OpenRouter 或 Vercel AI Gateway 密钥——与 LLM 回答相同。 | 提供商的 token 费用;调用方需要等待(它计为让调用方等待的 3 个调用之一)。 |
当值已经存在时——在状态或回答中——使用 template。当值埋在文本中时使用 extract:电子邮件中的订单号、聊天消息中的姓名。
字段
schema 是一个 JSON Schema 对象,与 LLM 提供商用于结构化输出的格式相同:
{
"type": "object",
"properties": {
"awb": { "type": "string", "description": "The tracking number" },
"team": { "type": "string", "enum": ["sales", "support", "billing"] },
"priority": { "type": "integer", "minimum": 1, "maximum": 4 },
"items": { "type": "array", "items": { "type": "string" }, "maxItems": 10 },
"note": { "type": ["string", "null"] }
},
"required": ["awb", "team"]
}| 关键字 | 用途 |
|---|---|
type | string、number、integer、boolean、object 或 array——或者 ["string", "null"] 以接受 null。根节点始终是 object。 |
properties、required | 对象的字段,以及哪些字段必须存在。每个对象都要声明其字段。 |
items | 列表包含的内容(array 必填)。 |
enum | 文本或数字字段的允许值(最多 50 个)。 |
description | 字段的含义——在 extract 模式下模型会读取它。 |
minimum、maximum、minLength、maxLength、minItems、maxItems | 数字、文本和列表的边界。 |
不在 schema 中的字段不被接受。限制:最多 3 层嵌套对象,总共 50 个字段,schema 最大 8 KB;输出本身最大 16 KB。在编辑器中,输出字段逐行构建 schema;JSON Schema 标签页以 JSON 形式显示它,你也可以在那里粘贴一个。
模板模式
模板是带变量的 JSON,编码方式与 API 请求的请求体相同:在引号外,变量会成为一个 JSON 值;在引号内,它会成为文本。
{
"key": "ticket",
"type": "json",
"when": { "conditions": [{ "field": "route", "on": "output", "operator": "eq", "value": "support" }] },
"params": { "awb": { "from": "state.awb", "required": true } },
"json": {
"mode": "template",
"schema": { "type": "object", "properties": { "awb": { "type": "string" }, "team": { "type": "string" }, "priority": { "type": "number" }, "summary": { "type": "string" } }, "required": ["awb", "team"] },
"template": "{\"awb\": {{params.awb}}, \"team\": {{result.route}}, \"priority\": {{scores.priority}}, \"summary\": \"Customer said: {{state.message}}\"}"
}
}- 来自状态的文本不会破坏 JSON:无论变量出现在哪里,引号和换行都会被转义。
- 不能使用密钥——输出会返回给调用方。保存时会拒绝
{{secrets.NAME}}。 - 保存时,模板代入示例值后必须是有效的 JSON,并且包含必填字段。编辑器中的按字段填充会写出一个初始模板:与状态字段、问题、复合指标或参数同名的字段会读取它。
提取模式
"json": {
"mode": "extract",
"schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "customer": { "type": "string" }, "request": { "type": "string", "enum": ["refund", "exchange", "tracking"] } }, "required": ["order_id", "request"] },
"provider": "openrouter",
"model": "openai/gpt-5-mini",
"instructions": "Extract the order this customer is writing about.",
"input": "{{state.message}}",
"temperature": 0,
"maxTokens": 1024,
"timeoutMs": 20000
}| 字段 | 默认值 | 说明 |
|---|---|---|
provider | openrouter | openrouter 或 vercel——保存在设置 → 引擎中的密钥。 |
model | — | 提供商的模型 ID。请选择支持结构化输出(JSON Schema)的模型。 |
instructions | — | 要提取什么(系统消息):最多 8,000 个字符。可以使用变量,不能使用密钥。 |
input | 整个状态 | 用户消息:最多 8,000 个字符。 |
temperature | 0 | 0 到 2。 |
maxTokens | 1024 | 16 到 4,096。 |
timeoutMs | 20000 | 1,000 到 25,000,包括重试。 |
Dcision 以提供商的严格结构化输出模式(response_format: json_schema)发送 schema。严格模式要求每个字段都存在,因此可选字段以可空形式发送,模型为它们写入的 null 会在验证之前被移除。如果回答仍然不符合——无效的 JSON、超出 enum 的值、缺少字段——Dcision 会带着问题把它发回一次,仍在同一个 timeoutMs 之内。
失败时
结构化输出永远不会使决策失败。条目会以 "status": "failed"、一个 error 返回,并在对象不匹配时附带 issues:
{
"key": "ticket",
"type": "json",
"mode": "template",
"status": "failed",
"error": "The output doesn't match the schema.",
"issues": [{ "path": "/awb", "message": "Must not be null." }]
}issues[].path 是指向该值的 JSON Pointer(/items/2)。顶层的 output 为:
| 情况 | output |
|---|---|
有一个 json 目的地完成 | 它的对象——当多个目的地触发时,按 schema 顺序取第一个。 |
json 目的地已触发,但没有一个完成 | null |
没有 json 目的地触发 | 不存在 |
界面(json-render)
使用 "format": "ui" 时,输出是一个界面而不是数据:一个 json-render 规范——卡片、文本、徽章、表格、按钮——由你的应用原生渲染。它用一个界面回应调用方,而不仅仅是一个值:带有联系客服按钮的订单状态,带有预约演示链接的线索摘要。
"json": {
"format": "ui",
"mode": "template",
"template": "{\"root\": \"card\", \"elements\": {\"card\": {\"type\": \"Card\", \"props\": {\"title\": \"Order {{state.awb}}\"}, \"children\": [\"status\", \"talk\"]}, \"status\": {\"type\": \"Badge\", \"props\": {\"text\": {{result.route}}}, \"children\": []}, \"talk\": {\"type\": \"Button\", \"props\": {\"label\": \"Talk to support\"}, \"children\": [], \"on\": {\"press\": {\"action\": \"reply\", \"params\": {\"text\": \"support\"}}}}}}"
}界面是 { "root", "elements" }:一个扁平的元素映射,每个元素有 type、props、children(元素键)以及可选的 on(事件 → 动作)。输出会完整返回——每个组件的每个 prop 都在,未使用时为 null。
组件目录
界面使用 Dcision 的组件目录——json-render shadcn 组件的一个精确子集,props 相同:
| 组件 | 用途 |
|---|---|
Card、Stack、Grid、Separator | 布局。 |
Heading、Text、Badge、Alert | 文本和状态。 |
Table、Image、Avatar、Progress | 数据和媒体。 |
Button、Link | 动作(on.press)。 |
| 动作 | 参数 | 含义 |
|---|---|---|
reply | { "text": "…" } | 把文本作为用户的下一条消息发回——快捷回复。 |
open_url | { "url": "https://…" } | 打开一个 URL。 |
Dcision 如何检查界面
每个界面——无论来自模板还是 LLM——都会经过 json-render 自身的检查和 Dcision 的加固:
- json-render 的
autoFixSpec修复常见的模型错误(props中的visible、不存在的子元素)。 - 结构必须成立:根节点存在,子元素存在,组件类型已知。
- 按组件检查 props,使用该组件的 schema——未知的 props 会被拒绝。
- 动作:仅限
reply和open_url,绑定在组件拥有的事件(press)上,并带有有效的参数。 - URL——
Link.href、Image.src、Avatar.src、open_url——必须是https://(不允许javascript:链接,不允许通过普通 http 追踪)。 - 仅限最终值:不允许
repeat、可见性条件或$state表达式;className始终为null。最多 60 个元素和 32 KB。
在 extract 模式下,模型会收到 json-render 的目录提示词以及你的指令;如果它生成的界面未通过检查,Dcision 会把问题发回一次。模板会在保存时使用示例值进行检查。
渲染它
npm install @json-render/core @json-render/react @json-render/shadcn zodimport { defineCatalog } from "@json-render/core";
import { JSONUIProvider, Renderer, defineRegistry } from "@json-render/react";
import { schema } from "@json-render/react/schema";
import { shadcnComponents } from "@json-render/shadcn";
import { shadcnComponentDefinitions as d } from "@json-render/shadcn/catalog";
import { z } from "zod";
const names = ["Card", "Stack", "Grid", "Separator", "Heading", "Text", "Badge", "Alert", "Table", "Image", "Avatar", "Progress", "Button", "Link"] as const;
const catalog = defineCatalog(schema, {
components: Object.fromEntries(names.map((name) => [name, d[name]])),
actions: {
reply: { params: z.object({ text: z.string() }), description: "Quick reply" },
open_url: { params: z.object({ url: z.string() }), description: "Open a URL" },
},
});
const { registry } = defineRegistry(catalog, {
components: Object.fromEntries(names.map((name) => [name, shadcnComponents[name]])),
actions: { reply: async () => {}, open_url: async () => {} },
});
export function DecisionScreen({ decision, send }) {
return (
<JSONUIProvider
registry={registry}
handlers={{
reply: async ({ text }) => send(text),
open_url: async ({ url }) => window.open(url, "_blank", "noopener"),
}}
>
<Renderer spec={decision.output} registry={registry} />
</JSONUIProvider>
);
}json-render 还可以用 React Native、React Email、React PDF 和其他目标渲染同一个规范——在那里映射相同的组件名称即可。
在 Playground 和日志中
- 在 Playground 中,
template目的地始终运行(它们是免费的);extract目的地会显示将要发送的提示词和严格 schema("status": "preview"),除非你真实执行目的地。界面会被渲染,按下按钮会显示它将发送的动作。 - 当决策保存输出时(
storeOutput),执行日志会保留output;使用storeOutput: false时,只保留输出是否已构建。 - SDK 将其暴露为
decision.output——在 TypeScript 中,用dcision.decide<Result, Output>(…)指定类型。