决策 schema
每个决策背后的 JSON 文档——它接受的状态、它回答的问题、复合指标、选择行动的策略、运行时设置和目的地。
一个决策由一个 JSON 文档定义,即决策 schema。编辑器和可视化构建器会替你编辑它(右侧面板在决策 schema 下显示它),CLI 可以离线生成脚手架并校验它,每个已部署的版本都保存了它的完整快照。
schema 与引擎无关:其中没有任何内容是 Jev 或其他引擎特有的。
完整示例
这是按存储形式展示的线索资格评估模板,所有默认值都已填入:
{
"stateSchema": {
"kind": "object",
"fields": [
{ "key": "message", "type": "string", "required": true, "description": "Inbound lead message" },
{ "key": "company_size", "type": "number", "required": false, "description": "Employee count" },
{ "key": "source", "type": "string", "required": false, "description": "website, referral, ads…" }
]
},
"questions": [
{
"key": "purchase_intent",
"type": "probability",
"instructions": "Does this lead have real intent to buy in the next 30 days?",
"criteria": {
"yes": "asks for pricing, a demo, a quote or a start date",
"no": "just browsing, student, vendor or spam"
}
},
{
"key": "priority",
"type": "score",
"instructions": "How urgent is it to answer this lead?",
"scale": ["low", "medium", "high", "critical"]
},
{
"key": "route",
"type": "choice",
"instructions": "Which team should receive this lead?",
"options": [
{ "value": "sales", "description": "high intent, ready to talk to sales" },
{ "value": "sdr", "description": "some intent, needs qualification" },
{ "value": "nurture", "description": "early stage, send content" },
{ "value": "spam", "description": "spam, vendor pitch or irrelevant" },
{ "value": "other", "description": "none of the options above" }
]
}
],
"composites": [
{
"key": "lead_score",
"description": "0–1 ranking: intent counts double, priority adds, spam-like routes don't count",
"terms": [
{ "question": "purchase_intent", "weight": 2 },
{ "question": "priority", "weight": 1 },
{ "question": "route", "option": "sales", "weight": 1 }
]
}
],
"policies": [
{ "field": "route", "on": "output", "operator": "eq", "value": "spam", "action": "block" },
{ "field": "purchase_intent", "on": "confidence", "operator": "lt", "value": 0.6, "action": "escalate" }
],
"settings": {
"storeInput": true,
"storeOutput": true,
"timeoutMs": 5000,
"fallbackAction": "escalate",
"onEngineError": "error"
}
}顶层字段
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
stateSchema | object | 是 | 决策接受的输入——参见状态 schema。 |
questions | array | 是 | 1 到 64 个问题——参见问题。 |
composites | array | 否 | 最多 20 个回答的加权组合。默认 []——参见复合指标。 |
policies | array | 否 | 最多 50 条规则,按顺序评估。默认 []——参见策略与行动。 |
context | string | 否 | 最多 8,000 个字符的业务上下文,随每个状态一起发送——参见上下文。 |
settings | object | 否 | 引擎、存储、时间预算、fallback 行动和引擎错误行为——参见决策设置。 |
destinations | array | 否 | 最多 20 个目的地——决策之后发生什么,按选项、级别、阈值或最终行动设置。默认 []——参见目的地。 |
键
状态字段、问题键、复合指标键和 choice 选项值遵循同一条规则,因为它们会成为 API 响应中的 JSON 键和值:
- snake_case:以小写字母开头,后接小写字母、数字或
_; - 最多 48 个字符(模式
^[a-z][a-z0-9_]{0,47}$); - 唯一:问题键和复合指标键在决策内唯一,字段键在状态内唯一,选项值在问题内唯一。
状态 schema
状态是你的应用在请求体中以 { "state": … } 发送的内容。从三种类型中选择一种——与 Jev 原生评估的三种形态相同:
| 类型 | 发送 | 适用于 |
|---|---|---|
object | 带类型字段的 JSON 对象 | 大多数决策:命名字段让输入的每个部分都清晰明确 |
text | 非空字符串 | 一条消息、评论或段落 |
list | 由字符串或对象组成的非空数组 | 聊天记录、一批记录 |
对象状态
{ "kind": "object", "fields": [{ "key": "message", "type": "string", "required": true }] }fields 最多包含 50 个字段定义:
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
key | string | — | 状态中的 JSON 键。 |
type | string | — | string、number、integer、boolean、array、object 之一——或者文件:image、audio、file(参见输入)。 |
required | boolean | false | 拒绝不包含此字段的状态。 |
description | string | — | 最多 255 个字符。在编辑器显示的 API 契约中为该字段提供说明。 |
引擎运行之前状态如何被校验:
- 状态必须是 JSON 对象(不能是数组、字符串或
null); required字段必须存在且不为null;可选字段可以缺失或为null;- 类型是严格的:
number是任意有限数字,integer是整数,object是非 null 且不是数组的对象——"500"不是number;image、audio和file接受data:URL、https://URL 或{ "data" | "url", "filename" }; - 未声明的字段会被接受并转发给引擎,因此你可以在不修改 schema 的情况下发送额外的上下文;
- 只报告第一个失败的字段,例如
422 INVALID_STATE并附带"Field company_size must be a number."。
字段描述只是文档
引擎接收的是你状态中的键和值、决策的 context 以及问题——而不是字段描述。请通过有描述性的字段名、context 和精确的指令为引擎提供它所需要的信息,并在指令中按名称引用字段:"Does `message` ask for a demo?"。
文本状态
{ "kind": "text" }状态必须是一个非空字符串:{ "state": "Congratulations! You won a $1000 gift card…" }。引擎接收的就是该字符串本身。
列表状态
{ "kind": "list", "items": "string" }状态必须是一个最多 500 项的非空数组。items 设定每一项是什么:
items | 每一项必须是 | 示例状态 |
|---|---|---|
string(默认) | 字符串 | ["Hi!", "My card was charged twice.", "Can you refund one?"] |
object | JSON 对象(不能是 null,也不能是数组) | [{ "role": "customer", "text": "My card was charged twice." }, { "role": "agent", "text": "Let me check." }] |
引擎接收的就是该数组本身。错误会指出问题所在:"Field state must be a non-empty array."、"Field state has too many items (612, max 500)." 或 "Item 2 of state must be an object."。
一个列表是一个状态:每个问题都是针对整个列表回答的——“这段对话是否在要求退款?”——而不是每一项回答一次。要独立地对各项分类,请为每一项发送一次决策,或者使用对象状态,例如 { "messages": [ … ] },并为每个位置设置一个问题("Is `messages[2]` a complaint?")。
大小限制
序列化后的状态必须在 128 KB 以内,并且约在 32,000 个 token 以内(按字符数 ÷ 4 估算)——不包括其中的文件,文件有它们自己的限制(每个 20 MB;其文本会被截断以适应——参见输入)。
Jev 对整个调用也有 token 预算:状态加最长的问题约为 32,000 个 token,状态加所有问题约为 64,000 个 token。Dcision 会在调用引擎之前检查这两项;超出限制的状态会以 422 INVALID_STATE 失败,并附带说明触及了哪个限制的消息——例如 "The state plus all questions is too large for one engine call (~65210 tokens, max 64000). Shorten the state or split the decision." 参见限制。
上下文
context 是自由文本,最多 8,000 个字符,以保留键 decision_context 随每个状态一起发送——例如 "Inbound messages from the pricing page of a B2B SaaS. Prices start at $29/month." 描述业务,而不是期望的答案。
引擎如何接收它:
| 状态类型 | 设置了 context 时引擎评估的内容 |
|---|---|
object | 你的对象加上一个 decision_context 字段 |
text、list | { "decision_context": "<context>", "input": <your state> } |
没有 context 时,引擎接收的是原样的状态。
decision_context 是保留键:当决策设置了 context 时,它会替换你的应用在对象状态中发送的 decision_context 字段。其他任何字段——包括名为 context 的字段——都会按原样转发。
结构化条目
指令、choice 选项描述、score 级别和 probability 判定标准除了文本之外,还接受 JSON 对象或数组——Jev 原生读取结构化内容。可以用它为长问题的各个部分加标签、传递辅助数据,或为每个选项提供评分细则。参见结构化指令和判定标准。
校验
同样的规则在所有地方运行:
-
编辑器——在你输入时进行校验,为每个问题显示跳转到错误链接,并且只自动保存有效的草稿。
-
API——保存或部署无效的 schema 会以
422 INVALID_SCHEMA失败;details会列出每个问题及其路径:{ "error": { "code": "INVALID_SCHEMA", "message": "The decision schema is invalid.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w", "details": [ { "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." }, { "path": "policies.1.field", "message": "Unknown question \"intent\"." }, { "path": "composites.0.terms.2.option", "message": "Pick the option whose probability counts." } ] } } -
CLI——
dcision validate decision.json离线检查一个文件,dcision check-state根据它检查一个状态。
校验规则可能会随着时间变得更严格——例如从 v0.3 起,规则的值会根据其所比较的选项、级别和范围进行检查("Use a number between 0 and 1 (e.g. 0.7, not 70).")。更严格的规则在你保存或部署时生效;已部署的版本会保持原样继续运行,因此收紧的规则永远不会让已上线的端点出错。
API 契约
编辑器的 API 契约视图展示了决策的客户端可以依赖的内容:以 JSON Schema 表示的状态、每个问题回答的结构以及复合指标。
{
"name": "lead-qualification",
"state": {
"type": "object",
"required": ["message"],
"properties": {
"message": { "type": "string", "description": "Inbound lead message" },
"company_size": { "type": "number", "description": "Employee count" },
"source": { "type": "string", "description": "website, referral, ads…" }
}
},
"questions": {
"purchase_intent": { "type": "probability", "range": [0, 1] },
"priority": { "type": "score", "scale": ["low", "medium", "high", "critical"] },
"route": { "type": "choice", "options": ["sales", "sdr", "nurture", "spam", "other"] }
},
"composites": {
"lead_score": { "type": "number" }
}
}文本状态显示为 { "type": "string" },列表状态显示为 { "type": "array", "items": { "type": "string" } }(或 "object")。score 等级会列出级别标签,结构化级别也是如此。只有当决策包含复合指标时,composites 才会出现。