错误处理与运维
错误处理与运维
自动重连机制
SDK 内置自动重连，无需开发者处理：
| 特性 | 行为 |
|---|---|
| 连接断开 | 自动重连，延迟 3 秒（threading.Timer） |
| 重连次数 | 无限重试（直到 release() 被调用） |
| 心跳 | 由 websocket-client 内置，每 10 秒发送 Ping（ping_interval=10s, ping_timeout=5s） |
| 签名刷新 | 每次鉴权调用时用 app_key / app_secret 即时计算 HMAC-SHA256 签名，无 token 过期问题 |
| 连接恢复后 | 机器人会重新发送 online 事件 |
认证回调
python
from linksoul_agentsdk import AgentAuthCallback
class MyAuth(AgentAuthCallback):
def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
if code == 0:
print("认证成功")
elif code == 1001:
print("Token 过期（不应出现）")
elif code == 1004:
print("签名验证失败，检查 app_key / app_secret 是否正确")
elif code == 1005:
print("WebSocket 握手失败")
else:
print(f"认证错误: code={code}, msg={msg}")
agent_sdk.register_auth(MyAuth())
通过 Response 返回业务错误
当 SDK 端处理失败时，通过 response.on_error() 通知机器人：
python
def on_request(self, agent_id, event_id, flag, buf, param, response):
try:
# 业务处理...
pass
except Exception as e:
response.on_error(event_id, 5001, f"ASR 服务超时: {e}")
错误码约定
| 范围 | 含义 | 示例 |
|---|---|---|
| 0 | 成功 | 认证成功、请求确认成功 |
| 1000-1999 | 认证/连接错误 | 1001=Token过期, 1004=签名错误 |
| 2000-2999 | 协议错误 | 消息格式错误 |
| 3000-3999 | 网关错误 | 路由失败 |
| 4000-4999 | 机器人端错误 | 机器人不在线 |
| 5000-5999 | SDK端业务错误 | 开发者自定义错误 |
资源释放
python
# 释放 SDK 实例（断开连接、清理所有注册的回调和缓存）
agent_sdk.release()
release() 会执行：
- 设置 released 标志，停止自动重连
- 关闭 WebSocket 连接（
linksky_client.stop()） - 清理 callbackType / agentId / agentMeta 注册表
- 按 client 引用清理 TaskFlow / Teleop / ExtSkill / Response 缓存
- 关闭本实例的 worker 线程池
注意：
release()后同一 appId 可以重新AgentSdk.create()获取新实例。
日志配置
SDK 使用标准库 logging，logger 名以 linksoul_agentsdk 为根：
python
import logging
# 正常运行
logging.getLogger("linksoul_agentsdk").setLevel(logging.INFO)
# 调试消息收发 / 线程池
logging.getLogger("linksoul_agentsdk.client").setLevel(logging.DEBUG)
logging.getLogger("linksoul_agentsdk.mgr").setLevel(logging.DEBUG)
常见问题排查
| 现象 | 可能原因 | 排查方式 |
|---|---|---|
| 认证失败 code=1004 | app_key / app_secret 错误，或签名串构造不一致 | 检查 app_key / app_secret 值；服务端期望签名串 "GET\n{path}\n{timestamp}\n{nonce}" |
| 连接成功但收不到消息 | 回调注册在 initialize() 之后 | 确保先注册回调再初始化 |
on_request 不被调用 | 机器人未上线或 callbackType 不匹配 | 检查 on_robot_online 是否触发 |
| Response 方法调用无效 | Response 已超时清理（120 秒） | 确保处理时间不超过 120 秒 |
| 内存持续增长 | 未调用 release() 或大量 agentId 未 offline | 检查机器人生命周期管理 |