错误处理与运维

自动重连机制

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

特性	行为
连接断开	自动重连，延迟 3 秒
重连次数	无限重试（直到 `release()` 被调用）
心跳	每 10 秒发送 Ping
Token刷新	每次重连自动生成新 JWT（1小时有效期）
连接恢复后	机器人会重新发送 online 事件

认证回调

java

agentSdk.registerAuth((appId, code, msg) -> {
    switch (code) {
        case 0    -> log.info("认证成功");
        case 1001 -> log.error("Token过期（不应出现，SDK自动刷新）");
        case 1004 -> log.error("签名验证失败，检查appKey/appSecret是否正确");
        case 1005 -> log.error("WebSocket握手失败");
        case 1006 -> log.error("未知异常: " + msg);
        default   -> log.error("认证错误: code={}, msg={}", code, msg);
    }
});

通过 Response 返回业务错误

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

java

@Override
public void onRequest(String agentId, String eventId, int flag,
                      byte[] buf, AgentParam param, Audio2LlmResponse response) {
    try {
        // 业务处理...
    } catch (Exception e) {
        response.onError(eventId, 5001, "ASR服务超时");
    }
}

错误码约定

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

资源释放

java

// 释放SDK实例（断开连接、清理所有注册的回调和缓存）
agentSdk.release();

release() 会执行：

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

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

日志配置

SDK 使用 SLF4J + Logback，建议配置：

xml

<!-- 正常运行 -->
<logger name="com.agibot.aiem.sdk" level="INFO"/>

<!-- 调试消息收发 -->
<logger name="com.agibot.aiem.sdk.client" level="DEBUG"/>

<!-- 调试线程池 -->
<logger name="com.agibot.aiem.sdk.mgr" level="DEBUG"/>

常见问题排查

现象	可能原因	排查方式
认证失败 code=1004	appKey / appSecret 错误，或签名串构造不一致	检查 appKey / appSecret 值；服务端期望签名串 `"GET\n{path}\n{timestamp}\n{nonce}"`
连接成功但收不到消息	回调注册在 initialize() 之后	确保先注册回调再初始化
onRequest 不被调用	机器人未上线或 callbackType 不匹配	检查 onRobotOnline 是否触发
Response 方法调用无效	Response 已超时清理（120秒）	确保处理时间不超过120秒
内存持续增长	未调用 release() 或大量 agentId 未 offline	检查机器人生命周期管理