# Jev 决策模型

Jev 是 TypeSafe 提供的决策模型，根据状态、问题和预设选项返回选中的选项、置信度及各选项概率。Device Agent 将其用于告警分类、工作流分流和简单设备快捷指令，无需为每次选择运行完整的智能体对话；需要生成文字或多步处理时，使用设备智能体。

## 配置 Jev

本地部署中：

1. 打开 **设置 → 模型 → 决策模型**。
2. 打开 **启用决策模型**。
3. 确认 **提供商** 为 **TypeSafe**，**模型** 默认使用 `jev-latest`（Jev）。
4. 填写 **接口密钥**，按需调整 **超时（ms）**（默认 `5000`，最小 `1000`）。
5. 保存。修改后对下一次决策立即生效，不需要重启。

![Jev 决策模型配置](../images/docs/usage/jev/zh/01-decision-model.png)

也可以在本地 `.env` 中设置 `TYPESAFE_API_KEY`。平台控制台中的模型设置只读，由部署管理员维护，密钥通过 Worker Secret 提供。变量说明见[环境变量](../operate-reference/configuration/environment-variables.md)。

## 决策方式

每次决策包含三部分：

| 输入 | 说明 |
| --- | --- |
| 状态 | 判断依据，例如触发工作流的设备事件。最大 32 KiB。 |
| 问题 | 要回答的问题，例如「当前电量该怎么处理？」 |
| 选项 | 2 到 20 个自定义选项，每个选项包含 ID 和 **何时选择此选项** 的说明。 |

系统自动增加 `insufficient_evidence`（证据不足）选项，用于在数据缺失、矛盾或无法支持其他选项时弃权。状态用于提供判断依据，问题和选项说明用于定义判断标准。

## 适用场景

适合交给 Jev 的判断需要结合描述或多条状态，可选结果少且固定，并允许证据不足时弃权。可以在工作流中按以下方式使用：

| 场景 | 让 Jev 选择 | 后续处理 |
| --- | --- | --- |
| 告警分级与降噪 | 紧急 / 维护 / 误报 / 证据不足 | 分别连接通知、维护或结束节点 |
| 工作流命令前置判断 | 执行 / 先确认 / 拒绝 | 将允许执行的出口连接到设备命令，其他出口连接通知或人工处理 |
| 故障初步诊断 | 传感器故障 / 网络问题 / 供电问题 / 真实异常 | 选项可以来自设备手册或运维经验，结果直接对应处理手册 |
| 工作流分支 | 自定义的分支出口 | 用 [工作流决策节点](./workflows.md#决策节点) 直接实现 |
| 事件分派 | 交给哪个团队、哪条流程、是否唤醒 Agent | 连接对应通知、处理动作或 Agent 节点 |

以下情况不建议使用 Jev：

- 条件可以明确写成规则，例如温度高于 80 ℃ 就关闭加热。使用工作流的条件分支。
- 纯数值异常检测。使用阈值、滑动窗口或统计方法。
- 需要生成文字、总结或多步推理。交给 Agent 处理。

## 工作流决策节点

在工作流中添加 **决策** 节点，填写 **决策问题** 和若干 **选项**。每个选项就是节点的一个出口，另有一个固定的 `insufficient_evidence` 出口。触发事件会作为状态交给 Jev，工作流只沿选中的出口继续执行。

例如，低电量告警可以结合 `payload.soc` 和 `payload.estimated_range_km`，在 `urgent`、`maintain`、`ignore` 之间选择，分别连接紧急提醒、充电建议或结束节点；证据不足时连接通知或人工处理。字段、问题和选项配置见[工作流决策节点](./workflows.md#决策节点)。

![工作流决策问题与选项](../images/docs/usage/jev/zh/02-workflow-decision.png)

## Jev 快捷指令

本地部署中，在设备智能体工作区选中设备，点击输入框旁的 **打开 Jev 快捷指令**，在浮窗中输入明确的控制请求并发送。Jev 从当前设备模型的可用命令和参数中选择后直接下发，不经过智能体对话。例如，温控器支持设置目标温度时：

```text
将目标温度设为 26 度。
```

![Jev 快捷指令执行结果](../images/docs/usage/jev/zh/03-quick-command.png)

逐项核对浮窗中的命令、参数和执行结果，再在设备状态面板确认目标温度已更新。目标值更新不代表实际温度立即达到该值。

快捷指令目前有以下限制：

- 使用明确的目标值；「调亮一点」「调高 2 度」这类相对调整应在智能体对话中处理。
- 参数可从布尔值、枚举和数值候选中选择，不支持自由文本或复杂参数。数值优先取请求中的合法数字，否则只能从模型的枚举或有限范围中选择。
- 当前设备模型需要有 2 到 19 个可用命令。
- 一句话最多连续执行 5 个命令。
- 没有匹配命令时不执行；必填参数无法确定或某一步失败时停止后续步骤，此前已执行的命令不会撤销。

复杂或模糊的控制请求，直接在对话区交给 Agent 处理。

## 故障排查

- 决策步骤失败并提示未配置：确认已启用决策模型并配置接口密钥；平台部署由管理员检查 Worker Secret。
- 决策超时：适当调大 **超时（ms）**，或减少状态内容。
- 工作流总是走 `insufficient_evidence`：检查问题和选项说明是否与事件字段对应，必要时在触发事件中补充判断所需的数据。
- 在工作流执行历史中展开决策步骤，可以查看选中的选项、置信度和各选项概率。