@tencent-ai/codebuddy-code 2.67.0 → 2.68.0

package/dist/web-ui/docs/cn/cli/scheduled-tasks.md

@@ -0,0 +1,161 @@
+# 定时任务
+
+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)