CoPaw Cron 定时任务系统详解

AI人工智能 6 小时前 0 0

CoPaw Cron 定时任务系统详解

CoPaw 的 Cron 系统是一个强大的定时任务调度器，让你可以自动化执行各种重复性任务，如定期检查、数据备份、报告生成等。本文将详细介绍 Cron 系统的配置和使用方法。

Cron 系统概述

什么是 Cron？

Cron 是 CoPaw 的定时任务调度系统，类似于 Unix/Linux 的 cron 任务调度器。它可以：

按照预定的时间执行任务
支持复杂的调度规则
管理任务的生命周期（创建、暂停、恢复、删除）
查看任务执行历史和日志

Cron 的应用场景

| 场景 | 频率 | 示例 |
|------|------|------|
| 定期检查 | 每 30 分钟 | 检查邮件、日历、通知 |
| 数据备份 | 每天凌晨 | 备份 Memory 数据库 |
| 报告生成 | 每周一 | 生成周报 |
| 系统维护 | 每月 | 清理临时文件 |
| 提醒事项 | 定时 | 提醒重要会议 |

Cron vs Heartbeat

| 特性 | Cron | Heartbeat |
|------|------|-----------|
| 精度 | 高精度，精确到分钟 | 低精度，约 30 分钟 |
| 适用场景 | 定时任务、独立任务 | 合并检查、上下文相关 |
| 配置方式 | Crontab 格式 | HEARTBEAT.md 配置 |
| 资源消耗 | 每个任务独立 | 合并执行更节省 |

使用原则：

用 Cron 当：精确时间很重要（"每周一上午 9:00 准点"）
用 Heartbeat 当：多个检查可以合并，时间可以浮动

Cron 配置

基本配置

编辑配置文件：

{
  "cron": {
    "enabled": true,
    "storage_path": ".copaw/cron",
    "timezone": "Asia/Shanghai",
    "max_concurrent_tasks": 5,
    "log_retention_days": 30,
    "notification": {
      "enabled": true,
      "on_failure": true,
      "channel": "telegram"
    }
  }
}

通过控制台配置

# 启用 Cron 系统
/config set cron.enabled true

# 设置时区
/config set cron.timezone Asia/Shanghai

# 设置最大并发任务数
/config set cron.max_concurrent_tasks 5

# 启用失败通知
/config set cron.notification.enabled true

# 保存配置
/config save

Cron 表达式语法

基本格式

┌───────────── 分钟 (0 - 59)
│ ┌─────────── 小时 (0 - 23)
│ │ ┌───────── 日期 (1 - 31)
│ │ │ ┌─────── 月份 (1 - 12)
│ │ │ │ ┌───── 星期 (0 - 7, 0 和 7 都表示周日)
│ │ │ │ │
│ │ │ │ │
* * * * *

特殊字符

| 字符 | 说明 | 示例 |
|------|------|------|
| | 任意值 | = 每分钟 |
| , | 列表分隔 | 1,3,5 = 每小时的第 1、3、5 分钟 |
| - | 范围 | 1-5 = 每小时的第 1-5 分钟 |
| / | 步长 | /10 = 每 10 分钟 |
| ? | 不指定（日期和星期） | 0 0 1 ? = 每月 1 号，不指定星期 |

常用示例

| 表达式 | 说明 |
|--------|------|
| 0 | 每小时的第 0 分钟执行 |
| /15 | 每 15 分钟执行 |
| 0 0 | 每天凌晨 0 点执行 |
| 0 9 | 每天上午 9 点执行 |
| 0 9 1-5 | 周一到周五上午 9 点执行 |
| 0 0 1 | 每月 1 号凌晨执行 |
| 0 0 1 1 | 每年 1 月 1 号执行 |
| 0 0 12 ? | 每天中午 12 点执行 |

Cron 任务管理

创建任务

基本命令

# 创建任务
/cron add <任务名称> --schedule <Cron表达式> --command <命令>

# 示例：每小时检查邮件
/cron add 检查邮件 --schedule "0 * * * *" --command "/mail check"

# 示例：每天凌晨备份
/cron add 数据备份 --schedule "0 0 * * *" --command "/memory backup --output backups/memory_$(date +%Y%m%d).zip"

带参数的任务

# 添加任务描述
/cron add 周报生成 --schedule "0 9 * * 1" --command "/report generate --type weekly" --desc "每周一生成周报"

# 添加任务标签
/cron add 日志清理 --schedule "0 0 * * 0" --command "/log cleanup --days 30" --tags maintenance,cleanup

# 设置任务超时
/cron add 数据同步 --schedule "*/30 * * * *" --command "/sync run" --timeout 300

查询任务

# 列出所有任务
/cron list

# 查看任务详情
/cron show <任务ID或名称>

# 按标签筛选
/cron list --tags maintenance

# 搜索任务
/cron search 邮件

任务状态管理

# 暂停任务
/cron pause <任务ID>

# 恢复任务
/cron resume <任务ID>

# 禁用任务
/cron disable <任务ID>

# 启用任务
/cron enable <任务ID>

# 删除任务
/cron delete <任务ID>

执行历史和日志

# 查看任务执行历史
/cron history <任务ID>

# 查看最新执行日志
/cron logs <任务ID>

# 查看所有任务的状态
/cron status

# 查看任务统计
/cron stats

常用 Cron 任务示例

1. 定期检查收件箱

# 每 30 分钟检查一次邮件
/cron add 检查邮件 --schedule "*/30 * * * *" --command "/mail check --unread"

# 设置通知
/cron set 检查邮件 --notification --channel telegram

2. 定期备份数据

# 每天凌晨 2 点备份 Memory
/cron add Memory备份 --schedule "0 2 * * *" --command "/memory backup --output backups/memory_$(date +\%Y\%m\%d).zip"

# 每周日备份配置
/cron add 配置备份 --schedule "0 3 * * 0" --command "/config backup --output backups/config_$(date +\%Y\%m\%d).zip"

# 保留最近 7 天的备份
/cron add 清理备份 --schedule "0 4 * * *" --command "/trash remove backups/memory_*.zip --older-than 7days"

3. 定期生成报告

# 每周一早上 9 点生成周报
/cron add 周报生成 --schedule "0 9 * * 1" --command "/report generate --type weekly --format html"

# 每月 1 号生成月报
/cron add 月报生成 --schedule "0 9 1 * *" --command "/report generate --type monthly --format pdf"

# 发送到指定频道
/cron set 周报生成 --output slack:reports

4. 定期系统维护

# 每周日凌晨清理临时文件
/cron add 清理临时文件 --schedule "0 3 * * 0" --command "/system cleanup --temp"

# 每月更新索引
/cron add 更新索引 --schedule "0 2 1 * *" --command "/memory index rebuild"

# 每天检查磁盘空间
/cron add 磁盘检查 --schedule "0 6 * * *" --command "/system check disk --threshold 80"

5. 定期提醒事项

# 每天早上 9 点提醒查看待办事项
/cron add 待办提醒 --schedule "0 9 * * *" --command "/memory search --tags todo --limit 10"

# 每周五下午 5 点提醒提交周报
/cron add 周报提醒 --schedule "0 17 * * 5" --command "/message send 你该提交周报了！"

# 每月 1 号提醒更新订阅
/cron add 订阅更新提醒 --schedule "0 9 1 * *" --command "/message send 记得更新订阅服务"

Cron 高级功能

任务依赖

# 创建主任务
/cron add 数据备份 --schedule "0 2 * * *" --command "/backup create"

# 创建依赖任务（备份完成后执行）
/cron add 备份验证 --schedule "" --command "/backup verify" --depends-on 数据备份

# 创建通知任务（验证完成后通知）
/cron add 备份通知 --schedule "" --command "/notify send 备份成功" --depends-on 备份验证

任务重试策略

# 创建带重试的任务
/cron add 数据同步 --schedule "*/30 * * * *" --command "/sync run" --retry 3 --retry-delay 60

