.. Copyright (c) 2025 Huawei Technologies Co., Ltd. All Rights Reserved.

状态维护与重构机制
==========================

在图引擎的运行过程中，系统通过树形结构维护状态信息，以实现状态的可追溯与高效重构。

状态树结构
~~~~~~~~~~~~~~~~~~~~~

* 每个节点的输入是一个完整的 ``State`` 对象。
* 节点的输出不是完整状态，而是该节点的 **状态增量（delta）**。
* 在运行过程中，所有状态以树的形式存储：

 - 根节点表示图引擎的输入状态。

 - 每个子节点包含其父节点引用和当前节点的 ``delta``。

 - 状态恢复时，会递归地从父节点向上合并，逐级重构完整状态。

状态重构逻辑
~~~~~~~~~~~~~~~~~~~~~

当节点或边需要使用完整状态时，图引擎会执行如下步骤：

* 按声明的 **更新策略（update strategy）** 从根节点向下合并所有 ``delta``。

* 将完整状态进行深拷贝后传递给节点或边执行。

.. note::

    由于深拷贝策略，节点和边对输入状态的修改不会影响引擎内部维护的状态树。

改变状态策略的影响
~~~~~~~~~~~~~~~~~~~~~~~

图引擎中存在两类特殊策略，可能导致状态树的根被重置：

* 节点的 ``multi_input_merge_strategy``

* 边的 ``state_filter``

由于这两者都是用户可自定义的合并逻辑，引擎无法保证其结果与原状态完全兼容。因此：

- 一旦执行上述策略，根节点会被重置为策略输出的状态。

- 如果这些策略删除了部分状态信息，这些信息将无法在后续节点中恢复。


**示例：** 有无 ``state_filter`` 的差异

假设有一条线性路径： ``A -> B -> C -> End``

* 初始状态（输入）为：

.. code-block:: python

    state = {"user": {"name": "Alice", "age": 20}, "score": 90}

* 各节点执行逻辑如下：

- **A** 输出增量： ``{"user": {"age": 21}}``
- **B** 输出增量： ``{"score": 95}``

**情况一：** 无 ``state_filter``

边 ``B -> C`` 没有定义 ``state_filter``，因此状态完整传递：

.. code-block:: python

  # Input state of Node C：
  {"user": {"name": "Alice", "age": 21}, "score": 95}

  # GraphEngine output：
  {"user": {"name": "Alice", "age": 21}, "score": 95}

**情况二：** 有 ``state_filter``

假设边 ``B -> C`` 定义了如下过滤器：

.. code-block:: python

  def state_filter(state):
      return {"score": state["score"]}

此时，``state_filter`` 的输出被视为新的根状态，导致 ``user`` 字段被永久丢弃。

.. code-block:: python

  # Input state of Node C：
  {"score": 95}

  # GraphEngine output：
  {"score": 95}

因为 ``state_filter`` 删除了 ``user`` 信息，后续节点无法再收到该字段。

最终状态输出
~~~~~~~~~~~~~~~~~~

图运行过程中， ``end`` 节点会构建 **状态队列** , 收集所有流入的状态：

* 队列中的状态按路由顺序排列。

* 引擎将根据定义的更新策略，依次合并队列中的状态。

* 最终输出即为所有状态合并后的完整 ``State`` 对象。

通过这种机制，图引擎能够在保证状态一致性的同时，实现灵活的状态重构与可追溯性。