openJiuwen agent-core-java PersistenceCheckpointer 持久化检查点全解析:基于 BaseKVStore 的会话状态保存、恢复与释放
openJiuwen agent-core-java PersistenceCheckpointer 持久化检查点全解析:基于 BaseKVStore 的会话状态保存、恢复与释放
PersistenceCheckpointer 是 openJiuwen agent-core-java 中基于 BaseKVStore 抽象实现的持久化检查点组件,它把 agent 状态、workflow 状态与图(graph)状态分别委托给内部存储类管理,从而让「中断的会话可以跨进程恢复」「多轮对话上下文持续延续」「workflow 异常可回退重试」成为开箱即用的能力。读完本文,你将掌握 PersistenceCheckpointer 的构造方式、四个生命周期入口的底层行为、状态落盘的 key 结构与序列化机制、通过 Provider / 工厂 / Runner 装配的完整链路,以及如何用测试证据验证它的恢复与清理语义。
类概览:一个检查点,三类存储
PersistenceCheckpointer 定义在包 com.openjiuwen.core.session.checkpointer 下,继承抽象基类 Checkpointer:
public class PersistenceCheckpointer extends Checkpointer
它的核心设计思想是状态委托:不自己维护任何内存 Map,而是把所有状态读写统一转发到底层 BaseKVStore,由构造函数创建四个内部存储组件:
| 内部组件 | 职责 | 对应命名空间常量 |
|---|---|---|
AgentStorage |
保存 / 恢复单个 agent 的会话状态 | SESSION_NAMESPACE_AGENT(agent) |
AgentTeamStorage |
保存 / 恢复 agent team 的全局状态 | SESSION_NAMESPACE_AGENT_TEAM(agent-team) |
WorkflowStorage |
保存 / 恢复 workflow 状态及其 commit updates | SESSION_NAMESPACE_WORKFLOW(workflow) |
PersistenceGraphStore |
保存 / 恢复图执行器的 checkpoint 数据 | WORKFLOW_NAMESPACE_GRAPH(workflow-graph) |
命名空间常量定义在 Checkpointer.java 中:
public static final String SESSION_NAMESPACE_AGENT = "agent";
public static final String SESSION_NAMESPACE_AGENT_TEAM = "agent-team";
public static final String SESSION_NAMESPACE_WORKFLOW = "workflow";
public static final String WORKFLOW_NAMESPACE_GRAPH = "workflow-graph";
从源码结构看,这类「多存储委托」设计对应 Python 版 openjiuwen/core/session/checkpointer/persistence.py 的实现,Java 侧在类注释中明确标注了这一点。
构造方式与存储后端的选择
PersistenceCheckpointer 只有一个公开构造方法:
| 签名 | 说明 |
|---|---|
public PersistenceCheckpointer(BaseKVStore kvStore) |
使用指定 BaseKVStore 初始化持久化检查点及其内部存储 |
kvStore 为 null 时构造函数会直接抛出 NullPointerException(见源码第 63 行 Objects.requireNonNull)。底层存储抽象 BaseKVStore.java 定义了 set、get、exists、delete、getByPrefix、deleteByPrefix、mget、batchDelete 与 pipeline() 等异步接口(全部返回 CompletableFuture),因此 PersistenceCheckpointer 天然不关心存储是内存、SQLite、文件还是数据库,只要实现了 BaseKVStore 即可接入。
仓库中已经具备三种内置后端:
InMemoryKVStore(源码):基于LinkedHashMap加ReentrantLock,进程退出即丢,适合测试与单进程验证;ShelveStore(源码):基于文件的对象存储,构造时自动创建父目录,提供轻量单机持久化;DbBasedKVStore(源码):基于javax.sql.DataSource的数据库后端,内部使用 Jackson 对值进行 JSON 编码并以__BYTES__:前缀区分字节数据,配合 SQLite 即形成文件型持久化方案。
静态工厂 createFromConfig:一行配置选定后端
PersistenceCheckpointer.createFromConfig(Map<String, Object> conf) 提供了从配置 Map 直接创建实例的便捷入口(源码第 70~96 行),解析优先级如下:
- 若存在
kv_store/kvStore/store键且值为BaseKVStore实例,直接使用该实例; - 否则读取
db_client/dbClient/data_source/dataSource:值为BaseKVStore直接使用,值为DataSource则包装成DbBasedKVStore; - 否则按
db_type(或dbType,默认sqlite)与db_path(或dbPath,默认checkpointer)创建:
db_type 取值 |
生成的后端 | 说明 |
|---|---|---|
memory / in_memory / inmemory |
InMemoryKVStore |
纯内存,测试友好 |
shelve |
ShelveStore |
自动剥离 .db 后缀(stripDbSuffix) |
sqlite(默认) |
DbBasedKVStore(sqliteDataSource(...)) |
自动补 .db 后缀、创建父目录、组装 jdbc:sqlite: URL |
| 其他值 | 抛出 StatusCode.CHECKPOINTER_CONFIG_ERROR |
错误信息包含 db type[...] is not supported |
sqliteDataSource 内部使用一个极简的 DriverManagerDataSource(实现 javax.sql.DataSource 的最小子集)按需创建 JDBC 连接,因此 sqlite 模式下即使不显式注入 DataSource 也能直接开箱运行。值得注意的是 db_path 支持直接传入 jdbc: 开头的完整 JDBC URL,此时 normalizeSqlitePath 会原样透传,不会追加 .db 后缀。
方法全览:生命周期入口与查询 / 释放能力
原文档列出的公开方法及其语义如下:
| 方法签名 | 行为要点 |
|---|---|
void preAgentExecute(BaseSession session, Object inputs) |
从持久化存储恢复 agent 状态;若 inputs 非空且 session.state() 可用,则以 Constant.INTERACTIVE_INPUT 为键写入包含该输入的 List |
void interruptAgentExecute(BaseSession session) |
agent 进入等待交互的中断态时保存 agent 状态 |
void postAgentExecute(BaseSession session) |
agent 执行完成时继续保存 agent 状态(不会自动清空) |
void preWorkflowExecute(BaseSession session, InteractiveInput inputs) |
恢复 workflow 状态;无交互输入但已存在检查点时,仅在强制删除开关打开时清理,否则抛错 |
void postWorkflowExecute(BaseSession session, Object result, Exception exception) |
workflow 异常或中断时保存状态;正常结束时清除 workflow 与图检查点 |
boolean sessionExists(String sessionId) |
通过 kvStore.getByPrefix(sessionId + ":") 判断会话是否已有任何持久化记录 |
void release(String sessionId) |
删除该会话前缀(sessionId + ":")下的全部持久化资源 |
void release(String sessionId, String agentId) |
仅释放某个 agent 的检查点;agentId 为空时退化为释放整个会话 |
Store graphStore() |
返回持久化图状态存储 PersistenceGraphStore |
preAgentExecute:恢复 + 注入交互输入
源码第 99~104 行:
@Override
public void preAgentExecute(BaseSession session, Object inputs) {
agentStorage.recover(session, null);
if (inputs != null && session.state() != null) {
session.state().update(mapOf(Constant.INTERACTIVE_INPUT, new ArrayList<>(List.of(inputs))));
}
}
恢复过程由 BaseSingleStateStorage.recover(...) 完成:通过 KV pipeline 并行读取「dump type」与「blob」两个 key,反序列化后调用 restoreState 写回 session.state()。测试 PersistenceCheckpointerTest.java 中的 agentStatePersistsThroughKvStoreAndRestoresInput 验证了完整闭环:先 preAgentExecute 注入 "first-input" → 更新 turn=1 → postAgentExecute 保存 → 新会话 preAgentExecute 恢复后,turn 仍为 1 且 INTERACTIVE_INPUT 恢复为 ["resume-input"]。
preWorkflowExecute:恢复执行与「旧状态冲突」保护
这是 PersistenceCheckpointer 最需要理解的分支(源码第 130~141 行):
- 有
InteractiveInput:调用workflowStorage.recover(session, inputs),走「恢复执行」路径——恢复 workflow state、把 raw input 写入Constant.INTERACTIVE_INPUT(WorkflowCommitState会走updateAndCommitWorkflowState),把 user inputs 按节点注入NodeSession,最后恢复 commit updates; - 没有交互输入:走
clearOrRejectExistingWorkflowState,若该 session + workflow 已有检查点:- 开启环境变量
SessionConstants.FORCE_DEL_WORKFLOW_STATE_KEY = true时,先graphStore.delete再workflowStorage.clear,允许强制重跑; - 否则抛出
StatusCode.CHECKPOINTER_PRE_WORKFLOW_EXECUTION_ERROR,错误信息为workflow state exists but non-interactive input and cleanup is disabled。
- 开启环境变量
测试 existingWorkflowStateRejectsNonInteractiveInputUnlessForced 精确验证了这两条路:无强制开关时 assertThrows(BaseError.class),开启 FORCE_DEL_WORKFLOW_STATE_KEY 后同一调用不再抛错。
postWorkflowExecute:异常 / 中断 / 正常完成三分支
源码第 144~160 行:
- 异常:
workflowStorage.save(session)保存现场,随后若为RuntimeException直接重抛,否则包装为IllegalStateException重抛——保存动作发生在重抛之前,因此异常现场可恢复; - 结果包含中断标记:通过
result中是否存在PregelConstants.TASK_STATUS_INTERRUPT键判断(containsInterrupt),命中则workflowStorage.save(session),等待交互恢复; - 正常完成:
graphStore.delete(sessionId, workflowId)删除图检查点 +workflowStorage.clear(workflowId, sessionId)删除 workflow 检查点,即「正常完成自动清理」。
sessionExists 与 release:前缀语义与租户感知
sessionExists 与 release 都经由 TenantKVStoreKeyResolver.resolvePrefix(...) 解析前缀。这意味着在启用多租户隔离时,实际落库前缀会带上租户标识,不同租户的同名 session 互不干扰。release(sessionId, agentId) 在 agentId 非空时只调用 agentStorage.clear(agentId, sessionId) 清理单个 agent 的状态,不会清理 workflow 与 graph 状态;agentId 为空或 null 时则 kvStore.deleteByPrefix(sessionId + ":", null) 全量删除。测试 releaseDeletesAgentOrWholeSessionPrefix 验证了:只 release(sessionId, agentId) 后 sessionExists 为 false(因为该测试场景只有 agent 状态),而 release(sessionId) 能把前缀下 agent + workflow + graph 全部清空。
存储键结构与序列化机制
Checkpointer 基类提供了统一的键构造规则(源码):
sessionId:namespace:entityId:suffix
即 buildKeyWithNamespace(sessionId, namespace, entityId, suffixes...),再经 TenantKVStoreKeyResolver 解析后落库。PersistenceCheckpointer 实际写入的键由各内部存储定义:
| 存储 | 落库键(suffix 部分) |
|---|---|
| AgentStorage | agent_state_blobs_dump_type、agent_state_blobs |
| AgentTeamStorage | agent_team_state_blobs_dump_type、agent_team_state_blobs |
| WorkflowStorage | workflow_state_blobs_dump_type、workflow_state_blobs、workflow_update_blobs_dump_type、workflow_update_blobs |
| PersistenceGraphStore | checkpoint_data_type、checkpoint_data_value |
例如一个真实键可能形如:
conversation-001:workflow-graph:transfer_flow_multi_1.0:checkpoint_data_value
序列化由内部共享的 Serializer(Serializer.create("java"))完成:保存时 serializeState 产出「类型 + 字节」二元组(dump type 为 java_serialized),分别写入两个 key;恢复时 deserializeState 先解码 dump type(支持 byte[] 与字符串两种形式),再对 blob 做 Base64 解码(解码失败时退化为 UTF-8 字节),最后 loadsTyped 还原对象。可见当前持久化主线是 Java 序列化对象恢复,而非跨语言统一交换格式。
与 InMemoryCheckpointer 的对比定位
仓库同时提供 InMemoryCheckpointer.java(基于 Guava Cache + 内存 Map + InMemoryStore,默认 TTL 7 天、默认容量 100 个 session),两者实现同一套 Checkpointer 生命周期接口,但定位截然不同:
| 维度 | InMemoryCheckpointer | PersistenceCheckpointer |
|---|---|---|
| 存储介质 | 进程内存 | 任意 BaseKVStore(内存 / shelve / SQLite / 数据库) |
| 进程重启恢复 | 不支持 | 支持(视后端而定) |
| 典型场景 | 本地开发、示例、单元测试 | 单机持久化、统一 KV 存储、生产会话延续 |
| 多租户键解析 | 前缀拼接 tenantId:sessionId |
经 TenantKVStoreKeyResolver 解析 |
测试 factoryCreatesMemoryBackedPersistenceCheckpointer 展示了一个有趣用法:CheckpointerFactory.create(new CheckpointerConfig("persistence", Map.of("db_type", "memory"))) 可以创建「存储后端是内存」的 PersistenceCheckpointer,用于在单元测试中验证持久化逻辑而不引入外部依赖。
装配链路:Provider → Factory → RunnerConfig
1. Provider:把配置转成实例
PersistenceCheckpointerProvider.java 实现了 CheckpointerProvider 接口,typeName() 返回 "persistence",create(conf) 直接委托给 PersistenceCheckpointer.createFromConfig(conf),其 Javadoc 给出了标准配置格式:
{
"kv_store": BaseKVStore instance // 可选,提供后优先使用
"db_type": "sqlite" | "shelve", // 可选,默认 sqlite
"db_path": "checkpointer.db" // 可选,数据库文件路径
}
2. Factory:注册表与内置类型
CheckpointerFactory.java 通过 ServiceLoader 自动发现 META-INF/services/com.openjiuwen.core.session.checkpointer.CheckpointerProvider 中声明的 Provider,并兜底注册 in_memory 与 persistence 两个内置类型;未显式配置时 getCheckpointer() 回退到共享的 InMemoryCheckpointer 单例。SPI 测试 CheckpointerFactorySpiTest.java 验证了「空 conf 仍能创建默认 sqlite 路径的 PersistenceCheckpointer」「kv_store 注入创建 PersistenceCheckpointer」以及 register() 运行时注册 / 覆盖自定义 Provider 的能力。
3. RunnerConfig:最推荐的统一入口
在业务代码中最推荐的做法是在 Runner 启动前通过 RunnerConfig 统一装配(RunnerConfig 的 builder 提供 checkpointerConfig(...),内部经 CheckpointerConfig.fromMap 解析为 type + conf,见 RunnerConfig.java):
import com.openjiuwen.core.runner.Runner;
import com.openjiuwen.core.runner.RunnerConfig;
import java.util.Map;
RunnerConfig config = RunnerConfig.builder()
.distributedMode(false)
.checkpointerConfig(Map.of(
"type", "persistence",
"conf", Map.of(
"db_type", "sqlite",
"db_path", "/data/checkpoints/checkpointer.db"
)
))
.build();
Runner.setConfig(config);
Runner.start();
Runner.start() 的初始化链路(见 Runner.java 的 initializeCheckpointer 与 RunnerImpl.release)依次为:读取 checkpointerConfig → CheckpointerFactory.installDefaultCheckpointer(config) → 内部 create(type, conf) 创建实例并设为默认。之后 Runner.release(sessionId)、AgentInteraction、Workflow/Agent 执行期的 session 都会默认使用它。
测试验证:把语义钉死在证据上
PersistenceCheckpointerTest.java 是理解该组件行为的最佳「可执行文档」,关键用例包括:
- agent 状态持久化与输入恢复:
preAgentExecute注入输入 →postAgentExecute保存 → 新 session 恢复,状态与INTERACTIVE_INPUT均还原; - team 全局状态只恢复 global:
AgentTeamStorage只保存getGlobal(null),本地 agent 状态不会被 team 检查点污染(recoveredState.get("agent_local")为 null); - workflow 中断恢复 raw input 与 user inputs:raw input 走 workflow state 的
INTERACTIVE_INPUT,而 user inputs 按NodeSession逐个注入(workflowUserInputsRestoreOnNodeSessionOnly中questioner节点恢复为["时间是明天提问"]); - graph store 增删查:
graphStore().save / get / delete围绕workflow-graph:前缀工作,delete 按前缀级联清理; - 旧状态冲突保护:无
FORCE_DEL_WORKFLOW_STATE_KEY时preWorkflowExecute(session, (Object) null)抛BaseError,开启后正常通过。
使用建议与注意事项
- agent 完成后不会自动清空:
postAgentExecute会继续保存 agent 状态以保证多轮对话延续;会话彻底结束时请显式调用Runner.release(sessionId)或checkpointer.release(sessionId),避免持久化数据无限累积。 - workflow 重启的旧状态冲突:同一 session 想重新执行一条 workflow,默认会抛「workflow state exists」错误;要么换新 sessionId,要么显式开启
FORCE_DEL_WORKFLOW_STATE_KEY=true。 - graph 与 workflow 状态分离:图检查点(
workflow-graph命名空间)与 workflow 状态(workflow命名空间)分开存储、分开清理,不要把它们理解成「一份 workflow 序列化」。 - 序列化是 Java 对象级:dump type 为
java_serialized,恢复依赖 Java 对象图,跨语言或跨版本升级场景需要额外评估兼容性。 - 自定义存储与脱敏:内置
PersistenceCheckpointer的序列化器是内部固定配置,无法仅靠 Provider 配置替换;需要过滤、加密或限流 checkpoint 数据时,应继承Checkpointer完整实现自定义检查点,并按需复用底层BaseKVStore。
参考入口
- 核心实现:PersistenceCheckpointer.java、Checkpointer.java
- 装配链路:PersistenceCheckpointerProvider.java、CheckpointerFactory.java、CheckpointerConfig.java
- 存储后端:BaseKVStore.java、DbBasedKVStore.java、ShelveStore.java、InMemoryKVStore.java
- 测试验证:PersistenceCheckpointerTest.java、CheckpointerFactorySpiTest.java
- 配套文档:Checkpointer检查点机制、session.checkpointer 根包