> 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/gai-lan/upgrade.md).

# 升级

{% hint style="warning" %}

### 代理式升级（推荐）

我们已将整个升级过程记录在一个专门的目录中 **`vendor/neuron-core/neuron-ai/upgrade`**。你可以将你的编码代理指向这个目录，它会自动接收准确的升级指令来升级你的代码。你可以使用以下提示词：

```
我已将 `neuron-core/neuron-ai` 依赖从 3.x 版本更新到 4.x。 
请查看 `vendor/neuron-core/neuron-ai/upgrade` 中的升级指南 
并在必要时更新我的应用代码。
```

{% endhint %}

## 从 v3 升级到 v4

在这个新的主版本中，Neuron 组件的公共 API 并没有发生大幅变化（我们尽可能将影响降到最低）。我们主要聚焦于改进整个框架所依赖的最重要组件。Workflow 是整个架构的基础，此新版本中实现的变更可能会影响你的代码，尤其是当你使用工具审批、中断和流式适配器等模式时。我们建议为编码代理使用升级指南。

我们也借此版本修复了 v3 中出现的其他关键问题，例如 Agent 中的工具审批流程，以及其他设计改进，以便未来以更少的破坏性变更拥有更大的演进空间。

我们将继续努力提供最佳的开发者体验，帮助你在 PHP 中创建成功的 AI 产品。

## 更新依赖

你应该更新 `composer.json` 文件：

```json
{
    "require": {
        ...,
        "neuron-core/neuron-ai": "^4.0",
    },
}
```

