SessionEvent

来自 Copilot 的所有消息都是 Revolution\Copilot\Types\SessionEvent 类。由于该类使用频率最高，因此加入了 Laravel 风格的便利功能。

`content()`

获取来自 AI 的最重要的响应消息。

$response = Copilot::run('1 + 1');
echo $response->content(); // '2'
// content() 可能会是 null

通过 __toString() 的隐式类型转换也返回消息内容。

echo (string) $response; // '2'
// 这个不会是 null

Event type 的判定

可以使用 isAssistantMessage()、isUserMessage()、isIdle()、isAssistantMessageDelta()。如果有经常使用的 Event type，将来可能还会加入更多辅助函数。用 is() 可以判定任意 EventType。

use Revolution\Copilot\Enums\SessionEventType;

if ($response->is(SessionEventType::HOOK_START)) {
    // 钩子开始事件时的处理
}

type() 返回 SessionEventType enum 的字符串值。

echo $response->type(); // 'assistant.message'

`session.autopilot_stopped`

SessionEventType::SESSION_AUTOPILOT_STOPPED（session.autopilot_stopped）会在 Autopilot 停止继续处理某个特定请求时触发。可以通过 $event->data['requestId'] 获取目标消息 ID，通过 $event->data['reason'] 获取停止原因。此事件并不表示整个会话已进入空闲状态。

`failed()` / `successful()`

当事件类型为 SESSION_ERROR 时，failed() 为 true。 successful() 则相反。为了与 Laravel 的命名保持一致，已从 isError() 改名。

`throw()`

与 Laravel 的 HTTP API 和 Process API 一样，会保留错误，并可以通过 throw() 抛出异常。没有错误时不做任何事，因此可以这样写。

$content = $response->throw()->content();

事件类型为 SESSION_ERROR 时会抛出 Revolution\Copilot\Exceptions\SessionErrorException。超时时会抛出 Revolution\Copilot\Exceptions\SessionTimeoutException。 JSON-RPC 的错误会抛出 Revolution\Copilot\Exceptions\JsonRpcException。

Conditionable

可以使用 when() 与 unless()。

$response->when($response->isAssistantMessage(), function (SessionEvent $event) {
    // 助手消息时的处理
});

Dumpable

可以使用 dump() 与 dd()。

$response->dump();

Tappable

可以使用 tap()。

return $response->tap(function (SessionEvent $event) {
    // 做些处理
    info($event->content());
});

InteractsWithData

此功能仅应用于 SessionEvent 的 $data 属性。可以使用 all()、has()、only()、collect() 等常见辅助函数。详情请参考 InteractsWithData。由于 SessionEvent 的 $data 会因 EventType 而结构不同，因此便于按事件访问值。 content() 内部也使用 InteractsWithData。

return $this->data('content', $default);

// 指定 default 后 content() 就不会是 null
echo $response->content('');

`toArray()` / `toJson()`

可以将整个 SessionEvent 转换为数组或 JSON。

$array = $response->toArray();
$json = $response->toJson();

没有面向整个事件的 collect() 方法。因为 $data 已有 InteractsWithData 的 collect()。如果想对整个事件进行 collection 操作，请使用 Laravel 的 collect() 辅助函数。

$collect = collect($response->toArray());

`broadcast()` / `broadcastNow()`

可以以与 Laravel AI SDK 的 StreamEvent 相同的接口进行广播。 AI SDK 在流式输出时使用它，但在 SessionEvent 中可以用于任意 EventType。

use Illuminate\Broadcasting\Channel;

$event->broadcast(new Channel('channel-name'));

broadcastNow() 不经过队列，立即广播。

$event->broadcastNow(new Channel('channel-name'));

流式输出时的使用示例：

use Illuminate\Broadcasting\Channel;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session) {
    $session->on(function (SessionEvent $event): void {
        if ($event->isAssistantMessageDelta()) {
            $event->broadcastNow(new Channel('copilot'));
        }
    });

    $session->sendAndWait(prompt: 'Tell me something about Laravel.');
}, config: new SessionConfig(streaming: true));

事件元数据

从 Copilot CLI 1.0.99 开始，部分事件包含额外的元数据。 SDK 会将这些值原样保存在 $data 中，因此你可以通过 $event->data 或 InteractsWithData 的辅助方法访问它们。

Compaction 事件

session.compaction_start 和 session.compaction_complete 中的 data.compactionAttemptId 是用于关联开始事件与完成事件的 ID。如果涉及模型切换，还会包含 switchTargetModel。如果切换目标的提示词令牌预算不同，还会包含 targetPromptTokenLimit。完成事件可能包含 initialModel、model、outcome、outcomeReason、failureReason、tokenAccountingBasis 等字段。 outcome 及各原因字段是将来可能新增取值的字符串。不要将它们当作固定的 Enum 处理，未知的值也请原样保留。字段缺失表示未提供该值。请勿推测默认值。

