> 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/human-in-the-loop.md).

# 中断

关键突破在于，中断不是 bug，而是一项功能。

Neuron 的中断模式让工作流可以暂停执行并等待外部输入——无论是人工决策，还是来自其他系统的事件——然后在稍后恢复，甚至在数小时或数天后、另一个进程中也可以。

在这个主要版本中，心智模型基于一条规则：

> **暂停会将数据&#x20;*****发送出去*****&#x20;，从节点中。恢复会将数据&#x20;*****带回*****.**

* **出站 — `InterruptRequest`**：对这次暂停的描述。节点构建它，是为了告诉外部世界 *它在等待什么* （需要批准的操作、事件名称、待审查内容）。它是不可变的，也绝不会被交回工作流中。
* **入站 — 载荷数组**：满足暂停的答案。一个普通的、可安全序列化的 `数组` ，通过 `resume(payload: [...])`传入。被中断的节点会把它接收为 **返回值** ，来自挂起调用。

### 工作原理

AI 工作流常常需要在执行中途停下来，通常是为了在采取行动前向人工请求批准，而不必在人工决定期间一直保持 PHP 进程存活。要暂停时，节点会调用 `interrupt()`：工作流停止遍历，持久化其进度，并且向调用者正常返回，同时将状态标记为已中断。

```php
namespace App\Neuron;

use NeuronAI\Workflow\Events\Event;
use NeuronAI\Workflow\Interrupt\Action;
use NeuronAI\Workflow\Interrupt\ApprovalRequest;
use NeuronAI\Workflow\Node;
use NeuronAI\Workflow\WorkflowState;

class ApprovalNode extends Node
{
    public function __invoke(
        PurchaseEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // 挂起工作流，将请求 OUTBOUND 发送出去。
        $payload = $this->interrupt(
            new ApprovalRequest(
                message: '您是否批准这笔购买？',
                actions: [
                    new Action(
                        id: 'purchase_1',
                        name: 'Purchase',
                        description: "购买 {$event->item}，价格为 {$event->price}$",
                    ),
                ],
            )
        );

        // 下方代码仅在恢复时运行。
        // $payload 是由 resume() 传入的 INBOUND 答案——你的节点会对它进行解析。
        if (($payload['purchase_1'] ?? null) === 'approve') {
            return new PurchaseApprovedEvent();
        }

        return new PurchaseRejectedEvent();
    }
}
```

生命周期：

1. **请求** — 节点构建一个 `InterruptRequest` 描述暂停的请求并调用 `interrupt()`.
2. **挂起** — 执行器停止遍历，持久化工作流的步骤，并将返回的状态标记为已中断。请求会随状态向外发送，供你的应用渲染。
3. **决策** — 你的应用向人工展示请求并收集答案。
4. **恢复** — 你调用 `resume($payload)` 在一个以相同 `runId`重建的工作流上。遍历会重新播放：已完成的节点会被跳过，而被中断的节点会带着注入的载荷重新运行—— `interrupt()` 它会返回该载荷，而不是再次挂起。

#### 持久化层

挂起与恢复通过 **重放**实现：每个节点都作为一个持久化步骤执行，已完成的步骤会被持久化，以便恢复后的运行能直接跳到被中断的节点。这需要一个持久化后端。没有它，就没有可恢复的来源。

```php
use NeuronAI\Workflow\Persistence\FilePersistence;
use NeuronAI\Workflow\Persistence\PersistenceInterface;
use NeuronAI\Workflow\Workflow;

class MyWorkflow extends Workflow
{
    ...
    
    protected function persistence(): PersistenceInterface
    {
        return new FilePersistence(__DIR__);
        // 或：new DatabasePersistence($pdo)
        // 或：Laravel 应用使用 EloquentPersistence
    }
}
```

默认的 `InMemoryPersistence` 支持在 **同一进程内** 挂起与恢复（在测试中很有用）；当恢复发生在稍后的请求或后台工作进程中时，请使用 `FilePersistence`, `DatabasePersistence`，或 `EloquentPersistence` 。

请求是一次性的。 `InterruptRequest` 请求本身不会被持久化；每个步骤只会存储一个“已中断”标志。恢复时，节点会重新执行并确定性地重建请求（通过重放重新运行）。

两个结果：

* 你可以放心地在自定义请求中放入活动对象实例，因为它们不会被序列化。
* 如果你的应用需要稍后显示“这个运行在等待什么？”，请在挂起时自行存储请求（见下文）；框架会通过返回的状态把它交给你。

### 捕获中断

挂起之后，你的应用必须检测工作流已暂停，向人工展示请求，并保留一个句柄以便之后回来。由于 `run()` 会正常返回，这里只需对返回的状态做一个简单检查： `isInterrupted()` 会告诉你工作流已暂停， `getInterruptRequest()` 会给你用于渲染的出站请求，而 `runId` 就是恢复令牌。

