定时任务

📖 适合谁:全员 —— 想让 AI 自动定时跑任务(监控、报表、备份、内容生成),不用每天手动操作的人

📖 阅读时长:3 分钟

📖 一句话:YingClaw 内置调度器,让 AI 助手按计划自动执行任务,支持 3 种调度方式(cron / at / every)和 2 类任务(shell / agent),多任务并发,带超时控制和失败 N 次自动禁用。对话中自然语言(「每天 9 点检查磁盘」)或显式调用 cron_add / cron_list / cron_runs 工具触发,全员可访问,每个用户独立任务列表。

---

一、核心价值

价值	说明
自动化	7×24 无人值守 — 监控、报表、备份、内容生成全部自动跑,解放人工
双任务类型	shell 任务(跑命令) + agent 任务(派 AI 做事),覆盖自动化全场景
多任务并发	多个任务可同时执行,互不阻塞;高优先级任务可抢占
弹性容错	单任务超时保护、失败重试、连续失败 N 次自动禁用,避免雪崩

二、主要能力

1. 三种调度方式

方式	说明	示例
cron	标准 cron 表达式(5 段:分 时 日 月 周)	0 9 * * *(每天 9 点)、*/5 * * * *(每 5 分钟)
at	指定时间点执行 一次	2026-12-31T23:59:00Z(春节零点)
every	固定间隔循环执行	every 30m(每 30 分钟)

Cron 简写:@hourly(每小时) / @daily(每天 0 点) / @weekly(每周日) / @monthly(每月 1 号) / @yearly(元旦)。

2. Shell 任务

跑一条 shell 命令 / 脚本,定时执行;自动捕获 stdout / stderr / exit code;输出超 1MB 截断并写日志。

cron_add(
  job_type="shell",
  command="df -h | grep '/dev'",
  schedule={"kind": "cron", "expr": "0 9 * * *"},  # 每天 9 点
  name="check-disk-daily",
  timeout_secs=300
)

3. Agent 任务

派发给 AI 代理执行,跑自然语言指令;支持 delivery 投递到 IM;session_target="isolated" 跑独立会话,不污染主对话。

cron_add(
  job_type="agent",
  prompt="检查服务器磁盘,有分区超 80% 立刻发告警",
  schedule={"kind": "cron", "expr": "0 9 * * *"},
  delivery={"mode": "announce", "channel": "telegram", "to": "ops_chat_id"},
  session_target="isolated"
)

4. 多任务并发

• 多个任务可 同时执行,互不阻塞
• 默认并发数 = 4,根据 CPU/内存动态调度
• 关键任务设 priority="high" 优先调度
• 任务依赖:A 跑完才跑 B,用 depends_on=["task-a-id"]

5. 超时控制

• timeout_secs 字段设置单任务最大执行时间
• shell 任务 超时 → kill 进程;agent 任务 超时 → 中断 agent 返回部分结果
• 默认超时:shell 5 分钟,agent 10 分钟

6. 自动禁用(失败保护)

• end_after_runs 跑 N 次后自动停(如应急部署窗口)
• 连续失败 N 次自动禁用(默认 3 次),避免刷屏日志
• 失败原因 + 触发禁用时间记录在 cron_runs 历史里

7. 任务管理 API

工具	作用
cron_add	创建任务
cron_list	列出所有任务
cron_update	修改任务(暂停/恢复/改 cron)
cron_remove	删除任务
cron_runs	查看执行历史
cron_run	立即手动触发一次(测试用)

纯 shell 任务也可走 schedule 工具,功能更轻量。

8. 执行历史与日志

• cron_runs(job_id, limit=10) 看最近 N 次执行结果
• 每条记录含:开始/结束时间、状态(success / failed / timeout)、输出摘要、错误信息
• 失败任务可一键 重跑(cron_run)

三、典型应用场景

场景 1:服务器巡检 —「每天 9 点检查磁盘」

shell 任务:cron 0 9 * * *  →  跑 df -h,使用率 > 80% 发告警

运维巡检(磁盘/内存/服务/日志)全部自动跑,异常立刻推送。

场景 2:定时报表 —「每周一生成上周销售报表」

agent 任务:cron 0 9 * * 1  →  拉数据 → 生成 Excel → 推企业微信群

业务报表(周报/月报/日报)自动生成 + 自动推送,告别手工。

场景 3:网站监控 —「每 5 分钟检查网站是否在线」

shell 任务:cron */5 * * * *  →  curl 检查 HTTP 200,失败发通知

可用性监控(HTTP 状态码/响应时间/SSL 证书)持续守护,挂了立刻告警。

场景 4:数据备份 —「每天凌晨 3 点备份数据库」

shell 任务:cron 0 3 * * *  →  mysqldump → gzip → 写 /backup/

数据备份(DB/文件/配置)定时执行,过期备份自动清理。

场景 5:AI 内容自动生成 —「每天 8 点生成 AI 新闻摘要」

agent 任务:cron 0 8 * * *  →  web_search → 提炼 5 条 → 推 Telegram

内容自动化(新闻摘要/竞品监控/舆情分析)Agent 任务一站搞定。

四、使用指南

第 1 步:用自然语言创建 — 直接说"每天 9 点检查磁盘"、"每周一生成销售报表"、"每 5 分钟监控网站",YingClaw 自动翻译成 cron 表达式 + 任务。

第 2 步:显式调用 cron_add — 复杂任务用 cron_add(name, schedule, command/prompt, job_type, ...):job_type 选 shell 或 agent;schedule 选 cron/at/every;timeout_secs 必填;关键任务加 delivery 推 IM。

第 3 步:管理任务 — cron_list 看所有;cron_runs <id> 看历史;cron_update <id> {"enabled": false} 暂停;cron_remove <id> 删除。

第 4 步:处理失败 — 看 cron_runs 错误信息 → 修复命令/prompt → cron_update 改 → 手动 cron_run 测一次 → 恢复定时。

第 5 步:清理任务 — 临时任务(春节祝福/一次性活动)用 at,跑一次自动结束;长期任务加 end_after_runs 避免无限期。

五、最佳实践

• 时区必须明确 — cron 默认服务器时区;中国用户显式 +08:00 或设 TZ=Asia/Shanghai,避免凌晨任务漂移
• 任务必须幂等 — 跑两次和跑一次结果一样(INSERT ... ON DUPLICATE KEY UPDATE、覆盖式写入),避免重复执行污染数据
• 加超时保护 — 任何任务都设 timeout_secs,避免卡死任务占住并发名额
• 失败要可观测 — 关键任务加 delivery 推 IM,失败立刻知道
• 任务命名要清晰 — daily-disk-check 比 task1 强 10 倍,团队协作出问题秒定位
• 不要设太频繁 — 每分钟跑、每 30 秒跑的任务慎用,容易打爆被监控的服务;监控类 5 分钟起步
• 优先用 every 跑简单循环 — 每 N 分钟/小时/天的循环用 every,比 cron 表达式更直观
• 复杂任务用 agent — 自然语言 + 多步操作(查数据 + 生成报表 + 推送)用 agent 任务,比 shell 链式更稳
• 关键任务用独立会话 — session_target="isolated" 跑独立会话,不污染主对话上下文
• 定期审计 cron_list — 每月过一次,删过期、改错位、合并重复,保持调度器干净