常见问题排除手册 & QA · JS / 浏览器
常见问题排除手册 & QA · JS / 浏览器
一、常见问题排除手册
1. 连接成功但心跳一直超时、反复重连
- 现象：
connected已触发，但几十秒后keepalive报timeout，连接被关闭重连，循环往复。 - 可能原因：服务端代理没有做 JSON ping ↔ 协议级 Ping 的转换。JS SDK 发的是
{"type":"ping"}文本，代理必须把它转成协议级 PingFrame 发给网关，再把 Pong 转回 JSON 回浏览器。 - 处理：这是接入契约——检查代理实现，见 快速开始 · 服务端代理。
2. authProvider 鉴权失败 / 握手 401、403
- 现象：代理连上游网关时返回 401 / 403。
- 可能原因：代理侧
appId/appKey/appSecret不属于同一应用；本机时钟偏差过大；签名串构造不一致。 - 处理：对齐凭证与时钟；签名串为
"GET\n{path}\n{timestamp}\n{nonce}"，五种头X-App-Id/X-App-Key/X-Timestamp/X-Nonce/X-Signature。appSecret只放服务端，绝不下发前端。
3. sendAudio / query / invoke 抛错
- 现象：调用时同步抛出
"Agent SDK is not connected"。 - 可能原因：未
connect()，或 WebSocket 尚在连接中（readyState !== OPEN）。 - 处理：先
await sdk.connect()；sendAudio前必须先startAudio。
4. message 里收到 Blob / ArrayBuffer，JSON.parse 失败
- 现象：某些浏览器下
event.data不是字符串。 - 处理：先判断类型，非字符串时
await data.text()再JSON.parse。
5. 非 https 环境麦克风 / crypto.randomUUID 不可用
- 现象：
getUserMedia被浏览器拒绝。 - 处理：使用 https 或 localhost（安全上下文）。
二、常见问题 QA
Q1. JS SDK 能用被动 / 主动交互吗？
A：暂未提供。 JS SDK 当前只内置 超视距遥操 + 扩展技能 两条路径；被动（8 种回调）与主动（任务流）请使用 Java / Python / Android / iOS SDK。详见 被动交互指南 与 主动交互指南。
Q2. 为什么浏览器不能像原生 SDK 那样直接鉴权？
A：浏览器的 WebSocket API 不能设置自定义请求头，无法在握手时带 X-App-Id / X-Signature。因此 JS SDK 通过 authProvider 回调，由同源服务端用 appSecret 签名并返回本地代理 URL。appSecret 绝不出现在前端。
Q3. 心跳为什么必须经代理转换？
A：浏览器只能发文本帧，发不了协议级 PingFrame，而网关心跳识别的是协议级 Ping。所以 SDK 发 JSON {"type":"ping"}，由代理转成 PingFrame，再把 Pong 合成 JSON 回浏览器。这是接入契约，缺失会导致"连接成功但心跳超时"。
Q4. appId / appKey / appSecret 从哪里获取？如何分布前后端？
A：登录灵心开放平台，在「应用」页面创建应用获取，三者属同一组凭证。其中 appId 可进前端（标识应用）；appKey / appSecret 只放服务端——appSecret 用于签名，严禁下发前端。
Q5. sendAudio 要不要自己算 audioLen？
A：不用。SDK 会就地 atob 解码 base64 计算解码后字节数一并下发；空帧直接丢弃。音频上行格式：24kHz / 16bit / 单声道 / 40ms 一帧（960 样本 = 1920 字节）。
Q6. JS SDK 的"主动能力"和任务流是一回事吗？
A：不是。JS SDK 的 扩展技能 ExtSkill 是"查询 / 触发单个扩展技能"，与"编排多步任务的任务流（Task Flow）"是两个能力。任务流 JS 未实现。