配置定时任务
定时任务让平台按计划执行后台工作，例如触发Agent对话、调用Webhook、执行内部函数，以及发送通知汇总。
什么时候用
- 需要定期触发Agent处理日常任务时
- 需要定期调用外部Webhook同步数据时
- 需要在指定时间点执行一次性后台任务时
- 需要查看任务执行历史和失败原因时
- 需要暂停/恢复任务执行时
你需要准备
- （对于Agent触发任务）至少一个已配置好的智能体，详见创建并配置智能体
- （对于Webhook任务）外部服务地址和可选的请求头/体配置（JSON格式）
- （对于CRON调度）了解基本的CRON表达式（分 时 日 月 周）
操作步骤
第 1 步：进入定时任务
左侧菜单 -> 定时任务。
页面默认显示「我的任务」标签页，列出该下所有自定义任务。点击右上角「新建任务」按钮进入创建表单。
第 2 步：选择任务类型
在新建任务表单中，首先选择任务类型：
| 任务类型 | 说明 |
|---|---|
| 触发Agent对话 | 定时向指定Agent发送消息并执行对话 |
| 调用Webhook | 定时调用外部HTTP接口 |
| 执行内部函数 | 定时执行平台内部函数（需插件支持） |
根据选择的任务类型，表单会显示相应的配置项。
第 3 步：配置任务内容
3.1 触发Agent对话
填写：
- Agent ID：要触发的智能体ID
- 触发消息：发送给Agent的消息内容
3.2 调用Webhook
填写：
- 请求URL：外部服务地址（必填）
- 请求方法：GET/POST/PUT/DELETE
- 请求头（JSON）：可选，JSON格式
- 请求体（JSON）：可选，JSON格式
3.3 执行内部函数
填写：
- 函数名称：内部函数标识（必填）
- 函数参数（JSON）：函数参数配置
第 4 步：选择调度类型
平台支持三种调度方式：
| 调度类型 | 说明 | 配置项 |
|---|---|---|
| CRON表达式 | 按CRON规则周期性执行 | CRON表达式、时区 |
| 固定间隔 | 按固定秒数间隔重复执行 | 间隔秒数（最小60秒） |
| 一次性执行 | 在指定时间点执行一次 | 执行日期时间 |
4.1 CRON表达式
- 格式：
分 时 日 月 周 - 示例：
0 9 * * *表示每天早上9点执行 - 时区默认使用Asia/Shanghai，可自定义
4.2 固定间隔
- 最小间隔：60秒
- 最大间隔：86400 * 7秒（7天）
- 调度器每次执行后重新计算下一次时间
4.3 一次性执行
- 选择具体的日期和时间
- 执行后任务状态会变为「已完成」
第 5 步：配置重试与超时
（可选）配置任务执行的重试策略和超时时间：
- 超时秒数：任务执行的最大时间（默认300秒）
- 最大重试次数：任务失败后的重试次数（默认3次）
- 重试间隔秒数：两次重试之间的等待时间（默认60秒）
第 6 步：保存并启用
点击「保存」按钮创建任务，任务会自动启用并开始按调度规则计算下次执行时间。
第 7 步：查看执行历史
在任务列表中，点击某个任务的「执行历史」按钮，查看该任务的所有执行记录：
- 状态：等待中/执行中/成功/失败/超时/已取消
- 触发方式：定时触发/手动触发
- 开始/结束时间
- 执行耗时
- 结果/错误信息
第 8 步：手动触发、暂停/恢复、删除
在任务列表操作列：
- 立即执行：手动触发一次任务执行（仅运行中任务可用）
- 暂停/恢复：暂停任务调度或恢复已暂停的任务
- 删除：删除该任务（系统任务不可删除）
第 9 步：查看系统任务
切换到「系统任务」标签页，查看平台提供的系统任务（如通知汇总）。管理员可以：
- 启用/禁用系统任务（受系统设置约束）
- 查看执行历史
怎么验证成功了
- 在任务列表中看到新创建的任务，状态为「运行中」
- 下次执行时间正确显示
- 手动触发一次任务，在执行历史中看到成功记录
- 对于CRON/间隔任务，能看到下次执行时间按时更新
常见问题
CRON表达式不合法
平台使用标准5段CRON（不支持秒）。请检查：
- 分钟：0-59
- 小时：0-23
- 日期：1-31
- 月份：1-12
- 星期：0-6（0=周日）
任务不执行
检查：
- 任务状态是否为「运行中」
- 下次执行时间是否已到
- 时区配置是否正确
- 任务调度是否正常运行
任务执行失败
查看「执行历史」中的错误信息。常见原因：
- Agent ID无效或Agent已删除
- Webhook地址不可达
- 请求头/体JSON格式错误
- 内部函数执行异常
暂停后任务仍在执行
暂停仅停止调度器触发新的执行，已在运行中的任务会继续执行直到完成或超时。
深入
核心概念
租户任务与系统任务
| 类型 | 说明 |
|---|---|
| 租户自定义任务 | 由租户创建、更新、暂停、恢复、删除、手动触发 |
| 系统任务 | 由平台提供，租户可查看、配置本租户启停、查看本租户执行历史 |
任务类型
| 任务类型 | 说明 |
|---|---|
| agent_trigger | 触发Agent对话 |
| webhook | 调用外部Webhook |
| internal | 执行内部函数 |
| plugin_task | 插件定时任务模板 |
| notification_digest | 通知汇总推送 |
调度类型
| 调度类型 | 说明 |
|---|---|
| cron | Cron周期执行 |
| once | 指定时间执行一次 |
| interval | 固定间隔执行 |
任务状态
| 状态 | 说明 |
|---|---|
| active | 调度器会扫描 |
| paused | 已暂停 |
| completed | 一次性任务已完成 |
| error | 错误状态 |
执行记录状态
| 状态 | 说明 |
|---|---|
| pending | 等待 |
| running | 执行中 |
| success | 成功 |
| failed | 失败 |
| timeout | 超时 |
| cancelled | 已取消 |
系统任务租户配置
系统任务本体归平台，租户保存自己的配置，包含：
- 当前租户是否启用
- 当前租户覆盖配置
调度器机制
调度器要点：
- 每15秒轮询
- 单实例每次最多50条到期任务
- 使用分布式锁防止重复执行
- 多实例按实例ID和总实例数分片
权限边界
| 操作 | 租户 admin | 平台管理员 |
|---|---|---|
| 创建租户任务 | 可以 | 可以 |
| 更新租户任务 | 可以 | 可以 |
| 删除租户任务 | 可以 | 可以 |
| 暂停/恢复租户任务 | 可以 | 可以 |
| 手动触发租户任务 | 可以 | 可以 |
| 查看本租户执行历史 | 可以 | 可以 |
| 创建系统任务 | 不可以 | 可以 |
| PUT系统任务 | 不可以 | 不建议通过租户路径 |
| DELETE系统任务 | 不可以 | 不建议通过租户路径 |
| 配置系统任务 | 可以，受allow_tenant_disable约束 | 可以 |
| 查看其它租户执行历史 | 不可以 | 可按平台权限处理 |
注意事项
- Cron使用5段，不支持秒
- 手动触发返回运行中不代表失败，后台完成后再查历史
- paused任务即使有next_run_time也不会执行
- 恢复任务会重新计算下次运行时间
- 租户不能删除系统任务，应使用系统任务配置禁用
- 系统任务禁用只影响当前租户
- 单轮最多处理50条到期任务
- 多实例系统任务按实例ID和总实例数分片
排错速查
| 症状 | 可能原因 |
|---|---|
| 创建失败 | Cron不合法 |
| 任务不执行 | 状态非active，或next_run_time未到 |
| 执行延迟 | 15秒轮询或批量限制 |
| 手动触发后running | 后台未完成 |
| 执行timeout | 超过超时 |
| 执行failed | 执行器异常 |
| 删除返回错误 | 删除系统任务 |
| 创建系统任务失败 | 非平台管理员 |
| 重复执行 | 分布式锁异常 |
- 通知汇总任务通常作为系统任务存在，可在「系统任务」标签页配置，详见配置通知渠道