> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-zh/gong-zuo-liu/managing-the-state.md).

# 状态管理

一般来说，工作流的目的是将初始状态作为输入，使节点能够在执行过程中操作该状态，并在工作流完成时返回最终状态。

### 工作流输入/输出

工作流本身的最终返回值是工作流状态的一个实例。因此，如果你需要收集工作流执行的结果，节点必须能够在工作流结束前读写状态，并将最终状态返回给父脚本。

你也可以为工作流提供一个初始状态，以传入输入值。

```php
// 1. 提供一个初始状态作为工作流输入，以传入一些数据
$workflow = Workflow::make(state: new WorkflowState(['query' => 'Hi!']))
        ->addNode(new InitialNode())
        ->addNode(...)
        ->addNode(...);

// 2. 执行工作流并获取最终状态
$finalState = $workflow->init()->run();

// 3. 使用最终状态数据
echo $finalState->get('message');
```

### 在节点中使用状态

到目前为止，在我们的示例中，我们一直通过自定义事件的属性在节点之间传递数据。这是一种强大的数据传递方式，但也有其局限性。例如，如果你想在没有直接连接的步骤之间传递数据，就需要让数据经过中间的所有节点。这会使你的代码更难阅读和维护。

为此，我们提供了 `WorkflowState` 对象可供工作流中的每个节点使用。要使用它，工作流会将 WorkflowState 实例注入为节点的第二个参数。

```php
namespace App\Neuron;

use NeuronAI\Workflow\Node;
use NeuronAI\Workflow\StartEvent;
use NeuronAI\Workflow\StopEvent;
use NeuronAI\Workflow\WorkflowState;

class InitialNode extends Node
{
    public function __invoke(StartEvent $event, WorkflowState $state): StopEvent
    {
        $state->set('message', 'Hello World!');
        
        return new StopEvent();
    }
}
```

### 自定义状态

默认的 `WorkflowState` 类是在工作流执行期间用于携带数据的容器。创建一个自定义状态类可能会很有用，它可以定义严格类型的属性，从而更好地支持节点中的代码补全、数据验证以及一般性调试。

创建一个 `CustomState` 类来引入自定义属性：

```php
use App\Models\User;
use NeuronAI\Workflow\WorkflowState;

class CustomState extends WorkflowState
{
    protected User $user;
    
    public function setUser(User $user): CustomState
    {
        $this->user = $user;
        return $this;
    }
    
    public function getUser(): User
    {
        return $this->user;
    }
}
```

节点可以接受一个 `CustomState` 而不是默认的 `WorkflowState`:

```php
class ExampleNode extends Node 
{
    public function __invoke(StartEvent $event, CustomState $state): StopEvent
    {
        // 在你的节点中使用状态属性
        if ($state->getUser()->isAdmin()) {
            //...
        }
        
        return new StopEvent();
    }
}
```

在工作流创建时注入 `CustomState` ：

```php
$state = new CustomState();
$state->setUser($user);

$workflow = MyWorkflow::make(state: $state);

$finalState = $workflow->init()->run();
echo $finalState->getUser()->email;
```