Cron 精确调度技能

核心准则: 心跳会漂移, cron 不会。

本技能提供时间管理的实用指南,解决"我错过了提醒"问题,通过强制区分随手检查(heartbeat)与硬性调度(cron)两类机制,确保提醒准时送达。

触发条件

当用户表达以下意图时,触发本技能:

强制触发规则:
- 用户提到"cron"、"定时"、"提醒"、"调度"任意关键词时,优先调用本技能
- 用户描述的延迟超过 1 分钟时,禁止使用 act:wait,必须改用 cron
- 用户要求"X点"、"每天"、"每周"等时间点触发时,默认进入 cron 模式

核心原则

一、设置可靠提醒

规则: 禁止对长延迟(>1 分钟)使用 act:wait。改用 cron:add 配合一次性 at 调度。

一次性提醒模式

• 负载选择: 推送通知用 AgentTurn + 严格指令;静默日志用 systemEvent
• 自动清理: 一次性任务成功后自动删除(deleteAfterRun: true)

企业微信推送提醒:

{
  "name": "提醒: 喝水",
  "schedule": { "kind": "at", "at": "2026-02-06T13:30:00+08:00" },
  "payload": {
    "kind": "agentTurn",
    "message": "DELIVER THIS EXACT MESSAGE:\n\n该喝水了!"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce", "channel": "wecom", "to": "user_id" }
}

钉钉推送提醒:

{
  "name": "提醒: 站会",
  "schedule": { "kind": "at", "at": "2026-02-06T09:55:00+08:00" },
  "payload": {
    "kind": "agentTurn",
    "message": "DELIVER THIS EXACT MESSAGE:\n\n5 分钟后开站会"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce", "channel": "dingtalk", "to": "user_id" }
}

飞书推送提醒:

{
  "name": "提醒: 周报",
  "schedule": { "kind": "at", "at": "2026-02-06T17:30:00+08:00" },
  "payload": {
    "kind": "agentTurn",
    "message": "DELIVER THIS EXACT MESSAGE:\n\n下班前提交周报"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce", "channel": "feishu", "to": "user_id" }
}

静默后台日志:

{
  "name": "日志: 心跳",
  "schedule": { "kind": "every", "everyMs": 3600000 },
  "payload": { "kind": "systemEvent", "text": "[PULSE] 系统正常" },
  "sessionTarget": "main"
}

二、自动清理(Janitor)

手动清理仅适用于以下情况:
- 以 deleteAfterRun: false 创建的一次性任务
- 不再需要的过期周期任务

系统维护任务始终通过 systemEvent 投递到 main 会话,由主 Agent 执行清理。

三、时区锁定

cron 正常运行的前提是 Agent 必须知道当前时间。
- 动作: 将用户时区写入 MEMORY.md(如 Asia/Shanghai)
- 校验: 用户说"晚上 9 点提醒我"时,必须先确认时区再调度
- 格式: 调度时间戳使用 ISO 8601 带偏移格式(如 2026-02-06T21:00:00+08:00)

四、自唤醒规则

• 等待 < 1 分钟(交互式): 保持工具循环开启(使用 act:wait)
• 等待 > 1 分钟(异步): 使用 Cron 并设置 wakeMode: "now"

错误处理

结构化错误码

排障速查

• "提醒没响": 见 ERR-001,先查 cron:list 再核时间戳
• "任务执行了但没消息": 改用 AgentTurn + announce 模式主动推送
• "网关超时": 见 ERR-002,清理状态文件后重启

能力边界

能做什么

• 精确到分钟级的定时提醒(受网关心跳周期约束)
• 周期性任务调度(每小时、每天、每周)
• 一次性任务执行后自动清理
• 时区锁定与自唤醒,避免长延迟漂移
• 通过企业微信、钉钉、飞书推送消息到指定用户

不能做什么

• 不能保证毫秒级精度(执行延迟取决于网关心跳,约 10-60 秒)
• 不能在无 LLM 环境下独立运行(依赖 Agent 平台)
• 不能替代操作系统级 crontab(仅作用于 Agent 会话内)
• 不能处理复杂日历规则(如"每月最后一个工作日"、"农历节日")
• 不能跨 Agent 实例共享任务状态(任务仅存于本机状态文件)

常见问题(FAQ)

Q1: 提醒没有按时触发,如何排查?

A: 按以下顺序检查: 1) 执行 cron:list 确认任务存在; 2) 核对 at 时间戳是否在未来且时区正确; 3) 确认 wakeMode: "now" 已设置; 4) 查看 MEMORY.md 中时区是否已写入。对应错误码 ERR-001。

Q2: 一次性任务执行后需要手动清理吗?

A: 不需要。只要创建时设置 deleteAfterRun: true,任务成功执行后会自动删除。仅当显式设置 deleteAfterRun: false 时,才需要手动清理或交给 Janitor 处理。

