定时任务¶

Echo Agent 内置定时任务系统，允许通过 cronjob 工具创建、管理和监控周期性任务。本指南涵盖调度系统的完整使用方式。

系统概述¶

定时任务系统由以下组件构成：

cronjob 工具 — 创建和管理定时任务的核心工具
Scheduler（调度器） — 负责按 cron 表达式触发任务执行
Cron Channel（定时通道） — 专用通道，承载定时任务的输出与状态
Dashboard Cron 页面 — 可视化管理界面

调度器配置¶

调度器通过 SchedulerConfig 进行全局配置：

scheduler:
  enabled: true
  max_concurrent_jobs: 10

参数	默认值	说明
`enabled`	`true`	是否启用定时任务系统
`max_concurrent_jobs`	`10`	最大并发任务数，超出时排队等待

创建定时任务¶

使用 cronjob 工具创建任务：

tool: cronjob
action: create
name: "daily-report"
schedule: "0 9 * * *"
task: "生成每日汇总报告并发送到通知通道"

Cron 表达式语法¶

采用标准五位 cron 格式：

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日 (1-31)
│ │ │ ┌───────────── 月 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6, 0=周日)
│ │ │ │ │
* * * * *

常用示例：

表达式	含义
`0 9 * * *`	每天 9:00
`/15 * * *`	每 15 分钟
`0 0 * * 1`	每周一 00:00
`0 8 1 * *`	每月 1 日 8:00
`0 /2 * *`	每 2 小时

授权模型¶

安全警告

cronjob 工具的风险等级为 dangerous。创建新的定时任务需要明确的授权审批。

为什么是 dangerous 级别¶

定时任务会在无人值守的情况下周期性执行，可能：

消耗大量系统资源
执行敏感操作
产生不可预期的副作用

审批流程¶

创建新任务需要满足以下条件之一：

人工审批（approval_source="human"）— 维护者在 Dashboard 或交互中确认
预授权标志（cron_authorized=true）— 在 ToolExecutionContext 中设置

# ToolExecutionContext 示例
context:
  cron_authorized: true
  unattended: false

授权按单个任务显式授予，没有通道级的自动授权规则——新建的定时任务默认未授权，不会因为属于 cron 通道就自动获得执行许可。

这样设计是为了让「定时」与「许可」分离：任务的调度配置可以随时改动，而它能否在无人看管时动手做事，需要一次明确的人工确认。

给已存在的任务补授权¶

授权与任务内容绑定，修改指令、频率或投递目标都会使已有授权失效，因此「重新授权」是常规操作，而不是异常情况。共有三条路径：

路径	服务运行中可用	说明
在对话里说「授权定时任务 `<job_id>`」	✅	agent 调用 `cronjob(action="authorize")`，会先列出该任务的指令/频率/投递目标请你确认
Dashboard 定时任务页勾选授权	✅	等价于 REST `PUT /cron/{id}` 带 `authorize_unattended: true`
`echo-agent cron authorize <job_id>`	❌	仅在服务已停止时可用

CLI 那条路径受实例锁保护：gateway 运行时它会直接拒绝，因为离线改动会被运行中的实例覆盖。所以服务正常运行期间，应使用对话或 Dashboard 授权。

# 以下命令需先停止服务
echo-agent cron list                  # 查看任务及其授权状态
echo-agent cron authorize <job_id>    # 授权指定任务
echo-agent cron revoke <job_id>       # 撤销授权

对话里同样可以撤销：说「撤销定时任务 <job_id> 的授权」即可（对应 cronjob(action="revoke")）。

无人值守模式¶

当 unattended=true 时，审批流程有所不同：

若同时设置 cron_authorized=true，任务可自动创建
若未设置 cron_authorized，任务创建将被拒绝（不会挂起等待人工审批）

Cron 通道¶

Cron 通道是定时任务的专用执行环境：

每个定时任务绑定到一个 cron 通道
任务输出和状态信息写入该通道
通道提供任务执行的隔离上下文

Dashboard Cron 页面¶

Dashboard 提供专门的 Cron 管理页面，支持：

查看所有定时任务列表及状态
手动触发任务执行
暂停/恢复任务
查看任务执行历史与日志
删除任务

管理任务¶

列出任务¶

tool: cronjob
action: list

暂停任务¶

tool: cronjob
action: pause
name: "daily-report"

恢复任务¶

tool: cronjob
action: resume
name: "daily-report"

删除任务¶

tool: cronjob
action: delete
name: "daily-report"

使用场景示例¶

每日报告生成¶

tool: cronjob
action: create
name: "daily-summary"
schedule: "0 9 * * *"
task: "汇总过去 24 小时的通道活动，生成摘要报告"

定期清理¶

tool: cronjob
action: create
name: "weekly-cleanup"
schedule: "0 3 * * 0"
task: "清理超过 30 天的临时文件和过期缓存"

健康检查¶

tool: cronjob
action: create
name: "health-check"
schedule: "*/30 * * * *"
task: "检查所有后端服务连通性，异常时发送告警"

数据同步¶

tool: cronjob
action: create
name: "sync-external-data"
schedule: "0 */4 * * *"
task: "从外部 API 同步最新数据到本地存储"

安全建议¶

最小权限原则

定时任务应仅授予完成其功能所需的最小权限。避免创建拥有广泛权限的定时任务。

定期审查活跃的定时任务列表
为敏感操作的定时任务设置执行时间窗口
监控 max_concurrent_jobs 使用情况，防止资源耗尽
在生产环境中谨慎使用 cron_authorized 预授权标志