---
name: cron
description: 通过 lightclaw 命令管理定时任务 - 创建、查询、暂停、恢复、删除任务
metadata: { "lightclaw": { "emoji": "⏰" } }
---

# 定时任务管理

使用 `lightclaw cron` 命令管理定时任务。

## 理解用户意图

用户想要定时任务时，**不要要求用户提供所有参数**。根据上下文主动推断：

| 用户说的 | 你应该做的 |
|---------|-----------|
| "每天早上 9 点提醒我喝水" | type=text, cron="0 9 * * *", text="该喝水了！💧" |
| "每天下午 5 点帮我总结今天的工作" | type=agent, cron="0 17 * * *", text="请帮我总结今天的工作进展" |
| "工作日每天提醒我站会" | type=text, cron="0 10 * * 1-5", text="站会时间到！" |
| "每周一早上发周报提醒" | type=text, cron="0 9 * * 1", text="本周周报该写了！" |
| "每 2 小时检查一下服务器状态" | type=agent, cron="0 */2 * * *", text="检查服务器运行状态" |

**判断 type 的原则**：
- 用户只是想**收到一条固定消息** → `text`
- 用户想让 **Agent 思考/查询/分析后回复** → `agent`

## 常用命令

```bash
# 列出所有任务
lightclaw cron list

# 查看任务详情（包含完整配置）
lightclaw cron get <job_id>

# 删除任务
lightclaw cron delete <job_id>

# 暂停任务（不删除，可恢复）
lightclaw cron pause <job_id>

# 恢复已暂停的任务
lightclaw cron resume <job_id>

# 立即执行一次（需要 LightClaw 服务运行中）
lightclaw cron run <job_id>
```

> **提示**：`pause`/`resume`/`delete` 操作前，先用 `lightclaw cron list` 查找 job_id。

## 创建任务

### 完整命令格式

```bash
lightclaw cron create \
  --type <text|agent> \
  --name <任务名称> \
  --cron "<cron表达式>" \
  --channel <频道，逗号分隔多个> \
  --target-user <用户标识> \
  --target-session <会话标识> \
  --text <消息内容> \
  --timezone <时区> \
  --mode <stream|final> \
  --enabled/--no-enabled
```

### 参数详解

#### `--type`（必填）

任务类型，决定任务执行时的行为：

| 值 | 行为 | 适用场景 |
|----|------|---------|
| `text` | 直接把 `--text` 的内容**原样发送**到频道 | 固定提醒、通知、打卡提示 |
| `agent` | 把 `--text` 作为**提问发送给 Agent**，Agent 的回复发送到频道 | 定时汇总、数据查询、智能分析 |

#### `--name`（必填）

任务显示名称，用于 `list` 时识别任务。取一个简洁有意义的名字，如 "每日早安"、"服务器巡检"。

#### `--cron`（必填）

标准 5 段 cron 表达式：`分钟 小时 日 月 星期`

```
┌───────────── 分钟 (0-59)
│ ┌─────────── 小时 (0-23)
│ │ ┌───────── 日 (1-31)
│ │ │ ┌─────── 月 (1-12)
│ │ │ │ ┌───── 星期 (0-6，0=周日)
│ │ │ │ │
* * * * *
```

**常用示例**：

| 表达式 | 含义 |
|--------|------|
| `0 9 * * *` | 每天 9:00 |
| `30 8 * * 1-5` | 工作日 8:30 |
| `0 */2 * * *` | 每 2 小时整点 |
| `*/15 * * * *` | 每 15 分钟 |
| `0 9 * * 1` | 每周一 9:00 |
| `0 0 1 * *` | 每月 1 号零点 |
| `0 9,18 * * *` | 每天 9:00 和 18:00 |
| `0 0 * * 0` | 每周日零点 |

> **注意**：不支持秒级精度（6 段表达式）。支持 4 段和 3 段的简写形式（自动补零）。

#### `--channel`（必填，支持多频道）

消息投递的目标频道，支持逗号分隔指定多个频道（如 `--channel dashboard,dingtalk`）。**默认应使用当前上下文中的 channel（即用户发送创建指令时所在的频道）**。可用频道取决于你已配置的频道：

| 值 | 说明 | target-user / target-session 含义 |
|----|------|----------------------------------|
| `dashboard` | Web 控制台（默认频道） | user_id 和 session_id 使用 "main" 即可 |
| `dingtalk` | 钉钉 | user_id = 发送者标识，session_id = 会话 ID（conversation_id 的后缀）。**注意**：需要用户先和机器人聊过天才能主动推送（sessionWebhook 有有效期） |
| `discord` | Discord | session_id 格式为 `discord:ch:<channel_id>`（频道消息）或 `discord:dm:<user_id>`（私信） |
| `qq` | QQ | user_id = 用户 openid，session_id 可包含 `group:<group_openid>` 或 `channel:<channel_id>` |
| `feishu` | 飞书 | session_id 格式为 `feishu:chat_id:<chat_id>`（群聊）或 `feishu:open_id:<open_id>`（私聊） |

