Cron 精确调度技能

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

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

触发条件

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

触发类型	触发词/场景示例	适用动作
定时提醒	"设置提醒"、"提醒我"、"X分钟后叫我"	创建一次性 cron 任务
周期任务	"每天X点"、"每周一"、"定时执行"、"周期任务"	创建周期 cron 任务
调度关键词	"cron"、"计划任务"、"定时任务"、"调度"	进入调度模式
任务清理	"清理过期任务"、"删除旧任务"、"janitor"	触发自动清理
排障请求	"提醒没响"、"任务没触发"、"cron 失效"	进入错误处理流程

强制触发规则:

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

核心原则

机制	行为	风险
心跳(Heartbeat)	"有空就检查"(每 30-60 分钟)	漂移: "10 分钟后提醒"在 30 分钟心跳下必然失败
Cron	"在 X 时刻准时执行"	冗余: 一次性任务需要清理

一、设置可靠提醒

规则: 禁止对长延迟(>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	提醒未触发	at 时间戳已过去或时区错位	1. 执行 cron:list 查看任务; 2. 核对时间戳是否在未来且时区正确; 3. 确认 wakeMode: "now" 已设置; 4. 重新创建任务
ERR-002	网关超时	任务列表过大或状态文件损坏	1. 备份并删除 ~/.skill-platform/state/cron/jobs.json; 2. 重启 Agent 平台; 3. 重新创建必要任务
ERR-003	任务名冲突	同名任务已存在	1. 执行 cron:list 查找同名任务; 2. 删除或重命名旧任务; 3. 使用唯一名称重新创建
ERR-004	时区未设置	MEMORY.md 缺少时区字段	1. 询问用户所在时区; 2. 写入 MEMORY.md; 3. 用 ISO 8601 带偏移格式重建任务
ERR-005	推送通道失败	企业微信/钉钉/飞书 webhook 失效或额度耗尽	1. 核对 channel 与 to 字段; 2. 检查 webhook 是否过期; 3. 切换备用通道重发; 4. 记录失败任务待补发
ERR-006	任务重复创建	重复调用 cron:add 导致同名任务堆积	1. 创建前执行 cron:list 检查同名任务; 2. 使用 name 字段加时间戳后缀确保唯一; 3. 批量清理重复任务
ERR-007	周期任务执行间隔异常	everyMs 计算错误或单位混淆(秒与毫秒)	1. 确认 everyMs 单位为毫秒(1秒=1000ms); 2. 使用 schedule.kind: "cron" 配合 cron 表达式替代; 3. 验证执行日志间隔
ERR-008	任务状态文件损坏	jobs.json 被外部进程修改或磁盘写入中断	1. 停止 Agent 平台; 2. 备份并删除状态文件; 3. 重启平台后重建关键任务; 4. 启用文件锁或原子写入

排障速查

• "提醒没响": 见 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: 会丢失本机状态文件中的任务。任务状态存储在 ~/.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

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 内置 LLM 提供

可用性分类

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

核心能力

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

适用场景

场景	输入	输出
定时提醒	时间+消息	cron 一次性任务
周期报告	频率+内容	cron 周期任务
系统巡检	周期+检查项	静默 systemEvent 日志
任务清理	过期任务列表	Janitor 清理指令

运行时异常预防

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

• 任务去重: 创建前执行 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. 失败时按错误码表排查