该 `inspector-php` 包已从默认依赖中移除。因此，如果你想将你的代理连接到 [Inspector](https://inspector.dev/) 监控仪表盘：

```shellscript
composer require inspector-apm/inspector-php
```

## 高影响变更

### 新的 Agentic 技能

面向编码代理的技能已被彻底重写并重新组织，以反映此新主版本的改进和新特性。我们建议删除你的编码代理文件夹中的 skills 目录（例如 `.claude`, `.agent`）并再次遵循安装指南。

<a class="button primary" data-icon="arrow-right-long">Agentic 技能</a>

### Agent 返回类型

在这个新的主版本中，Agent 实体经历了大量重构，以消除高级用例中的许多摩擦，并使 agent 类更像一个普通的 Workflow，从中继承而来。

最重要的影响在于返回类型。Agent 返回一个 `AgentState` 的实例，它是底层 `WorkflowState` ，并带有一些辅助方法，尽可能保持你的应用所见到的外部 API 不变。

最具影响的变更在于 `stream()` 方法。若没有 `AgentHandler` ，该方法会直接返回生成器。

```php
foreach ($agent->stream(new UserMessage("你好")) as $event) {
    if ($event instanceof TextChunk) {
        echo $event->content;
    }
}
```

如果你与前端协议交互，必须在 agent 实例上注册 stream 适配器。

```php
$generator = MyAgent::make()
    ->setStreamAdapter(new AGUIAdapter('thread_id'))
    ->stream(
        new UserMessage("你好")
    );

foreach ($generator as $event) {
    echo $event;
    ob_flush();
    flush();
}
```

对此没有变化 `structured()` 和 `chat()`.

### 工具变为完全抽象

该 `Tool` 该类现在是抽象类，不能再直接使用。其设计现在旨在可扩展，让你能够用更少的代码和更大的灵活性实现自己的工具。

我们还从抽象类中移除了构造函数，因此你可以将工具名称和描述指定为普通类属性，而不必调用父构造函数。如果你只想向工具传递外部依赖，仍然可以使用类构造函数：

```php
class MyTool extends Tool
{
    protected string $name = 'my_tool';
    
    protected ?string $description = '这个工具的作用。';
    
    public function __construct(protected string $apiKey){}
    
    public function __invoke()
    {
        ...
    }
}
```

### 移除 WorkflowHandler

Workflow 组件经过了一次重要重构，以简化其使用和公共 API。在上一版本中使用 Workflow 时，你需要调用 `init()` 方法来获取 `WorkflowHandler` 实例，然后调用 `run()` 或 `events()` 在 handler 上，最终执行工作流：

```php
$handler = MyWorkflow::make()->init();

// 单次运行
$finalState = $handler->run();

// 流式事件
foreach($handler->events() as $chunk) {
    // ...
}
$finalState = $handler->getResult();
```

经过对工作流执行逻辑的大幅简化，不再需要 handler，现在可以直接在 workflow 上调用这两个方法。 `run()` 和 `events()` 直接地

```php
// 单次运行
$finalState = MyWorkflow::make()->run();

// 流式事件
$generator = MyWorkflow::make()->events();
foreach($generator as $chunk) {
    // ...
}
$finalState = $generator->getResult();
```

### Workflow 中断/恢复

工作流执行及其中断能力的架构已重新设计，以更易于管理中断和工具审批，同时也为实现持久化、抗崩溃的 Agentic 工作流打开大门。

#### 移除 WorkflowInterrupt 异常

在发生中断时，Workflow 不会抛出特殊的 `WorkflowException` 来通知调用方脚本中断情况。它只会返回一个“已中断”状态：

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

if ($state->isInterrupted()) {
    // 使用请求中的信息
    $request = $state->getInterruptRequest();
    // 恢复令牌会自动生成，并可从 workflow 实例中获取
    $workflowId = $workflow->getWorkflowId();
}
```

不再需要 try/catch 块。

此更改了 [工具审批](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/tool-approval.md) 流程。请查看文档，如果你在你的代理中使用了此 middleware。

#### 恢复负载为普通数组

你从节点中传播的中断请求现在只是一条信号，用于将信息从节点传递给外部调用脚本。要恢复工作流，你不再需要将该请求传回工作流。恢复负载现在只是一个简单数组：

```php
// 调用 interrupt() 的节点示例
class InterruptableNode extends Node
{
    public function __invoke(FirstEvent $event, WorkflowState $state): NextEvent
    {
        $payload = $this->interrupt(new ApprovalRequest('需要人工输入'));
        $state->set('received_feedback', $payload);
        return new NextEvent();
    }
}

// 定义传入负载 —— 它将由 interrupt() 方法返回
$payload = ['action_id' => 'approve'];

$finalState = $workflow->resume($payload);
```

### Agent 指令

Agent 指令必须是新的消息类型的实例 `SystemMessage`。你只需将字符串传递给构造函数，使其与此新版本兼容：

```php
use NeuronAI\\Chat\\Messages\\SystemMessage;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        ...
    }
    
    protected function instructions(): SystemMessage
    {
        return new SystemMessage(
            "你是一个专门撰写 YouTube 视频摘要的 AI Agent"
        );
    }
}
```

### 工具审批

工具审批流程已被完全重写。Agent 类现在管理整个流程。你只需要负责渲染 UI，以便用户可以决定批准还是拒绝一次工具调用。

需要审批的工具状态存储在聊天历史中的最后 `ToolCallMessage`。这使你能够设计 UI，只需渲染聊天历史中的消息，当它遇到一个 `ToolCallMessage` 时，你可以检查工具的审批状态以显示批准/拒绝操作，或者正常的工具调用已经发生。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/tool-approval.md" class="button primary" data-icon="arrow-right-long">工具审批</a>

#### 新工具 `requiresApproval()` 方法

我们引入了 `requiresApproval()` 方法到 Tool 类中，以根据工具调用的参数判断是否需要审批：

```php
class MyTool extends Tool
{
    ...,
    
