# web.rest.aiSystemOne

`web.rest.aiSystemOne` 是纯 aardio 的 AI 结构化决策客户端，实现 `Jev System One`（`POST .../systemone`）兼容协议。

## 定位与安装位置

- `web.rest.aiChat` 面向生成式对话；`web.rest.aiSystemOne` 面向基于 `state` 与 `questions` 映射表的结构化判定（`noul`）、分类（`choice`）和评分（`score`）。
- 支持所有兼容 Jev System One（`/systemone`）协议的平台与服务端（如 TypeSafe Jev、Modelink、OpenRouter 等），不限定模型厂商。
- 公共库：`~/lib/web/rest/aiSystemOne.aardio`。

## 快速开始

```aardio
import web.rest.aiSystemOne;

var client = web.rest.aiSystemOne({
    url = "https://api.modelink.ai"; // 或 "https://openrouter.ai/api/v1" 等兼容接口基址
    key = "你的 API Key";
    model = "typesafe/jev-latest"; // 当前指向 Jev 1.14；中文仍应先用业务样本验收
});

var questions = {
    department = ["choice", "这条工单应由哪个团队处理？", {
        ["财务"] = "付款、发票和退款问题";
        ["技术"] = "软件故障、服务中断和系统集成问题";
        ["销售"] = "价格咨询、套餐升级和购买意向";
        ["其他"] = "不属于以上类别或信息不足";
    }];
    urgent = ["noul", "这条工单是否需要立即处理？"];
    severity = ["score", "当前问题对业务造成的影响有多严重？", [
        "轻微影响，主要功能正常",
        "部分功能受影响，业务仍可继续",
        "核心业务完全中断，无法继续工作"
    ]];
};

var result,err,errCode = client.evaluate({
    state = {
        message = "生产系统从今天早上起完全无法登录，所有员工都无法开展工作，请立即修复！";
    };
    questions = questions;
});

if(!result){
    print("请求失败：",err,errCode);
    return;
}

print("实际模型：",result.model);
print("负责团队：",result.answers.department.choice);
print("需要立即处理的概率：",result.answers.urgent.noul);
print("业务影响评分（0～2）：",result.answers.severity.score);
print("输入、输出用量：",result.usage.input_tokens,result.usage.output_tokens);
```

后面的代码片段沿用这里的 `client`。协议字段、类型名与程序标识符保留原样。

## 问题声明

`questions` 是按问题 ID 命名的表，每项可使用以下两种数据形式，并允许混用：

- **数组简写**：`[type, instructions, criteria]`。`noul` 通常只需前两项；`choice` 的第 3 项为选项到说明的映射表，`score` 的第 3 项为从低到高的等级数组。
- **原生对象**：`{type="noul";instructions="是否紧急？"}`。需要自解释字段名或额外协议字段时优先使用。

例如，同一请求中可以混用：

```aardio
var questions = {
    urgent = ["noul", "这条工单是否需要立即处理？"];
    department = {
        type = "choice";
        instructions = "这条工单应由哪个团队处理？";
        criteria = {
            ["财务"] = "付款、发票和退款问题";
            ["技术"] = "软件故障、服务中断和系统集成问题";
            ["销售"] = "价格咨询、套餐升级和购买意向";
            ["其他"] = "不属于以上类别或信息不足";
        };
    };
    outage = {type="noul";instructions="当前核心业务是否完全中断？";criteria={
        ["true"] = "无法继续开展核心业务";
        ["false"] = "核心业务仍然可以继续";
    }};
};
```

**声明只是数据，不会请求模型。** `evaluate` 调用 `buildPayload` 时，才将问题的纯数组 `[]` 转换为接口要求的对象。不要把数组简写直接传给底层 `post`。

仅转换 `questions` 的直接成员；不转换 `state` 中的数组、`choice` 选项说明或 `score` 等级数组。不修改调用者的声明，原生问题对象中的扩展字段会保留。数组简写必须有 2～3 项且前两项为字符串，否则 `buildPayload` / `evaluate` 返回 `null,err`，不会发送请求；其他协议约束由服务端检查。

`noul.criteria` 可省略；指定时使用字符串键 `"true"` 与 `"false"`，不要改为中文键或布尔键。它们的说明可以是中文。需要结构化 `instructions` 或服务支持的扩展字段时，使用原生问题对象；数组简写仍要求前两项为字符串。

## 两种调用方式

### `(state, questions)`

```aardio
var result = client.evaluate(
    "同一订单扣了两次款，请退回重复扣款。",
    {
        refund = ["noul", "客户是否要求退回款项？"];
        team = ["choice", "这条工单应由哪个团队处理？", {
            ["财务"] = "付款和退款问题";
            ["客服"] = "一般使用咨询或其他问题";
        }];
    }
);
```

### 完整请求表

```aardio
var result = client.evaluate({
    state = "这笔付款是正常消费，不需要退款，只想补开发票。";
    questions = {
        refund = {type="noul";instructions="客户是否要求退回款项？"};
    };
    session_id = "中文工单演示";
});
```

完整请求表保留 `state` 和其他扩展字段（如单次指定 `model`）。`questions` 同样支持原生对象和数组简写，发送前统一为对象形式。

## 配置

```aardio
var client = web.rest.aiSystemOne({
    url = "https://api.modelink.ai";
    key = "你的 API Key";
    model = "typesafe/jev-latest";
    extraHeaders = {
        ["HTTP-Referer"] = "https://example.com";
    };
});
```

- `url` 指定接口服务根地址或基址（不需要包含 `/systemone` 后缀；若传入无路径的域名如 `https://api.modelink.ai`，会自动补充 `/v1`）。
- 支持：`extraHeaders`、`extraParameters`、`extraUrlParameters`、`proxy`、`proxyBypass`、`httpFlags` 等 `web.rest` 配置。

