JoyInside 接入手册

主题

第 9 章 故障排查 ​

按故障现象组织,不按技术概念。你看到设备"不说话/打不断/建不上联",直接跳到对应小节找根因和修复步骤。

排查前先确认手里有这一轮的 roundId(见 4.5 roundId),它是服务端日志定位的主键,没有它京东技术支持无法帮你查。

目录 ​

故障现象决策树 ​

按设备表现快速定位章节:

排查前先拿到出问题那一轮的 roundId(见 4.5 roundId),没有它京东技术支持无法查服务端日志。

9.1 建联失败类 ​

9.1.1 签名鉴权失败(getToken 返回 1001-1006) ​

现象:getToken 接口返回非 200,或返回 code 在 1001-1006 之间,拿不到 accessToken,后续 WS 建联无从谈起。

根因与排查:按返回码定位,完整码值见 9.7 错误码速查表。最常见三类:

返回码含义排查
1003时间戳错误accessTimestamp 必须 不晚于当前时间 15 分钟,且不能大于当前时间。设备 NTP 未校准是首因,见 11.2 NTP 校准
1005签名不合法key 必须按小写后字符代码升序排列;请求参数必须与签名生成参数完全一致
1001参数非法vendorId 与 botId 至少传一个且必须正确,两者都为空会报 1001

签名生成注意事项(HMAC-MD5 V2,详见 4.1 签名算法):

  1. accessTimestamp 不晚于当前时间戳 15 分钟,不能大于当前时间戳;
  2. 参与签名的 key 转换为小写后,按字符代码顺序升序排列;
  3. accessVersion 必须为 V2。

getToken 注意事项:

  1. 请求参数必须与签名生成参数完全一致;
  2. vendorId 与 botId 必须传一个,且必须是正确 ID;
  3. accessToken 有效期 2 小时,建议 WS 建连前重新获取,不要复用快过期的 token。

9.1.2 WebSocket 建连返回 400(TLS 版本问题) ​

现象:C 语言或模组端 WS 建连,服务端返回 400 状态码。

根因:wss:// 是 "WebSocket + TLS 加密",要求设备端先完成 TLS 握手(配置根证书、启用 TLS 1.2+)。如果设备端把 wss 当 ws(非加密)处理,没做 TLS 配置:

  • TLS 握手失败,服务器拒绝后续 WebSocket 升级请求,返回 400;
  • 或 TLS 没启用,发送的升级请求是明文,服务器预期加密数据,解析失败返回 400。

修复:

  1. 确认建联参数正确:botId/requestId/sessionId 等关键参数齐全,参数为标准 JSON 格式;
  2. 检查 SSL/TLS 证书版本,启用 TLS 1.2+;
  3. 仍失败则联系对接技术群中的京东技术支持联查,需提供设备公网 IP。

9.1.3 WebSocket 建连返回 408(CRLF 结尾缺失) ​

现象:WS 建连返回 408 状态码。

根因:HTTP header 结束需要两个 \r\n\r\n。Authorization: Bearer 作为 header 最后一个参数时,如果少了一个 \r\n,服务器认为 header 没发完,返回 408。

修复:所有 header 结束后多加一个 \r\n,确保有 \r\n\r\n 结尾。

9.1.4 频繁断连 / REPEAT_CLIENT_SESSION(设备互踢) ​

现象:设备反复断连重连,日志出现 "eventType":"REPEAT_CLIENT_SESSION"。

根因:同一个 botId 在服务端同时存在两个 WS 连接,新连接会踢掉旧连接。排除 API 主动断连后,可能是:

  1. 端侧网络问题:网络抖动导致旧连接未释放就新建连接 → 端侧自行处理网络重连逻辑;
  2. 设备互踢:同一个 botId 反复建连。常见于:
    • 第三方模组开发时,多个设备共用同一个 botId 和 SN(应保证每个设备 botId 和 SN 一一对应);
    • 端侧多线程开发,ws 探活逻辑触发重连,或并发问题触发重连。可根据建连时 requestId 排查——如果同一个 requestId 在建连时重复出现,基本就是多线程场景下重连导致的。