if ($event->is(SessionEventType::SESSION_COMPACTION_COMPLETE)) {
    $attemptId = $event->data('compactionAttemptId');
    $outcome = $event->data('outcome');
}

工具执行用量

tool.execution_complete 中的 data.toolUsage 是提供商针对运行时所拥有的工具操作报告的用量。它与对话模型的 assistant.usage 是分开的用量。即使工具执行失败，也可能包含已报告的用量。 toolUsage.model 是工具操作所请求的模型，而不是对话模型。令牌数和计费信息可能只提供一部分。字段缺失表示不可用，并不表示 0 个令牌。

$usage = $event->data['toolUsage'] ?? null;
$inputTokens = $usage['inputTokens'] ?? null;
$imageTokens = $usage['inputTokensDetails']['imageTokens'] ?? null;

inputTokensDetails 和 outputTokensDetails 中按模态划分的令牌数是各自合计值中包含的明细。请勿将它们加到合计值上。 toolUsage.requestId 是运行时用于排除重复投递和重放的 ID，并不是上游的计费标识符。 session.usage_checkpoint 和 session.shutdown 中的 data.toolUsageRequestIds 同样是运行时内部的去重元数据，用于标识会计快照中包含的工具操作。请勿将其当作上游计费 ID。

Fusion 解析事件

当服务器端路由选择了与本地规则不同的工作流时，session.fusion_resolved 中的 data.selectedRuleId 用于标识该服务器规则。没有替换时会被省略。

MCP 服务器工具加载事件

SessionEventType::SESSION_MCP_SERVER_TOOLS_LOADED（session.mcp_server_tools_loaded）会在 MCP 服务器的工具列表可用时触发。这是每个连接只触发一次的 ephemeral 事件，不会被持久化。它包含 data.serverName 和 data.toolCount。 MCP 服务器变为 connected 并不代表工具已加载完成。离开连接状态后，在下次收到此事件之前，请将其视为加载中。使用缓存工具时，此事件可能会先于 connected 到达。

if ($event->is(SessionEventType::SESSION_MCP_SERVER_TOOLS_LOADED)) {
    info("{$event->data('serverName')}: {$event->data('toolCount')} tools loaded");
}

指令更新事件

SessionEventType::INSTRUCTION_UPDATE（instruction.update）会在运行时更新权威的开发者指令时触发。该事件从 Copilot CLI 1.0.103 开始新增。

字段	说明
`data.content`	指令文本
`data.authority`	更新来源：`runtime`、`host` 或 `managedPolicy`
`data.boundary`	指令适用的边界
`data.fallback`	提供商不支持该指令时的行为
`data.lifetime`	指令的有效期
`data.name`	用于诊断的可选名称

if ($event->is(SessionEventType::INSTRUCTION_UPDATE)) {
    $instruction = $event->data['content'];
}

persistent 更新会按事件顺序保留，并在 replay、resume、rewind、fork 和 compaction 之后恢复。 turn 更新是临时的，其 ephemeral 为 true。这些值以通用数组形式保存，因此未知的 Enum 值会原样传递。

最新信息请参考 GitHub 仓库。

GitHub Copilot

SDK

AI SDK

VOICEVOX

启动套件

Feed 与 RSS

中间件

SessionEvent

SessionEvent

`content()`

Event type 的判定

`session.autopilot_stopped`

`failed()` / `successful()`

`throw()`

Conditionable

Dumpable

Tappable

InteractsWithData

`toArray()` / `toJson()`

`broadcast()` / `broadcastNow()`

事件元数据

Compaction 事件

工具执行用量

Fusion 解析事件

MCP 服务器工具加载事件

指令更新事件

​SessionEvent

​content()

​Event type 的判定

​session.autopilot_stopped

​failed() / successful()

​throw()

​Conditionable

​Dumpable

​Tappable

​InteractsWithData

​toArray() / toJson()

​broadcast() / broadcastNow()

​事件元数据

​Compaction 事件

​工具执行用量

​Fusion 解析事件

​MCP 服务器工具加载事件

​指令更新事件

SessionEvent

`content()`

Event type 的判定

`session.autopilot_stopped`

`failed()` / `successful()`

`throw()`

Conditionable

Dumpable

Tappable

InteractsWithData

`toArray()` / `toJson()`

`broadcast()` / `broadcastNow()`

事件元数据

Compaction 事件

工具执行用量

Fusion 解析事件

MCP 服务器工具加载事件

指令更新事件