English · 简体中文
持久化与持久性¶
Note (v0.6.7): 本文中对
par ask的引用是历史性的(CLI 已移除)。SQLite 持久化层没有变化,仍是推荐的嵌入式存储——用法见 SDK 概览。
PAR 可以完全不使用持久化,也可以使用嵌入式 SQLite 数据库。本文解释为什么存在两个层级、它们在实践中如何不同,以及从运行时发布事件到事件落盘之间发生了什么。这是一篇解释性文章,不是配置参考。配置字段名请阅读 lib/core/types.ml 和 docs/sdk/ 下的 SDK 参考。这里我们追踪写入路径、拆解 schema,并说明何时选择哪个层级。
持久化在 PAR 中的用途¶
Agent 运行时会产生事件。每次工具调用、每次任务状态变更、每次工作流检查点、每次 bash 命令及其风险分类,都作为 Par.Types.event 发出。这些事件有三个用途:审计(agent 做了什么、什么时候做的)、调试(为什么走那条路径)、恢复(崩溃后能否恢复这个工作流)。没有持久化,进程退出的瞬间三者全部丢失。
PAR 把持久化视为最终一致的审计日志,而非事务性状态存储。Agent 循环本身不会在持久化上阻塞。Runtime.invoke 发出 Tool_invoked 事件时,事件去往事件总线,再到批量写入器,最后到 SQLite,全程异步。写入失败时运行时记录日志并继续运行。Agent 的正确性不依赖审计日志的持久性,只依赖 LLM 响应和工具结果在内存中的正确性。这种分离让 PAR 在负载下保持快速,同时事后给你审计轨迹。
例外是检查点。工作流状态存储在 workflow_states 表中,在 Sequential 链的每一步完成后写入,并带上该步绑定的变量,因此被中断的运行可以从停下的位置继续。持久化 invoke 的检查点(invoke_checkpoints)在 invoke 所在的 fiber 上同步写入——进程死亡时可能还留在缓冲区里的检查点不算检查点。工作流检查点始终开启;invoke 检查点是可选的,因为长工具循环每批都要付一次「整份会话大小」的写入。其余审计日志仍然异步。
恢复被中断的工作流¶
所属进程已死掉的运行会以 running 状态留在存储里。Runtime.create 会把这些行读回来、放回内存表,并对每行发一次 Workflow_orphaned。不会自动恢复:重跑一个已经产生副作用的步骤应由调用方决定,而不是库在启动时替你做。
Runtime.recover_workflow rt run_id 从检查点重新进入。检查点之前的步骤不再执行,之后的步骤继续执行。语义是 at-least-once:如果进程是在某一步执行中途死掉的,检查点仍指向上一步,那一步会被重跑。请让对外部世界有影响的步骤可重入,或在重复前先检查效果。
控制流节点在恢复时是原子的。Parallel、Map_reduce 与 Sub_workflow 不会为子步骤写检查点,因此在这些节点内部崩溃时,检查点停在节点之前,恢复会整块重跑。Conditional 会进入它当时选择的分支——前提是该分支是 Sequential。若检查点的 schema_version 比运行时能理解的新,会被拒绝而不是猜测。
子工作流目前不能独立恢复:子工作流崩溃时只留下父级的检查点,因此恢复会重跑整个 Sub_workflow 步骤。
恢复被中断的 invoke¶
Agent 循环有自己的崩溃恢复路径,而且是可选的。Runtime.invoke ~durable:true(或给运行起名 ~invoke_id)会在第 0 次迭代后、以及每个完成的工具批次后,往 invoke_checkpoints 表写一次检查点。该行只在运行期间存在:任何终止结果——成功、失败、主动取消、因审批挂起——都会删除它,因此活过进程的行是「没有跑完就停止的写入者」留下的。
需要恢复时请自己给运行起名:~invoke_id:"order-42"。自动生成的 id 只出现在 invoke_result.invoke_id 里,而崩溃的进程永远返回不了它。重启后,Runtime.create 读回遗留的行、对每行发一次 Invoke_orphaned;Runtime.list_orphaned_invokes 以 (invoke_id, agent_id) 返回它们。该事件在 create 执行期间发布,所以订阅必须在创建 runtime 之前挂好——或者在创建之后直接调用 list_orphaned_invokes。Runtime.recover_invoke rt ~invoke_id 带着检查点里的会话、迭代计数、已耗时预算、workspace、appendix 与 skill 快照重新进入循环。
语义与工作流一致:
- at-least-once:崩溃时正在进行的那一轮会重跑。检查点是在批次完成后写的,因此被中断那一轮的 assistant 消息从未落盘——模型会被重新询问,可能选择不同的工具调用。已完成的批次不会重跑。
- 显式:不会自动恢复,且只有启动时重水化的 id 才有资格——本进程仍在运行的 invoke 会被拒绝,因为恢复它会导致双重执行;另一个 runtime 仍在执行的运行同样被拒绝:运行在途期间它的持有者持有该 invoke id 的租约,而持有者进程消失时租约即被释放,因此崩溃的运行可以立即恢复。用孤儿的 id 发起新 invoke 同样被拒绝:恢复是显式的,新运行必须换一个 id。
- 批次原子:并行工具批次只在全部结果折入会话后写一次检查点,批次内部崩溃会整轮重跑。
- schema 校验:
schema_version比运行时能理解的新时,检查点被拒绝,而不是猜测。如果更新后的形状连解码都做不到,启动时会保留该行,拒绝信息会说明版本——旧运行时不得销毁新写入者的状态。
检查点记录的是实际在跑的 agent。handoff 之后就是目标 agent,因此恢复时使用的是目标 agent 的工具,而不是调用方最初指定的那套。
需要如实说明的限制。上下文按记录重放而不是重新计算:系统提示词与静态工具集来自检查点(包含 skill 驱动的过滤),schema_version 2 还会记录 invoke 使用的 workspace、appendix 与 skill 快照,因此恢复后的运行会放行相同的路径、重组相同的提示词。记录中的 workspace 根目录若已不存在,恢复会被拒绝,而不是回退到另一个 workspace。仍有两项不会重放:tool_search 的动态提升(恢复后的运行从检查点里的静态工具集开始),以及调用方回调与 steering/follow-up 队列(需要在 recover_invoke 时重新传入)。因审批挂起的运行会保留检查点,并记录它在等什么,因此等待期间的崩溃不会丢掉这个运行。approvals 行仍然拥有那个决定,入口是 Runtime.resume_approval;在该决定仍然开放期间,恢复会拒绝这个运行并指向 resume_approval,而不是重跑批次再问一次。决定过期后,批次会重跑并重新发起审批。检查点写入是 best-effort:写失败会记录日志并发布 Invoke_checkpoint_failed,但运行继续,因此那一步不可恢复。
检查点在 invoke 所在的 fiber 上同步写入,不经过批量事件写入器。这是刻意的——进程死亡时可能还在缓冲区里的检查点不算检查点——也是持久化必须可选的原因:长工具循环每个批次都要付一次会话大小的写入。这也意味着 Runtime.close 应在 runtime 空闲时调用:它会关闭持久化句柄,之后落地的检查点写入或删除都会失败(并按上面所述上报)。
Durability 覆盖 invoke 与 invoke_content(invoke_async 透传)。invoke_structured、invoke_generate、invoke_parallel 与 workflow 的 Agent_call 步各有自己的路径或没有:只有上面这三个入口会创建 durable 检查点。如果调用方设了 save=false,durable 运行仍会把会话写进检查点表——durability 与「保存对话」是两个独立的持久化决定。
两个持久化层级¶
PAR 提供两个持久化层级,通过 runtime_config 的 persistence 字段控制:
`Sqlite是唯一的持久化后端,也是默认值。单个文件(测试用:memory:)。零外部依赖:sqlite3库是par包的硬依赖。你得到 WAL 模式、完整 schema、保留期裁剪,全套功能。这就是par ask和 Python quickstart 使用的后端。公共配置类型是[Sqlite of string ]`,字符串是数据库路径。没有其他配置变体。`Noop是测试用的内存后端。丢弃所有内容。无事件总线、无写入 fiber、无 I/O。只关心 agent 行为的测试运行更快且不留下文件。Noop 以内部持久化类型的变体形式在编程接口中可用,但不作为配置选项暴露:公共配置只携带 SQLite 路径。如果想从配置层面获得内存行为,把 SQLite 指向:memory:即可。
`Noop 层级也是一个微妙的架构声明。持久化为 noop 时,运行时完全跳过事件总线的接线。没有死总线喂给死写入器。Persistence_writer 和 Event_bus 实例在运行时记录上是 None。这让测试路径精简,也使单元测试中意外留下后台 drain fiber 运行变得不可能。
Schema:四张表¶
SQLite 使用 lib/persistence/sqlite_persistence.ml 中定义的 schema。四张表:
CREATE TABLE events (
id TEXT PRIMARY KEY,
task_id TEXT NOT NULL,
payload TEXT NOT NULL,
timestamp REAL NOT NULL,
idempotency_key TEXT UNIQUE NOT NULL,
session_id TEXT NOT NULL DEFAULT '',
actions_json TEXT
);
CREATE TABLE task_states (
id TEXT PRIMARY KEY,
state TEXT NOT NULL,
updated_at REAL NOT NULL
);
CREATE TABLE workflow_states (
id TEXT PRIMARY KEY,
workflow_id TEXT NOT NULL,
status TEXT NOT NULL,
checkpoint TEXT,
updated_at REAL NOT NULL
);
CREATE TABLE invoke_checkpoints (
invoke_id TEXT PRIMARY KEY,
state_json TEXT NOT NULL,
updated_at REAL NOT NULL
);
events 是追加式审计日志。每个发布的事件被 JSON 序列化到 payload,标记 task_id 和 timestamp,通过 idempotency_key 去重。session_id 列让你按会话过滤事件,actions_json 携带结构化的副作用数据(比如 bash 调用的命令向量)。两个索引 idx_events_task_id 和 idx_events_session_id 保持常见查询路径的性能。
task_states 跟踪任务生命周期:排队、运行中、完成、失败。workflow_states 保存工作流检查点,使多步工作流在崩溃后可以恢复。invoke_checkpoints 为每个持久化 invoke 保存一份在途会话快照。它们都用 updated_at 作为单调时钟排序。
前三张表借鉴自 LangGraph 的三表模型,它是对检查点系统需求的抽象:发生过什么的日志(events)、瞬时状态的快照(task_states)、长期运行状态的快照(workflow_states)。PAR 刻意没有发明第四种形态。invoke_checkpoints 仍是同一个「瞬时状态快照」思路,只是以 invoke id 为键:invoke 不是 task_state 行,而把会话大小的负载塞进调度器的状态记录,会让每次任务查询都为用不到的持久化数据付费。这张表存在,是为了让两个关注点各自独立,而不是挤在同一行里堆列。
写入路径:从事件总线到磁盘¶
有趣的部分是事件如何从 rt.publish_event_fn 到 SQLite 而不阻塞 agent 循环。路径有三跳。
Runtime.publish_event
│
▼
Event_bus(内存中,扇出到订阅者)
│ └─ 订阅者: Persistence_writer.push
│
▼
Persistence_writer.buffer(容量 1000,Mutex 保护的列表)
│
│ 每 50ms,drain fiber 唤醒:
▼
grab_pending ◄── 取走整个 buffer,重置为 []
│
▼
save_fn(batch) ◄── persistence.save_events_fn ─► SQLite
第一跳:publish_event_fn 是事件总线的发布函数。总线是内存中的扇出结构,带死信队列。每个订阅者收到每个事件。其中一个订阅者是调用 Persistence_writer.push 的闭包。
第二跳:写入器在 mutex 保护的列表中缓冲事件。容量 1000 个事件。新事件到来时缓冲已满,溢出函数触发,把事件路由到总线的 DLQ 而非静默丢弃。缓冲是列表,逆序前插,所以 push 是 O(1),刷新时批量反转。
第三跳:一个 drain fiber,在运行时创建时通过 Eio.Fiber.fork_daemon 作为守护进程 fork 出来,永远循环。它 yield 两次(给其他 fiber 机会),取走整个待处理缓冲区,然后对批量调用 save_fn。刷新间隔是 50 毫秒,由 Persistence_writer.create 中的 flush_interval: 0.05 设置。这意味着在稳定负载下,事件在发布后 50 毫秒内落盘,批量写入而非每次 INSERT 一个事件。
这里有两个重要属性。第一,agent 循环从不在持久化上阻塞。publish_event_fn 立即返回;实际 I/O 在单独的 fiber 上发生。第二,关闭是干净的。Runtime.close 把写入器的 running 标志设为 false,调用 flush_sync,在运行时拆解前取走剩余事件并写入。drain fiber 发现 running 为 false 后以 `Stop_daemon 退出。因为它是守护 fiber,退出不会阻塞 switch 拆解。如果取消到达时正在刷新中,它会捕获 Eio.Cancel.Cancelled,执行最后一次同步刷新,然后停止。优雅关闭时不会丢失任何事件。
WAL 模式与并发¶
SQLite 的 WAL(Write-Ahead Logging)模式让读者和单个写者可以并发进行而不互相阻塞。PAR 启用 WAL,因为典型负载是一个写者(批量 drain fiber)和多个读者(历史查询、恢复查找、par history CLI 命令)。不启用 WAL 的话,每次读取都要获取共享锁并阻塞写者。
WAL 有一个运维影响:数据库目录必须可写,因为 SQLite 会在主 .db 文件旁创建 -wal 和 -shm sidecar 文件。如果你把 PAR 指向只读目录,WAL 设置会失败,Runtime.create 时报错。临时或测试运行用 :memory: 可以完全规避这个问题。
WAL 加 SQLite 文件锁有一个约束:同一时间只有一个进程应该写入文件。单个 PAR 运行时拥有文件是支持的模型。两个运行时从不同进程指向同一个 .db 文件会在锁上竞争,负载下会看到 SQLITE_BUSY 错误。
保留期:7 天默认值¶
不加控制的话,events 表会无限增长。PAR 会裁剪它。默认保留 TTL 为 7 天(default_retention_ttl = 7. *. 24. *. 60. *. 60.,在 lib/persistence/sqlite_persistence.ml 中)。SQLite 后端打开时会运行一次裁剪,删除所有超过 TTL 的事件。你可以在创建时为每个后端覆盖 TTL。
裁剪基于时间戳,仅针对 events 表。task_states、workflow_states 与 invoke_checkpoints 不自动裁剪,因为它们的行代表可恢复状态而非历史噪音。如果你想清理它们,自己写 DELETE。假设是长期运行的服务关心审计历史的过期清理,但不关心丢失可能仍需恢复的工作流检查点。
何时选择哪个层级¶
| 场景 | 层级 | 原因 |
|---|---|---|
| 本地开发、单实例生产 | `Sqlite |
零配置,文件在磁盘上,WAL 处理读写混合负载。单个 SQLite 运行时通过批量写入器可以处理每秒数百个事件;瓶颈通常是 LLM provider 而非数据库。备份 .db 文件。 |
| 测试、CI、任何不需要磁盘审计轨迹的场景 | `Noop |
无 I/O、无残留文件、最快。 |
值得直说的诚实局限:SQLite 是单文件、单写者数据库。它的文件锁无法跨容器的多进程写入同一文件。如果你需要多个 PAR 进程同时访问相同数据,当前选项是在应用层分片(一个运行时,一个数据库文件,按租户或会话分区)或运行一个写者让其他实例读副本。跨实例共享状态在路线图上规划为未来的远程层,而非 SQLite 目前能提供的。见"即将到来"部分。
单个 SQLite 运行时足以应对大量真实负载。想超越它的原因是带共享状态的水平扩展,而这正是双层架构工作要填补的空白。
即将到来¶
当前模型是单层:事件去往一个后端,仅此而已。未来版本计划双层模型:快速本地层(SQLite,低延迟,短保留期)加远程层(未来的持久化后端或对象存储,持久化,长保留期)。本地层吸收突发流量,异步转发到远程层。这是标准的热/冷日志架构。在它落地之前,根据上面的矩阵选择你的层级,接受目前只有一层的事实。
双层设计在路线图上(bd issue PAR-4dt,目标 v0.6+),因为单层模型迫使你在延迟(SQLite,本地,快)和跨实例持久性(能承受多写者的远程层)之间做选择。一个同时需要两者的服务必须在每个实例本地运行 SQLite 并放弃跨实例共享查询,或者对自己的负载做分片。双层路径会让服务保留本地 SQLite 做亚毫秒级审计写入,同时复制到远程层做跨实例查询。理论上是这样。实现还没到。
另请参阅¶
- 架构 持久化在模块结构中的位置和事件流图
- 并发模型 drain fiber 如何与运行时 switch 和取消协作
- Workflow API 工作流检查点如何与
workflow_states交互 - SDK 概览 事件总线订阅 API(本写入路径的读取侧配套)