修复:

  • 端侧检查网络情况;
  • 第三方模组:确保每个设备有唯一的 botId 和 SN,一一对应;
  • 多线程场景:排查 ws 探活和重连逻辑,避免并发触发重连。

双连接互踢的根本原因见 4.2 双连接互踢。

9.1.5 WebSocket 连接自动断开 ​

现象:WS 长连接不定时断开,无明确错误码。

排查:

  1. 先按 9.1.4 REPEAT_CLIENT_SESSION 排查互踢;
  2. 检查端侧 WS 长连接机制和 maxIdleTime 空闲连接超时时间是否合理;
  3. 确认心跳 PING 间隔 30s 是否稳定发送(见 4.3 心跳与保活);
  4. 完善端侧 WS 长连接保活机制。

9.1.6 首次建联慢(DNS 解析) ​

现象:终端开机后首次建联明显变慢。

根因:首次建联需要对域名进行 DNS 解析,DNS 解析时间较长导致建联慢。

修复:终端开机后提前进行域名解析,然后再建联。需要预解析的域名:

  • api.joyinside.com(getToken / 设备注册 / 视觉 / 闹钟)
  • ws.joyinside.com(WS 语音对话)
  • storage.360buyimg.com / s.360buyimg.com(CDN 资源)
  • audio.joyinside.com(音频资源)

9.1.7 WS 建连 40100-40104(不返回设备端) ​

现象:WS 建连被关闭,但设备端看不到具体错误码。

根因:WS 建连鉴权失败码 40100-40104 不返回设备端,设备只看到连接被关闭。具体码值需结合服务端日志排查。场景见 10.7 错误码速查表,排查结合服务端日志与 roundId。

9.1.8 4G物联网卡建连失败 ​

现象:4G物联网卡连接Joyinside服务端失败 排查步骤:

  • 如果发现是时好时坏(有一定概率能建连成功)大概率是物联网卡自身的问题
  • 排查joyinside.com 是否加白名单
  • 排查ws建连时是否填写SNI信息
  • 根据HTTP协议定义的语法规则，请求头必须换行结尾，请求头中每个内容都需要单独一行，此时需要连续两个空行表示请求头结束
  • 如果上面步骤都排查完还不能建连，则通过抓包工具抓取日志，提供给joyinside技术人员帮助排查

9.2 设备不说话 / 答非所问 ​

9.2.1 上传音频后未收到云端回复(EMPTY_CONTENT) ​

现象:设备上传了音频,但云端不下发 TTS,或下发的是 EMPTY_CONTENT 事件。

根因:EMPTY_CONTENT 事件代表云端 ASR 未识别到有效音频。JoyInside 拒识有四层防护(见 4.5 拒识四层),EMPTY_CONTENT 是其中一层的输出。

排查:

  1. 确认上传的是有效音频(非静音、非噪声、音量足够);
  2. 确认音频格式与 CLIENT_VOICE_CHAT_UPDATE 配置一致(PCM 16k/16bit/单声道 或 Opus);
  3. 确认音频包均匀发送,间隔等于音频时长(否则延时异常,见 4.4 音频格式);
  4. 定位下行事件中 content.eventType 是否为 EMPTY_CONTENT,是则确认上述三项。

9.2.2 记忆紊乱 / 对话串台(uid 固定值) ​

现象:不同用户的对话记忆混在一起,或设备答非所问、上下文错乱。

根因:上行事件 uid 参数传了固定值(如所有设备都用 123456),导致服务端把不同用户的对话归到同一个会话。

修复:uid 传递真实的用户 pin 等信息,或者不传递(不传递时服务端按设备维度隔离)。禁止所有设备使用相同固定值。

uid 规则:非必传,但传了必须一致,值与 null 不能混。详见 4.2 uid 规则。用户 pin 在平台导航栏最下方「个人信息」中查看。

9.2.3 审核命中 / 回复被拦截(finishReason=audit) ​

现象:对话回复内容被截断或被替换为安全提示,AGENT 事件中 finishReason 字段值为 audit。

根因:回复内容命中内容审核。服务端会下发 USER_AUDIT_FAIL 事件(详见 附录 B.3),同时 AGENT 事件 finishReason 置为 audit。

