# 14 定时任务

> 状态：**已实施（2026-10-27）**。

## 1. 目标

用户在对话中说"每个工作日早上 9 点帮我汇总前一天的销售数据"，AI 创建一个定时任务，当前会话或工作组就成为"定时会话 / 定时工作组"，之后由服务端按时自动执行，结果留在同一个会话或工作组的时间线中。

- 创建、修改、暂停、删除都可以通过对话完成，界面上也可以暂停和删除。
- 不需要在后台手工配置；后台只提供总览和管理。
- 不做结果通知（Webhook），以后按需再加。

## 2. 使用流程

1. 用户提出定期或将来某个时间执行的需求。
2. AI 调用 `schedule_create`，把时间转成结构化的时间表（§3），把要做的事写成到时候可以独立执行的完整指令。
3. 会话中出现确认卡片：时间表的中文描述、接下来 3 次的执行时间、指令内容；如果无人值守时会遇到审批，卡片上给出提示。用户确认后才生效。
4. 会话或工作组的顶部显示定时任务栏（时间表、下次执行时间、上次结果，可以暂停、恢复、删除）。
5. 到点时，服务端往同一个会话或工作组中发一条消息：`【定时任务「标题」· 11月3日 周一 09:00】` + 指令，AI 照常执行。

## 3. 时间表

AI 填写结构化的时间表，服务端校验并计算下次执行时间，不依赖 AI 记时间：

| kind | 字段 | 说明 |
|---|---|---|
| `once` | `at`：`YYYY-MM-DD HH:mm` | 只执行一次，执行后结束 |
| `daily` | `time`：`HH:mm` | 每天 |
| `weekdays` | `time` | 周一到周五 |
| `weekly` | `days`（1=周一 … 7=周日）、`time` | 每周的某几天 |
| `monthly` | `day`（1–31）、`time` | 每月某天；超过当月天数时取最后一天 |
| `interval` | `hours` | 从创建时起每 N 小时 |

- 时区：系统设置 `schedules.timezone`（默认 Asia/Shanghai）。
- 最小间隔：`schedules.minIntervalHours`（默认 1 小时），只约束 `interval`。

## 4. 工具（MCP Gateway 内置）

普通会话和工作组中的所有机器人都有这组工具（工具列表固定，Codex 沿用第一次连接时的工具列表也不受影响）：

| 工具 | 说明 |
|---|---|
| `schedule_create(title, prompt, schedule)` | 创建；显示确认卡片，用户确认后生效 |
| `schedule_list()` | 本会话 / 本工作组的定时任务 |
| `schedule_update(schedule_id, title?, prompt?, schedule?, status?)` | 修改时间表或指令需要确认；只暂停或恢复不需要 |
| `schedule_delete(schedule_id)` | 删除 |

- 普通会话中创建的定时任务属于这个会话；工作组中创建的属于工作组。
- 工作组中由组员创建时，到点的消息 @ 这个组员；由组长创建时交给组长。
- 引擎自带的定时工具（Claude 的 CronCreate、ScheduleWakeup 等）继续禁用：它们依赖引擎进程常驻。

## 5. 执行

- 调度器每 30 秒检查一次到期的定时任务；服务重启期间错过的执行在启动后补跑一次（不逐次补跑），然后从当前时间计算下次执行时间。
- **会话**：以用户消息的形式开始一轮（与平台发消息相同）。会话正在执行时跳过本次并记录。
  - 每次执行的时长上限 `schedules.maxMinutesPerRun`（默认 60 分钟），超时中断。
  - 每次执行的成本上限 `schedules.maxCostUsdPerRun`（默认 $2）：一轮结束后超出时暂停这个定时任务并记录原因，避免持续超支。
- **工作组**：以系统消息发到工作组，按工作组的规则交给组长或被 @ 的组员。还有进行中的任务或机器人在工作时跳过本次；工作组暂停或关闭时跳过。成本由工作组的任务限额约束。
- **无人值守时的审批**：照常显示审批卡片，等待 `limits.interactionTimeoutSec`（默认 10 分钟）后按超时拒绝，时间线中留有记录。
- 每次执行都记录在执行记录中：开始 / 完成 / 失败 / 跳过 / 已发出（工作组），以及原因和成本。
- 会话或工作组删除时，它的定时任务一起删除。

## 6. 限制

| 设置 | 默认 |
|---|---|
| `schedules.maxPerTarget`：每个会话 / 工作组的定时任务数 | 5 |
| `schedules.minIntervalHours` | 1 |
| `schedules.maxMinutesPerRun` | 60 |
| `schedules.maxCostUsdPerRun` | 2 |
| `schedules.timezone` | Asia/Shanghai |

## 7. 数据模型

- `schedules`：id、目标（`session_id` 或 `team_id`）、创建者（工作组中的机器人 id）、标题、指令、时间表、时区、状态（active / paused / ended）、下次执行时间、上次执行时间与结果、执行次数。
- `schedule_runs`：每次执行的时间、结果、Run id、成本、说明。

## 8. API

| API | 接口 |
|---|---|
| Agent API | `GET /v1/sessions/:id/schedules`；`PATCH /v1/schedules/:id`（`{ status }`）；`DELETE /v1/schedules/:id`；`GET /v1/schedules/:id/runs` |
| Bot API | `GET /bot/v1/teams/:id/schedules`；`PATCH`、`DELETE /bot/v1/teams/:id/schedules/:scheduleId`；`GET …/runs` |
| 后台 | `GET /admin/v1/schedules`（全部，带目标信息）；修改、删除、执行记录同上 |

SDK：`AgentClient.sessions.schedules`、`AgentClient.schedules.*`、`BotClient.teams.schedules` 等；`<AgentChat>` 与 `<TeamChat>` 顶部显示定时任务栏。

## 9. 界面

- `<AgentChat>`、`<TeamChat>`：有定时任务时顶部显示定时任务栏，可以展开查看、暂停、恢复、删除。
- 后台"定时任务"页面：全部定时任务，按状态筛选，查看执行记录，跳转到对应的会话或工作组。
- 系统设置增加"定时任务"一节（§6）。

## 10. 实施记录（2026-10-27）

- 系统提示词的"运行环境"中说明了定时任务工具和时区。真实验收时，Claude 一开始用 `sleep 120` 等待，没有使用工具：MCP 工具在 Claude 中按需搜索，模型不知道它存在。
- `once` 除了 `at`，还可以填 `after_minutes`（多少分钟后），用于"两小时后"这类相对时间，模型不需要知道当前时间。`schedule_list` 的结果中带有当前时间。
- 已用真实 Claude（haiku）验收：
  - "两分钟后提醒我喝水"：模型换算出执行时间并创建一次性任务，确认卡片显示时间表、下次执行时间和无人值守提示；到点后在同一个会话中执行，执行记录为完成，成本 $0.006。
  - "每个工作日早上 9 点出日报"：创建每个工作日 09:00 的定时任务，Playground 顶部显示定时任务栏，后台"定时任务"页面列出。