后台工作生命周期
ZeroClaw 有几种在启动它的入站请求结束后继续工作的方式。Cron 作业、SOP 运行、委托任务和运行时生成的子代理共享部分执行机制,但它们不共享同一个生命周期或同一个持久化存储。目标模式定义了一个相关的目标契约,但尚未实现端到端的连接。
当变更添加计划任务或自主运行的工作、引入等待或审批状态、改变取消或重启行为,或将子工作连接到所属任务时,请使用此页面。首要的设计问题不是“它如何在后台运行”,而是“哪个子系统负责管理其生命周期?”
所有权映射
| 工作类型 | 当前所有者或状态界面 | 持久化记录 |
|---|---|---|
| 定时任务 | Cron 调度器和存储 | data/cron/jobs.db |
| SOP 运行 | SopEngine 和 SopRunStore | 默认使用进程内存;当持久化 SQLite 初始化成功时使用 data/sop/runs.db |
| 后台委派 | 委托结果 API,支持在可用时使用控制平面的监督覆盖项 | <workspace>/delegate_results/<task-id>.json;已启动的守护进程下 data/control_plane.db 中的一条尽力而为的任务行 |
| 运行时生成的子代理 | 可用时通过控制平面监管生成站点 | 启动的守护进程下 data/control_plane.db 中的一条尽力而为任务记录 |
持久元数据并不等同于持久化执行。结果文件或任务行可以保留已知信息,并让恢复流程将工作标记为丢失、超时或终态,而无需保留负责执行该工作的进程本地 future。
Cron 作业
Cron 将声明式成员关系与 SQLite 执行存储相结合。运行时创建的作业和经过协调的配置作业都带有其所属的 agent_alias;执行时会解析该 agent 的安全策略,而不是在隐式的守护进程身份下运行。
调度器会轮询已到期、已启用且未认领的行。认领一行可防止其在处理期间被重复选取。完成后会记录受限输出,然后重新调度周期性任务,删除成功的自动删除一次性任务,或禁用其他一次性任务。如果进程在释放认领之前退出,调度器下次启动时会清除过期锁。
启动行为是显式的。启用追赶功能时,会考虑执行逾期作业。否则,逾期的一次性作业会被禁用,并产生跳过结果;而周期性作业会推进到下一个未来触发时间,不记录运行结果。调度器会在轮询迭代之间检查其取消令牌,因此关闭过程会等待当前到期作业批次完成后,循环才会退出。取消调度器并不保证已经分派的外部副作用可以回滚。
SOP 运行
SOP 定义位于配置的 sops 目录下。SopEngine 负责运行推进、审批等待、检查点、终止转换以及进程内状态呈现。当 SopRunStore 接纳并认领某个运行时,它是并发的唯一可信来源。
运行持久化为可选功能。在默认的 sop.persist_runs = false 配置下,引擎使用内存存储。启用持久化后,默认的 SQLite 后端会将 runs.db 写入 <data_dir>/sop 目录,除非通过 run_state_dir 覆盖该路径。存储初始化成功后,活跃快照、终态记录、事件、修订版本及并发声明均可支持重启恢复。若存储初始化失败,守护进程会记录警告并回退至内存存储。
Memory 后端中的 SOP 审计记录是一个独立的可观测性层面。它们不会取代 run store,也不得用作判断某次运行是活动、已暂停、已批准还是终态的权威依据。
仅当运行存储持久化时,审批和检查点状态才是持久化的控制状态。超时策略默认保持故障关闭:超时的审批会升级并继续等待,除非配置明确选择取消或旧版自动审批行为。
委派和子代理
子代理会继承其父代理的有效安全边界。策略和内存覆盖可以收窄父级范围,但无法将其扩大;同时,子代理的操作计数使用父代理的跟踪器,因此生成子代理无法绕过父代理的操作预算。
spawn_subagent路径是同步的:父运行会等待子运行完成,并且此路径没有本地超时或后台取消句柄。
delegate 工具可以同步运行,也可以启动后台任务并返回一个 UUID。后台结果会以原子方式写入传递给该工具的工作区,可以对其进行检查、列出、批量等待或取消。实时取消注册表将任务 ID 映射到进程本地令牌;取消操作会更新已持久化的结果,并在该实时令牌仍然可用时向正在运行的任务发出信号。
在已启动的守护进程下,delegate 和 subagent 生产者也会将任务行写入持久化控制平面。这些写入采用尽力而为方式,并且独立于 delegate 结果文件的写入。delegate 结果读取仍然以文件优先;只有仍标记为 running 的文件,才会根据控制平面状态叠加为 lost 或 timed_out,因此这两条记录可能会出现分歧。
当前 delegate 和 subagent 行会填充 agent、status、owner PID 和 boot ID、depth 以及 timestamps。它们会将 heartbeat、parent task、route 和 principal 留空。启动恢复会将上一次启动中处于运行状态的行标记为 lost;timed_out 仅适用于发出过期 heartbeat 的生产者,而这些生产者目前不会这样做。task 行会让被中断的子项可见,但不会重新创建其执行。
目标模式目标合约
ADR-008 认可任务控制平面将作为目标生命周期、所有权、路由、主体、父级关系和恢复资格的未来权威。存储库中包含目标存储和控制平面 API,但生产环境中的目标准入和执行尚未实现端到端打通。
后台路径只有在保留了所属目标关系,并将终端状态和模型使用情况回报给该目标之后,才能参与目标模式。在此之前,该路径只是普通的后台工作,而非目标模式执行。
变更检查清单
对于后台工作变更,请在评审者批准前回答以下问题:
- 哪个子系统负责生命周期管理,哪个存储是权威数据源?
- 这项工作是进程本地的、具备持久化监督的,还是确实能够在重启后恢复的?
- 哪个令牌或控制平面操作可以取消它,哪些内容可能仍在传输中?
- 此路径实际会填充哪些父任务、代理、路由、主体、递归深度和用量字段?
- 等待、审批、检查点、丢失、超时和终止状态是否可区分?
- 启动恢复是否会重复执行副作用,或静默地遗留一个未处理的 claim?
- 结果交付在重启后观察到完成时是否仍保持幂等性?
源指针
- Cron 调度器与持久化:
crates/zeroclaw-runtime/src/cron/scheduler.rs、crates/zeroclaw-runtime/src/cron/store.rs - SOP 引擎和运行存储:
crates/zeroclaw-runtime/src/sop/engine.rs、crates/zeroclaw-runtime/src/sop/store/ - 委派和子代理行为:委派与子代理、
crates/zeroclaw-runtime/src/tools/delegate.rs、crates/zeroclaw-runtime/src/tools/spawn_subagent.rs、crates/zeroclaw-runtime/src/subagent/mod.rs - 持久化任务控制平面与恢复:
crates/zeroclaw-runtime/src/control_plane/ - 目标模式决策:ADR-008
- SOP 操作员指南:SOPs 如何运行