会话定时任务

有时候你希望 Agent「过一会儿再来看看」「每天定时跟进一下」「某件长任务跑完了再叫醒我继续」。 Spark Work 的会话内定时任务就是为这类场景准备的：在某个会话作用域里创建持久化任务， 到点后调度器自动在这个会话里排一轮新对话，沿用会话当时的 Agent、模型、权限和工作区继续推进。

1. 会话级作用域：任务跟着会话走

每个定时任务都绑定在创建它的那个会话上：scheduled_tasks 表里的scope 为 'session'，session_id 指向会话。 触发时它不会新开会话，而是往原会话里排一轮 turn （内部标记 turnSource: 'scheduled_task'、userMessageVisibility: 'hidden'）， 因此这一轮用的是会话当前的 Agent、Provider/模型、权限模式、推理强度和工作区目录。 你之后切换模型或调整权限，下一次触发会自动按最新配置执行。

• 归属校验：Agent 侧工具用「task id + 当前会话 id」双重校验， 任务必须 scope === 'session' 且 sessionId 与当前会话一致才允许读写， 猜 id 也拿不到别的会话或全局任务。
• 删除会话即级联清理：session_id 外键带ON DELETE CASCADE，删除会话时它的任务随之删除。
• 归档会暂停：会话被归档时，启用中的会话任务进入 paused 状态； 取消归档时只有归档前启用的那些会被恢复，并重新计算下次执行时间。
• 会话不存在 / 读不到状态：任务会被停用并记Bound session no longer exists；只是暂时读不到会话状态则推迟重试并记录原因。

2. 两个入口，别搞混作用域

2.1 会话工具栏：只管理本会话

会话顶部工具栏有一个时钟图标按钮（提示文案「计划任务」），点开是会话计划任务面板。有启用中的任务时按钮上会带一个小红点。 面板支持新建、编辑、启停、立即运行、删除，提交时固定scope: 'session' + 当前 sessionId + concurrencyPolicy: 'queue'。

面板表单的默认值：

• 触发类型 interval，间隔 30 分钟（提交时换算成秒，最小 10 秒）。
• Cron 预填 0 */1 * * *。
• skipIfSessionRunning 与 continueOnError 默认勾选。
• 名称与任务正文必填；once 必须选一个合法时间。

2.2 侧栏「定时任务」：全局任务，不是会话任务

左侧导航的 「定时任务」 页是另一套作用域：它列出的是scope: 'global' 的任务，新建时也按 global 写入（默认 concurrencyPolicy: 'skip'）。 全局任务触发时会新建一个会话（默认落在「无项目对话」目录，标题前缀带任务名）， 而不是续在原会话里。想「在某个会话里继续」就必须用会话面板或 Agent 工具创建。

用户侧 IPC 通道：scheduled-task:list / get / create / update / delete / toggle / run-now / export / import / export-to-file / import-from-file， 执行记录用 task-execution:list / get / cancel。 「立即运行」会立刻建一条 trigger_type: 'manual' 的执行记录， 并在 10 秒内把新会话 id 还给界面用于跳转，真正的 turn 在后台跑。

3. 字段与默认值

会话任务的 agent_id、team_id、model_id、workspace_id一律写 null，permission_mode 写 'auto'： 这是刻意的设计——会话任务只跟随会话当时的运行时配置，不给自己绑一份会过期的快照。

4. 三种触发方式怎么选

会话任务的这层校验只在 scope === 'session' 时强制执行，报错文案分别是 「interval must be at least 10 seconds」「requires a valid five-field cron expression」 「runAt must be in the future」。

5. Agent 也能自己建任务

Agent 通过 mcp__spark_platform__session_schedule_* 这组工具自助管理会话定时任务， 适合「每 5 分钟检查一下部署状态，好了告诉我」这类需求：

这组工具与用户面板的差异：

• 会话绑定由运行时提供，模型不能传 sessionId：参数里没有会话字段， 工具被注入到哪个会话就只作用于哪个会话；工具说明也明确要求不要询问或编造 session id。
• 入参是严格 schema：多传未知字段会直接报错；intervalSeconds、cronExpression 等都按上面的上限校验。
• 默认值偏向安全：skipIfSessionRunning 与continueOnError 默认 true，concurrencyPolicy 默认queue，timeoutSeconds 默认 300，historyRetentionDays 默认 30。
• 生命周期要求写进了系统提示词：创建后简短告知用户并结束本轮； 每次唤醒先看真实状态，还没完成就留着，任务完成后必须调用session_schedule_delete 清理，不能无限空跑。禁用只是暂停，不算清理。

6. 调度引擎的行为

6.1 并发与会话忙

• 调度器是桌面主进程里的定时器，每 1 秒 tick 一次：应用没运行时不会触发。
• 同一任务已有 running 的执行记录时：skip 跳过本次并重算下次时间；cancel 把旧执行标记为 canceled 再开新的；queue 直接再开一个。
• skipIfSessionRunning 生效时，只要会话有正在执行或已排队等待的 turn， 本次触发就顺延（once 任务顺延 60 秒后重试）。
• 会话报 error 且 continueOnError 为 false 时，任务被暂停而不是继续触发。

6.2 重试

失败后按 maxRetries 与退避策略重试，重试的延迟公式：

• fixed：baseDelay × 1
• linear：baseDelay × (attempt + 1)
• exponential：baseDelay × 2^attempt

每次重试都是一条独立执行记录（trigger_type: 'retry'、带retry_attempt 与 parent_execution_id），所以你能在记录里看出是第几次尝试。 超过 timeoutSeconds 的执行记为 timeout 而不是 failed。

6.3 生命周期与错过的运行

• 错过的运行不补跑：应用关闭期间到点的会话任务，在下次启动时会被跳过—— 周期任务直接挪到下一个未来时间点，错过的单次任务会被停用。
• 执行状态：running / completed / failed / cancelled / timeout。
• 任务状态：idle / running / disabled / error。
• 达到 maxExecutions 或单次任务执行完成后，任务自动 disabled。
• 每次执行结束按 historyRetentionDays 清理历史执行记录。

7. 触发时注入了什么

触发的那一轮不是普通用户消息，系统会把它包成 [Scheduled Task Context]：

• 说明这轮由调度器发起、不是用户手动发送。
• 任务名、任务 id（会话任务专属），并提示任务完成后要调用session_schedule_delete 清理。
• 执行触发来源、配置的计划、下次执行时间与时区。
• 明确要求「不要反过来问用户间隔 / Cron / 触发时间」，按既有计划执行。
• 最后跟 [Task Instructions]，即你写的任务正文。

任务正文支持模板变量，会在写入提示词前替换：{{date}}、{{time}}、{{taskName}}、{{triggerType}}、{{executionCount}}、{{interval}}、{{cronExpression}}、{{runAt}}、{{timezone}}、{{nextRunAt}}。 认不出的变量保持原样，方便你发现拼写错误。

8. 使用规范与排查

• 轮询类任务的间隔尽量 ≥ 60 秒，避免空转过快消耗 token。
• 目标达成（长任务完成、条件满足）后必须调用 session_schedule_delete 清理， 不要让任务无限空跑；只想临时停机用「停用」。
• 一次性提醒用 once，不要用 interval 模拟。
• 在任务正文里写清「检查什么、状态在哪、什么算完成、还没完成时怎么办、什么时候删任务」， 无人值守的那一轮才不需要向你追问。
• 任务定义与执行记录都落本地 SQLite（scheduled_tasks / task_executions）； 触发时复用本会话的模型与权限配置，不会绕过权限模式或注入额外能力。

常见问题对照：