跳轉到主要內容

例外與錯誤處理

SDK 拋出的所有例外都位於 Revolution\Copilot\Exceptions 命名空間中。例外的出現方式有兩種:一種保存在工作階段的執行結果中,呼叫 throw() 時才拋出;另一種在 RPC 呼叫等場合當場拋出。

工作階段錯誤與逾時

在 sendAndWait() 與 Copilot::run() 中,工作階段錯誤或逾時不會當場拋出,而是將例外保存在回傳的 SessionEvent 中。與 Laravel 的 Http 和 Process 一樣,呼叫 throw() 會拋出保存的例外。沒有錯誤時 throw() 不做任何事,因此可以繼續鏈式呼叫方法。
若要在不拋出例外的情況下檢查是否成功,請使用 failed() 與 successful()。詳情請參閱 SessionEvent。

SessionTimeoutException

等待 session.idle(回應完成)逾時時保存。逾時時間透過 sendAndWait() 的 timeout 參數指定。省略時使用設定值 copilot.timeout(預設 60 秒)。

SessionErrorException

工作階段透過 SESSION_ERROR 事件回傳錯誤時保存。訊息中包含執行階段回傳的錯誤內容。

JsonRpcException

當 CLI 針對 RPC 呼叫回傳 JSON-RPC 錯誤時立即拋出。從 code 屬性讀取 JSON-RPC 錯誤碼,從 data 屬性讀取附加於錯誤的資料。

SessionFsSqliteTransactionFailure

這是實作 SessionFs 的 SQLite 提供者時使用的例外。它不是用來捕捉的,而是從提供者的 transaction() 中拋出,以告知執行階段應如何分類失敗。分類透過 errorClass 指定:
  • Fatal(預設):無法復原的失敗
  • BusyOrLocked:僅在 SQLite 於提交前回傳 BUSY/LOCKED 且交易已回滾時使用
  • PostCommitAmbiguous:無法判定提交後的結果
從 transaction() 拋出的其他任何例外都會以 fatal 回報。

StrayRequestException

測試用 fake 在你送出沒有註冊對應 fake 的請求時拋出。若意外出現,表示你忘了為該請求註冊 fake。fake 的用法請參閱測試。
最後修改於 2026年11月15日