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点)。

Q1: 如何在Cron任务中指定执行时间，比如每天早上8点？

A: 在Cron任务中，你可以使用cron表达式来指定执行时间。例如，要设置每天早上8点执行的任务，你可以使用0 8 * * *这个cron表达式，其中0代表分钟，8代表小时，*代表每月的每一天，*代表每个月，*代表每周的每一天。

Q2: 如果我想让Cron任务在特定日期和时间执行，应该怎么做？

A: 如果需要Cron任务在特定日期和时间执行，你可以在cron表达式中使用@reboot来指定任务在系统启动时执行，或者使用@daily、@hourly等来指定周期性执行。对于特定日期和时间，你可以使用at命令来创建一次性任务，或者手动编辑Cron表来添加一个特定的cron表达式。

Q3: 我在Cron任务中使用了@reboot，但任务没有按预期执行，为什么？

A: 如果使用@reboot后任务没有执行，可能是因为任务脚本没有正确设置执行权限，或者脚本路径不正确。确保脚本具有执行权限（使用chmod +x script.sh），并且脚本路径在系统的PATH环境变量中，或者直接指定完整的脚本路径。

Q4: 我有一个需要每周特定一天执行的任务，应该使用哪种Cron表达式？

A: 对于每周特定一天的任务，你可以在cron表达式中使用0 * * * [day_of_week]。例如，如果你想每周五早上8点执行任务，你可以使用0 8 * * 5，其中5代表星期五（Cron表达式中星期天是0，星期一是1，以此类推）。

Q5: 我在Cron任务中遇到了时区问题，任务没有在正确的时间执行，怎么办？

A: 时区问题可能导致Cron任务在错误的时间执行。确保你的Cron守护进程配置了正确的时区，或者在你的cron表达式中的时间使用的是UTC时间。如果使用本地时间，确保你的系统时区设置正确。你可以通过在cron表达式中添加时区信息（如0 8 * * * Europe/Paris）来指定任务执行的时区。

实践建议

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

技术创新

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
设置一次性提醒	2分钟	10秒	1分50秒	100%
创建周期任务	5分钟	30秒	4分30秒	100%
自动清理任务	10分钟	1分钟	9分钟	100%
时区设置	5分钟	30秒	4分30秒	100%
自唤醒规则配置	10分钟	1分钟	9分钟	100%
错误处理	30分钟	5分钟	25分钟	100%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
易用性	高	低	中	高
准确性	高	低	中	高
覆盖性	广泛	有限	中	广泛
成本	低	高	中	高
维护性	低	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
定时任务漂移	定时任务无法准时执行，导致错过提醒	影响用户效率和体验	采用Cron精确调度，消除漂移问题	准确率提升至100%
任务管理复杂	手动管理大量定时任务，效率低下	影响任务执行效率	自动清理和调度，简化任务管理	效率提升50%
时区管理困难	不同地区用户时区不同，任务执行困难	影响跨时区任务执行	时区锁定，确保任务准确执行	准确率提升至100%

诊断与修复

错误现象	可能原因	诊断步骤	解决方案
提醒未到	定时任务未创建或创建失败	检查Cron任务日志，确认任务创建状态	重新创建Cron任务
任务执行失败	任务脚本错误或权限问题	检查任务脚本和权限设置	修复脚本或调整权限
时区设置错误	用户时区设置错误	重新设置用户时区	修正时区设置
自唤醒规则失效	Cron任务未设置或设置错误	检查Cron任务设置，确认自唤醒规则	重新设置自唤醒规则
消息推送失败	推送平台配置错误或网络问题	检查推送平台配置和网络状态	修复配置或解决网络问题

安全规范

1. [与「Cron 精确调度」相关的安全注意事项]
   • 确保Cron任务脚本的安全性，防止恶意脚本执行。
   • 对Cron任务执行权限进行严格控制，避免未授权访问。
   • 定期检查Cron任务日志，及时发现并处理异常情况。
   • 限制Cron任务的创建和修改权限，防止未授权操作。
   • 对Cron任务进行加密，保护敏感数据不被泄露。

安全风险防范

风险项	等级	防护措施	验证方法
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

主要功能特点

• 自动化执行: cron精确调度,心跳会漂移cron不会
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

错误处理策略

针对Cron 精确调度使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

Cron 精确调度通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

依赖说明

运行环境

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

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。