AgentServer/docs/design/14-schedules.md

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 顶部显示定时任务栏，后台"定时任务"页面列出。