决策原语

共享状态与命名问题

原生 state 字段必填，值可以是字符串、JSON 对象、数组或 null。数组仍是一份共享状态，不代表多条独立请求组成的批次。每个命名问题都评估这份状态；独立状态应分别调用。

instructions 可省略或为 null，提供时也可使用字符串、对象和数组。Noul criteria 可省略、为 null，或描述 true 与 false。这些原生形式与官方 @typesafe-ai/sdk@0.6.0 声明一致，会转发给上游决定接受或拒绝，但 State 字段本身不可省略。请使用普通 JSON，问题与选项名称须包含非空白字符，最多 128 个字符。

下方工厂函数来自项目 @system-one-ai/sdk@0.3.0，要求非 null 的 state 与显式 instructions，并且不接受 null Noul criteria。更宽的 nullable 形式请使用官方客户端示例或原生 HTTP，不要把 null 静默替换为空字符串。

Choice：选项

import { choice } from '@system-one-ai/sdk';

const team = choice('选择处理团队。', {
  billing: '付款与发票',
  support: '技术支持',
  review: '需要人工审核',
});

TypeSafe 原生 Choice 答案必须包含 type、choice、原始 probabilities 分布与上游的 confidence。返回选项须为已定义的键之一，分布必须包含且仅包含这些键。选项数量为 1–255。上方请求的完整示意答案如下：

{
  "type": "choice",
  "choice": "review",
  "probabilities": { "billing": 0.1, "support": 0.2, "review": 0.7 },
  "confidence": 0.5
}

置信度不一定等于所选项概率，两者都不是通用动作阈值。原生必需统计缺失时会返回无效响应错误，不会编造分布。OpenRouter 适配结果与旧缓存有独立兼容规则，应检查响应模式。

Score：评分

import { score } from '@system-one-ai/sdk';

const quality = score('根据标准评估答案。', [
  '未回答问题',
  '部分回答问题',
  '完整回答问题',
]);

评分档位从 0 编号到 档位数量 - 1，必须提供 2–10 个有序档位。TypeSafe 原生 Score 答案必须包含 type、score、probabilities、confidence 和 legend，其中分布和 legend 的键为档位下标。分数可以是小数，对应加权结果：

score = sum(档位下标 * 该档位的概率)

例如，三档标准上的示意分布 [0.1, 0.3, 0.6] 得到加权评分 1.5。这只是算术示例，不是真实模型响应记录。调整评分标准的顺序会改变含义，也会改变用于计费和幂等判断的规范化请求。

{
  "type": "score",
  "score": 1.5,
  "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
  "confidence": 0.3,
  "legend": { "0": "未回答问题", "1": "部分回答问题", "2": "完整回答问题" }
}

Boolean / Noul：布尔概率

import { booleanQuestion } from '@system-one-ai/sdk';

const duplicate = booleanQuestion('消息是否反映了重复扣款？', {
  true: '同一订单被扣款多次',
  false: '没有反映重复扣款',
});

数值代表 P(true)，范围为 0 到 1，不会自动转换为 true 或 false。应用应针对自身任务决定阈值、人工复核规则或暂不执行动作的条件。

校验与应用策略

网关检查原生答案类型、选项键、必需统计、概率范围及总和、评分范围及加权结果。它使用声明的舍入精度或 Jev 两位小数显示容差，不插入 rounding、不改变数值。有效 TypeSafe JSON 与扩展字段原样返回，缺失的用量、token 计数、warnings 和 rounding 不会被补齐；null token 计数在账本中保持未知。无效响应返回 502 并触发预扣退款，不会转换成默认动作；即时退款失败会单独报告。

项目 SDK 0.3.0 会转换自己的结果，并可能添加默认 rounding/warnings，其结果不等于网关原始正文。平台扣费与请求 ID 始终从响应头读取，即使上游正文含有 billing 或 request_id 同名字段也是如此。

概率描述预测结果，不代表某个动作已经获得授权、一定安全或一定正确。你可以定义 review 或 think 选项，再由应用实现审核或独立的规划调用。System One 不会代替应用执行这些工作流。

API 参考中的限制是本平台边界，不是对每个 Jev 版本或上游能力的承诺。