# Automation 使用参考

[返回介绍](../README.zh.md) · [English](reference.md)

## 运行前，了解这几个边界

- 运行时需保持 DSH 在线；重启后，每个符合条件的任务只补跑最近错过的一次，暂停期间的周期会被跳过。
- 同一插件实例一次执行一个自动化任务。默认运行上限为 1 小时，可通过 `maxRunDurationMs` 调整。
- 暂停影响未来调度，已开始的运行会继续；停止当前运行、立即运行或「恢复并运行」都不改变原计划。
- 要求交互批准的权限不会被自动批准，无人值守任务可能等待到超时。
- 固定会话沿用其上下文及 Agent／模型配置，应用任务权限，不重新加载技能。创建后更换绑定需在界面中操作；目标忙碌或不可用时直接失败，不另建替代会话。
- 失败运行可手动重试；可选自动暂停将失败和超时计入连续次数，成功后清零。意外重启时未完成记录的运行标为「结果未知」，不会自动重跑。
- 消息投递单独记录状态；发送失败不重跑任务、不自动重发，发送中重启标为结果未知。手动取消或 Host 关闭导致的中断不触发报告；平台接受消息不等于终端已收到。

## Agent 工具与调度参数参考

| 工具                 | 用途                                           |
| -------------------- | ---------------------------------------------- |
| `automation_options` | 查询 Host 当前的 Agent、模型、技能和权限选项。 |
| `automation_create`  | 用户确认完整配置后创建任务。                   |
| `automation_update`  | 更新任务及执行配置；权限变更需要确认。         |
| `automation_list`    | 查看任务和运行状态。                           |
| `automation_run`     | 立即运行一次，不改变原计划。                   |
| `automation_pause`   | 暂停未来调度。                                 |
| `automation_resume`  | 恢复任务，可同时立即运行一次。                 |
| `automation_delete`  | 删除任务及未来调度，保留已有会话。             |

创建与更新支持 `agent_preset`、`provider` / `model` 和有序 `skills`；更新可清除执行覆盖或替换技能列表。创建时还可传入 `execution_mode: pinned-session`、`target_session_id` 和经用户确认的 `session_target_confirmed: true`。创建后更换目标会话，以及配置消息投递，需在界面中操作。

| 类型 | 参数        | 格式 / 示例                                                             |
| ---- | ----------- | ----------------------------------------------------------------------- |
| 单次 | `once_at`   | RFC 3339 UTC 时间，例如 `2027-01-04T01:00:00.000Z`。                    |
| 周期 | `rrule`     | 单行 RFC 5545 规则，不含 `DTSTART`，例如 `FREQ=WEEKLY;BYDAY=MO,WE,FR`。 |
| 周期 | `time_zone` | IANA 时区，例如 `Asia/Shanghai`。                                       |
| 周期 | `start_at`  | 本地时间，格式 `YYYY-MM-DDTHH:mm:ss`。                                  |

周期任务需同时提供 `rrule`、`time_zone`、`start_at`。