agent-core-java 会话状态机制详解:com.openjiuwen.core.session.state 包中的状态分区、提交回滚与快照恢复
agent-core-java 会话状态机制详解:com.openjiuwen.core.session.state 包中的状态分区、提交回滚与快照恢复
本篇围绕 com.openjiuwen.core.session.state 包展开,系统讲解 openJiuwen agent core Java(agent-core-java)中 session 状态管理的核心抽象:状态如何按 io/global/comp/workflow 分区组织、State/StateLike/CommitStateLike 接口体系如何划分只读、可写、可恢复与可提交四类能力、InMemoryState 工厂如何快速构造工作流状态,以及节点级状态分区如何配合 checkpointer 实现中断恢复。读完本文,你可以直接读懂源码中的状态读取、更新、commit/rollback 调用链,并在自定义 Session 扩展或调试工作流状态时正确选用这些类型。
一、状态包定位:session 状态管理的核心抽象
com.openjiuwen.core.session.state 包定义了状态读取、更新、快照恢复、提交回滚以及工作流节点级状态分区的核心抽象,源码位于 core/src/main/java/com/openjiuwen/core/session/state/。该包共 11 个类型,官方 API 文档总览见 state.README.md,各类型的独立文档位于 session/state 目录。
包内类型一览(继承自 state.README.md 的类型表):
| 类型 | 说明 |
|---|---|
AgentStateCollection |
管理 agent 级状态与全局状态分区。 |
CommitStateLike |
为状态对象补充提交、回滚与待提交更新访问能力。 |
InMemoryCommitState |
带待提交缓冲区的内存状态实现。 |
InMemoryState |
创建内存版 WorkflowCommitState 的工厂。 |
InMemoryStateLike |
StateLike 的内存实现。 |
ReadableState |
只读状态接口。 |
RecoverableState |
支持快照导出与恢复的状态接口。 |
State |
session 状态管理的顶层接口。 |
StateLike |
可读写的状态接口。 |
WorkflowCommitState |
带提交/回滚能力的工作流状态集合。 |
WorkflowStateCollection |
管理 io/global/comp/workflow 多分区状态的工作流状态集合。 |
从源码的 Javadoc 注释可以看到(如 State.java 中的 Mirrors Python's State in openjiuwen/core/session/state/base.py),Java 版的状态体系与 Python 版 openjiuwen 的状态实现一一对应,便于两种语言版本的概念互查。
二、接口体系:从只读到可提交的四级能力划分
状态包的核心设计是把"状态"按能力切成四个可组合的接口,源码分别为 ReadableState.java、RecoverableState.java、StateLike.java、CommitStateLike.java:
public interface ReadableState {
Object get(Object key);
Object getByPrefix(Object key, String nestedPrefix);
}
public interface RecoverableState {
Map<String, Object> getState();
void setState(Map<String, Object> state);
}
public interface StateLike extends ReadableState, RecoverableState {
void update(Map<String, Object> data);
Object getByTransformer(Function<Object, Object> transformer);
}
public interface CommitStateLike extends StateLike {
void updateById(String nodeId, Map<String, Object> data);
void commit(String nodeId);
default void commit() { commit(null); }
void rollback(String nodeId);
Map<String, Object> getUpdates();
void setUpdates(Map<String, Object> updates);
}
各接口承担的职责:
ReadableState:只读能力。get(key)按键读取;getByPrefix(key, nestedPrefix)在给定前缀下读取嵌套状态——这是节点间读取输入输出的关键入口,因为工作流状态把"节点输出"以nodeId为前缀存放在 IO 分区中;RecoverableState:快照能力。getState()导出当前状态映射、setState(state)从快照恢复,二者共同支撑 checkpointer 的持久化与恢复流程;StateLike:可读写能力。update(data)合并一组状态更新;getByTransformer(transformer)允许调用方传入转换函数直接从状态对象中提取派生数据,避免把整个 Map 复制出来;CommitStateLike:在StateLike之上引入事务语义。updateById(nodeId, data)把更新先记入待提交缓冲区而不是直接落盘;commit(nodeId)提交指定节点(nodeId = null时实现可以提交全部节点的待提交更新);rollback(nodeId)丢弃指定节点的待提交更新;getUpdates()/setUpdates(updates)用于导出/恢复待提交缓冲区,使"事务中间态"也可以被快照化。
顶层接口 State 则面向 Session 场景,把上述能力与分区键组合起来:
public interface State extends RecoverableState, SessionStateAccess {
String IO_STATE_KEY = "io_state";
String IO_STATE_UPDATES_KEY = "io_state_updates";
String GLOBAL_STATE_KEY = "global_state";
String GLOBAL_STATE_UPDATES_KEY = "global_state_updates";
String COMP_STATE_KEY = "comp_state";
String WORKFLOW_STATE_KEY = "workflow_state";
String AGENT_STATE_KEY = "agent_state";
String COMP_STATE_UPDATES_KEY = "comp_state_updates";
String WORKFLOW_STATE_UPDATES_KEY = "workflow_state_updates";
String DEFAULT_NODE_ID = "default";
String DEFAULT_WORKFLOW_ID = "workflow";
Object getGlobal(Object key);
void updateGlobal(Map<String, Object> data);
void updateTrace(Object span);
void update(Map<String, Object> data);
Object get(Object key);
Map<String, Object> getState();
void setState(Map<String, Object> state);
Map<String, Object> dump();
}
从 State.java 可以看到,State 定义了两类常量:
- 分区键:
io_state(输入输出)、global_state(全局)、comp_state(组件)、workflow_state(工作流)、agent_state(agent)、trace_state(链路追踪),以及对应的*_updates待提交更新键。工作流状态快照就是一张以这些键为 key 的 Map,WorkflowStateCollection.getState() 导出的正是io/global/comp/workflow四个分区组成的映射; - 默认标识:
DEFAULT_NODE_ID = "default"与DEFAULT_WORKFLOW_ID = "workflow",用于根节点和默认工作流分区的引用。
State 的方法分为四组:
getGlobal(key)/updateGlobal(data):读写全局状态分区;get(key)/update(data):读写组件/局部状态(在工作流实现中按当前nodeId包装,见后文);updateTrace(span):写入当前节点的 trace 数据;getState()/setState(state)/dump():快照恢复与调试导出。其中dump()返回已提交状态 + 待提交更新的完整调试视图,而getState()只导出已提交的分区快照,两者区别在 WorkflowStateCollection.dump() 中体现得很清楚——dump()额外包含io_state_updates、global_state_updates、comp_state_updates、workflow_state_updates四个待提交区。
另外还有一个不列入类型表的 SessionStateAccess 接口,它是 BaseSession 等调用方共用的状态表面:只强制要求 get(key) 和 update(data),其余方法(getGlobal、updateGlobal、updateTrace、dump、getState、setState)都给了宽松默认值(返回 null / 空 Map / 空实现),用于兼容那些只提供局部状态读写的轻量实现。
三、InMemoryStateLike:带深拷贝的内存状态实现
InMemoryStateLike 是 StateLike 的内存实现,也是整个状态包的基石。它有三个关键设计点:
1. 对外一律返回深拷贝。 get(key) 和 getState() 返回的都是通过 deepCopy 复制出的 Map/List,嵌套结构也会递归复制(不可复制的值类型原样返回)。这样调用方拿到快照后随意修改,都不会污染状态对象内部数据。测试 StateTest 中有直接验证:
// StateTest.testGetStateDeepCopy
InMemoryStateLike state = new InMemoryStateLike(Map.of("key", "value"));
Map<String, Object> copy = state.getState();
copy.put("newKey", "newValue");
assertNull(state.get("newKey")); // 原始状态不受影响
2. update 做嵌套合并。 update(data) 经由 SessionUtils.updateDict 把传入数据合并进内部状态:先对 data 深拷贝再合并,避免外部 Map 被内部状态持有。对嵌套 Map,行为是"合并不覆盖"——测试 testUpdateMergesNested 验证了初始 data.a=1,更新 data.b=2 后 a、b 同时存在。
3. 全部方法 synchronized。 get、update、getState、setState 均加了同步修饰,状态对象可以安全地在多线程的节点执行场景中被共享。
public class InMemoryStateLike implements StateLike {
private Map<String, Object> state;
public InMemoryStateLike(Map<String, Object> initialState) {
this.state = initialState == null ? new LinkedHashMap<>() : deepCopyMap(initialState);
}
@Override
public synchronized Object get(Object key) {
return deepCopy(SessionUtils.getBySchema(key, state));
}
@Override
public synchronized void update(Map<String, Object> data) {
SessionUtils.updateDict(deepCopyMap(data), state);
}
// getByPrefix / getByTransformer / getState / setState 略
}
注意 getByTransformer(transformer) 是把内部原始状态直接交给转换函数处理的,不经过深拷贝,适合"只读提取"型场景。
四、InMemoryCommitState:待提交缓冲区与提交/回滚
InMemoryCommitState 在 StateLike 之上实现了 CommitStateLike,核心是一个 Map<String, List<Map<String, Object>>> updates 待提交缓冲区,按 nodeId 分组缓存更新。其事务语义如下:
| 方法 | 行为(源码依据:InMemoryCommitState.java) |
|---|---|
update(data) |
直接抛异常。提交型状态不允许无节点上下文的更新,强制调用方显式提供 nodeId。 |
updateById(nodeId, data) |
把一份深拷贝后的更新追加到该节点的待提交列表;nodeId = null 时抛异常。 |
commit(nodeId) |
将指定节点的全部待提交更新依次应用到底层 state,然后清空该节点缓冲区;nodeId = null 时提交所有节点的全部待提交更新并清空整个缓冲区。 |
rollback(nodeId) |
清空指定节点的待提交更新,底层已提交状态不受影响。 |
getUpdates() / setUpdates(updates) |
导出/恢复待提交缓冲区,使事务中间态可快照化。 |
get/getByPrefix/getByTransformer/getState/setState |
全部透传到底层 StateLike,读取的始终是已提交的数据。 |
StateTest 对这条事务链有完整验证(StateTest.java):
InMemoryCommitState commitState = new InMemoryCommitState();
commitState.updateById("node1", Map.of("key", "value"));
assertNull(commitState.get("key")); // 提交前读不到
commitState.commit("node1");
assertEquals("value", commitState.get("key")); // 提交后可读
// rollback 场景
commitState.updateById("node1", Map.of("key", "value"));
commitState.rollback("node1");
commitState.commit("node1");
assertNull(commitState.get("key")); // 回滚后提交也不会落盘
正是"先缓冲、后落盘"的机制,让工作流在节点执行失败时可以整节点回滚,而不会留下半提交状态。
五、WorkflowStateCollection 与 WorkflowCommitState:四分区工作流状态
5.1 四分区集合
WorkflowStateCollection 是 State 的工作流实现,同时持有四个 CommitStateLike 分区——ioState(IO)、globalState(全局)、compState(组件)、workflowState(工作流)——外加 traceState 缓存以及 parentId/nodeId 节点标识。构造时 parentId 缺省为空字符串,nodeId 缺省为 State.DEFAULT_NODE_ID。
其读写路由规则值得细看:
update(data):把组件状态包装在当前nodeId之下(wrappedData.put(nodeId, data))再写入compState的待提交区。即组件状态按节点隔离,get(key)通过compState.getByPrefix(key, nodeId)读回当前节点的那一段;key = null时返回节点整段状态;getGlobal(key):优先读globalState;若缺值则依次回退到ioState.getByPrefix(key, parentId)和ioState.getByPrefix(key, nodeId)——即全局读取带有"父节点 IO → 当前节点 IO"的兜底链路;updateGlobal(data):记入当前节点对应的全局状态待提交区(globalState.updateById(nodeId, data)),并非立即生效;commitCmp():只提交当前节点的compState与ioState,用于节点完成时的局部提交。
5.2 WorkflowCommitState:节点级状态分区与提交/回滚
WorkflowCommitState 继承 WorkflowStateCollection,在其上补齐了完整的提交/回滚/节点派生能力,是 Session 层最常用到的状态对象。关键方法:
public void commit() {
ioState.commit(null);
compState.commit(null);
globalState.commit(null);
workflowState.commit(null);
}
public void rollback() {
compState.rollback(nodeId);
ioState.rollback(nodeId);
globalState.rollback(nodeId);
workflowState.rollback(nodeId);
}
public WorkflowCommitState createNodeState(String newNodeId, String newParentId) {
return new WorkflowCommitState(ioState, globalState, compState, workflowState,
traceState, newParentId, newNodeId);
}
commit()把四个分区中所有节点的待提交更新一次性落盘;而rollback()只针对当前节点做回滚,粒度差异是理解执行流程的关键;createNodeState(newNodeId, newParentId)用共享的四个分区对象创建一个新的节点级状态对象——父子节点共享同一份分区存储,但各自维护独立的nodeId/parentId视角,这正是"节点级状态分区"的实现方式:每个节点看到的状态是按自身nodeId前缀隔离的子集;- IO 分区辅助方法:
setOutputs(data)把当前节点输出以nodeId为前缀写入ioState待提交区;getInputs(schema)/getOutputs(targetNodeId)通过getByPrefix按前缀解析节点输入输出;commitUserInputs(inputs)把用户输入同时写入 IO 与全局分区并立即commit(); getState()/setState()导出/恢复io/global/comp/workflow四分区快照;getUpdates()/setUpdates()额外处理四分区各自的*_updates待提交区,保证 checkpointer 持久化的不只是已提交状态,还包括未提交的事务中间态。
5.3 在 Session 与图执行中的真实使用
WorkflowCommitState 是 graph 执行与检查点机制的交汇点。从源码结构看:
- graph/AtomicNode.java 中的
validateSessionAndState(session)会把 Session 携带的状态校验为WorkflowCommitState后交给原子节点执行,图节点在执行时通过它读写分区状态; - checkpointer/InMemoryCheckpointer.java 在保存/恢复检查点时,多次对
session.state()做instanceof WorkflowCommitState判断,利用其getState()/setState()快照与getUpdates()/setUpdates()待提交区完成状态持久化与中断恢复; - graph/Vertex.java 与 graph/stream_actor/ActorManager.java 同样以
WorkflowCommitState作为节点执行期的状态载体。
对使用者而言这意味着:只要 Session 的状态是 WorkflowCommitState,中断恢复、检查点、节点级回滚等能力即可自动生效;自定义状态实现时需要至少覆盖 RecoverableState 的快照接口并保持 State 的分区键约定。
六、AgentStateCollection 与 InMemoryState 工厂
6.1 Agent 侧的两分区实现
AgentStateCollection 是 State 的 agent 侧实现,只管理 globalState 与 agentState 两个 InMemoryStateLike 分区(外加空的 traceState 缓存),且不引入待提交缓冲:
get(key)/update(data):读写 agent 状态分区,key = null时返回完整 agent 状态映射;getGlobal(key)/updateGlobal(data):读写全局分区,key = null时返回完整全局映射;getState()/setState():导出/恢复global_state+agent_state组成的快照;dump()额外附带trace_state;updateTrace(span)当前为空实现(与 Python 版行为一致);另提供getGlobalStateLike()暴露内部全局状态对象。
从源码结构看,Agent 场景(如 ReAct 循环)不需要节点级事务,因此直接使用直写的 InMemoryStateLike,与工作流侧的 InMemoryCommitState 形成对照。
6.2 InMemoryState:一行构造完整工作流状态
InMemoryState 是私有构造的工厂类,用于快速组装内存版 WorkflowCommitState:
// 空状态
WorkflowCommitState state = InMemoryState.create();
// 携带初始分区数据(任一分区可传 null)
WorkflowCommitState state = InMemoryState.create(ioState, globalState, compState,
workflowState, traceState);
// 从 getState()/快照 Map 恢复
Map<String, Object> snapshot = state.getState();
WorkflowCommitState restored = InMemoryState.fromMap(snapshot);
fromMap(stateMap) 按 io_state、global_state、comp_state、workflow_state、trace_state 五个键解包快照,null 入参会退化为空的 create();新建的状态对象使用 parentId = ""、nodeId = State.DEFAULT_NODE_ID 作为根节点视角。这个"快照 Map → 状态对象"的往返正是快照恢复流程中最常用的一对操作,session/internal/WorkflowSession.java 与 workflow/Workflow.java 等 Session/工作流入口都通过该工厂构建初始状态。
七、类型关系总结与验证入口
把整个包串起来,类型关系可以概括为一条继承链加两条集合实现:
ReadableState ─┐
├─ StateLike ── CommitStateLike ──┐
RecoverableState ┘ │
│(分区组件)
SessionStateAccess ── State ◄─ WorkflowStateCollection ◄─ WorkflowCommitState
◄─ AgentStateCollection
InMemoryStateLike implements StateLike
InMemoryCommitState implements CommitStateLike(底层复用 StateLike)
InMemoryState ── 工厂 ──► WorkflowCommitState
- 需要只读 + 快照(检查点、调试)时依赖
ReadableState/RecoverableState; - 需要事务语义(节点级缓冲、提交/回滚)时实现
CommitStateLike,参考InMemoryCommitState; - 组装完整工作流 Session 状态时直接用
InMemoryState.create()/fromMap(); - 组装 Agent 侧状态时用
new AgentStateCollection()。
功能验证可以运行状态包的专属测试 core/src/test/java/com/openjiuwen/core/session/state/StateTest.java(覆盖 InMemoryStateLike 深拷贝与嵌套合并、InMemoryCommitState 的 updateById/commit/rollback 全链路、以及 WorkflowCommitState/AgentStateCollection 的快照往返),相关文档也提到 AgentSessionApiTest、SessionBasicTest、SessionTest、StreamOutputTest、WorkflowInteractionTest 等测试间接覆盖这些类型;Session 层整体行为可结合 session.README.md 与 Checkpointer检查点机制 继续阅读。