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,而是立即廣播。
事件中繼資料
從 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 儲存庫。