决策 schema

每个决策背后的 JSON 文档——它接受的状态、它回答的问题、复合指标、选择行动的策略、运行时设置和目的地。

一个决策由一个 JSON 文档定义,即决策 schema。编辑器和可视化构建器会替你编辑它(右侧面板在决策 schema 下显示它),CLI 可以离线生成脚手架并校验它,每个已部署的版本都保存了它的完整快照。

schema 与引擎无关:其中没有任何内容是 Jev 或其他引擎特有的。

完整示例

这是按存储形式展示的线索资格评估模板,所有默认值都已填入:

decision.json
{
  "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"
  }
}

顶层字段

字段类型必填描述
stateSchemaobject是决策接受的输入——参见状态 schema。
questionsarray是1 到 64 个问题——参见问题。
compositesarray否最多 20 个回答的加权组合。默认 []——参见复合指标。
policiesarray否最多 50 条规则,按顺序评估。默认 []——参见策略与行动。
contextstring否最多 8,000 个字符的业务上下文,随每个状态一起发送——参见上下文。
settingsobject否引擎、存储、时间预算、fallback 行动和引擎错误行为——参见决策设置。
destinationsarray否最多 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 个字段定义:

属性类型默认值描述
keystring—状态中的 JSON 键。
typestring—string、number、integer、boolean、array、object 之一——或者文件:image、audio、file(参见输入)。
requiredbooleanfalse拒绝不包含此字段的状态。
descriptionstring—最多 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?"]
objectJSON 对象(不能是 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 才会出现。

本页内容