Cron 定时调度

为什么 Cron 是一等公民

在平台六层架构中，定时调度与事件触发并列，都是"把事件送到 Session"的基础设施：

Rendering diagram…

Cron 让 Agent 能完成周期性、需主动触发的工作——日报、周报、定期巡检、闹钟提醒、批量任务调度。

三种调度类型

类型	说明	`schedule_value` 示例
`at`	一次性定时，执行完自动失效	`2026-04-25T09:00:00`（ISO 格式，至少 1 分钟后）
`cron`	标准 5 段 crontab	`0 9 * * `（每天 9 点）/ `0 10 * 1`（每周一 10 点）
`every`	固定间隔	`30m`、`2h`、`1d`（最小 5 分钟）

两种执行模式

模式	说明	适用场景
`isolated` ⭐	创建临时 Session 独立执行	默认推荐，任务之间互不影响
`main`	在创建它的 Session 中执行	需要继承当前会话的资料、记忆、上下文

投递模式

调度触发后，结果可以投递到：

模式	说明
SESSION	投递回一个 Session（默认）
CHANNEL	推送到消息渠道（飞书群、企业微信群、邮件）
WEBHOOK	回调一个 HTTP 端点
LOG	只记日志不推送

如果任务是在群聊中被创建的，结果会自动推送回那个群——不用额外配置。

冲突策略

当一个任务还在执行、下一次又到点时：

策略	行为
SKIP	跳过本次，等下一个周期
QUEUE	排队等待，前一次完成后执行
FALLBACK_ISOLATED	本次降级为 isolated 单独执行

重试策略

最大尝试：默认 3 次
退避序列：30s → 60s → 300s → 900s → 3600s
可重试错误：timeout / rate_limit / server_error / network_error
不可重试：业务错误、权限错误等 permanent_error

Agent 自主调度

Agent 有一个内置工具 manage_cron_job，支持在对话中用自然语言创建、列表、删除定时任务——用户不需要进管理后台：

用户：每天早上 9 点给我一份前一天的研发进展简报

Agent 调用：
manage_cron_job(
    action="create",
    name="每日研发进展简报",
    schedule_type="cron",
    schedule_value="0 9 * * *",
    prompt="汇总昨日所有 PR/MR 的变更、测试结果、Bug 进展，按团队分组，生成简报",
    execution_mode="isolated",
)

到点后，系统自动：

Rendering diagram…

典型场景

早上 9 点推送前日简报             → cron "0 9 * * *"
每周一 10 点发团队周报             → cron "0 10 * * 1"
每 30 分钟巡检 CI/CD               → every "30m"
下周一开会前 15 分钟提醒            → at "2026-04-28T09:45:00"
每晚 2 点重建长期记忆索引           → cron "0 2 * * *"
每周五下午自动跑合规审计            → cron "0 15 * * 5"
每日凌晨同步 DOORS 需求变更         → cron "0 1 * * *"

Cron vs EventTrigger 如何选

维度	Cron 定时调度	EventTrigger 事件触发
触发源	时间到了	外部事件来了
典型用途	周报、巡检、闹钟、定期同步	PR 审查、需求变更通知、消息处理
创建方式	Agent 自主创建 / 管理后台	管理后台配置 Webhook / 路由规则
典型并发	同任务通常单实例	同事件可能短时间高并发

可以组合使用：定时任务可以触发 EventTrigger 的链式事件；EventTrigger 也可以在 Session 内创建定时任务。

持久化与可观测

MySQL 持久化 — 进程重启不丢失任务
执行历史 — 每次执行的状态、耗时、输出、错误都可查
审计日志 — 创建/修改/删除全记录，跨租户不混
APM 追踪 — 每次触发都有独立 Trace ID，详见可观测性