Steering 与 Queueing

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

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

概览

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

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

Steering（`"immediate"`）

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

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');
});

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

Queueing（`"enqueue"`）

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

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 实际上没有意义。

// 因为 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 从头开始有时更合适。

参考

最新信息请参考 GitHub 仓库。