处理:这是平台内容安全策略,端侧无需特殊处理,正常播放下发的 TTS 即可。如确认是误判,联系京东技术支持。

9.2.4 TTS 自言自语(回声未消净) ​

现象:设备播放 TTS 时仿佛在跟自己说话,自己说完又触发识别。

根因:终端模组固件收音质量不达标,回声没有消除干净(AEC 未生效),TTS 音频被回采进麦克风,触发 ASR 误识别。

修复:

  1. 优先排查终端模组固件收音质量;
  2. 确认全双工模式下 AEC 已启用并调参(见 5.2 全双工模式);
  3. 收音质量差时回声消除不干净,必然导致自言自语。

9.3 打断失效 / TTS 异常 ​

9.3.1 新轮次对话开始的标识是什么 ​

标识:新一轮轮次开始时,服务端下发 CALL_AGENT_INTERRUPTED 事件。端侧收到后,打断正在播放的 TTS 音频流,准备播放新的音频流。

事件协议见 附录 B.3。

9.3.2 语音打断未生效 / TTS 音频播放重叠 ​

现象:用户已经开始说新一轮,但旧 TTS 还在播放,出现重叠。

根因:端侧收到 CALL_AGENT_INTERRUPTED 后没有正确清理本地 TTS。

修复:端侧收到 CALL_AGENT_INTERRUPTED 后必须:

  1. 停止 TTS 播放;
  2. 清理本地缓存的 TTS 音频;
  3. 清除播放队列;
  4. 等待新的 TTS 音频下发。

9.3.3 正在播放的 TTS 打不断(并发监听) ​

现象:TTS 播放中无法被打断,或打断延迟很大。

根因:端侧 WS 监听事件用单线程处理,下行事件排队,CALL_AGENT_INTERRUPTED 排在队列后面无法及时处理。

修复(解决 80% 问题):

  1. 步骤一:将 WS 监听逻辑改为并发监听(多线程快速消费下行事件),可解决 80% 的 TTS 打断不了的问题;
  2. 步骤二:如果使用了模具,需模具技术同事与京东技术支持一起排查,排查前先打印日志方便定位。

9.3.4 TTS 音频卡顿(攒包 / 单线程) ​

现象:TTS 播放不流畅,出现卡顿。

根因:端侧收到 TTS 音频包后攒包再播放,或用单线程处理 TTS 接收与播放。

修复:

  1. 终端收到 TTS 音频包后直接播放,不要攒包;
  2. JoyInside 下发 TTS 时已切包,以相同间隔有序下发:首次下发 3 个包,每包 60ms(总计 180ms),然后间隔 54ms 下发后续包;
  3. 单线程处理 TTS 的,改成多线程处理 TTS 音频接收与播放。

9.3.5 TTS 音频被流量控制(快包配置) ​

现象:网络不稳定时 TTS 播放卡顿。

处理:联系 JoyInside 侧进行快包配置修改——在一轮交互的 TTS 下发阶段,生成音频时首次下发 N 个包(注意端侧内存问题,内存不足不要用 mp3 格式)。

9.4 有声书 / 内容播放类 ​

有声书分按键交互(V1,feature=AUDIO_BOOK + clientType=AUDIO_BOOK)和连续对话(V2,feature=AUDIO_BOOK_V2)两种模式,排查前先确认属于哪种。详见 6.2 有声书。

9.4.1 用户让播放有声书 / 歌曲时不播放 ​

排查链路(逐项确认):

  1. 检查 WS URL 是否添加有声书参数,feature 是否传入正确(V1 还是 V2);
  2. 检查是否下发 AUDIO_BOOK_PLAY 事件;
  3. 检查端侧是否有处理 AUDIO_BOOK_PLAY 事件的逻辑;
  4. 检查端侧是否上传 AUDIO_BOOK_PLAY 事件,是否上传 AUDIO_BOOK_PING(心跳);
  5. 确认应用下已添加有声书和歌曲点播技能。
  6. 有声书场景下会先下发澄清内容，比如“我这有两个故事，一个是xxx，另一个是yyy，你想听哪个？”，此时如果用户不回复澄清内容，不会下发开播事件

