# 定时任务

定时任务用于让设备智能体保存未来执行的对话指令；在对话里说清任务、时间和目标设备即可创建，读取状态或下发命令时需确保目标设备已通过 MQTT、SDK 或模拟器在线，并让任务描述保持完整。

## 创建任务

在设备智能体工作区选中目标设备，然后输入自然语言请求：

```text
1 分钟后把当前温控器的目标温度设为 24 度。
```

设备智能体会把请求保存为一次性、固定间隔或 `cron` 计划，并返回下一次运行时间。

| 任务类型 | 示例 |
| --- | --- |
| 延迟执行 | `1 分钟后把当前温控器的目标温度设为 24 度。` |
| 固定间隔 | `每 5 分钟检查一次当前温度，超过 30 度就把目标温度设为 24 度。` |
| 每日执行 | `每天早上 9 点把当前温控器切换到节能模式。` |

![定时任务对话](../images/docs/usage/scheduled-tasks/zh/01-scheduled-task.png)

## 查看执行结果

任务到期后，网关会以 `cron:<timerId>` 启动独立执行。测试时以 [日志](../operate-reference/logs.md) 中的 `Timer` 模块为准：

```text
[14:27:17] [INFO ] [Timer] Scheduled task 8362d16a-e712-4f4d-9d08-caaa6a88f7eb fired {"timerId":"8362d16a-e712-4f4d-9d08-caaa6a88f7eb","scheduleKind":"once","scheduleExpr":"1m","status":"fired"}
[14:27:21] [INFO ] [Timer] Scheduled task 8362d16a-e712-4f4d-9d08-caaa6a88f7eb completed {"timerId":"8362d16a-e712-4f4d-9d08-caaa6a88f7eb","scheduleKind":"once","scheduleExpr":"1m","status":"complete"}
```

执行失败时，同一个 `timerId` 会出现 `status:"error"`。Web 控制台打开时也会显示开始、完成或失败通知；点击通知里的 **查看日志** 会带着 `timerId` 跳到日志页并直接筛选相关记录。

如果原会话还能接收回复，执行结果可能回到原会话；如果不能，网关会忽略这次会话回复。无论回复是否进入会话，`Timer` 日志都会记录触发和终态。

## 查询和取消任务

可以继续在对话里管理定时任务：

```text
列出当前还在运行的定时任务。
```

```text
刚才创建的目标温度任务还剩多久执行？
```

```text
取消刚才创建的目标温度定时任务。
```

如果存在多个相似任务，先列出任务，再按任务 ID 或任务内容取消。取消后任务会被标记为已删除，不再触发。周期任务不再需要时应及时取消。

## 验证设备动作

定时任务只负责在指定时间唤起设备智能体。任务是否真正改变设备状态，还需要在设备状态、设备日志或 MQTT 消息中验证。设备控制动作仍然必须匹配设备规格中定义的命令。