错误处理与运维 · JS / 浏览器

自动重连

特性	行为
连接断开	自动重连，默认延迟 3s（`reconnect.delayMs` 可调）
重连开关	`reconnect`: `true`（默认）/ `false` / `{ delayMs?: number }`
保活超时	空闲 ≥ `readIdleMs` 进入探测，连续 `maxProbes` 次无响应 → `close(4000)` 触发重连
鉴权刷新	每次重连重新调用 `authProvider` 换取新签名 URL
上报	每次 `connected` 自动重新上报 `sdk_meta.report`

连接事件订阅

sdk.on('error', (err) => console.error('连接错误', err));
sdk.on('disconnected', ({ willReconnect }) => {
  if (!willReconnect) console.warn('已关闭且不再重连');
});
sdk.on('keepalive', ({ state, probes }) => {
  if (state === 'timeout') console.warn('心跳超时，即将重连');
});

下行 ACK / 错误码判读

JS SDK 无回调类，所有下行在 sdk.on('message') 里按 type 判读。code 语义与原生一致：

`code`	含义
`0`	成功
`-1`	服务端拒绝 / 机器人离线（`message` 字段携带详情）

sdk.on('message', ({ data }) => {
  let msg: { type: string; code?: number; message?: string };
  try { msg = JSON.parse(typeof data === 'string' ? data : ''); } catch { return; }
  switch (msg.type) {
    case AgentEventType.TeleopEnterAck:
    case AgentEventType.ExtSkillQueryResult:
      // msg.code === 0 才成功
      break;
  }
});

未连接时调用

sendAudio / query / invoke 等最终走 sdk.send()；WebSocket 未连接（readyState !== OPEN）时会同步抛错 "Agent SDK is not connected"，不走 code 回调。

资源释放

sdk.close();     // 关闭连接、停止重连与保活
sdk.release();   // close() + 从单例表移除（同 appId 可重新 createAgentSdk）

常见问题排查

现象	可能原因	排查方式
连接成功但心跳一直超时	服务端代理未做 JSON ping ↔ 协议级 Ping 转换	确认代理把 `{"type":"ping"}` 转成 PingFrame
`authProvider` 无法鉴权	代理未用 `appSecret` 正确签名，或未返回可连接的 URL	检查代理端签名串与返回 URL
`message` 收不到业务数据	事件里 `data` 可能是 `Blob`/`ArrayBuffer`	非字符串时先 `await data.text()` 再 `JSON.parse`
`sendAudio` 抛错	未先 `startAudio`，或未 `connect`	按 enter → startAudio → sendAudio 顺序；确保已连接
非 https 环境麦克风/`crypto.randomUUID` 不可用	浏览器安全上下文限制	使用 https 或 localhost