JoyInside 接入手册

主题

第 12 章 验收 ​

上线前的最终自检。本章把前 10 章的验收点汇总成可执行的 checklist,覆盖云端配置、端侧实现、协议合规、场景联调、量产就绪五维度。

目录 ​

12.1 端侧自检清单 ​

鉴权与建联 ​

  • [ ] generate_sign 签名算法实现正确(HMAC-MD5 V2,key 小写升序,见 4.1 签名算法);
  • [ ] accessTimestamp 与服务端时间误差 ≤15min,不大于当前时间(NTP 校准,见 11.2);
  • [ ] accessVersion = V2;
  • [ ] vendorId / botId 至少传一个且正确(见 9.1.1);
  • [ ] getToken 成功,返回 accessToken + refreshToken;
  • [ ] accessToken 有效期 2h,主动刷新机制就绪(见 11.1);
  • [ ] refreshToken 有效期 7d,续期机制就绪;
  • [ ] WS 建联 URL 参数齐全(botId / sessionId / requestId);
  • [ ] WS Header Authorization: Bearer ${accessToken};
  • [ ] TLS 1.2+ 已启用,根证书已配置(避免 400,见 9.1.2);
  • [ ] HTTP header 以 \r\n\r\n 结尾(避免 408,见 9.1.3);
  • [ ] 域名预解析就绪(api.joyinside.com / ws.joyinside.com 等,见 9.1.6);

设备身份 ​

  • [ ] botId 已固化到设备(产测烧录,见 10.3);
  • [ ] deviceId 使用设备 SN,SN 全局唯一;
  • [ ] 量产设备 type = PHYSICAL_ROBOT(见 10.1);
  • [ ] uid 传真实用户 pin 或不传,禁止固定值(见 9.2.2);
  • [ ] SecretKey 未入设备固件(见 附录 F);

音频 ​

  • [ ] 上行 PCM:16k / 16bit / 单声道,单包 ≤300ms(见 4.4);
  • [ ] 上行 Opus:单包 ≤480 字节,帧长 ≤120ms(建议 60ms);
  • [ ] 音频包均匀发送,间隔 = 音频时长(否则延时异常);
  • [ ] CLIENT_VOICE_CHAT_UPDATE 每连接只发一次(切换角色除外);
  • [ ] 收到 SERVER_VOICE_CHAT_UPDATED 才算配置成功;
  • [ ] 二进制传输:开启 audio.binary=true 后用 ws.send(bytes);
  • [ ] 下行 TTS:PCM 帧长 60-120ms / Opus 帧长 10/20/40/60ms;
  • [ ] 下行 TTS 直接播放,不攒包(见 9.3.4);
  • [ ] 下行 TTS 接收与播放用多线程(单线程会卡顿);

打断与心跳 ​

  • [ ] 收到 CALL_AGENT_INTERRUPTED 后清空播放队列(见 9.3.2);
  • [ ] WS 下行事件并发监听(多线程,解决 80% 打断问题,见 9.3.3);
  • [ ] 手动模式音频结束发 CLIENT_AUDIO_FINISH;
  • [ ] 手动模式打断发 CLIENT_INTERRUPT;
  • [ ] 心跳 PING 间隔 30s(见 4.3 心跳与保活);
  • [ ] 收到 PONG 视为心跳成功;

日志 ​

  • [ ] 每轮对话日志打印 roundId(排查主键,见 11.3);
  • [ ] 日志含 eventType / eventTime / requestId / botId;
  • [ ] 异常事件(40104 / REPEAT_CLIENT_SESSION / 网络断连)实时记录;

12.2 云端配置验收 ​

企业与型号 ​

  • [ ] 企业已注册审核通过,拿到 vendorId;
  • [ ] 产品型号已创建,品类正确(不确定选「通用」);
  • [ ] 产品部件(可选)按需配置(见 6.1);
  • [ ] IoT 平台(可选)按需配置;

应用配置 ​

  • [ ] 应用已创建,appId 已获取;
  • [ ] 接入类型:语音智能体接入(推荐);
  • [ ] 全局人设已配置(提示词定义角色);
  • [ ] 默认音色已设置(系统或自定义,见 音色复刻);
  • [ ] 开场白已配置(轮播最多 5 条,见 开场白);
  • [ ] 静默推送按需配置(5 组时段,见 静默消息推送);
  • [ ] 事件反馈按需配置(配 extInfo,见 事件反馈);

技能与指令(按场景) ​

  • [ ] 系统技能按需启用(闲聊 / 天气等);
  • [ ] 自定义技能按需创建(准入描述:意图 + 触发条件 + 不可触发 + 正反例,见 6.6.3 设置自定义意图);
  • [ ] 指令集已绑定到设备型号(见 9.5.1);
  • [ ] 控制项指令数据类型正确(SWITCH / ENUM / NUMERIC,见 6.1.1);
  • [ ] 任务规划器按需开启(并行 vs 串行,见 6.1.4);
  • [ ] 垫句按需配置(清空 + 关执行反馈 = 静默,见 6.1.6);

场景专属配置(按需) ​

设备 ​

  • [ ] 设备已注册,botId 已获取;
  • [ ] 量产设备 type = PHYSICAL_ROBOT;
  • [ ] deviceId = SN;
  • [ ] deviceModel 如使用已申请(非标准参数,见 4.2);
  • [ ] 单设备音色按需覆盖(见 音色复刻);

