> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Steering 与 Queueing

> 说明 Laravel Copilot SDK 中 steering（immediate）与 queueing（enqueue）的区别，以及在 Laravel 中实用的选用方式。

## Steering 与 Queueing

<Info>
  在常规的 Laravel 应用流程中，几乎不会直接用到 steering。在 Laravel 的同步执行模式下很难获得收益，基本上默认的 queueing 运行方式即可。
</Info>

在代理处理过程中发送消息，有 **steering** 和 **queueing** 两种模式。

## 概览

`send()` / `sendAndWait()` / `sendAndStream()` / `Copilot::run()` 全部都有 `$mode` 参数。

| 模式                      | 行为                 |
| ----------------------- | ------------------ |
| `"enqueue"`（默认）         | 在当前 turn 完成后作为队列处理 |
| `"immediate"`（steering） | 立即插入当前正在处理的 turn   |

## Steering（`"immediate"`）

将消息直接注入到代理正在处理的 turn。代理会实时接收消息并调整响应。适用于希望在不中断正在进行的工作的情况下调整方向。

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;

Copilot::start(function (CopilotSession $session) {
    // 启动一个耗时较长的任务
    $messageId = $session->send(prompt: 'Refactor the authentication module to use sessions');

    // 代理处理过程中调整方向
    $session->send(
        prompt: 'Actually, use JWT tokens instead of sessions',
        mode: 'immediate',
    );

    // 等待直到进入 idle 状态
    $response = $session->sendAndWait(prompt: 'Summarize what you did');
});
```

<Warning>
  Steering 是尽力而为的。如果代理已经提交了工具调用，则会在该工具调用完成后再应用，但仍在同一 turn 内处理。若 steering 消息在 turn 结束后才到达，会自动移动到队列中。
</Warning>

## Queueing（`"enqueue"`）

将消息加入队列，当前 turn 完成后依次处理。每个入队的消息都作为独立的 turn 执行。省略 `$mode` 时的默认行为。

```php theme={null}
Copilot::start(function (CopilotSession $session) {
    // 启动第一个任务
    $session->send(prompt: 'Set up the project structure');

    // 在代理处理过程中把后续任务加入队列
    $session->send(prompt: 'Add unit tests for the auth module', mode: 'enqueue');
    $session->send(prompt: 'Update the README with setup instructions', mode: 'enqueue');

    // 等待直到队列为空
});
```

## 在 Laravel 中的实用思路

Laravel 主要采用使用 `Copilot::run()` 或 `sendAndWait()` 的同步模式。它们会发送消息并等待直到进入 idle 状态，因此 **代理在处理过程中并没有插入的机会，`$mode` 实际上没有意义**。

```php theme={null}
// 因为 Copilot::run() 内部会调用 sendAndWait()，
// 指定 mode 没有意义

$response = Copilot::run(prompt: 'Tell me something about Laravel.');

// 在会话中如果只是依次调用 sendAndWait() 也不需要
Copilot::start(function (CopilotSession $session) {
    $r1 = $session->sendAndWait(prompt: 'First task');
    $r2 = $session->sendAndWait(prompt: 'Second task');
});
```

Steering（`"immediate"`）真正能发挥作用的场景，是通过 `send()` 异步发送消息、同时用另一个消息介入进行中的 turn 时。在 Laravel 的同步处理流程中很难创造这种机会，所以 **基本上不指定 `$mode`、保持默认较为合适**。

## 该用哪一个

| 场景             | 模式                      |
| -------------- | ----------------------- |
| 代理正朝着错误方向前进    | Steering（`"immediate"`） |
| 想到了下一步要做的事     | Queueing（`"enqueue"`）   |
| 想依次执行多个任务      | Queueing（`"enqueue"`）   |
| 通常的 Laravel 应用 | 默认（无需 `$mode`）          |

## 最佳实践

* **默认使用 queueing** — 省略 `$mode`（或指定 `"enqueue"`）对多数情况都合适。行为可预测。
* **Steering 仅用于纠偏** — 只在代理明显做错时才使用 `"immediate"`。
* **Steering 消息要简洁** — 应是能在当前上下文中理解的简短消息。冗长复杂的 steering 消息反而会造成混乱。
* **避免连续 steering** — 短时间内多次 steering 可能降低 turn 的质量。如果需要大幅转向，中断当前 turn 从头开始有时更合适。

## 参考

* [基本用法](/zh/packages/laravel-copilot-sdk/bare-usage)
* [Streaming](/zh/packages/laravel-copilot-sdk/streaming)
* [send-on](/zh/packages/laravel-copilot-sdk/send-on)

<Info>
  最新信息请参考 [GitHub 仓库](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [send() 与 on()](/zh/packages/laravel-copilot-sdk/send-on.md)
- [授权（Gate 与 Policy）](/zh/authorization.md)
- [Laravel 与 AI 开发](/zh/ai.md)
- [Laravel Fortify 与 Starter Kit](/zh/advanced/fortify.md)
- [Score 与 Note 详解 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/song-score-note.md)