错误处理与运维 · iOS

自动重连机制

SDK 内置自动重连，无需开发者处理：

特性	行为
连接断开	自动重连，延迟 3 秒
重连次数	无限重试（直到 `release()` 被调用）
心跳	PingBurst 控制器发送协议级 Ping
鉴权重签	每次重连自动重新生成 HMAC 签名头
连接恢复后	机器人会重新发送 online 事件

认证回调

swift

final class AuthCallback: AgentAuthCallback {
    func onAuthState(appId: String, code: Int, msg: String) {
        switch code {
        case 0:    print("认证成功")
        case 1004: print("签名验证失败，检查 appKey/appSecret 是否正确")
        case 1005: print("WebSocket 握手失败")
        default:   print("认证错误: code=\(code), msg=\(msg)")
        }
    }
}
agentSdk.registerAuth(AuthCallback())

通过 Response 返回业务错误

当 SDK 端处理失败时，通过 response.onError(...) 通知机器人：

swift

override func onRequest(agentId: String, eventId: String,
                        flag: Int, audio: Data?, param: AgentParam,
                        response: Audio2LlmResponse) {
    do {
        // 业务处理...
    } catch {
        response.onError(eventId: eventId, errorCode: 5001, errorMsg: "ASR服务超时")
    }
}

错误码约定

范围	含义	示例
0	成功	认证成功、请求确认成功
1000-1999	认证/连接错误	1000=连接已关闭, 1004=签名错误, 1005=握手失败
2000-2999	协议错误	消息格式错误
3000-3999	网关错误	路由失败
4000-4999	机器人端错误	机器人不在线
5000-5999	SDK 端业务错误	开发者自定义错误

资源释放

swift

agentSdk.release()   // 断开连接、清理所有注册的回调和缓存

release() 会执行：

设置 released 标志，停止自动重连
关闭 WebSocket 连接
清理 callbackType 注册
清理所有内部状态映射，并从单例注册表移除

注意：release() 后同一 appId 可以重新 create() 获取新实例。

日志配置

SDK 使用 AgentSdkLogger 前门，默认输出到 stderr。业务方可调整级别或替换 handler：

swift

AgentSdkLogger.minLevel = .debug   // .debug / .info / .warn / .error

AgentSdkLogger.handler = { level, text in
    // 自定义日志输出
    print("[AgentSdk] \(text)")
}

常见问题排查

现象	可能原因	排查方式
认证失败 code=1004	appKey / appSecret 错误，或签名串构造不一致	检查凭证值；签名串 `"GET\n{path}\n{timestamp}\n{nonce}"`
连接成功但收不到消息	回调注册在 initialize() 之后	确保先注册回调再初始化
onRequest 不被调用	机器人未上线或 callbackType 不匹配	检查 onRobotOnline 是否触发
Response 方法调用无效	Response 已超时清理	确保处理时间不要过长，及时调用 response 方法
内存持续增长	未调用 release()	检查机器人生命周期管理
命令行示例跑不起来	executableTarget 未声明 platforms	Package.swift 加 `platforms: [.iOS(.v13), .macOS(.v10_15)]`，示例用 `RunLoop.main.run()` 保活