9.4.2 用户说停止播放后,有声书 / 歌曲不停止 ​

排查链路:

  1. 检查 WS URL feature 是否传入正确;
  2. 检查是否下发 AUDIO_BOOK_STOP 事件(按键模式 V1 不会下发该事件,靠客户端自行停止);
  3. 检查端侧是否有处理 AUDIO_BOOK_STOP 事件的逻辑;
  4. 检查端侧是否上传 AUDIO_BOOK_STOP 事件,是否停止上传 AUDIO_BOOK_PING;
  5. 检查建连时 uid 和有声书心跳事件 uid 是否一致——可以同时为空,但不能不一致。

9.4.3 有声书播放断断续续 ​

根因:端侧一次性下载整段音频资源再播放,响应慢且分段播放时后台未下载好。

修复:遵守播放 + 下载同步进行,设置合理 buffer,分段下载:

  • 一个音频包切分为 10 段下载;
  • 下载第一段后立即播放,同时下载第二段;
  • 这样播放响应快,分段播放时后台已下载好,避免断续。

9.4.4 有声书串场词混乱 ​

现象:有声书开播时串场词播放混乱,或不该播放串场词时播放了。

根因:JoyInside 资源下发分有声书、歌曲等多种,部分场景不包含串场词下发。

修复:接收到有声书开播事件后,通过字段 includeTTS 是否为 true 判断此次下发是否包含串场词:

  • includeTTS=true:包含串场词,先播串场词再播资源;
  • includeTTS=false:不包含,直接播放资源即可。

9.4.5 有声书播放过程中下发闲聊 TTS(被打断) ​

现象:有声书播放中,云端突然下发闲聊 TTS,打断有声书。

原因一:JoyInside 云端通过有声书心跳判断端侧是否处于流媒体资源播放状态:

  • 心跳进行中 → 过滤所有非播控意图之外的 TTS 下发;
  • 心跳异常 → 认为端侧未处于播放状态,不会过滤 TTS 下发。

修复:确认端侧 AUDIO_BOOK_PING 心跳稳定上报(建议 ≤2s 间隔),心跳异常会导致过滤失效。

原因二: 用户主动上传了停播事件

  • 云端收到音频事件后下发了打断事件，端侧收到打断事件后上传了AUDIO_BOOK_STOP事件，停止播放有声书

修复:确认端侧 是否上传了停播事件

9.5 IOT 指令类 ​

9.5.1 应用与指令集的型号配置不一致,设备无法控制 ​

现象:语音指令下发给设备,设备无法执行,或指令根本不下发。

根因:运营平台应用的型号与指令集的型号不一致。系统生成提示词是通过型号获取型号下所有指令集生成的,型号不匹配会导致指令集缺失。

修复:将指令集的型号改成应用的型号,保持一致。

9.5.2 IOT 指令不下发 / 静默不生效 ​

现象:用户说了指令,设备没收到 CALL_SKILL_EVENT,或收到了但端侧没反应。

排查:

  1. 确认指令集已绑定到设备对应的型号(见 9.5.1);
  2. 确认指令的准入描述配置正确(见 7.1.3 配置技能准入);
  3. 确认任务规划器与垫句配置:开启并行下发时垫句会先播;垫句清空 + 关执行反馈 = 静默执行(见 6.1.5 垫句机制);
  4. 确认指令数据类型正确:SWITCH/ENUM/NUMERIC 易混淆,详见 6.1.1 配置前准备。

9.5.3 IOT 新配设备怎么对接 ​

见 6.1 IOT 控制 的配置流程总览与分步操作指南。

9.6 音色 / 查询类 ​

9.6.1 运营平台切换音色后不生效 ​

现象:在运营平台切换了音色,但设备播放的 TTS 还是旧音色。

根因:音色配置在 WS 建连时下发(CFG_BOT_EVENT),运行中切换不会主动推送。

修复:重新建立 WebSocket 连接方可生效。音色复刻与使用位置见 音色复刻。

