定时任务让 Cockpit 按计划替你跑一个 AI prompt —— 延迟一次性、每 N 分钟、或按 cron 表达式。给那些你本来要每天早上、每小时、每周五下午记住做的事用。

## 打开面板

侧栏有**定时任务**面板(时钟图标)。列出你设过的所有任务,带新建、编辑、暂停 / 恢复、立即运行、删除、拖动重排的控件。

## 三种调度方式

新建任务时选三种调度类型之一:

| 类型 | 什么时候跑 | 填什么字段 |
|---|---|---|
| **Once** | 延迟一次性 | `delayMinutes` —— 从现在起多少分钟 |
| **Interval** | 每 N 分钟重复 | `intervalMinutes` —— 多久一次。可选 `activeFrom` / `activeTo` **时段窗口**(`HH:MM` 格式;支持跨午夜,比如 `22:00–06:00`) |
| **Cron** | 标准 cron 表达式 | **5 字段**(分 时 日 月 周),例 `0 9 * * *`(每天 9 点)。不支持秒字段。 |

任务面板每行尾会显示距离下次触发的**倒计时**(比如 `下次:23 分钟后`),实时刷新。

## 你填什么

一个定时任务带:

- **项目** —— 跑在哪个项目的工作目录里。
- **引擎** —— Claude / Codex / DeepSeek / Kimi / Ollama。
- **prompt** —— 发什么消息。单行可以、多行也行。
- **调度** —— 上面三种之一。

典型的早上任务长这样:

```
项目: ~/code/my-service
引擎: Claude
调度: cron, 工作日早上 9 点  (0 9 * * 1-5)
prompt: 总结这个仓库昨天合并的 PR:标题、作者、改动的文件、
        一句话说明"为什么重要"。按功能区分组。
```

## 同一个会话累计跑

**每个定时任务绑定一个 sessionId** —— 每次触发都用 `resume` 续在那个 session 后面,不开新会话。所以:

- 多次触发的输出**累积在同一个聊天里**,后面的提问能看到前面的回复。AI 有"我之前已经汇报过昨天的 PR 了"这类记忆。
- 适合需要"长期跟进同一件事"的场景(每日 PR 汇报、巡查、监控)。
- 想要每次干净从头开始?**删了任务重新建一个**,这样会拿到新 sessionId。

## 任务跑完后

每个任务显示**最后一次运行状态**(✓ success / ✗ error),以及如果你还没读结果会有个**红点**提示。点任务打开它跑在的会话 —— AI 的回复在那。红点清除。

定时任务跑完也会触发[会话完成 toast](/zh/docs/agent/sessions/#会话完成-toast),跟你自己启动的任务一样。

## 手动控制

| 按钮 | 做什么 |
|---|---|
| **✏ 编辑** | 改 prompt / 调度 / 引擎等。 |
| **▶ 立即运行** | 不等计划立刻触发任务(还是续在 sessionId 后)。 |
| **⏸ 暂停 / ▶ 恢复** | 切换;暂停期间不触发计划运行,恢复后按下一个计划点继续。 |
| **✕ 删除** | 移除任务(下次想干净 session 时也用它)。 |
| **拖动手柄** | 在面板里重排序。 |

## Cockpit 必须开着

定时任务从 Cockpit 服务器内的 daemon 触发,**不是从浏览器**。所以:

- ✅ 浏览器 tab 关了 → 任务照跑(服务器在跑)。
- ✅ 电脑休眠 → 电脑醒了后任务按下一个计划点继续(**不会**补跑错过的)。
- ❌ Cockpit 服务器停了 → 任务不跑。重新启动 `cockpit` 它们按正常计划恢复(任务定义持久化,内存里的 timer 会按下次时间重建)。

要任务跨重启幸存,确认 Cockpit 在跑。最简单的方式:工作日开始时终端起一个 `cockpit` 放着。

## 定时任务适合什么

几个实际可行的模式:

- **每日 PR 摘要** —— cron 早上 9 点,让 AI 总结昨天合并的 PR。
- **陈旧 issue 巡查** —— cron 一周一次,列出 30+ 天没活动的开放 issue。
- **构建健康检查** —— interval 每 2 小时,跑 `npm test` 报告。
- **release notes 草稿** —— Once 用例,几天后到点起草 changelog。
- **长任务保姆** —— 大迁移期间 interval 每 5 分钟检查进度,卡了就 ping 你。

## 限制

- **失败不重试** —— 失败的运行只是标 `error`,下次计划运行照样准时。
- **不能条件执行** —— 不能说"只有当有新提交时才跑"。你得让 AI 自己在 prompt 里检查这个。
- **没有跑历史日志** —— 只记最后一次结果。要历史可以让 AI 把每次输出附加到一份笔记或 issue 里。
- **时区按本地** —— cron 和 `HH:MM` 都按 Cockpit 服务器所在机器的本地时间。

## 下一步

- [会话管理](/zh/docs/agent/sessions/) —— 定时任务跑起来后长什么样
- [Skills](/zh/docs/agent/skills/) —— 你的定时任务 prompt 可以用 `/qa`、`/fx`、`/cg`、`/cr` 等
