Cron 自动化

August 23, 2026 · View on GitHub

使用 HotPlex Cron 调度器实现 AI Agent 自动化工作流

概述

HotPlex 内置 AI-native Cron 调度器，支持从自然语言到自动化执行的完整流程。不同于传统 cron 系统，HotPlex 的定时任务由 AI Agent 执行——你只需用自然语言描述任务，Agent 会自主完成。

核心架构（internal/cron/）：

组件文件职责
Schedulercron.go任务生命周期管理、内存索引、CRUD
timerLooptimer.gotick 引擎、collect → 并发槽 → execute
Storestore.goSQLite 持久化
Executorexecutor.goWorker 执行适配、Session 构造、环境注入
Deliverydelivery.go结果投递到飞书/Slack
CLI routingembedded hotplex-cliCron 的 canonical Skill route；不可用时以当前 hotplex cron --help/create --help 为准

三种调度模式

cron 表达式（周期性任务）

标准 5 段 cron 表达式，支持周几映射：

hotplex cron create \
  --name "weekday-standup" \
  --schedule "cron:0 9 * * 1-5" \
  -m "生成本日 standup 报告" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID"

hotplex cron get <JOB_ID> --json
字段允许值特殊字符
分钟0-59* , -
小时0-23* , -
日1-31* , - ?
月1-12* , -
周几0-6（0=周日）* , - ?

every 固定间隔

按固定间隔执行，支持 s/m/h 单位：

hotplex cron create \
  --name "health-check" \
  --schedule "every:30m" \
  -m "检查系统健康状态" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID"

hotplex cron get <JOB_ID> --json

at 一次性延迟任务

指定精确时间执行一次，支持绝对 RFC3339 或 parser 接受的 at:+10m 相对形式，并支持指数退避重试：

hotplex cron create \
  --name "deploy-verify" \
  --schedule "at:2026-05-15T09:00:00+08:00" \
  -m "验证生产环境部署是否成功" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID"

hotplex cron get <JOB_ID> --json

常见自动化模式

每日健康检查

hotplex cron create \
  --name "daily-health" \
  --schedule "cron:0 9 * * 1-5" \
  -m "执行以下检查并报告：
1. 运行 go test ./... 确认所有测试通过
2. 检查 go vet 是否有警告
3. 运行 golangci-lint
4. go vuln check 检查安全漏洞" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID"

hotplex cron get <JOB_ID> --json

部署后验证

hotplex cron create \
  --name "post-deploy" \
  --schedule "at:2026-05-11T14:30:00+08:00" \
  -m "部署刚完成，请验证：
1. curl /health 返回 200
2. 检查最近 5 分钟的错误日志
3. 验证数据库连接正常" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID"

hotplex cron get <JOB_ID> --json

带生命周期的提醒

hotplex cron create \
  --name "water-reminder" \
  --schedule "every:30m" \
  -m "提醒：该喝水了！" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID" \
  --max-runs 8 \
  --expires-at "2026-05-11T18:00:00+08:00"

hotplex cron get <JOB_ID> --json

任务在执行 8 次或到达过期时间后自动停止（以先到者为准）。

执行上下文

Cron 任务执行时，Gateway 通过 platformKey（map[string]string 形式）传递任务元数据，而非进程环境变量：

platformKey 字段说明
cron_job_idCron 任务 ID
bot_id触发任务的 Bot ID（对应 CLI --bot-id）
owner_id任务所有者 ID（对应 CLI --owner-id）
channel_idSlack Channel ID（结果投递目标）
chat_id飞书 Chat ID（结果投递目标）

这些字段在 executor.go 中通过 platformKey := map[string]string{"cron_job_id": job.ID} 构造，传递给 StartSession 作为平台路由依据。

任务消息自动添加执行上下文前缀：

[cron:<job_id> <job_name>] <你的消息内容>
2026-05-10T09:00:00+08:00

Agent 能看到任务 ID、名称和执行时间，据此调整行为。

结合 Agent 能力

Cron 任务由完整的 AI Agent 执行，可以使用所有配置的 Tool。通过 --allowed-tools 限制可用工具：

# 只读检查任务，限制为只读工具
hotplex cron create \
  --name "safe-check" \
  --schedule "cron:0 9 * * *" \
  -m "检查代码质量" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID" \
  --allowed-tools "read_file,grep,glob"

hotplex cron get <JOB_ID> --json

监控 Cron 任务

执行历史

hotplex cron history daily-health        # 查看历史
hotplex cron history daily-health --json # JSON 格式

任务状态追踪

每个 CronJob 维护运行时状态（CronJobState）：

字段说明
last_status最近一次执行结果（success/failed/timeout）
consecutive_errors连续错误次数
run_count总执行次数
last_run_at_ms最近执行时间
next_run_at_ms下次计划执行时间

Silent 模式

后台维护任务不需要投递结果给用户，启用 Silent 模式：

hotplex cron create \
  --name "cache-cleanup" \
  --schedule "cron:0 3 * * *" \
  -m "清理过期的临时文件和缓存" \
  --bot-id "$BOT_ID" --owner-id "$USER_ID" \
  --silent

hotplex cron get <JOB_ID> --json

Silent 模式下任务正常执行，但不发送消息卡片到飞书/Slack。

一次性任务 vs 周期性任务

维度at 类型cron/every 类型
执行次数1 次持续执行
自动清理--delete-after-run 可选需手动删除
生命周期expires_at 自然过期max_runs + expires_at
重试机制指数退避重试（max_retries）无自动重试
适用场景部署验证、延迟通知定期检查、持续监控

管理命令

# 列出所有任务
hotplex cron list [--json] [--enabled]

# 查看任务详情
hotplex cron get <id|name>

# 手动触发（需 Gateway 运行中）
hotplex cron trigger <id|name>

# 更新任务
hotplex cron update <id|name> --enabled=false

# 删除任务
hotplex cron delete <id|name>

执行流程

timerLoop tick → collectDue → CAS 并发槽 → executeJob → Worker 执行 → 结果投递
  1. collectDue：收集 NextRunAtMs <= now 且未在执行中的任务
  2. 并发槽 CAS：maxConcurrent（默认 3）限制同时执行数，atomic.Int32 保护
  3. executeJob：
    • DeriveCronSessionKey(jobID, epoch) 生成唯一 Session Key（独立 UUIDv5 命名空间）
    • 构造 Session，注入环境变量
    • 调用 Agent 执行任务
  4. 结果投递：按 platform 字段发送到飞书卡片或 Slack 消息

自然语言创建

Cron 请求优先路由到当前 Session 实际暴露的 embedded hotplex-cli canonical Skill；不可用时 查询当前二进制的 hotplex cron --help 与 hotplex cron create --help。真实 Skill 只以 <name>/SKILL.md 为入口，Scheduler 启动不向 Skills 目录发布 flat Markdown 手册。Agent 可通过 自然语言识别调度意图：

  1. 用户发送"每天早上 9 点检查代码质量"
  2. Brain 层 Router 识别为 cron 意图
  3. Agent 自动调用 CLI 创建 cron job
  4. 结果回传给用户

Prometheus 监控

指标类型说明
cron_fires_totalCounter任务触发次数
cron_errors_totalCounter执行错误
cron_duration_secondsHistogram执行时长