cron

# 定时任务管理

## 什么时候用

只有在需要**未来某个时间自动执行**，或**按周期重复执行**时，使用本 skill。

### 应该使用
- 用户要求"每天 / 每周 / 每小时"执行某事
- 用户要求"明天 9 点 / 下周一 / 某个时间"自动提醒或执行
- 需要长期周期性通知、检查、汇报

### 不应使用
- 只是要**现在立即执行一次**
- 只是当前会话中的正常回复
- 用户没有明确执行时间或周期
- 目标 channel / user / session 还不明确

## 决策规则

1. **只有在未来定时执行或周期执行时才使用 cron**
2. **如果只是立即做一次，通常不要创建 cron**
3. **创建前必须确认执行时间/周期、目标 channel、target-user、target-session**
4. **所有 cron 命令都必须显式传 `--agent-id`**
5. **不要依赖默认 agent，否则任务可能落到 default workspace**
6. **如果 agent 任务只需后台执行、不向渠道输出，添加 `--silent`；执行、会话历史、追踪和可选收件箱记录仍会继续**

---

## 硬规则

### 必须显式指定 `--agent-id`

所有 `qwenpaw cron` 命令都**必须**传：

```bash
--agent-id <your_agent_id>
```

你的 agent_id 在系统提示中的 Agent Identity 部分（Your agent id is ...）。
不得省略，否则任务可能错误创建到 default agent 的 workspace。

---

## 常用命令

```bash
# 列出任务
qwenpaw cron list --agent-id <agent_id>

# 查看任务详情
qwenpaw cron get <job_id> --agent-id <agent_id>

# 查看任务状态
qwenpaw cron state <job_id> --agent-id <agent_id>

# 创建任务
qwenpaw cron create --agent-id <agent_id> ...

# 删除任务
qwenpaw cron delete <job_id> --agent-id <agent_id>

# 暂停 / 恢复任务
qwenpaw cron pause <job_id> --agent-id <agent_id>
qwenpaw cron resume <job_id> --agent-id <agent_id>

# 立即执行一次已有任务
qwenpaw cron run <job_id> --agent-id <agent_id>

# 更新已有任务
qwenpaw cron update <job_id> --agent-id <agent_id> ...
```

---

## 创建任务

支持两种类型：
- **text**：定时发送固定消息
- **agent**：定时向 agent 提问，并把回复发送到目标 channel

支持两种调度形态：
- **cron**（`--schedule-type cron`）：经典 cron 周期（如每天 9 点、每 2 小时），与循环任务相对应
- **scheduled**（`--schedule-type scheduled`）：日程任务（从 `--run-at` 开始，可一次性或按天重复）

### 调度选择规则（必须遵守）
- 用户表达“每小时/每天/每周”且不强调具体起始日时，优先用 `cron`
- 用户表达“明天/下周一/从某天开始/未来两周/有明确截止时间”时，优先用 `scheduled`
- `scheduled` 不重复时（即一次性任务）：只传 `--run-at`，不要传 `--repeat-*`
- `scheduled` 重复时：传 `--repeat-every-days`，并根据结束条件传：
  - 限定次数：`--repeat-end-type count --repeat-count N`
  - 限定结束时间：`--repeat-end-type until --repeat-until <ISO8601>`
  - 不设结束：`--repeat-end-type never`

### 超时设置

默认超时 120 秒（2 分钟）。对于较长的 agent 任务，应显式设置更大的超时时间，避免任务被提前取消：

```bash
--timeout 600   # 10 分钟
--timeout 3600   # 1 小时
```

**核心规则**：
1. 如果 agent 任务涉及联网搜索、代码执行或多步工具调用，建议设置 `--timeout 600` 或更高
2. **timeout 必须小于调度周期**，避免前一次执行未完成时下一次已触发，导致任务重叠运行。例如：
   - 每 15 分钟执行：`--timeout` 不应超过 900 秒
   - 每 10 分钟执行：`--timeout` 建议不超过间隔的 80%（即 480 秒）
   - 每天执行：`--timeout` 可以设置较大，不需要特别限制
