跳转至

会话定时任务

会话定时任务（conversation-defined scheduled tasks）允许用户直接在聊天里定义未来触发的任务，并让系统在指定时间重新进入对话或创建隔离会话执行一次新的 Agent turn。

能力范围

v1 已支持：

  • at：单次定时触发
  • every：固定间隔重复触发
  • cron：5-field cron 表达式
  • bound_session：默认模式，回到原始会话继续执行
  • isolated_session：为每次触发创建独立 synthetic session

当前不支持：

  • UI 内直接创建任务
  • 暂停 / 恢复任务
  • 自定义 payload kind（v1 固定为 prompt）

创建与执行流程

  1. 用户在 conversation 中提出定时需求。
  2. Orchestrator capability pipeline 的 scheduler stage 使用结构化输出来识别 create_task、list_tasks、cancel_task 或 no_scheduler_action。
  3. ScheduledTaskService 校验 schedule、timezone、target mode 与 conflict policy，并持久化 scheduled_tasks 记录。
  4. 后台 TimerSchedulerService 在任务到期后 claim task / run，写入 lease token 与 heartbeat。
  5. Scheduler 通过共享 execute_session_turn(...) 路径执行一次新的会话 turn，并把结果写回 scheduled_task_runs、messages、conversation_turns。
  6. 新生成的 conversation_turns 会在写库时同时记录 generation token usage；scheduled_task_runs 只保留 conversation_turn_id，控制面通过该引用派生 usage，不维护第二份 token 真相源。

Human Takeover 冲突策略

当任务目标为 bound_session 且源会话处于 HUMAN_ACTIVE 时，v1 使用每个任务独立配置的 conflict policy：

  • defer：延后到 defer_retry_seconds 之后重试
  • skip：本次跳过，并为 recurring task 计算下一次执行时间
  • run_anyway：忽略人工接管，继续执行

默认策略为 defer。

Admin 控制面

Admin Frontend 新增 Scheduled Tasks 页面，提供：

  • 任务列表与过滤：按 prompt、agent、session、status、target mode、schedule kind 浏览
  • 详情抽屉：查看 prompt payload、schedule payload、worker heartbeat 与 run history
  • run history：直接显示从关联 turn 派生的 generation token usage 与来源状态
  • 取消操作：通过控制面停止未来执行，但保留历史 run ledger

对应 Admin API：

  • GET /scheduled-tasks
  • GET /scheduled-tasks/{task_id}
  • GET /scheduled-tasks/{task_id}/runs
  • POST /scheduled-tasks/{task_id}/cancel

配置

后台调度开关位于 config.toml 的 [scheduled_tasks]：

[scheduled_tasks]
enabled = true
dispatcher_idle_seconds = 1.0
supervisor_interval_seconds = 5.0
worker_stale_seconds = 900
worker_heartbeat_interval_seconds = 60.0
defer_retry_seconds = 300
max_list_records = 100

关键建议：

  • 本地或测试环境先显式开启 enabled = true 再验证后台触发
  • recurring task 建议保留合理的 worker_stale_seconds 与 defer_retry_seconds，避免 slow run 被过早回收
  • 若只需查看任务持久化结果，可暂时关闭后台执行

观测与排障

排查定时任务时，优先检查以下维度：

  • scheduled_tasks.status、next_run_at、failure_count
  • scheduled_task_runs.execution_state、heartbeat_stale、error_message
  • scheduled_task_runs.conversation_turn_id 对应 turn 的 generation_usage
  • 源会话是否处于 HUMAN_ACTIVE
  • [scheduled_tasks].enabled 是否已开启

常见现象：

  • 任务创建成功但未执行：通常是后台调度未开启，或 next_run_at 仍未到达
  • run 卡在 heartbeat_expired：worker 在执行期内失联，supervisor 会按 stale recovery 逻辑回收并重试
  • bound-session 任务不断延后：源会话可能长期处于人工接管状态，且 conflict policy 为 defer