    public function requiresApproval(array $inputs): bool
    {
        return $inputs['amount'] > 100;
    }
}
```

要启用工具审批流程，你始终需要将 [ToolApproval](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/tools.md#tool-approval) 中间件附加到 Agent 上。中间件上的自定义审批策略优先于工具中定义的 `requiresApproval()` 方法中列出的相同顺序运行这些后处理器。

### 工作流持久化数据库模式

由于工作流执行模型的变化，跨中断持久化的数据库模式已更改，以支持新特性。查看专门章节，准备执行 SQL 查询，以便使用新的数据库格式开始。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/gong-zuo-liu/persistence.md" class="button primary" data-icon="arrow-right-long">持久化</a>

### 移除了 Guzzle 依赖

在上一版本中，guzzle 是一个必需的 composer 依赖，用于驱动框架默认的 `GuzzleHttpClient`。这个新主版本随附默认的 `CurlHttpClient` ，它不需要任何包依赖，只需要 `ext-curl` ，该扩展在任何 PHP 安装中通常都已可用。

如果你向框架组件传递的是自定义的 GuzzleHttpClient 实例，则必须在你的应用中显式要求安装 guzzle。

```shellscript
composer require guzzlehttp/guzzle
```

### 内置向量存储过滤

`VectorStoreInterface` 已更改以支持内置过滤功能。方法的名称和签名都已更改。如果你正在自己实现 `VectorStoreInterface` ，你应该将你的实现迁移到新的契约。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/rag/vector-store.md" class="button primary" data-icon="arrow-right-long">向量存储</a>

### 计算器工具包

事实证明，模型在组合多个工具调用来解析数学表达式时非常吃力，而在表达式表示方面却表现很好。CalculatorToolkit 已被重构，采用一个主要的 `Evaluate` 工具，移除了代表单个数学运算的工具： `add`, `subtract`, `multiply`，等等。模型现在可以描述它想要求解的公式，evaluate 工具会解释该表达式并返回结果，一次完成，无论表达式多么复杂。由于发送给提供方 API 的工具更少，这一策略还能节省大量 token。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/tools.md#toolkits" class="button primary" data-icon="arrow-right-long">计算器工具包</a>

### 聊天历史

聊天历史经过了重大重构，以实现两个目标：

* 将消息存储与历史和上下文窗口管理分离
* 使 Neuron 更容易集成到你的应用中

`ChatHistoryInterface` 已被移除。新的公共 API 由新的 `MessageStoreInterface`支持。顾名思义，消息存储只负责将你的消息存储到持久层中。它会将超出上下文窗口的消息标记为 `已归档` ，而不是删除它们，因此模型看到的是被裁剪后的线程，而你的存储则保留完整历史。

{% hint style="warning" %}
我们建议依赖 agentic 升级流程，将你的 Agent 和历史实现迁移到新的 API。
{% endhint %}

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/chat-history-and-memory.md" class="button primary" data-icon="arrow-right-long">聊天历史</a>

### 中间件签名

Workflow 引擎允许你声明 `资源` 你希望在执行期间携带、且不需要在中断时保存的内容。中间件也会接收资源，因此你可以在工作流执行期间与这些项交互。例如在 Agent 中，资源包含工具、Agent 指令和聊天历史。中间件方法现在多了一个额外参数 `$resources`.

```php
interface WorkflowMiddleware
{
    public function before(
        NodeInterface $node, 
        Event $event, 
        WorkflowState $state, 
        WorkflowResources $resources, // 中间件在状态之外还会接收资源。
    ): void;

    public function after(
        NodeInterface $node, 
        Event $result, 
        WorkflowState $state, 
        WorkflowResources $resources, // 中间件在状态之外还会接收资源。
    ): void;
}
```

### 更改 ReaderInterface 契约

该契约只有一个静态方法 `getText()`。静态方法使得带有自定义构造的真实 reader 实例变得毫无意义。该接口现在强制实现具体实例，而不是静态实例：

{% hint style="warning" %}
**自定义 reader 必须相应调整**。agentic 升级将涵盖此重构。
{% endhint %}

```php
interface ReaderInterface
{
    public function read(string $filePath): string;
}
```

## 中等影响

### 监控

框架正在迁移到 [PSR-14 Event Dispatcher](https://www.php-fig.org/psr/psr-14/) 接口，而不是 PHP 原生的 \SplObserver。我们保留了现有接口，也保留了 `LogObserver` ，通过适配器实现，但它们被标记为 `@deprecated`.

这将使得将 Neuron agents 和更广泛的 agentic 工作流与其他现有框架和应用集成更容易。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/observability.md" class="button primary" data-icon="arrow-right-long">监控</a>

### 提供方返回 ProviderResponse

AI 提供方方法 `chat()` 和 `stream()` 现在返回 `ProviderResponse` 而不是 `消息`。该 `ProviderResponse` 包装了助手消息，并提供对原始 HTTP 响应体和响应头的访问。

**这只会影响独立使用提供方的情况。** 当提供方在 Agent 内部使用时（通过 `chat()`, `stream()`，或 `structured()` 在 Agent 本身上），无需更改——Agent 会在内部处理 `ProviderResponse` 。

你只需要重构那些直接调用提供方方法的代码，例如脚本、控制器、命令或自定义工作流中的代码。

```php
$response = $provider->chat(new UserMessage(...));

// 获取助手消息
$response->message();

// 获取提供方原始 body
$response->body();

// 获取响应头
$response->headers();
```

### AIProviderInterface 的变更

我们移除了 `messageMapper()` 和 `toolPayloadMapper()` 从 `AIProviderInterface`，并引入了新的 `getModel()` 方法。如果你有任何直接使用此接口的自定义提供方实现，需要相应地调整。

```php
interface AIProviderInterface
{
    public function getModel(): string;

    public function systemPrompt(string|array|null $prompt): AIProviderInterface;

    public function setTools(array $tools): AIProviderInterface;

    public function chat(Message ...$messages): ProviderResponse;

    public function stream(Message ...$messages): Generator;

    public function structured(array|Message $messages, string $class, array $response_schema): ProviderResponse;

    public function setHttpClient(HttpClientInterface $client): AIProviderInterface;
}
```

## 新特性

### AG-UI 自定义事件

AG-UI 使用其原生的 `STEP_STARTED`, `STEP_FINISHED`, `ACTIVITY_SNAPSHOT`、以及 `CUSTOM` 事件。Vercel 会发出临时的 `data-*` 片段，因此中间的领域信息无需添加到助手消息历史中，就可以供 UI 使用。

当领域代码应保持与 Neuron 的可移植事件对象独立时，你可以按其精确类名映射应用事件。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/streaming.md#custom-events" class="button primary" data-icon="arrow-right-long">UI 协议自定义事件</a>

### 流式通道

随着 agent 变得越来越交互式和更有能力，由于超时限制，应用开发者越来越被迫在 HTTP 请求生命周期之外运行它们，这使得流式输出无法到达 UI。通道通过外部流式系统将 Agents 和 Workflows 的流式输出传送到用户界面，例如 [Pusher](https://pusher.com/)，websockets、Redis 队列，或你的应用已经在使用的任何其他方案。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/streaming.md#delivery-channels" class="button primary" data-icon="arrow-right-long">流式通道</a>

### 部分事件流式

像 Pusher、Socketi 或任何兼容 Pusher 的实时服务器，通常都会对负载大小设置限制。Pusher 将事件限制在 10 KB；Reverb 默认同样如此，Soketi 则为 100 KB。

为了在你的实时服务器有此类限制时仍支持流式传输，超出最大大小的事件——通常是工具结果或消息快照——会被拆分为连续片段。此外，服务器不保证片段按顺序到达，也不保证不会交错。因此，浏览器必须能够协调这种分片与顺序，才能向你的 UI 组件提供一致的流式体验。

Neuron 4 随附一个第一方 TypeScript 模块，将此能力带入你的前端。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/streaming.md#event-fragmentation" class="button primary" data-icon="npm">@neuron-core/streaming</a>

### 语义记忆

你的代理现在可以记住对某个人来说在多次对话中重要的内容。拥有多个活跃线程的用户可以看到代理记住他们过去的对话和偏好。

V4 引入了 `SemanticMemoryRetrieval` 组件，它会自动在用户会话之间存储和回忆记忆。它属于 RAG agent，可根据你的应用逻辑进行定制或替换。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/rag/retrieval.md#semantic-memory" class="button primary" data-icon="arrow-right-long">语义记忆</a>

### 可停止的 HttpClient

在流式输出进行到一半时停止答案，用于“停止生成”按钮。提供方会将截至目前流式传输的文本作为部分内容保留，并将其存储在聊天历史中。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/async.md#stoppablehttpclient" class="button primary" data-icon="arrow-right-long">HTTP 客户端</a>

### 分类器

在 Neuron AI 中，你已经可以用它们来回答 [结构化输出](https://docs.neuron-ai.dev/agent/structured-output)：描述允许的答案，将响应强制转换为 PHP 类，读取属性。它与 [AI 作为裁判](https://docs.neuron-ai.dev/agent/evaluation#ai-as-a-judge) 模式在智能体评估中的机制相同。当决策只是偶尔做一次时，它运行良好。麻烦在于，当你希望它在每一次对话的每一轮都运行时，因为生成式模型会一个 token 接一个 token 地生成文本，而你却在花钱雇一个通用写作者，用它的延迟和价格，去换来一个词。如果一个护栏让智能体的响应时间翻倍，那么第一次有人抱怨时它就会被关闭。如果一个裁判的成本和它评估的智能体一样高，那它只会在部分流量上运行，甚至根本不会运行。

分类器没有对话，也没有可供流式传输的文本。Neuron AI Classifier 有其自己的契约， `ClassifierInterface`，用于针对某些输入提出封闭式问题并返回概率。你可以用它在你的 Agents 或 Workflows 中做决策，例如护栏、提示注入、对响应质量打分等。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/ti-gong-shang/classifier.md" class="button primary" data-icon="arrow-right-long">分类器</a>
