Repository navigation
Description
Is there an existing issue for this?
- I have searched the existing issues
Current Behavior
用户通过 KeyStrategyFactory 为 "input" key 注册了非 Replace 语义的策略(如 AppendStrategy)后,只要图使用了 checkpoint(StateGraph.compile() 默认注册 MemorySaver,因此实际总是开启),第一次节点执行完成后,CompiledGraph 内部共享的 keyStrategyMap 中 "input" 的策略就会被静默覆写为 ReplaceStrategy,并影响后续所有运行与状态恢复路径。
根因是三段代码的叠加:
CompiledGraph.cloneState(graph-core,CompiledGraph.java#L493-495)把编译期共享的keyStrategyMap按引用传入OverAllState2 参构造:
public OverAllState cloneState(Map<String, Object> data) throws IOException, ClassNotFoundException {
return new OverAllState(stateGraph.getStateSerializer().cloneObject(data).data(), getKeyStrategyMap());
}OverAllState2 参构造(OverAllState.java#L169-174)直接持有该引用,并无条件覆写注册"input" -> new ReplaceStrategy():
protected OverAllState(Map<String, Object> data, Map<String, KeyStrategy> keyStrategies) {
this.data = data != null ? new HashMap<>(data) : new HashMap<>();
this.keyStrategies = keyStrategies != null ? keyStrategies : new HashMap<>();
this.registerKeyAndStrategy(OverAllState.DEFAULT_INPUT_KEY, new ReplaceStrategy()); // put 进共享 map
}其中 registerKeyAndStrategy 是 this.keyStrategies.put(key, strategy)(无条件覆盖)。
GraphRunnerContext.addCheckpoint(GraphRunnerContext.java#L255-266)在每个节点输出后调用cloneState(overallState.data()),于是每次 checkpoint 都会触发一次对共享 map 的覆写写入。
Expected Behavior
cloneState产出的克隆状态不应改动CompiledGraph共享的keyStrategyMap;- 用户为
"input"(或任何 key)注册的策略语义在 checkpoint / resume / HITL 场景下保持不变。
Steps To Reproduce
-
In this environment:
spring-ai-alibaba-graph-core模块,Spring AI Alibaba 1.1.2.2(与 main 分支一致),JDK 17,无需任何外部依赖。 -
With this config: 通过
KeyStrategyFactory为"input"key 注册非 Replace 语义的策略(AppendStrategy),并用StateGraph.compile()编译——compile()默认注册MemorySaver,因此 checkpoint 实际总是开启:
KeyStrategyFactory keyStrategyFactory = () -> {
Map<String, KeyStrategy> m = new HashMap<>();
m.put("input", new AppendStrategy()); // 用户为 input 注册追加语义
m.put("messages", new AppendStrategy());
return m;
};
var workflow = new StateGraph(keyStrategyFactory)
.addNode("agent", node_async(state -> Map.of("messages", "hello")))
.addEdge(START, "agent")
.addEdge("agent", END);
var app = workflow.compile(); // 默认注册 MemorySaver
// 编译后策略正确
assertInstanceOf(AppendStrategy.class, app.getKeyStrategyMap().get("input"));- Run
app.invoke(Map.of("input", "a"))——第一次节点执行会触发addCheckpoint→cloneState。完整最小复现测试如下(或mvn test -Dtest=CloneStateKeyStrategyPollutionTest -pl spring-ai-alibaba-graph-core):
public class CloneStateKeyStrategyPollutionTest {
@Test
public void cloneStateMustNotMutateCompiledGraphKeyStrategyMap() throws Exception {
KeyStrategyFactory keyStrategyFactory = () -> {
Map<String, KeyStrategy> m = new HashMap<>();
m.put("input", new AppendStrategy()); // 用户为 input 注册追加语义
m.put("messages", new AppendStrategy());
return m;
};
NodeAction agent = state -> Map.of("messages", "hello");
var workflow = new StateGraph(keyStrategyFactory)
.addNode("agent", node_async(agent))
.addEdge(START, "agent")
.addEdge("agent", END);
var app = workflow.compile(); // 默认注册 MemorySaver
// 编译后策略正确
assertInstanceOf(AppendStrategy.class, app.getKeyStrategyMap().get("input"));
app.invoke(Map.of("input", "a")); // 触发节点执行 → addCheckpoint → cloneState
// 断言失败:此时 getKeyStrategyMap().get("input") 已经是 ReplaceStrategy
assertInstanceOf(AppendStrategy.class, app.getKeyStrategyMap().get("input"),
"cloneState 不应污染 CompiledGraph 共享的 keyStrategyMap");
}
}- See error: 第二处断言失败——首次 checkpoint 后,
CompiledGraph共享的keyStrategyMap中"input"的策略已被静默覆写为ReplaceStrategy:
org.opentest4j.AssertionFailedError: cloneState 不应污染 CompiledGraph 共享的 keyStrategyMap
==> Unexpected type, expected: <com.alibaba.cloud.ai.graph.state.strategy.AppendStrategy>
but was: <com.alibaba.cloud.ai.graph.state.strategy.ReplaceStrategy>
Environment
- Spring AI Alibaba version(s): 1.1.2.2(main 分支,spring-ai-alibaba-graph-core)
- JDK: 17
- Maven: 3.9.4
- OS: Windows 11Debug logs
org.opentest4j.AssertionFailedError: cloneState 不应污染 CompiledGraph 共享的 keyStrategyMap
==> Unexpected type, expected: <com.alibaba.cloud.ai.graph.state.strategy.AppendStrategy>
but was: <com.alibaba.cloud.ai.graph.state.strategy.ReplaceStrategy>
Anything else?
影响面
- 策略语义静默退化:注册了
"input" -> AppendStrategy(或 MergeStrategy 等非 Replace 策略)的用户,在第一次 checkpoint 后 input 的合并语义退化为 REPLACE。resume / 人工介入(HITL)等依赖getInitialState按 strategy 合并输入的场景,行为会随「是否已经跑过 checkpoint」而不同。 - 并发隐患:
CompiledGraph是可并发复用的,而每次 checkpoint 都对共享的HashMap做一次put写入,与并发invoke中的读路径(策略查找、遍历)构成非同步的读写竞争。 - 同一覆写逻辑也存在于
OverAllState.snapShot()(OverAllState.java#L120-123):并行分支快照(ParallelNode.java#L458)会丢失自定义的"input"策略(仅影响快照本身,不污染共享 map)。
修复建议
2 参 / 3 参构造对传入的策略 map 做防御性拷贝,并且仅在 key 不存在时补默认的 "input" 策略:
this.keyStrategies = keyStrategies != null ? new HashMap<>(keyStrategies) : new HashMap<>();
this.keyStrategies.putIfAbsent(OverAllState.DEFAULT_INPUT_KEY, new ReplaceStrategy());这样 cloneState / snapShot 既保留用户注册的全部策略(含 "input"),也不再与共享 map 产生别名关系。已排查过可能的兼容性影响:正常使用路径中,克隆态上的策略注册不应外溢到 CompiledGraph;如果维护者确认存在依赖「克隆态写策略传播回全局」的用法,也可以只在 cloneState 调用处做拷贝,保持构造器行为不变。
我已在本地(1.1.2.2)复现并验证了上述分析与修复思路,如果确认是 bug,我可以提交修复 PR(含回归测试)。
Activity
yuluo-yx commentedon Oct 6, 2026
https://github.com/agentic-ai-java/argi
可以提在这里
konlue commentedon Oct 7, 2026
@yuluo-yx 感谢指引!我已经把完整修复提到 argi 了:agentic-ai-java/argi#115(fix(graph): preserve
user-registered input KeyStrategy across state cloning and snapshots)
和 PR #5002 的关系说明一下:#5002 的构造器防御性拷贝已经解决了共享 keyStrategyMap
的别名污染与并发写入,这部分没问题;不过拷贝之后两个构造器仍会无条件
registerKeyAndStrategy("input", new ReplaceStrategy()),克隆态自身还是丢用户注册的
input 策略——影响 OverAllState.snapShot()(ParallelNode / ConditionalParallelNode
的并行分支快照)和 NodeExecutor 传给 InterruptableAction 的克隆态,对应本 issue 的
Expected Behavior 第 2 点。
argi 这个 PR 在拷贝基础上把默认 input 注册改成了 putIfAbsent,并补了 2 个回归测试
(修复前红 / 修复后绿,argi-graph-core 模块回归无破坏)。
fix(graph): keep user-registered input strategy across clones and sna…