Skip to main content

SessionEvent

來自 Copilot 的訊息全部都是 Revolution\Copilot\Types\SessionEvent 類別。 由於這個類別最常被使用,因此加入了 Laravel 風格的便利功能。

content()

取得 AI 最重要的回應訊息。
透過 __toString() 的隱式型別轉換也會回傳訊息內容。

Event type 判斷

可使用 isAssistantMessage()、isUserMessage()、isIdle()、isAssistantMessageDelta()。 若有常用的 Event type,可能會再新增輔助方法。 可用 is() 判斷任意 EventType。
type() 會回傳 SessionEventType enum 的字串值。

failed() / successful()

當事件類型為 SESSION_ERROR 時,failed() 為 true。 successful() 則相反。 為配合 Laravel 的命名慣例,由 isError() 改名而來。

throw()

與 Laravel 的 HTTP API 或 Process API 一樣,錯誤會被保留,可透過 throw() 拋出例外。 沒有錯誤時不會做任何事,因此可以這樣寫。
事件類型為 SESSION_ERROR 時會拋出 Revolution\Copilot\Exceptions\SessionErrorException。 逾時會拋出 Revolution\Copilot\Exceptions\SessionTimeoutException。 JSON-RPC 錯誤會拋出 Revolution\Copilot\Exceptions\JsonRpcException。

Conditionable

可使用 when() 與 unless()。

Dumpable

可使用 dump() 與 dd()。

Tappable

可使用 tap()。

InteractsWithData

此功能僅適用於 SessionEvent 的 $data 屬性。 可使用熟悉的輔助方法,例如 all()、has()、only()、collect()。 詳細請參閱 InteractsWithData。 SessionEvent 的 $data 會依 EventType 有不同結構,方便針對各事件存取其值。 content() 內部也是使用 InteractsWithData。

toArray() / toJson()

可將整個 SessionEvent 轉為陣列或 JSON。
沒有針對整個事件的 collect() 方法。 因為 $data 已經有 InteractsWithData 的 collect()。 若要對整個事件進行 collection 操作,請使用 Laravel 的 collect() 輔助函式。

broadcast() / broadcastNow()

可以與 Laravel AI SDK 的 StreamEvent 相同介面進行廣播。 AI SDK 中用於 streaming,但在 SessionEvent 中可用於任意 EventType。
broadcastNow() 不經由 queue,而是立即廣播。
Streaming 時的使用範例:

事件中繼資料

從 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,未知的值也請原樣保留。 欄位缺少表示未提供該值。請勿推測預設值。

工具執行用量

tool.execution_complete 中的 data.toolUsage 是供應商針對執行環境所擁有的工具操作回報的用量。 它與對話模型的 assistant.usage 是分開的用量。 即使工具執行失敗,也可能包含已回報的用量。 toolUsage.model 是工具操作所要求的模型,而不是對話模型。 權杖數與計費資訊可能只提供一部分。 欄位缺少表示無法取得,並不代表 0 個權杖。
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 抵達。
最新資訊請參閱 GitHub 儲存庫。
最後修改於 2026年10月19日