Cron Scheduler - 定时调度机制

与 L13 Background Tasks 的区别#

关键洞察：定时调度不是另一套 agent，最终还是回到同一条主循环。

三组件心智模型#

1
调度记录 → 定时检查器 → 通知队列

完整流程：

1. schedule_create(…) → 把记录写到列表或文件里
2. 后台检查器每分钟看一次”现在是否匹配”
3. 如果匹配，就把 prompt 放进通知队列
4. 主循环下一轮把它当成新的用户消息喂给模型

验证你的理解#

Q1：定时调度为什么不能”后台默默执行”？

:::details 答案 系统行为不透明 + 模型不统一决策 + 主循环结构乱。

如果后台默默执行：

1. 模型不知道定时任务触发 → 行为不透明
2. 后台直接调用工具 → 权限检查缺失
3. 多条执行线 → 主循环结构混乱

正确设计：走通知队列 → 主循环统一处理 → 模型决策 → 行为透明。 :::

ScheduleRecord 定义#

1
schedule = {
2
    "id": "job_001",           # 唯一编号
3
    "cron": "0 9 * * 1",       # 定时规则（分 时 日 月 周）
4
    "prompt": "...",           # 到点后要注入主循环的提示
5
    "recurring": True,         # 是否反复触发
6
    "durable": True,           # 是否落盘保存（跨会话）
7
    "created_at": 1710000000,  # 创建时间
8
    "last_fired_at": None,     # 上次触发时间（防重复）
9
}

字段职责#

关键字段详解#

last_fired_at：防止短时间内重复触发同一任务。

1
def should_fire(schedule: ScheduleRecord, now: datetime) -> bool:
2
    # 1. cron 匹配
3
    if not cron_matches(schedule["cron"], now):
4
        return False
5

6
    # 2. 未触发过
7
    if schedule["last_fired_at"] is None:
8
        return True
9

10
    # 3. 上次触发不是同一分钟
11
    last_minute = schedule["last_fired_at"].minute
12
    current_minute = now.minute
13
    return last_minute != current_minute

没有这个字段，系统容易在检查周期内多次触发。

durable：是否落盘保存。

recurring：是否反复触发。

验证你的理解#

Q2：为什么 durable=true 需要落盘，而不只是内存存储？

:::details 答案 跨会话保留——程序重启后调度记录仍然存在。

如果只存内存：

1. 用户设置”每天早晨检查日志”
2. 程序重启（用户关闭应用）
3. 调度记录丢失 → 不再触发
4. 用户困惑：为什么定时任务消失了？

正确设计：durable=true → 写磁盘 → 重启后重新加载 → 定时任务继续有效。 :::

5字段格式#

1
分 时 日 月 周

示例解析#

特殊符号#

注意：初学者常见错误——沉迷 cron 语法细节。主线是”调度记录如何回到主循环”，不是语法。

验证你的理解#

Q3：0 9 * * 1 表示每周一9点，那 0 9 1 * 1 表示什么？

:::details 答案 每月1号且是周一的9点。

解析：

• 分=0，时=9 → 9:00
• 日=1 → 1号
• 月=* → 任意月
• 周=1 → 周一

触发条件：同时满足”1号”和”周一”。

这意味着不是”每月1号或周一”，而是”既是1号又是周一”。如果某月1号不是周一，就不会触发。

设计决策：日和周是”AND”关系，不是”OR”。这是 cron 标准行为。 :::

检查周期：分钟级而非秒级#

1
# 后台检查循环
2
def cron_checker_loop():
3
    while True:
4
        sleep(60)  # 每分钟检查一次
5
        check_all_schedules()

为什么分钟级？

通知注入：统一主循环处理#

1
def check_all_schedules():
2
    now = datetime.now()
3

4
    for schedule in schedules:
5
        if should_fire(schedule, now):
6
            # 1. 放入通知队列
7
            notification = {
8
                "type": "scheduled_prompt",
9
                "schedule_id": schedule["id"],
10
                "prompt": schedule["prompt"],
11
            }
12
            notifications.append(notification)
13

14
            # 2. 更新 last_fired_at
15
            schedule["last_fired_at"] = now
16

17
            # 3. 处理 recurring
18
            if not schedule["recurring"]:
19
                schedules.remove(schedule)

为什么走通知队列？

验证你的理解#

Q4：为什么定时检查器是后台独立循环，而不是每轮对话触发？

:::details 答案 检查频率固定，与对话轮次无关。

如果每轮对话触发：

1. 用户不说话 → 不检查 → 定时任务错过
2. 用户频繁说话 → 检查过多 → 资源浪费
3. 检查频率不可控 → 行为不确定

正确设计：后台独立循环 → 每分钟固定检查 → 不依赖对话 → 行为确定。 :::

系统整合#

到了 L14，系统有两条外部事件输入：

统一方式：都走通知队列，在下一轮模型调用前统一注入。

与后续课程的关系#

核心洞察：Cron Scheduler 是”等开始时机”的机制。理解 L14，就理解了 Agent 如何”定时触发回归主循环”。后续课程都在扩展调度机制——团队轮询、跨会话保留。

L14 核心概念的理解升级路径#

如何检验你达到了 L2？#

用这个问题自测：

如果定时检查器每秒检查一次（秒级），会有什么问题？完整链条是什么？

:::details L2 层级回答 资源消耗高 + 重复触发风险 + 检查频率不可控。

完整链条：

1. 每秒检查一次 → 每秒遍历所有 jobs
2. 100个 jobs → 每秒100次检查 → CPU消耗高
3. cron 匹配后 → 1分钟内可能触发60次（每秒检查一次）
4. last_fired_at 需要更精细（秒级而非分钟级）→ 字段设计复杂
5. 检查频率固定 → 与对话轮次无关 → 但资源消耗不可控

正确设计：分钟级检查 → 资源消耗可控 → 大多数任务精度够用 → last_fired_at 分钟级防重复。 :::

本章目标：让每个核心概念都从 L0 升级到 L2。理解 L14，不只是记住 cron 语法，而是掌握”如何在循环上叠加定时触发”的设计原则。

调度器核心流程#

与后台任务的对比#

系统整合：两条外部事件#

关键字段职责#

durable + recurring 组合#