cron

Files (2)

• SKILL.md
• tools.ts

SKILL.md (first lines)

# Cron Skill

管理 MaxClaw 的定时任务系统。

## 核心模型（2026-07-28 重构）

**Cron 没有独立常驻 agent。** 三种 payload：

| kind | 执行方式 |
|---|---|
| `channel-message` | 把任务文本注入目标 channel，由该 channel 的 agent **带完整上下文**执行 |
| `notification` | 确定性写通知（无 agent loop），适合静态提醒 |
| `script` | 本地脚本（`cron-tasks/` 或 `data/cron-tasks/`），无 agent loop、零 token |

旧 `message` / `skill` kind（创建孤立 cron session 的全权限零上下文 agent）已彻底移除。
历史教训（2026-06-11）：孤立 cron agent 与活跃会话并行修改同一容器/文件互相踩踏。
channel-message 模式下消息进入目标 session 的**串行队列**（session-queue），与该
channel 的用户消息排同一队列，结构上杜绝并行冲突；且 agent 记得 channel 历史
（上次执行结果、Max 最近的指示）。

`native` kind（内建任务 registry）2026-07-28 消灭：**定时任务不引入代码部分**——
加任务不该等于改源码发布。原四个 native 任务全部移植为 `cron-tasks/` 脚本。

## script kind：确定性门 + 按需 agent 接力

巡检类任务的正确形态：**门是确定性代码**（df、阈值比较——每次触发零 token），
**只有触发阈值才叫醒 agent**。脚本 stdout 协议：

- `{"title","body","topic"?,"severity"?}` → 写 notification（告警永远由脚本确定性
  写出，不依赖 LLM 成功）；
- `{"wake":{"subagent":"任务文本","model"?,"timeoutMs"?}}` → 派一次性隔离 subagent
  （默认 palette:light / 5min）同步跑完，出口由任务文本约定（通常自己写
  notification）——机械诊断/体力活用这个，别借宿 channel 烧默认模型；
- `{"wake":{"channel":"web:chat-x","text":"..."}}` → 借宿已有 channel 接力
  （需要上下文连续性或 Max 在场交互时）；
- 非 JSON 行 → 日志；非零退出/超时/wake 被拒 → cron 统一失败告警。

何时用哪个：

- 任务**每次运行都需要 LLM 判断/多步工具操作**（周报生成、reflection）
  → `channel-message`，接受全上下文成本。
- 任务**正常路径是纯检查、异常才需要分析**（磁盘水位、库存轮询、连胜核验）
  → `script`（+ wake），别把主 channel agent 当 `df | awk` 用。
- 纯静态提醒 → `notification`。

零 token ≠ 静默：正常路径也发 info 心跳通知，否则"跑了正常"和"根本没跑"无法区分。
repo 内的范例脚本：`vps-stock-watch.ts`（纯轮询）、`disk-watchdog.ts`（门 +
wake-subagent enrich）、`health-audit.ts`（sqlite 直读门）、`duolingo-gate.ts` +
`duolingo-verify.ts`（CDP 门 + wake-subagent 练习 + 独立复检 job——"不信任
subagent 自述"的复检纪律用调度器编排保住）。

## channel-message 语义

- `channel` 省略时默认**当前调用方 channel**——给自己所在对话挂定时任务零成本。
- 当前仅支持 `web:*` target；目标 chat 不存在时注入会自动建 session（出现在 sidebar）。
- 触发时任务文本被框架包裹为 `<framework from="cron:<任务名>" trust="system">`，
  payload text **不要自带 framework 标签**。
- agent 的回复直接出现在目标 channel 里——channel 即出口，没有"完成通知"。
  需要结构化事件（告警、异常分支）时，由执行 agent 在任务文本指示下调 `notification_create`。
- 注入失败（channel 不可用）→ 自动写 `topic='cron'` severity=alert 的失败告警。
- 系统级任务（不属于任何活跃对话的巡检/扫描类）统一收口到专用 chat
  `web:chat-cron-tasks`，避免散落污染日常对话。

## 工具列表

- **cron_list** — 列出所有定时任务
- **cron_add** — 添加定时任务
- **cron_update** — 按 id 更新已有任务的部分字段（name/schedule/payload/enabled），保留原 id 和 createdAt/lastRunAt。修改已有任务用这个，不要 cron_remove + cron_add——那样会换 id、丢运行历史，且非原子（remove 成功后 add 失败就任务没了）
- **cron_remove** — 删除定时任务（按 id）
- **cron_run_now** — 立即触发某个任务（按 id）

## Schedule 格式

| kind    | 字段         | 示例                                      |
|---------|-------------|-------------------------------------------|
| `cron`  | `expr`, `tz` | `{ kind: "cron", expr: "0 9 * * *", tz: "Asia/Shanghai" }` |
| `at`    | `at`         | `{ kind: "at", at: "2025-07-10T21:00:00+08:00" }` |
| `every` | `everyMs`    | `{ kind: "every", everyMs: 3600000 }` （1小时）|

## Payload 示例

```json
{
  "kind": "channel-message",
  "channel": "web:chat-cron-tasks",
  "text": "执行每周 clawt-engine-v2 审计：读 anchor 文档 + 查 PnL/drawdown + 漂移检查，异常时 notification_create(topic='clawt')。"
}
```

```json
{
  "kind": "notification",
  "title": "本周菜谱提醒",
  "body": "早上好～本周菜谱发我一下？我好帮你做饮食分析和推荐 🍽",
  "topic": "meal-menu"
}
```

```json
{
  "kind": "script",
  "path": "data/cron-tasks/my-watch.ts"
}
```

`notification` 可选字段：`topic`（默认 cron）、`severity`（默认 info）、`pushChannels`
（额外推送目标，自动 union `telegram:private` 全量通知出口）。

## 注意

- `at` 类型是一次性任务，触发后自动删除。
- `cron` 表达式使用标准 5 字段格式（分 时 日 月 周）。
- 时区默认 UTC，中国时间请指定 `tz: "Asia/Shanghai"`。
- 写 channel-message 任务文本时面向"将来在 channel 里执行的 agent"：写清步骤、
  数据源、异常分支；该 agent 看得到 channel 历史，可以引用"本 channel 之前的讨论"。
- 任务文本里若需要静默语义（正常时不打扰），直接在 text 里写"正常时简短回复一句即可，
  不要创建 notification"——没有 silent 字段了。

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss