# 定时任务

CodeBuddy Code 支持在会话中创建和管理定时任务，可以按照设定的时间表重复执行指令，或者在未来某个时间点触发一次性操作。常见用途包括：定期检查构建状态、轮询任务完成情况、在特定时间点提醒自己等。

> **注意**：定时任务是会话级别的。任务只在 CodeBuddy Code 运行期间有效，退出后自动清除。


## 创建一次性提醒

如果只需要在未来某个时间点提醒一次，可以直接用自然语言描述：

```
下午四点半提醒我同步一下今天的进展
```

```
一个小时后看看刚才那个构建任务有没有产出
```

```
明天早上 9 点帮我生成一份昨天的工作日报
```

这类任务会在指定时间触发一次，执行完毕后自动删除。

---

## 管理已有任务

### 查看当前所有任务

```
我现在有哪些定时任务？
```

列表中包含任务 ID、执行频率、任务类型（循环 / 一次性）以及对应的指令。

### 取消任务

```
取消部署检查的定时任务
```

或者通过任务 ID 取消：

```
帮我删掉 ID 为 xxx 的定时任务
```

底层分别对应 `CronList` 和 `CronDelete` 工具，可以通过对话直接操作，无需记住具体命令。

---

## 任务执行机制

### 执行时机

任务只会在会话**空闲**时触发，即系统没有在处理其他请求的时候。如果正好在执行某个操作，触发时间会顺延到操作完成后。

### 时间偏移（Jitter）

系统会对任务的触发时间添加少量随机偏移，以避免大量任务同时执行带来的拥堵：

- **循环任务**：最多延迟周期时长的 10%（上限 15 分钟）
- **一次性任务**：对于整点和半点任务，最多提前 90 秒执行

例如，设置 `每小时` 执行的任务，实际触发时间可能在整点后的 0-6 分钟内随机分布。

### 自动过期

**循环任务在创建 3 天后自动过期删除**，过期前会最后触发一次。  
如果需要任务持续更长时间，可以在过期后重新创建，或者改用外部调度方案（如 GitHub Actions 等）。

---

## Cron 表达式参考


需要「每周一早上 10 点」「每月 1 号」这类精确时间，直接告诉 AI 你的需求，它会自动转成 cron 表达式并创建任务：

```
每周一早上 10 点帮我生成本周的工作计划
```

```
每月 1 号早上统计上个月的代码提交量，按人汇总
```

```
每周五下午 5:30 提醒我同步进度、更新任务状态
```

```
每天中午 12 点检查一下有没有待我审查的 PR
```

```
工作日早上 9:15 把昨天未合并的 PR 列出来
```

AI 回复时会告诉你实际使用的 cron 表达式和执行频率，方便确认是否符合预期。

**格式：**
```
分钟  小时  日期  月份  周几
```

**常用表达式：**

| 表达式 | 含义 |
|--------|------|
| `*/5 * * * *` | 每 5 分钟 |
| `*/15 * * * *` | 每 15 分钟 |
| `0 * * * *` | 每小时整点 |
| `0 9 * * *` | 每天上午 9 点 |
| `0 9 * * 1-5` | 工作日上午 9 点 |
| `0 0 1 * *` | 每月 1 日午夜 |
| `30 18 * * 5` | 每周五下午 6:30 |

**字段说明：**

| 字段 | 取值范围 | 特殊符号 |
|------|---------|---------|
| 分钟 | 0–59 | `*`（任意）、`*/N`（每 N 分钟）、`N,M`（列举）、`N-M`（范围）|
| 小时 | 0–23 | 同上 |
| 日期 | 1–31 | 同上 |
| 月份 | 1–12 | 同上 |
| 周几 | 0–6 | 0 或 7 = 周日，1 = 周一，依此类推 |

---

## 注意事项

| 事项 | 说明 |
|------|------|
| **会话绑定** | 任务随会话存在，CodeBuddy Code 退出后任务消失，不会写入磁盘 |
| **循环任务上限** | 每个会话最多同时存在 50 个定时任务 |
| **最小间隔** | 1 分钟（秒级设置会被自动向上取整） |
| **任务过期** | 循环任务 3 天后自动清除 |
| **不补跑** | 会话中断期间错过的任务不会补发执行 |

---

## 禁用定时任务

如果需要完全关闭定时任务功能，可以设置环境变量：

```bash
CODEBUDDY_DISABLE_CRON=1 codebuddy
```

启用后，`/loop` 技能不再可用，`CronCreate`、`CronList`、`CronDelete` 工具也会被禁用。

---

## 相关文档

- [技能系统](./skills.md)
- [斜杠命令参考](./slash-commands.md)
- [会话与上下文管理](./cli-reference.md)
- [Hooks 事件系统](./hooks.md)