## 答案读取

客户端不把决策答案转换成文本，也不按厂商重新包装，返回值保持 System One 协议原始结构：

- `result.answers[id].type`
- Noul：`result.answers[id].noul`，回答“是”的概率，范围为 0 到 1；`0` 是合法结果，接近 `0.5` 表示不确定，不是“中等严重”。
- Choice：`choice` 是选中的选项键，可直接是中文；`probabilities` 是各选项概率，`confidence` 描述分布集中程度，不代表保证正确。
- Score：n 个等级从 **0 到 n-1** 编号；`score` 是概率加权的位置，可能为小数，不是统一的 0～1 概率，也不是 aardio 数组下标。
- Box（Jev 1.14 扩展）：`box` 包含 `top`、`bottom`、`left`、`right` 四个 0～1 的归一化边界；这是图像实验能力，不能假定所有兼容服务都支持。
- `legend` 将 `"0"`、`"1"` 等字符串键映射回等级说明；`probabilities` 同样按字符串键读取。不能用小数 `score` 直接索引数组。
- 协议规范中 `probabilities`、`confidence`、`legend` 为可选字段，跨平台或跨模型使用时应先检查它们是否存在，不能因为某次响应包含这些字段就假定永远存在。
- `result.model` 为实际服务该请求的模型版本；`result.provider` 是可选的服务商标识。
- `result.usage.input_tokens` 与 `result.usage.output_tokens` 为用量，`result.usage.cost` 为可选的费用字段。不同模型的分词器及用量统计可能不同，不按固定输出 token 数判断协议兼容性。

也可以使用：

```aardio
var answer = client.answer(result,"department");
var probability = client.noulValue(result,"urgent");
```

读取答案时，缺失问题或类型不符应进入错误处理/人工复核，不要当作“否”或安全放行。特别注意 aardio 中 `0` 是假值，判断数值是否缺失应使用 `===null`，不要使用 `if(!probability)`。

## Jev 1.14 图像与 Box 扩展（实验能力）

TypeSafe Jev 1.14 支持图像输入，并提供 `box` 问题类型。它们是 TypeSafe 的实验性扩展，不属于所有 System One 服务都支持的通用字段；客户端会原样透传 `assets` 与 `box` 问题。

下面的 `imageAsset` 使用 JSON + Base64 方式构造资产；图像引用必须同时出现在 `state`、问题的 `instructions` 或 `criteria` 中，且每个资产都必须被引用：

```aardio
client.setHeaders({["TypeSafe-Danger-Zone-Images"] = "true"});

var photo,photoErr = client.imageAsset("/res/photo.jpg");
if(!photo) return null,photoErr;

var result,err = client.evaluate({
    model = "typesafe/jev-latest";
    state = {photo = "photo-1"};
    assets = {["photo-1"] = photo};
    questions = {
        visible = {type="noul";instructions="图片 `photo` 中是否有一辆汽车？"};
        location = {type="box";instructions="定位图片 `photo` 中的汽车。"};
    };
});
```

`imageAsset` 也接受二进制 `string` 或 `buffer`，但必须另行指定 `"png"`、`"jpg"` 或 `"jpeg"` 格式。TypeSafe 当前图像接口只接受 PNG/JPEG 静态图像，并有图像尺寸、文件大小、请求大小和实验性准确率限制；正式使用前应按目标模型和中文/图像业务样本进行验收。

`imageAsset` 会自动添加 HTTP 头 `TypeSafe-Danger-Zone-Images: true`（使用图像或 `box` 时需要指定）。若服务端不支持该扩展，不要发送 `assets` 或 `box`。

## 协议兼容与模型切换

- 兼容 Jev System One 的服务使用相同的 `/systemone` 端点及 `model / state / questions` 请求结构，基础问题类型为 `noul / choice / score`；`box`、`assets` 等属于服务端扩展。在同一基础协议下切换模型或兼容平台不需要修改基础问题声明结构，但使用扩展能力前必须确认目标服务支持。
- 本库不硬编码模型白名单、问题数量上限、上下文长度或业务阈值。可以通过完整请求传入服务端支持的 `provider`、`session_id`、`trace`、`user` 等字段；原生问题对象与响应中的扩展字段也会保留。透传字段不等于所有服务端都支持，实际能力由目标模型和端点决定。
- `state` 可为字符串、对象或数组；只提供判断所需上下文。问题之间相互独立，同一请求中的问题不能读取彼此的答案；有依赖关系时应分成多次调用。
- 当前 `typesafe/jev-latest` 指向 `typesafe/jev-1.14.0`，中文和其他非英语输入通常应优先使用它，而不是旧的 `typesafe/jev-1.13`。但这只是两个版本中相对较新的选择，不代表中文能力已经达标：官方明确说明非英语（包括中文）整体仍弱于英语，不能把 1.14 的小幅多语言改进写成“中文已经可靠”。中文生产场景不应默认信任 Jev，必须先用自己的样本验收；需要结果可复现时可固定为 `typesafe/jev-1.14.0`。别名会移动，生产阈值应随模型版本重新验证。
- 本库不自动重试或切换模型。失败返回 `null,err[,errCode]`；数组简写错误属于本地错误，不产生新的 HTTP 请求，`lastStatusCode` 可能仍保留上次请求状态。不要将它误认为本次本地错误的 HTTP 状态。

## 参考

- [OpenRouter Decisions API 参考](https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-request)
- [OpenRouter 决策模型排行榜](https://openrouter.ai/rankings/decisions)
- [OpenRouter 通用决策模型使用说明](https://openrouter.ai/skills/openrouter-decisions)