Q3: 心跳模式和 cron 模式如何选择?

A: 看延迟时长与精度要求。延迟 < 1 分钟且需要交互时用心跳(act:wait); 延迟 > 1 分钟或要求"准点触发"时必须用 cron。记住核心准则: 心跳会漂移,cron 不会。

Q4: 如何确保时区正确,避免"晚上 9 点"歧义?

A: 创建任务前必须先确认用户时区并写入 MEMORY.md。调度时间戳统一使用 ISO 8601 带偏移格式(如 2026-02-06T21:00:00+08:00),不要用 UTC 让用户自行换算。对应错误码 ERR-004。

Q5: 国内平台推送失败怎么办?

A: 见错误码 ERR-005。常见原因: webhook 过期、to 字段填错、调用额度耗尽。排查步骤: 1) 核对 channel(wecom/dingtalk/feishu)与 to 字段; 2) 在对应平台后台测试 webhook; 3) 切换备用通道重发; 4) 记录失败任务待补发。

Q6: 网关超时后任务数据会丢失吗?

A: 会丢失本机状态文件中的任务。任务状态存储在 ~/.skill-platform/state/cron/jobs.json,损坏时需删除并重建。建议对关键任务保留创建参数备份,以便重建。对应错误码 ERR-002。

Q7: 如何防止任务重复创建?

A: 见错误码 ERR-006。建议做法: 1) 创建前先执行 cron:list 检查同名任务; 2) 在 name 字段中加入时间戳或唯一标识后缀(如 提醒:喝水_20260206); 3) 对周期任务使用固定名称便于管理和替换。

Q8: 周期任务执行间隔不稳定怎么办?

A: 见错误码 ERR-007。everyMs 字段单位为毫秒,常见错误是将秒数直接填入。正确换算: 1分钟=60000ms, 1小时=3600000ms。若需更精确的调度,改用 schedule.kind: "cron" 配合标准 cron 表达式(如 0 9 * * 1-5 表示工作日9点)。

实践建议

• 创建任务前先 cron:list 检查是否已有同名任务,避免重复
• 一次性任务始终设置 deleteAfterRun: true,防止任务堆积
• 关键任务保留创建参数备份,以便状态文件损坏后快速重建
• 周期任务优先使用 cron 表达式而非 everyMs,调度更精确
• 时区信息写入 MEMORY.md 后,所有时间戳统一使用 ISO 8601 带偏移格式
• 推送通道建议配置至少两个(如企业微信+钉钉),互为备用
• 定期执行 Janitor 清理过期任务,保持任务列表简洁

文档参考

• ISO 8601 时间格式标准: https://www.iso.org/iso-8601-date-and-time-format.html
• Cron 表达式语法: https://crontab.guru/
• 企业微信 webhook 文档: https://developer.work.weixin.qq.com/document/path/91770
• 钉钉自定义机器人: https://open.dingtalk.com/document/robots/custom-robot-access
• 飞书消息卡片: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/feishu-cards/card-json-structure

依赖说明

运行环境

• Agent 平台: 支持 SKILL.md 的任意 AI Agent
• 操作系统: Windows / macOS / Linux

依赖项

可用性分类

• 分类: MD+EXEC(纯 Markdown 指令,部分功能需要 exec 命令行执行能力)

核心能力

• 精确 cron 调度与心跳机制分离
• 可靠提醒设置与自动清理
• 时区锁定与自唤醒规则
• 国内平台(企业微信/钉钉/飞书)消息推送

适用场景

运行时异常预防

为提升调度稳定性,执行过程中应遵循以下预防措施:

• 任务去重: 创建前执行 cron:list 检查同名任务,避免重复堆积
• 自动清理: 一次性任务设置 deleteAfterRun: true,无需手动干预
• 时区校验: 调度前确认 MEMORY.md 中时区字段存在,时间戳使用 ISO 8601 带偏移格式
• 通道冗余: 配置至少两个推送通道(如企业微信+钉钉),单通道故障时自动切换
• 状态备份: 关键任务的创建参数保留备份,状态文件损坏后可快速重建
• 间隔校验: 使用 everyMs 时确认单位为毫秒,或改用 cron 表达式避免换算错误
• 日志监控: 周期任务执行后检查日志输出,确认任务按预期触发

Related Skills

与本技能相关的其他技能方向(在 SkillHub 平台检索对应名称):

• reminder-engine: 通用提醒引擎,支持自然语言时间解析与多通道推送
• schedule-manager: 日程管理技能,集成日历视图与冲突检测
• task-queue-manager: 任务队列管理,支持优先级调度与依赖编排
• timer-alert: 简易计时器,适用于短延迟(< 1 分钟)交互式等待场景

使用流程

1. 确认运行环境满足依赖说明
2. 根据场景选择 heartbeat 或 cron 模式
3. 设置 timezone 并创建任务
4. 验证任务执行结果
5. 失败时按错误码表排查