#### `--target-user`（推荐从上下文获取）

消息接收者的用户标识。**默认应使用当前上下文中的 `user_id`**，确保定时任务结果能发回给发起者。不同频道的含义不同（见上方表格）。如果省略，CLI 会自动从该频道最近的聊天记录中解析。

#### `--target-session`（推荐从上下文获取）

消息投递的会话标识。**默认应使用当前上下文中的 `session_id`**，确保定时任务结果能发回到同一个会话。不同频道的含义不同（见上方表格）。如果省略，CLI 会自动从该频道最近的聊天记录中解析。

#### `--text`（必填）

- **text 类型**：原样发送的消息内容
- **agent 类型**：发送给 Agent 的提问/指令，Agent 会思考后回复

#### `--timezone`（默认 "UTC"）

cron 表达式使用的时区。常用值：
- `Asia/Shanghai` — 北京时间
- `Asia/Tokyo` — 东京时间
- `America/New_York` — 美东时间
- `Europe/London` — 伦敦时间
- `UTC` — 协调世界时

> **重要**：用户说 "每天早上 9 点" 时，应确认其时区。中国用户默认用 `Asia/Shanghai`。

#### `--mode`（默认 "final"）

消息投递模式：
- `final` — 等待完成后一次性发送最终结果（推荐）
- `stream` — 流式逐步发送中间结果

#### `--enabled / --no-enabled`（默认启用）

创建时是否立即启用。`--no-enabled` 可以先创建但不激活。

### 快速创建示例

```bash
# 中国用户：每天早上 9 点发送早安（北京时间）
lightclaw cron create \
  --type text \
  --name "每日早安" \
  --cron "0 9 * * *" \
  --timezone "Asia/Shanghai" \
  --channel dashboard \
  --text "早上好！新的一天开始了 ☀️"

# 每 2 小时让 Agent 汇总待办
lightclaw cron create \
  --type agent \
  --name "待办汇总" \
  --cron "0 */2 * * *" \
  --timezone "Asia/Shanghai" \
  --channel dashboard \
  --text "请帮我检查并汇总当前的待办事项"

# 工作日下午 5 点让 Agent 总结当天工作
lightclaw cron create \
  --type agent \
  --name "日报生成" \
  --cron "0 17 * * 1-5" \
  --timezone "Asia/Shanghai" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "请帮我生成今天的工作日报"

# 多频道投递：同时发送到 dashboard 和钉钉
lightclaw cron create \
  --type text \
  --name "双通道提醒" \
  --cron "0 9 * * 1-5" \
  --timezone "Asia/Shanghai" \
  --channel dashboard,dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "工作日早安提醒 ☀️"
```

### 从 JSON 文件创建（高级）

```bash
lightclaw cron create -f job_spec.json
```

JSON 文件格式参考：

```json
{
  "name": "每日巡检",
  "enabled": true,
  "task_type": "agent",
  "schedule": {
    "cron": "0 9 * * *",
    "timezone": "Asia/Shanghai"
  },
  "dispatch": {
    "channel": ["dashboard"],
    "target": {
      "user_id": "default",
      "session_id": "default"
    },
    "mode": "final"
  },
  "request": {
    "input": [
      {
        "role": "user",
        "type": "message",
        "content": [{ "type": "text", "text": "执行每日系统巡检" }]
      }
    ]
  },
  "runtime": {
    "max_concurrency": 1,
    "timeout_seconds": 120,
    "misfire_grace_seconds": 60
  }
}
```

## 使用策略

1. **投递目标默认使用当前上下文**：用户在哪个 channel 发的创建指令，就默认把该 channel 作为 `--channel`，同时把当前上下文中的 `user_id` 作为 `--target-user`、`session_id` 作为 `--target-session`。这样可以确保定时任务的结果回复到用户发起请求的同一个会话中。只有用户明确指定了其他频道或目标时才覆盖。
2. **缺参数时主动推断**：用户只说了想做什么和频率，就帮他补全其他参数，确认后再创建
3. **时区敏感**：问清用户所在时区，中国用户默认 `Asia/Shanghai`
4. **操作前先查**：暂停/删除/恢复前，先 `lightclaw cron list` 查找目标任务的 job_id
5. **给用户的命令要完整**：可直接复制执行，不要留占位符
6. **`run` 需要服务在线**：`lightclaw cron run` 是通过 HTTP API 触发服务端执行，需要 LightClaw 服务正在运行
