> 功能说明: 本技能涵盖 中文交互、化工作流场景 等核心能力。

Skill平台 Cron Setup

Cron 是 Gateway 内置的调度器，持久化存储任务，在指定时间唤醒 agent 执行，并可选择将结果投递到聊天频道。

核心概念

两种执行模式

三种调度类型

部署指引

1. 创建一次性提醒（主会话）

skill-platform cron add \
  --name "提醒事项" \
  --at "20m" \
  --session main \
  --system-event "20 分钟后检查日历" \
  --wake now \
  --delete-after-run

2. 创建周期性任务（独立会话）

skill-platform cron add \
  --name "晨间简报" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结昨晚的邮件和日历事件" \
  --announce \
  --channel telegram \
  --to "+8613800138000"

3. 创建带模型覆盖的深度任务

skill-platform cron add \
  --name "周报分析" \
  --cron "0 9 * * 1" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "分析本周项目进展" \
  --model "opus" \
  --thinking high \
  --announce \
  --channel whatsapp \
  --to "+8613800138000"

常用命令

skill-platform cron list

skill-platform cron run <job-id>

skill-platform cron runs --id <job-id> --limit 10

skill-platform cron edit <job-id> --message "新提示词"

skill-platform cron remove <job-id>

JSON Schema（工具调用）

一次性主会话任务

{
  "name": "提醒",
  "schedule": { "kind": "at", "at": "2026-03-04T10:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "提醒内容" },
  "deleteAfterRun": true
}

周期性独立会话任务

{
  "name": "晨间简报",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": { "kind": "agentTurn", "message": "总结隔夜更新" },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "+8613800138000",
    "bestEffort": true
  }
}

投递模式（Delivery）

仅适用于 isolated 任务：

省略 delivery 时默认行为： announce 模式

Telegram 话题投递

支持论坛话题（topic）：

--to "-1001234567890:topic:123"  # 推荐：显式话题标记
--to "-1001234567890:123"         # 简写：数字后缀

示例

当前工作配置示例（$HOME/.skill-platform/cron/jobs.json）：

{
  "name": "daily-health-summary",
  "schedule": {
    "kind": "cron",
    "expr": "0 10 * * *",
    "tz": "Asia/Shanghai"
  },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "从 Bitable 查询健康数据并生成总结"
  },
  "delivery": {
    "mode": "none",
    "channel": "last"
  }
}

高级配置

在 $HOME/.skill-platform/config.json 中：

json5

{
  cron: {
    enabled: true,
    sessionRetention: "24h",      // 独立会话保留时长
    runLog: {
      maxBytes: "2mb",            // 运行日志最大大小
      keepLines: 2000,            // 保留行数
    },
  }
}

Cron vs Heartbeat

文档来源： <https://docs.skill-platform.ai/automation/cron-jobs>

安装与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明

API Key 配置

• 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

可用性分类

• 分类: MD+execute(纯Markdown指令,部分功能需要exec命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

能力矩阵

• Gateway 内置定时任务调度器
• 用于创建一次性提醒、周期性任务、后台自动化
• 支持主会话系统事件和独立会话执行，可配置投递到聊天频道或
  Webhook
• 触发关键词: 周期性任务, setup, 性提醒, 用于创建一次, webhook, cron, , 内置定时任务

典型场景

不适用于：需要人工判断的复杂决策场景

疑问整理

Q1: 如何开始使用 Cron Setup？

A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

Q2: 遇到错误怎么办？

A: 请参考错误处理章节，按照表格中的处理方式操作。

Q3: Cron Setup有什么限制？

A: 请参考已知限制章节了解具体限制。

能力边界

• 需要LLM支持，无LLM环境无法使用
• 复杂场景可能需要人工辅助判断
• 性能取决于底层模型能力

安全保证

安全风险防范

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

效能分析

差异分析

帮助指南

Q1: Cron Setup支持哪些输入格式？

A1: Gateway 内置定时任务调度器。支持主会话系统事件和独立会话执行，可配置投递到聊天频道或。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

异常恢复指引

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

Cron Setup通用排查步骤

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