```php
use NeuronAI\Workflow\Persistence\FilePersistence;
use NeuronAI\Workflow\Persistence\PersistenceInterface;
use NeuronAI\Workflow\Workflow;

class MyWorkflow extends Workflow
{
    protected function nodes(): array
    {
        return [
            new FirstNode(),
            new ApprovalNode(),
            new FinalNode(),
        ];
    }
    
    protected function persistence(): PersistenceInterface
    {
        return new FilePersistence(__DIR__);
    }
}

// 运行工作流
$state = $workflow->setWorkflowId('wk_id')->run();

// 检查它是否被中断
if ($state->isInterrupted()) {
    $request = $state->getInterruptRequest();  // 出站请求——将其渲染出来
    $runId = $workflow->getRunId();            // 恢复令牌——将其保存

    // 例如连同恢复令牌一起为你的 UI 存储它
    $stmt = $pdo->prepare("INSERT INTO pending_approvals (run_id, request) VALUES (?, ?)");
    $stmt->execute([$runId, json_encode($request)]);
}
```

每个 `InterruptRequest` 都是 `JsonSerializable`，所以 `json_encode($request)` 能为你的前端提供渲染该暂停所需的一切。

#### 恢复

一旦你拿到人工的答案，就用 **相同的 `runId`** ，并传入入站载荷。你永远不需要重建或把请求传回去——载荷本身就是答案。 `resume()` 不接受步骤标识符：框架通过重放找到被中断的步骤。

```php
// 一个新的进程，一个新的 HTTP 请求——数小时后。
$workflow = Workflow::make(runId: $runId)->setWorkflowId('wk_id');

// 入站载荷——一个包含该暂停答案的普通数组。
$finalState = $workflow->resume(['purchase_1' => 'approve']);
```

如果工作流在下游再次挂起（多个审批点），返回的状态会再次处于中断状态，循环会以相同的 `runId`.

### 条件中断

使用 `interruptIf()` 仅在条件成立时才挂起。该条件可以是布尔值或回调；当条件不成立时，该方法返回 `null` 并继续执行。

```php
$payload = $this->interruptIf(
    $order->total > 1000,
    new ApprovalRequest(
        message: '高价值订单——需要批准。',
        actions: [new Action('order_1', '批准订单', "总额：{$order->total}$")],
    )
);

// 或延迟求值
$payload = $this->interruptIf(
    fn (): bool => $state->get('confidence', 1.0) < 0.5,
    new ApprovalRequest(/* ... */)
);
```

### 等待外部事件

有时答案并不是来自人工，而是来自其他系统，比如支付 webhook、文档上传、第三方 API 的回调。针对这种情况 `awaitEvent()` 会在给定名称的事件送达之前挂起工作流。它是 `interrupt()` 的语法糖，内置了 `WaitForEventRequest`，因此无需自定义类。

```php
class WaitForPaymentNode extends Node
{
    public function __invoke(
        OrderCreatedEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // 挂起，直到收到 'payment.confirmed'。
        $payment = $this->awaitEvent('payment.confirmed');

        $state->set('transaction_id', $payment['transaction_id']);
        return new OrderPaidEvent();
    }
}
```

发送该事件只是一次从事件在你的应用中落地之处发起的恢复——通常是一个 webhook 控制器：

```php
// 当支付提供方回调时，你的 webhook 控制器：
$workflow = OrderWorkflow::make(runId: $order->workflow_run_id)
    ->setPersistence($persistence);

$workflow->signal('payment.confirmed', ['transaction_id' => $webhook['tx_id']])->run();
```

请求上的事件名称是你的应用用来把正确事件路由到正确运行的依据。框架本身不会派发事件；你的代码决定哪个被中断的 `runId` 对应于传入的事件。

### 自定义中断请求

内置的 `ApprovalRequest` 用于对一组操作建模批准/拒绝决策。当你的暂停需要不同的形态——比如，人类在保存前编辑生成内容——就继承一个现有请求类型，并添加 UI 所需的出站上下文。扩展 `WaitForEventRequest` （人工答案是一个传递给工作流的外部事件）；你专门化的是载荷，而不是暂停类别。

```php
namespace App\Neuron;

use NeuronAI\Workflow\Interrupt\WaitForEventRequest;

class ContentReviewRequest extends WaitForEventRequest
{
    public const EVENT_NAME = 'content.review';
    
    public function __construct(
        protected string $message,
        protected string $content,
        ?DateTimeImmutable $expiresAt = null,
    ) {
        parent::__construct(self::EVENT_NAME, $expiresAt);
    }

    public function getMessage(): string
    {
        return $this->message;
    }

    public function getContent(): string
    {
        return $this->content;
    }

    public function jsonSerialize(): array
    {
        return [
            'type' => $this->type(),
            'note' => $this->note,
            'content' => $this->content,
        ];
    }
}
```

该请求只描述这次暂停，并可用于携带你的应用需要向用户展示被中断流程的信息。

在节点中使用它。答案会作为载荷返回：

```php
class ContentReviewNode extends Node
{
    public function __invoke(
        DraftEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // 先把文章生成一次，并持久化（见下方 memoize）。
        $draft = $this->memoize('draft', fn (): string => ContentCreatorAgent::make()
            ->chat(new UserMessage($event->prompt))
            ->getMessage()
            ->getContent());

        // 挂起：将草稿发送出去供审阅。
        $payload = $this->interrupt(
            new ContentReviewRequest('请在发布前审阅这篇文章。', $draft)
        );

        // 恢复：编辑后的文本会作为载荷回传。
        $state->set('content', $payload['edited_content']);

        return new PublishEvent();
    }
}
```

在应用侧：

```php
$state = $workflow->setWorkflowId('wk_id')->run();

if ($state->isInterrupted()) {
    /** @var ContentReviewRequest $request */
    $request = $state->getInterruptRequest();
    // 在你的编辑器 UI 中渲染 $request->getContent()...
}

// 稍后，将编辑后的文本作为载荷传入：
$finalState = $workflow->signal(
    event: ContentReviewRequest::EVENT_NAME, 
    payload: ['edited_content' => $editedText]
)->run();
```

### 消费反馈

对中断的答案就是你传给 run() 方法的 **载荷** ，而消费它的主要方式就是挂起动词的返回值，也就是暂停发生的那个位置：

```php
$payload = $this->interrupt(new ContentReviewRequest(...));
// 恢复时：$payload 是返回的答案
```

如果你需要在 *到达* interrupt 调用之前就分支——例如在恢复时完全跳过挂起前逻辑——节点直接暴露恢复上下文：

```php
public function __invoke(
    InputEvent $event, 
    WorkflowState $state,
    WorkflowResources $resources
): Event {
    // 当该节点运行由 resume() 触发时，isResuming() 为 true：
    // 入站载荷已经被注入，并且可以在一开始直接读取。
    if ($this->isResuming()) {
        $payload = $this->getResumePayload();

        if (($payload['review_1'] ?? null) === 'approve') {
            $state->set('is_sufficient', true);
            return new OutputEvent();
        }
    }

    // 首次通过（或被拒绝）：执行工作并挂起。
    $this->interrupt(
        new ApprovalRequest(
            message: '我还要继续吗？',
            actions: [new Action('review_1', '回答审阅', $state->get('review'))],
        )
    );

    return new InputEvent(); // 首次运行时不可达；在被拒绝的恢复时可达
}
```

在大多数节点中，你不需要这样做：把挂起前的工作包进 `memoize()` ，然后让节点重新运行。已 memoize 的工作会被回忆，不会重复，线性的 `interrupt()`-返回答案风格依然易读。

### 持久化步骤和 `memoize()`

当工作流恢复时，被中断的节点 **会从顶部重新执行** ——在 interrupt 调用之前的任何语句都会再次运行，可能会重复计费一次 LLM 调用或再次发送一封电子邮件。有两层持久性保护你。

**节点之间，你可以免费获得持久性。** 每个节点都作为一个持久化步骤执行：已完成的步骤会被持久化并在重放时跳过。 *到达* 未被中断的节点永远不会重新运行。

**在节点内部，使用 `memoize()`.** 它会执行一个闭包，并在节点内部、节点返回之前持久化其返回值。节点重新执行时——在恢复后，或在崩溃后——记录下来的值会被返回 *而无需* 再次运行该闭包。

```php
class SentimentNode extends Node
{
    public function __invoke(
        ReviewEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // 即使跨越该节点的恢复/崩溃重放，也最多运行一次。
        $sentiment = $this->memoize('sentiment', fn (): SentimentResult => MyAgent::make()
            ->structured(new UserMessage($event->review), SentimentResult::class));

        if ($sentiment->isNegative()) {
            $payload = $this->interrupt(
                new ApprovalRequest(
                    message: '检测到负面评价。要我回复它吗？',
                    actions: [new Action('review_1', '回答评价', $sentiment->content)],
                )
            );

            // 恢复时，上面 memoize 的 $sentiment 会立即被回忆，
            // 而 interrupt() 在这里返回了答案。
            if (($payload['review_1'] ?? null) === 'approve') {
                return new AnswerReviewEvent();
            }
        }

        return new SkipReviewEvent();
    }
}
```

`memoize()` 需要：

* 一个 **名称**，在节点内唯一（框架会自动将其限定到该次特定的节点执行）；
* 一个 **闭包** ，包装住其结果必须在重运行后仍然存在的工作。

> `checkpoint()` 来自上一个主要版本的接口已弃用，现在会委托给 `memoize()`。与旧的内存 checkpoint 不同， `memoize()` 都是 **是持久化的**：该值会被持久化，所以它也能防护崩溃——不只是中断。
