# web.rest.aiSystemOne 库模块帮助文档

<details>  <summary>接口说明</summary>  <p>

## AI 结构化决策客户端（System One 协议）

`web.rest.aiSystemOne` 用于实现 Jev System One（`/systemone`）兼容协议（包括 TypeSafe Jev、Modelink、OpenRouter Decisions 等兼容服务端），不限定模型厂商；
目标模型与服务必须支持该协议。

> System One（也常写作 System 1）是诺贝尔经济学奖得主丹尼尔·卡尼曼在《思考，快与慢》中提出的著名概念，代表人类的“快思考”机制——即直觉、快速、几乎不费力气的反应模式。

返回值保持协议原生的 `model / answers / usage` 结构，不转换成文本。

`questions` 的各项可直接写为 `{type="noul";instructions="是否紧急？"}`，
也可简写为 `["noul","是否紧急？"]` 或 `[type,instructions,criteria]`。
`evaluate` 调用前统一将数组简写转换为协议对象，不改变调用者的数据；原生对象保留所有字段。
声明问题不会发送请求，只有调用 `evaluate` 才会请求模型。

兼容 System One 协议的决策服务使用相同的 `state / questions / model` 请求结构；
本库保留完整请求和原生问题对象的扩展字段，也会透传 `assets` 等协议扩展，不硬编码上下文长度或判定阈值。

Jev 1.14 的图像与 `box` 能力属于 TypeSafe 的扩展，
调用 imageAsset 方法将自动添加 HTTP 头 `TypeSafe-Danger-Zone-Images: true`。
需遵守服务端的图像格式、尺寸和请求大小限制。

更换模型后应重新评估业务样本与判定阈值。

</p></details>

