结构化输出

返回一个你的系统可以直接使用的 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"]
}
关键字用途
typestring、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
}
字段默认值说明
provideropenrouteropenrouter 或 vercel——保存在设置 → 引擎中的密钥。
model—提供商的模型 ID。请选择支持结构化输出(JSON Schema)的模型。
instructions—要提取什么(系统消息):最多 8,000 个字符。可以使用变量,不能使用密钥。
input整个状态用户消息:最多 8,000 个字符。
temperature00 到 2。
maxTokens102416 到 4,096。
timeoutMs200001,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 的加固:

  1. json-render 的 autoFixSpec 修复常见的模型错误(props 中的 visible、不存在的子元素)。
  2. 结构必须成立:根节点存在,子元素存在,组件类型已知。
  3. 按组件检查 props,使用该组件的 schema——未知的 props 会被拒绝。
  4. 动作:仅限 reply 和 open_url,绑定在组件拥有的事件(press)上,并带有有效的参数。
  5. URL——Link.href、Image.src、Avatar.src、open_url——必须是 https://(不允许 javascript: 链接,不允许通过普通 http 追踪)。
  6. 仅限最终值:不允许 repeat、可见性条件或 $state 表达式;className 始终为 null。最多 60 个元素和 32 KB。

在 extract 模式下,模型会收到 json-render 的目录提示词以及你的指令;如果它生成的界面未通过检查,Dcision 会把问题发回一次。模板会在保存时使用示例值进行检查。

渲染它

npm install @json-render/core @json-render/react @json-render/shadcn zod
import { 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>(…) 指定类型。

本页内容