跳转到主要内容

异常与错误处理

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日