openJiuwen agent-core-java PersistenceCheckpointer 持久化检查点全解析:基于 BaseKVStore 的会话状态保存、恢复与释放

原创2026-10-14 12:02:551,901 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

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 行),解析优先级如下:

  1. 若存在 kv_store / kvStore / store 键且值为 BaseKVStore 实例,直接使用该实例;
  2. 否则读取 db_client / dbClient / data_source / dataSource:值为 BaseKVStore 直接使用,值为 DataSource 则包装成 DbBasedKVStore;
  3. 否则按 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,开启后正常通过。

使用建议与注意事项

  1. agent 完成后不会自动清空:postAgentExecute 会继续保存 agent 状态以保证多轮对话延续;会话彻底结束时请显式调用 Runner.release(sessionId) 或 checkpointer.release(sessionId),避免持久化数据无限累积。
  2. workflow 重启的旧状态冲突:同一 session 想重新执行一条 workflow,默认会抛「workflow state exists」错误;要么换新 sessionId,要么显式开启 FORCE_DEL_WORKFLOW_STATE_KEY=true。
  3. graph 与 workflow 状态分离:图检查点(workflow-graph 命名空间)与 workflow 状态(workflow 命名空间)分开存储、分开清理,不要把它们理解成「一份 workflow 序列化」。
  4. 序列化是 Java 对象级:dump type 为 java_serialized,恢复依赖 Java 对象图,跨语言或跨版本升级场景需要额外评估兼容性。
  5. 自定义存储与脱敏:内置 PersistenceCheckpointer 的序列化器是内部固定配置,无法仅靠 Provider 配置替换;需要过滤、加密或限流 checkpoint 数据时,应继承 Checkpointer 完整实现自定义检查点,并按需复用底层 BaseKVStore。

参考入口

登录后查看全文
agent-core-java