Skip to content

[BUG] graph-core: CompiledGraph.cloneState 按引用共享 keyStrategyMap,首次 checkpoint 后用户注册的 "input" KeyStrategy 被静默覆写为 ReplaceStrategy #4999

Open

Description

@konlue

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,并影响后续所有运行与状态恢复路径。

根因是三段代码的叠加:

  1. CompiledGraph.cloneState(graph-core,CompiledGraph.java#L493-495)把编译期共享的 keyStrategyMap 按引用传入 OverAllState 2 参构造:
public OverAllState cloneState(Map<String, Object> data) throws IOException, ClassNotFoundException {
    return new OverAllState(stateGraph.getStateSerializer().cloneObject(data).data(), getKeyStrategyMap());
}
  1. OverAllState 2 参构造(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)(无条件覆盖)。

  1. GraphRunnerContext.addCheckpoint(GraphRunnerContext.java#L255-266)在每个节点输出后调用 cloneState(overallState.data()),于是每次 checkpoint 都会触发一次对共享 map 的覆写写入。

Expected Behavior

  1. cloneState 产出的克隆状态不应改动 CompiledGraph 共享的 keyStrategyMap;
  2. 用户为 "input"(或任何 key)注册的策略语义在 checkpoint / resume / HITL 场景下保持不变。

Steps To Reproduce

  1. In this environment: spring-ai-alibaba-graph-core 模块,Spring AI Alibaba 1.1.2.2(与 main 分支一致),JDK 17,无需任何外部依赖。

  2. 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"));
  1. 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");
    }
}
  1. 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 11

Debug 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?

影响面

  1. 策略语义静默退化:注册了 "input" -> AppendStrategy(或 MergeStrategy 等非 Replace 策略)的用户,在第一次 checkpoint 后 input 的合并语义退化为 REPLACE。resume / 人工介入(HITL)等依赖 getInitialState 按 strategy 合并输入的场景,行为会随「是否已经跑过 checkpoint」而不同。
  2. 并发隐患:CompiledGraph 是可并发复用的,而每次 checkpoint 都对共享的 HashMap 做一次 put 写入,与并发 invoke 中的读路径(策略查找、遍历)构成非同步的读写竞争。
  3. 同一覆写逻辑也存在于 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

  1. konlue commented on Oct 7, 2026

    @konlue
    Author

    @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 模块回归无破坏)。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions