# 工作流

工作流用于在设备状态、事件、命令响应或校验错误到达后自动执行处理动作。它把设备上报和后续处理连成一条自动链路：设备状态或事件变化后，系统可以立即记录、控制、通知或交给 Agent 判断。创建时不需要手工编排节点和步骤，只要说明触发条件、处理目标和是否需要 Agent 判断，Agent 会生成可查看、可启停、可复查的工作流。

## 创建工作流

本教程使用内置 **车载 / Smart Cockpit Range** 示例。事件名和字段均来自该示例的 DeviceSpec。
完成后，当模拟设备上报低电量事件时，工作流会记录事件数据，并由 Agent 生成一条简短处理建议。

1. 创建设备智能体时，选择 **示例** > **车载** > **Smart Cockpit Range**。
2. 创建完成后，启动一台浏览器模拟设备，并选中它。
3. 在对话区输入：

```text
创建名为 battery-low-alert 的工作流：当当前设备上报 battery_low_warning 事件且 payload.soc 小于 20 时，记录一条 device_event。detail 包含 soc 和 estimated_range_km。随后让 Agent 生成一条简短处理建议。
```

![通过对话创建工作流](../images/docs/usage/workflows/zh/01-workflow-authoring.png)

4. 打开左侧 **工作流**，确认 `battery-low-alert` 已启用。

![查看工作流图](../images/docs/usage/workflows/zh/02-workflow-graph.png)

5. 回到模拟设备状态面板，点击 **模拟上报**，选择 `battery_low_warning`，Payload 填：

```json
{
  "soc": 15,
  "estimated_range_km": 42
}
```

这里的 Payload 是本次事件上报的数据，字段必须和 DeviceSpec 中的事件定义一致。

6. 点击 **上报事件**。成功后可以在 **最近上报事件**、[日志](../operate-reference/logs.md) 和工作流通知中看到结果。

![工作流处理通知](../images/docs/usage/workflows/zh/03-workflow-notification.png)

## 选择合适的自动化方式

| 需求 | 用法 |
| --- | --- |
| 到点执行 | [定时任务](./scheduled-tasks.md) |
| 设备上报后自动处理 | 工作流 |
| 需要多路径判断 | 分支工作流 |
| 只是扩展对话能力 | [技能与工具](./tools.md) |

## 选择处理方式

工作流既可以执行固定规则，也可以在触发后让 Agent 分析上下文。

| 场景 | 推荐方式 |
| --- | --- |
| 条件明确、结果必须稳定，例如温度高于阈值就关闭加热或切换安全模式 | 固定条件 + 固定动作 |
| 需要综合多条状态判断，例如车辆无人、车门已锁但空调仍开启 | 让 Agent 分析后再执行处理动作 |

## 描述工作流需求

用自然语言说明触发条件和处理目标即可，不需要手工编排流程节点。创建工作流时，建议包含以下信息：

- 触发来源：`device_event`、`telemetry`、`status`、`command_response` 或 `validation_error`。
- 触发条件：事件名、事件类型、设备 ID、字段阈值。
- 处理动作：`log_event`、`send_command`、`mqtt_publish`，或让 Agent 总结。
- 工作流 ID：使用稳定英文，例如 `battery-low-alert`。

修改已有工作流时，说明工作流 ID 和需要调整的内容。

## 管理工作流

在 **工作流** 页面可以刷新、启用、停用、删除和全屏查看工作流。创建和完整更新仍建议在对话区完成。

## API

HTTP API 只负责查询、启停和删除；创建由对话里的工作流工具完成。请求示例见 [API 参考](../operate-reference/api.md#工作流)。

## 故障排查

- 事件名必须在 DeviceSpec 的 `events` 中存在。
- 条件字段要写成事件 payload 路径，例如 `payload.soc`。
- 工作流必须处于启用状态。
- 模拟上报只对浏览器模拟设备可用。