9.6.2 可视化调试工具测试开场白不播放 ​

现象:运营平台可视化调试工具建联后,开场白不播放。

根因:端到端模式为语音入语音出,开场白支持的条件是建联后首次收到音。Web 调试工具输入框左边有个录音按钮,建联后不开启该按钮,Web 页面不收音,触发不了开场白播放。

修复:开启录音按钮,收到音后就会播放开场白。

9.6.3 输入音频格式(PCM / Opus / mp3) ​

  • 默认格式:PCM(所有语音数字化原始数据本身就是 PCM);
  • Opus:需要先发送 CLIENT_VOICE_CHAT_UPDATE 上行事件更新配置后再传(见 4.4 音频格式);
  • mp3:不支持上行,仅下行 TTS 支持。

9.6.4 端侧状态查询(电量 / 音量等) ​

通过语音查询设备状态,有两种方案让大模型回复:

方案一:端侧组装内容回复(推荐)

  1. 在运营平台创建自定义指令(如电量查询,见 6.1);
  2. 用户语音触发指令下发(如"当前电量还有多少");
  3. 端侧收到指令事件后,查询设备状态(如电量 30%);
  4. 端侧自行组装文本(如"当前电量还有 30%,记得充电哦");
  5. 发送上行事件 CLIENT_INPUT_TEXT_TO_SPEECH 请求音频合成(内容为组装的文本,不触发智能体);
  6. 端侧等待云端下发 TTS 并播放。

方案二:云端大模型回复(运营平台暂不支持)

1-3 同方案一; 4. 端侧通过上行事件 VOICE_CHAT_TRIGGER 主动触发对话发给云端,kvData 填设备状态值(如 voice_limit: 30); 5. 等待云端下发 TTS 并播放。

方案二需找云端技术人员配置,运营平台暂不支持。事件协议见 附录 B.3。

9.6.5 同一个 SN 重复注册设备 ​

现象:同一个 SN 重复注册,返回同一个 botId。

说明:同一个 SN 只能注册一个设备,不能重复注册。如果重复注册,返回之前注册的 botId。详见 4.2 设备注册。

9.6.6 历史对话信息查询接口 ​

说明:平台目前未开放该接口。

9.6.7 厂商自定义开发智能体 ​

说明:平台目前不具备独立开发智能体环境,可通过运营平台三方技能模块注册三方智能体访问链接。见 7.1 外部智能体接入。

9.7 错误码速查表 ​

getToken 鉴权错误码(1001-1006) ​

码含义排查章节
1001参数非法必填缺失 / vendorId+botId 都为空4.1
1002版本号错误accessVersion 非 V24.1
1003时间戳错误格式错 / 超 15min 误差 / NTP 未校准11.2 NTP
1004企业或设备不存在vendorId / botId 不正确4.2
1005签名不合法签名算法错 / key 未小写升序 / 参数不一致4.1 签名
1006系统异常联系京东技术支持—

WS 建连鉴权(40100-40104,不返回设备端) ​

⚠ WS 建连 40100-40104 不返回设备端,设备只看连接被关闭。排查结合服务端日志与 roundId。

码含义排查
40100缺少鉴权必须参数vendorId 或 botId 没传
40101企业配置不合格配置缺失
40102接口未授权不在企业使用白名单
40103token 错误验证失败
40104token 过期accessToken 过期(2h),重新 getToken

HTTP 状态码(WS 建连阶段) ​

码含义修复
400TLS 版本问题启用 TLS 1.2+,配置根证书,见 9.1.2
408CRLF 结尾缺失header 结束补 \r\n\r\n,见 9.1.3

其他错误 ​

码含义修复
{"code":400,"msg":"audio binary not support."}未启用二进制但传了 bytesCLIENT_VOICE_CHAT_UPDATE 中 audio.binary=true 开启二进制,见 4.4
"eventType":"REPEAT_CLIENT_SESSION"双连接互踢同 botId 重复建连,见 9.1.4
"eventType":"EMPTY_CONTENT"ASR 未识别有效音频见 9.2.1
"eventType":"USER_AUDIT_FAIL"内容审核命中见 9.2.3

下一步 ​