预览调试 ​

  • [ ] 平台预览调试窗已跑通(云端跑通点,见 3.2);
  • [ ] 录音按钮已开启(测试开场白需开,见 9.6.2);

12.3 协议合规验收 ​

按 附录 B.4 上下行消息一览表 与 B.4 上下行消息一览表 逐项核对实现完整性,完整 JSON 协议见 附录 B.3。下列事件为验收重点(带 ⚠ 的为高频踩坑项):

上行事件 ​

事件验收重点
CLIENT_VOICE_CHAT_UPDATE⚠ 每连接一次,收到 SERVER_VOICE_CHAT_UPDATED 才成功
AUDIO流式上传,间隔 = 音频时长
PING30s 间隔
CLIENT_INTERRUPT / CLIENT_AUDIO_FINISH手动模式必需
TEXT / CLIENT_INPUT_TEXT_TO_SPEECH / VOICE_CHAT_TRIGGER按场景按需
CLIENT_UPDATE_CHAT_CONTEXT需申请权限,effectiveTimeMinutes 1~1440

下行事件 ​

事件验收重点
EMPTY_CONTENT⚠ 拒识,见四层防护(10.2.1)
AGENT⚠ finishReason = stop / audit
CALL_AGENT_INTERRUPTED⚠ 端侧清空播放队列(10.3.2)
CALL_SKILL_EVENT指令事件,data.args + data.intentClassify
ALARM_CLOCK_EVENTdata.op = add/delete/clear_all
USER_AUDIT_FAIL审核命中
REPEAT_CLIENT_SESSION互踢,同 botId 双连接(10.1.4)
CFG_BOT_EVENT / SERVER_VOICE_CHAT_UPDATED / ASR / TTS / TTS_COMPLETE / COMPLETE / PONG / ACTIVITY / CLIENT_CHAT_CONTEXT_RECEIVED按附录 B.3 逐项核对

完整事件协议明细见 附录 B.3,字段速查见 附录 B。

12.4 场景联调验收 ​

跑通验证(必验) ​

  • [ ] 云端配置完成,预览调试跑通(云端跑通点);
  • [ ] 端侧 Demo 改凭证跑通(端侧跑通点);
  • [ ] 一轮真实可听语音对话完成(ASR → Flow → TTS);
  • [ ] 多轮对话上下文连贯;

场景专属验收(按需) ​

  • [ ] IOT 控制:语音指令下发到端侧,执行反馈正确(见 6.1);
  • [ ] 有声书:开播 / 停播 / 播控 / 续播 / 唤醒停止(见 6.2);
  • [ ] 魔法打印:三态机切换,PRINT 协议 8 事件(见 6.3);
  • [ ] 视觉对话:needAsrPartial(开启ASR事件监听)，image/report API 关联 sessionId(见 6.4);
  • [ ] 闹钟:op = create/delete/delete_all,提示音频(见 6.5);
  • [ ] AI 角色:CRUD + 绑定 + 改昵称(见 附录 A.4 AI 角色管理);
  • [ ] 音色复刻:3-15s 单段音频,同企业唯一,切换需重建 WS(见 音色复刻);
  • [ ] 自定义技能 / A2A:Service Token 鉴权,Message → Instruction → Done(见 7.1 外部智能体接入);

故障现象回归 ​

  • [ ] 建联失败场景验证(签名 / 400 / 408 / 互踢);
  • [ ] 打断场景验证(TTS 播放中用户重新说话);
  • [ ] 拒识场景验证(静音 / 噪声输入);
  • [ ] 审核场景验证(触发审核词,finishReason = audit);

12.5 上线前回归 ​

量产就绪 ​

  • [ ] 设备注册(单设备)调用通过,SN ↔ botId 一一对应(见 4.2);
  • [ ] token 过期验证通过(跨夜唤醒可正常对话,见 10.2);
  • [ ] SN ↔ botId 一一对应,烧录到设备;
  • [ ] 产测自检通过(见 10.3);
  • [ ] 灰度发布计划就绪(见 10.4);

运维就绪 ​

  • [ ] Token 刷新机制就绪(见 11.1);
  • [ ] NTP 校准机制就绪(见 11.2);
  • [ ] roundId 日志打印就绪(见 11.3);
  • [ ] 心跳保活机制就绪(见 4.3 心跳与保活);
  • [ ] 监控告警指标就绪(见 11.4);
  • [ ] 京东技术支持沟通渠道就绪(见 11.6);

回滚预案 ​

  • [ ] 旧版本配置可快速切回;
  • [ ] 灰度异常时回滚流程明确;
  • [ ] 量产设备异常时批次召回方案就绪;

12.6 上线后监控 ​

核心指标(参考 11.4) ​

  • [ ] WS 建联成功率 ≥95%;
  • [ ] 对话完成率 ≥90%;
  • [ ] TTS 播放成功率 ≥95%;
  • [ ] 互踢率 ≤1%;
  • [ ] 签名失败率 ≤1%;
  • [ ] 心跳成功率 ≥99%;
  • [ ] 首次响应延迟 ≤2s;

持续运维 ​

  • [ ] 灰度逐步放量(canary → 10% → 50% → 100%);
  • [ ] 异常 roundId 收集与京东技术支持联查;
  • [ ] 配置变更后设备重建 WS 生效;
  • [ ] 定期回归验收 checklist;

验收通过 ​

完成以上 checklist 后,设备具备正式商用条件。