# Claude Code 定时调度 (Cron) 功能

> **官方文档**: https://code.claude.com/docs/en/scheduled-tasks.md
> **工具参考**: https://code.claude.com/docs/en/tools-reference.md
> **文档索引**: https://code.claude.com/docs/en/claude_code_docs_map.md

## 概述

Claude Code 原生支持定时调度，通过 `CronCreate` / `CronList` / `CronDelete` 三个原生工具实现。

## 核心工具

| 工具 | 用途 |
|------|------|
| `CronCreate` | 创建定时任务。接受 5-field cron 表达式 + prompt + 是否循环 |
| `CronList` | 列出当前所有定时任务及其 ID、调度、prompt |
| `CronDelete` | 通过 8 位 ID 取消指定任务 |

## Cron 表达式格式

标准 5-field: `minute hour day-of-month month day-of-week`

| 表达式 | 含义 |
|--------|------|
| `*/5 * * * *` | 每 5 分钟 |
| `*/3 * * * *` | 每 3 分钟 |
| `*/30 * * * *` | 每 30 分钟 |
| `0 * * * *` | 每小时整点 |
| `0 9 * * *` | 每天早 9 点 |
| `0 9 * * 1-5` | 工作日早 9 点 |

## 调度方式对比

| | Cloud | Desktop /schedule | /loop (CLI) |
|---|---|---|---|
| 运行在 | Anthropic 云端 | 本地机器 | 本地机器 |
| 需要机器开启 | 否 | 是 | 是 |
| 需要打开会话 | 否 | 否 | **是** |
| 跨重启持久化 | 是 | 是 | **否 (session-scoped)** |
| 访问本地文件 | 否 | 是 | 是 |
| 最小间隔 | 1 小时 | 1 分钟 | 1 分钟 |

## 关键限制

1. **Session-scoped**: `/loop` 和 `CronCreate` 创建的任务仅在 Claude Code 运行且空闲时触发。关闭终端或退出会话后，所有任务取消。
2. **3 天过期**: 循环任务自动在 3 天后过期，防止无限运行。
3. **最多 50 个**: 每个会话最多 50 个并发定时任务。
4. **不补发**: 如果任务触发时 Claude 正在忙，等空闲后只触发一次，不补发错过的。
5. **Jitter**: 循环任务有最多 10% 的延迟抖动（上限 15 分钟）。

## LemonBoss 持久化方案

由于 CronCreate 是 session-scoped，我们使用 **cron.json + 会话启动自动注入** 来实现持久化：

### cron.json 格式

```json
[
  {
    "schedule": "*/5 * * * *",
    "prompt": "读取 plan.md 检查已分发任务进度",
    "recurring": true,
    "enabled": true
  }
]
```

### 工作流程

1. Agent 目录下有 `cron.json` 定义期望的定时任务
2. 每次新建 ACP 会话时，后端自动读取 cron.json
3. 在第一条 system prompt 中注入 CronCreate 恢复指令
4. Agent 调用 CronCreate 重建所有定时任务

### 文件位置

- 文档: `docs/done/claude-code-cron.md` (本文件)
- 模板: `packages/agent-core/AgentScaffold.js` (_defaultCronJson)
- 注入点: `server/routes/agent-chat.js` (buildPrompt)
- Agent 配置: `data/agents/{agent-id}/cron.json`