# 查看重试配置
/cron show 数据同步

任务超时处理

# 设置任务超时
/cron add 长任务 --schedule "0 2 * * *" --command "/longtask run" --timeout 3600

# 超时后的操作
/cron set 长任务 --on-timeout notify --on-timeout-cmd "/alert 任务超时"

条件执行

# 只在工作日执行
/cron add 工作日检查 --schedule "0 9 * * 1-5" --command "/workday check"

# 在特定条件下执行
/cron add 条件备份 --schedule "0 2 * * *" --command "/backup conditional --if-online"

并发控制

# 设置任务并发数
/cron add 批量处理 --schedule "0 */2 * * *" --command "/batch process --parallel 5"

# 限制同一任务并发
/cron add 数据导入 --schedule "0 3 * * *" --command "/import data" --max-concurrent 1

Cron 和 Skills 集成

调用 Skills 作为任务

# 使用 blog_publish skill 定期发布文章
/cron add 文章发布 --schedule "0 10 * * *" --command "/skill blog_publish --auto-draft"

# 使用 code_review skill 定期代码审查
/cron add 代码审查 --schedule "0 18 * * 1-5" --command "/skill code_review --branch main"

自定义 Cron Skill

在 active_skills/cron/SKILL.md 中定义自定义任务：

# 自定义 Cron Skill

## 示例：每周数据清理

创建任务：

bash

/cron add 每周清理 --schedule "0 3 0" --command "/skill data_cleanup --days 7"


清理逻辑：
1. 清理过期日志
2. 清理临时文件
3. 清理缓存数据
4. 生成清理报告

Cron 监控和通知

监控任务执行

# 启用任务监控
/config set cron.monitoring.enabled true

# 设置监控间隔
/config set cron.monitoring.interval 60

# 保存配置
/config save

# 查看监控状态
/cron monitor status

配置通知

# 任务失败时通知
/cron set 数据备份 --notify-on-failure true --notify-channel slack:alerts

# 任务成功时通知
/cron set 数据备份 --notify-on-success true --notify-channel telegram

# 超时时通知
/cron set 长任务 --notify-on-timeout true --notify-channel email

任务统计

# 查看任务统计
/cron stats

# 查看任务成功率
/cron stats --success-rate

# 查看平均执行时间
/cron stats --avg-duration

Cron 最佳实践

1. 合理设置任务时间

# ❌ 不好：所有任务都在整点执行
0 0 * * * /task1
0 0 * * * /task2

# ✅ 好：错开任务执行时间
0 0 * * * /task1
0 5 * * * /task2

2. 使用标签组织任务

# 为任务添加标签
/cron add 数据备份 --schedule "0 2 * * *" --command "/backup" --tags backup,daily
/cron add 日志清理 --schedule "0 3 * * 0" --command "/cleanup" --tags maintenance,weekly

# 按标签查询
/cron list --tags backup
/cron list --tags weekly

3. 设置合理的超时时间

# 根据任务特性设置超时
/cron add 快速检查 --schedule "*/10 * * * *" --command "/check" --timeout 30
/cron add 数据备份 --schedule "0 2 * * *" --command "/backup" --timeout 3600

4. 定期检查任务状态

# 创建监控任务
/cron add Cron监控 --schedule "0 9 * * 1" --command "/cron status --email admin@example.com"

# 查看失败任务
/cron list --status failed

5. 合并相似任务

# ❌ 不好：多个独立任务
/cron add 检查邮件 --schedule "*/30 * * * *" --command "/mail check"
/cron add 检查日历 --schedule "*/30 * * * *" --command "/calendar check"
/cron add 检查通知 --schedule "*/30 * * * *" --command "/notify check"

# ✅ 好：合并为一个任务
/cron add 定期检查 --schedule "*/30 * * * *" --command "/check all --mail --calendar --notify"

Cron 故障排查

Q1: 任务没有按时执行？

检查步骤：

# 1. 检查任务状态
/cron show <任务ID>

# 2. 检查 Cron 服务是否运行
/cron status

# 3. 查看日志
/cron logs <任务ID>

# 4. 检查时区设置
/config get cron.timezone

Q2: 任务执行失败？

排查方法：

# 查看详细日志
/cron logs <任务ID> --verbose

# 手动执行命令测试
<command>

# 检查重试配置
/cron show <任务ID>

Q3: 任务执行时间不对？

常见原因：

# 1. 时区设置错误
/config set cron.timezone Asia/Shanghai

# 2. Cron 表达式错误
# 验证表达式
/cron validate "0 9 * * 1-5"

# 3. 系统时间不准确
/system check time

Q4: 任务占用资源过多？

解决方案：

# 1. 限制并发任务数
/config set cron.max_concurrent_tasks 3

# 2. 设置任务超时
/cron set <任务ID> --timeout 300

# 3. 限制资源使用
/cron set <任务ID> --max-memory 512MB --max-cpu 50%

Q5: 如何调试 Cron 任务？

# 启用调试模式
/cron set <任务ID> --debug true

# 手动触发执行
/cron run <任务ID>

# 查看详细输出
/cron logs <任务ID> --debug

Cron vs 心跳 (Heartbeat)

使用场景对比

| 场景 | 推荐方式 | 原因 |
|------|---------|------|
| 精确时间任务 | Cron | 需要精确时间控制 |
| 多项合并检查 | Heartbeat | 节省 API 调用 |
| 独立后台任务 | Cron | 不依赖上下文 |
| 上下文相关检查 | Heartbeat | 需要对话上下文 |

Heartbeat 配置示例

创建 HEARTBEAT.md：

# Heartbeat 清单

## 每次触发时执行

1. 检查未读邮件
   - 有重要邮件 → 总结并发送通知

2. 检查今日日程
   - 有重要会议 → 提前 30 分钟提醒

3. 检查待办事项
   - 高优先级 → 推送到 Telegram

## 每周执行

1. 整理 Memory
   - 归档旧的每日笔记
   - 更新长期记忆

2. 生成周报
   - 统计本周活动
   - 发送到 Slack

总结

通过本教程，你应该已经掌握了：

✅ Cron 系统的基本概念
✅ Cron 表达式语法
✅ 任务管理（创建、查询、暂停、删除）
✅ 高级功能（依赖、重试、超时）
✅ Cron 和 Skills 集成
✅ 监控和通知
✅ 最佳实践和故障排查
✅ Cron vs Heartbeat 的选择

在下一章中，我们将学习 CoPaw MCP (Model Context Protocol) 集成，了解如何连接外部工具和服务。

CoPaw Cron 定时任务系统详解

Cron 系统概述

什么是 Cron？

Cron 的应用场景

Cron vs Heartbeat

Cron 配置

基本配置

通过控制台配置

Cron 表达式语法

基本格式

特殊字符

常用示例

Cron 任务管理

创建任务

基本命令

带参数的任务

查询任务

任务状态管理

执行历史和日志

常用 Cron 任务示例

1. 定期检查收件箱

2. 定期备份数据

3. 定期生成报告

4. 定期系统维护

5. 定期提醒事项

Cron 高级功能

任务依赖

任务重试策略

任务超时处理

条件执行

并发控制

Cron 和 Skills 集成

调用 Skills 作为任务

自定义 Cron Skill

Cron 监控和通知

监控任务执行

配置通知

任务统计

Cron 最佳实践

1. 合理设置任务时间

2. 使用标签组织任务

3. 设置合理的超时时间

4. 定期检查任务状态

5. 合并相似任务

Cron 故障排查

Q1: 任务没有按时执行？

Q2: 任务执行失败？

Q3: 任务执行时间不对？

Q4: 任务占用资源过多？

Q5: 如何调试 Cron 任务？

Cron vs 心跳 (Heartbeat)

使用场景对比

Heartbeat 配置示例

总结

下一章

相关资源

相关文章

发表回复 取消回复

发表回复取消回复