3. 对于高频任务（间隔 ≤ 10 分钟），遵循 **timeout ≤ 调度间隔的 80%**；低频任务（每小时及以上）按实际需要设置即可

### 创建前最少要确认
- `--type`
- `--name`
- `--schedule-type`
- `--cron`（当 `--schedule-type cron`）
- `--run-at`（当 `--schedule-type scheduled`）
- `--channel`
- `--target-user`
- `--target-session`
- `--text`
- `--agent-id`
- `--timeout`（对于 agent 类型任务，根据预期执行时间设置合适的超时）

如果缺少这些信息，应先向用户确认，再创建任务。

### 创建示例

```bash
# 循环任务（对应 --schedule-type cron）
qwenpaw cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type cron \
  --name "每日早安" \
  --cron "0 9 * * *" \
  --channel imessage \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "早上好！"
```

```bash
# 循环任务（对应 --schedule-type cron）
qwenpaw cron create \
  --agent-id <agent_id> \
  --type agent \
  --schedule-type cron \
  --name "检查待办" \
  --cron "0 */2 * * *" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "我有什么待办事项？" \
  --timeout 600
```

如果是后台 agent 任务，可在上面的命令中添加 `--silent`。`text` 任务不能使用该参数。

```bash
# 日程一次性：明天 9 点提醒（不重复）
qwenpaw cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type scheduled \
  --name "明早提醒" \
  --run-at "2026-05-13T09:00:00+08:00" \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "9 点开组会" \
  --save-result-to-inbox
```

```bash
# 日程重复：未来两周每天 9 点（共 14 次）
qwenpaw cron create \
  --agent-id <agent_id> \
  --type text \
  --schedule-type scheduled \
  --name "未来两周组会提醒" \
  --run-at "2026-05-13T09:00:00+08:00" \
  --repeat-every-days 1 \
  --repeat-end-type count \
  --repeat-count 14 \
  --channel dingtalk \
  --target-user "CHANGEME" \
  --target-session "CHANGEME" \
  --text "9 点开组会" \
  --save-result-to-inbox
```

### 从 JSON 创建

```bash
qwenpaw cron create --agent-id <agent_id> -f job_spec.json
```

---

## 最小工作流

```
1. 判断是否真的是"未来定时"或"周期执行"
2. 确认执行时间/周期
3. 确认 channel、target-user、target-session
4. 显式带上 --agent-id
5. qwenpaw cron create 创建任务
6. 后续用 list / state / pause / resume / delete 管理
```

---

## Cron 表达式示例

```
0 9 * * *      每天 9:00
0 */2 * * *    每 2 小时
30 8 * * 1-5   工作日 8:30
0 0 * * 0      每周日零点
*/15 * * * *   每 15 分钟
```

---

## 常见错误

### 错误 1：把一次性立即执行当成 cron

如果只是现在执行一次，通常不要创建 cron。

### 错误 2：没传 --agent-id

这会导致任务落到错误的 agent / workspace。所有 cron 命令都必须显式传 `--agent-id`。

### 错误 3：信息没补全就创建

如果用户没说明时间、周期、目标 channel 或目标 session，应先追问。

### 错误 4：操作已有任务前不先查

暂停、恢复、删除前，先用：

```bash
qwenpaw cron list --agent-id <agent_id>
```

找到正确的 `job_id`。

---

## 使用建议

- 缺少参数时，先问用户再创建
- 修改/暂停/删除前，先 `qwenpaw cron list --agent-id <agent_id>`
- 排查问题时，用 `qwenpaw cron state <job_id> --agent-id <agent_id>`
- 给用户展示命令时，提供完整、可直接复制的版本
- 用户提到“结果进收件箱/不进收件箱”时，显式加 `--save-result-to-inbox` 或 `--no-save-result-to-inbox`，否则不要添加该项。
- 用户要求后台或静默执行且不向渠道回复时，对 `agent` 任务添加 `--silent`。

---

## 帮助信息

```bash
qwenpaw cron -h
qwenpaw cron list -h
qwenpaw cron create -h
qwenpaw cron get -h
qwenpaw cron state -h
qwenpaw cron pause -h
qwenpaw cron resume -h
qwenpaw cron delete -h
qwenpaw cron run -h
```