# Automation 使用参考

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

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

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

## 推理等级

新建会话模式下，进入「编辑 → Agent 执行配置」，选择具体的提供商，在合并的模型下拉菜单中选择「模型」或「推理等级」。界面复用 Host 原生 Menu，不会改动聊天会话的模型设置。选项来自该模型的 Host 元数据，不固定为低／中／高。「默认（不覆盖）」沿用正常的 Agent／模型默认行为，不代表关闭推理；旧任务行为不变。在编辑器切换模型会将该项重置为默认。

使用 Agent 工具时，先向 `automation_options` 传入候选 `provider` 和 `model`（或已有任务 `id`）查询，再设置 `reasoning_effort`。显式等级要求具体的提供商／模型组合，保存和运行前由 Host 校验。创建时省略使用默认，更新时省略保留原值，更新传 `null` 清除覆盖。HTTP 更新字段为 `execution.reasoningEffort`。通过工具/API 更换模型时，也应清除或替换不兼容的等级。固定会话始终沿用会话自身的推理配置；任务级覆盖仅对新建会话生效。

## 手动删除运行记录

在「运行历史」展开一条记录，点击「删除记录」并确认。仅移除该条记录及其摘要、错误和投递状态，不删除对应会话、不撤回消息，也不改变任务计划、连续失败计数或暂停状态。删除后不可恢复。

排队中、运行中或消息仍在发送的记录不可删除；同一任务正在执行时，仍可删除其他已结束记录。删除最新记录后，概览显示剩余记录中的最新结果；全部删除后显示「暂无运行记录」。

## 状态保存

运行历史默认不限制保留条数；只有显式配置插件的 `maxRunHistory` 时才按该上限保留。此前已被裁剪的记录不会因修改设置而恢复。

状态先写入同目录临时文件并同步，再通过原子重命名替换旧文件。Windows 跳过目录 fsync，其他平台在重命名后尝试目录同步。如果这一步失败，Host 会记录 `AUTOMATION_DIRECTORY_SYNC_FAILED` 告警：操作已经提交，内存与新文件保持一致，但不能保证系统崩溃或断电后仍保留该次更新。此时应排查文件系统告警，而不是重试操作。重命名前的失败仍会拒绝操作，保留原有状态。

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

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

创建与更新支持 `agent_preset`、`provider` / `model`、`reasoning_effort` 和有序 `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`。