[» 使用指南](https://www.aardio.com/zh-cn/docs/library/web/rest/aiSystemOne/index.html) [» 范例](https://www.aardio.com/zh-cn/docs/examples/AI/aiSystemOne.html)

## web.rest 成员列表 <a id="web.rest" href="#web.rest">&#x23;</a>

### web.rest.aiSystemOne <a id="web.rest.aiSystemOne" href="#web.rest.aiSystemOne">&#x23;</a>
AI 结构化决策客户端。  
实现 Jev System One（/systemone）兼容协议。  
输入 state 与以问题 ID 为键的 questions，返回结构化 answers；不绑定单一平台或模型厂商。

### web.rest.aiSystemOne() <a id="web.rest.aiSystemOne" href="#web.rest.aiSystemOne">&#x23;</a>
[返回对象:webRestAiSystemOneObject](#webRestAiSystemOneObject)

### web.rest.aiSystemOne(cfg) <a id="web.rest.aiSystemOne" href="#web.rest.aiSystemOne">&#x23;</a>
创建 System One 决策客户端。  
配置表可指定 url,key,model,extraHeaders,extraParameters 等字段。  
url 指定提供 `/systemone` 接口的服务根地址或基址（无路径时默认补充 `/v1`）。

## webRestAiSystemOneObject 成员列表 <a id="webRestAiSystemOneObject" href="#webRestAiSystemOneObject">&#x23;</a>

### webRestAiSystemOneObject._http <a id="webRestAiSystemOneObject._http" href="#webRestAiSystemOneObject._http">&#x23;</a>
inet.http客户端，用于执行 http 请求  

[返回对象:inetHttpObject](https://www.aardio.com/zh-cn/docs/library-reference/inet/http.html#inetHttpObject)

### webRestAiSystemOneObject.answer(response,questionId) <a id="webRestAiSystemOneObject.answer" href="#webRestAiSystemOneObject.answer">&#x23;</a>
从响应中安全读取指定问题的答案。

### webRestAiSystemOneObject.buildPayload(request) <a id="webRestAiSystemOneObject.buildPayload" href="#webRestAiSystemOneObject.buildPayload">&#x23;</a>
完整请求表补充默认模型并转换问题数组简写；保留其他协议字段，包括 `assets`。

### webRestAiSystemOneObject.buildPayload(state,questions) <a id="webRestAiSystemOneObject.buildPayload" href="#webRestAiSystemOneObject.buildPayload">&#x23;</a>
构造请求体但不发送请求。  
将 questions 中的数组简写转换为协议对象，不改变调用者数据；简写格式错误返回 null,err。

### webRestAiSystemOneObject.close() <a id="webRestAiSystemOneObject.close" href="#webRestAiSystemOneObject.close">&#x23;</a>
关闭对象释放资源

### webRestAiSystemOneObject.config <a id="webRestAiSystemOneObject.config" href="#webRestAiSystemOneObject.config">&#x23;</a>
API 配置表。  
由构造参数浅拷贝生成；model、url 记录客户端选用的模型与归一化后的接口基址。

### webRestAiSystemOneObject.defaultHeaders <a id="webRestAiSystemOneObject.defaultHeaders" href="#webRestAiSystemOneObject.defaultHeaders">&#x23;</a>
替换所有请求默认添加的HTTP头  
请求结束时不会清空此属性  
该值可以是一个字符串,也可以是键值对组成的table对象

### webRestAiSystemOneObject.evaluate(request) <a id="webRestAiSystemOneObject.evaluate" href="#webRestAiSystemOneObject.evaluate">&#x23;</a>
传入完整请求表调用 `/systemone` 决策接口；`assets` 等扩展字段会原样透传。

### webRestAiSystemOneObject.evaluate(state,questions) <a id="webRestAiSystemOneObject.evaluate" href="#webRestAiSystemOneObject.evaluate">&#x23;</a>
调用 `/systemone` 决策接口。  
questions 为问题 ID 到问题声明的表，各项支持原生对象或 [type,instructions[,criteria]] 数组简写，可混用。成功返回原始响应，失败返回 null,err[,errCode]。

### webRestAiSystemOneObject.extraHeaders <a id="webRestAiSystemOneObject.extraHeaders" href="#webRestAiSystemOneObject.extraHeaders">&#x23;</a>
设置每次请求都附加的 HTTP 请求头，可在构造参数表中指定初始值。  
此属性值可以是 web.joinHeaders 函数支持的字符串、表（数组、键值对）。

### webRestAiSystemOneObject.extraParameters <a id="webRestAiSystemOneObject.extraParameters" href="#webRestAiSystemOneObject.extraParameters">&#x23;</a>
指定附加到所有请求参数中的默认参数，值为表。  
由底层 REST 客户端补充；模型应使用 model 配置，问题应放在 evaluate 的 questions 中。

### webRestAiSystemOneObject.extraUrlParameters <a id="webRestAiSystemOneObject.extraUrlParameters" href="#webRestAiSystemOneObject.extraUrlParameters">&#x23;</a>
指定附加到所有请求 URL 的默认参数。  
该值可以是一个表或字符串。  
表参数使用 inet.url.stringifyParameters 转换为字符串。  
表中的值如果是函数则每次请求都调用该函数取值

### webRestAiSystemOneObject.get(网址,参数表) <a id="webRestAiSystemOneObject.get" href="#webRestAiSystemOneObject.get">&#x23;</a>
使用该GET方法提交请求,获取资源  
请求参数将会自动转换为URL附加参数,  
请求参数可以指定表或字符串,如果是表请求前会转换为字符串  
成功返回数据,失败返回空值,错误信息,错误代码

### webRestAiSystemOneObject.imageAsset(source,format) <a id="webRestAiSystemOneObject.imageAsset" href="#webRestAiSystemOneObject.imageAsset">&#x23;</a>
将本地 PNG/JPEG 文件或二进制 string/buffer 转换为 `{type="image";format;data_base64}` 资产对象；文件路径会根据扩展名推断格式，返回 null,err 表示失败。

### webRestAiSystemOneObject.lastRequestUrl <a id="webRestAiSystemOneObject.lastRequestUrl" href="#webRestAiSystemOneObject.lastRequestUrl">&#x23;</a>
获取最后一次请求的 URL。  
允许在 beforeRequestHeaders 事件中修改此属性以改变请求地址。

### webRestAiSystemOneObject.lastResponse() <a id="webRestAiSystemOneObject.lastResponse" href="#webRestAiSystemOneObject.lastResponse">&#x23;</a>
获取最后一次服务器返回的数据，流式调用时此函数返回值无意义。  
如果控制台已打开或在开发环境中导入 console 库则在控制台输出数据  
下载文件时该值为空

### webRestAiSystemOneObject.lastResponseError() <a id="webRestAiSystemOneObject.lastResponseError" href="#webRestAiSystemOneObject.lastResponseError">&#x23;</a>
返回服务器最后一次返回的错误响应，并转换为错误对象。  
与调用 API 时转换响应数据一样，支持相同的服务器响应格式 。  
如果错误来自本地（lastStatusCode 属性为 null）则此函数返回 null 。  
如果最后一次发生请求成功，则此函数返回 null 。  

如果在参数 @1 中指定返回字段，且错误对象包含该字段则使用直接下标获取并返回字段值。  
获取字段失败返回 null 而非抛出异常

### webRestAiSystemOneObject.lastResponseObject() <a id="webRestAiSystemOneObject.lastResponseObject" href="#webRestAiSystemOneObject.lastResponseObject">&#x23;</a>
获取最后一次服务器返回的 JSON 对象。  
请求失败或下载文件时为空。

### webRestAiSystemOneObject.lastResponseString() <a id="webRestAiSystemOneObject.lastResponseString" href="#webRestAiSystemOneObject.lastResponseString">&#x23;</a>
获取最后一次服务器返回的原始数据，流式调用时此函数返回值无意义。  
请求失败，或者下载文件时此属性值为空

### webRestAiSystemOneObject.lastStatusCode <a id="webRestAiSystemOneObject.lastStatusCode" href="#webRestAiSystemOneObject.lastStatusCode">&#x23;</a>
获取最近一次请求返回的HTTP状态码  
100 ~ 101 为信息提示  
200 ~ 206 表示请求成功  
300 ~ 305 表示重定向  
400 ~ 415 表示客户端请求出错  
500 ~ 505 表示服务端错误

### webRestAiSystemOneObject.lastStatusMessage() <a id="webRestAiSystemOneObject.lastStatusMessage" href="#webRestAiSystemOneObject.lastStatusMessage">&#x23;</a>
获取最近返回的HTTP状态码文本描述  
第二个返回值为状态码

### webRestAiSystemOneObject.noulValue(response,questionId) <a id="webRestAiSystemOneObject.noulValue" href="#webRestAiSystemOneObject.noulValue">&#x23;</a>
读取 Noul 答案的 yes 概率（0 到 1）。

### webRestAiSystemOneObject.ok() <a id="webRestAiSystemOneObject.ok" href="#webRestAiSystemOneObject.ok">&#x23;</a>
最后一次请求是否成功  
服务器应答并且状态码为2XX该函数返回真

### webRestAiSystemOneObject.post(网址,参数表) <a id="webRestAiSystemOneObject.post" href="#webRestAiSystemOneObject.post">&#x23;</a>
使用该POST方法提交请求,新增或修改资源  
请求参数可以指定表或字符串,如果是表请求前会转换为字符串  
成功返回数据,失败返回空值,错误信息,错误代码

### webRestAiSystemOneObject.referer <a id="webRestAiSystemOneObject.referer" href="#webRestAiSystemOneObject.referer">&#x23;</a>
引用页地址。  
如果此属性指定了一个值，则每次请求都会使用该引用页。  
如果不指定，每次请求都会自动设置上次请求的网址为引用页。  
这个属性不像 inet.http 对象的 referer 属性那样每次请求结束都会清空。

### webRestAiSystemOneObject.setHeaders <a id="webRestAiSystemOneObject.setHeaders" href="#webRestAiSystemOneObject.setHeaders">&#x23;</a>
设置所有请求默认添加的HTTP头

### webRestAiSystemOneObject.setHeaders(headers) <a id="webRestAiSystemOneObject.setHeaders" href="#webRestAiSystemOneObject.setHeaders">&#x23;</a>
参数 @headers 必须指定一个表,  
用该表中的键值对更新 defaultHeaders 属性中的键值  
如果 defaultHeaders 的原属性值不是一个表,则先清空该属性

### webRestAiSystemOneObject.setTimeouts(连接超时,请求超时,接收超时) <a id="webRestAiSystemOneObject.setTimeouts" href="#webRestAiSystemOneObject.setTimeouts">&#x23;</a>
设置 HTTP 超时，单位为毫秒。  
本库 evaluate 使用非流式 JSON 请求。
