主题
JoyInside 接入手册
给硬件厂商从零接入到量产运维的官网开发者手册。核心思路:跑通一个真实可听的语音对话，再按场景扩展——不要求读完，每一章都服务于让你尽快到达下一个可感知的里程碑。
你是哪种接入者？选一条路
不同角色入口不同，选最接近你的那条。这一节是手册首页，先选路再看目录。
路径一：新接入者（从零开始接入 JoyInside）
第1章 认识 JoyInside ← 先理解 JoyInside 能做什么（1 分钟决策）
↓
第2章 选接入场景与方案 ← 确认你要做的硬件属于哪类场景，是否需要小程序
↓
第3章 JoyInside 接入预览 ⭐ ← 必走！跑通第一轮语音对话
↓
第4章 协议详解 ← 跑通后回来读，理解"为什么"
↓
按需：第5章硬件与音频处理 / 第6章场景扩展 / 第7章外部资源对接
↓
可选增强：扩展小程序交互面 → 第三部分（第8/9章）关键里程碑：完成第 3 章，你手里有一台能真实对话的设备。 入口：第1章 认识 JoyInside · 或直接 第3章 JoyInside 接入预览 抄代码跑通
路径二：已有设备迁移者（从其他方案迁移到 JoyInside）
第2章 §2.5 已有设备迁移 ← 4 种迁移模式：意图体系+A2A / 整体接入 / 小程序控制 / 控制通道分离
↓
第3章 JoyInside 接入预览 ⭐ ← 仍需走通，确认基础链路
↓
第6章 对应场景扩展 ← 按你的硬件形态选 6.1-6.6
↓
第7章 外部资源对接 ← A2A 协议（迁移者常用）关键里程碑：完成第 3 章 + 第 6 章对应场景，旧设备在 JoyInside 上跑通。 入口：第2章 §2.5 已有设备迁移（涉及小程序的迁移模式见第8章）
路径三：排查者（设备跑通了但出问题了）
第9章 联调与故障排查 ⭐ ← 直接按"故障现象"找答案
↓ （10.x 指向具体协议章节）
回看第4章对应协议块 ← 10.1→4.1鉴权 / 10.2→4.5服务端 / 10.3→4.3WS
↓
附录 B. JoyInside 协议速查 ← 查事件/参数/错误码故障现象速查：
| 你遇到的现象 | 直接跳转 |
|---|---|
| 建联失败（400 TLS / 408 CRLF / 鉴权 1001-1006） | 第9章 §9.1 |
| 设备不说话 / 答非所问 / 延迟断续 | 第9章 §9.2 |
| TTS 打不断 / 打断失效 | 第9章 §9.3 |
| 有声书不播放 / 不停止 / 串场词混乱 | 第9章 §9.4 |
| IOT 指令不下发 / 执行反馈异常 | 第9章 §9.5 |
| 音色切换不生效 / 开场白不播放 | 第9章 §9.6 |
| 查全部错误码 | 第9章 §9.7 |
入口：第9章 联调与故障排查
路径四：先跑通再说
不想读概念，只想最快听见设备开口？直接走第 3 章。 入口：第3章 JoyInside 接入预览 —— 听见云端回复。
手册结构
手册按 5 部分组织，从「认识选型」到「量产运维」层层递进：
| 部分 | 主题 | 章节 | 里程碑 |
|---|---|---|---|
| 第一部分 | 认识与选型 | 第 1-3 章 | 知道 JoyInside 能做什么、自己走哪条接入线、跑通第一轮语音对话 |
| 第二部分 | 语音对话接入 | 第 4-7 章 | 协议/硬件/场景/高级按需扩展 |
| 第三部分 | 小程序接入 | 第 8 章 | 扩展用户交互面（配网/角色/绑定/聊天/在线设备管理），可选增强 |
| 第四部分 | 联调与量产运维 | 第 9-12 章 | 从"跑通一台"到"量产万台"，稳定运维 |
| 第五部分 | 附录 | A-G | 查即止，字典式 |
| 第六部分 | 端侧程序设计（参考） | 端侧程序设计详解 | 正常对接时参考了解的端侧设计准则 |
⚠️ 小程序是「可选增强场景」，不是独立接入方式——设备端语音接入是前置条件。京东不提供成品小程序，需客户自研。详见 第8章。
完整目录
第一部分 · 认识与选型
| 章节 | 一句话定位 | 状态 |
|---|---|---|
| 第1章 认识 JoyInside | 让硬件开口说话、用自然语言驱动设备；三类核心能力 + 3 个真实场景案例 + 两条工作面 | ✅ 已完成 |
| 第2章 选择接入场景与方案 | 顶层场景决策树 + 5 类硬件场景 + 4 种迁移模式 + 小程序接入决策 + 时长预估 | ✅ 已完成 |
| 第3章 JoyInside 接入预览 | 接入全景 + 两个阶段（智能体搭建并验证 + 体验设备端接入），听见云端回复 | ✅ 已完成 |
第二部分 · 语音对话接入
| 章节 | 一句话定位 | 状态 |
|---|---|---|
| 第 4 章 语音对话协议 | 跑通后讲清"为什么这么设计"；鉴权/设备身份/WS 协议/音频/服务端链路/事件 + 核心参数总表 | ✅ 已完成 |
| ├ 4.1 Token 鉴权 | HMAC-MD5 V2 签名、Token 生命周期、鉴权失败场景 | ✅ |
| ├ 4.2 设备注册与绑定 | appId→botId→sn 三层映射、设备绑定角色/用户、双连接互踢 | ✅ |
| ├ 4.3 重要参数介绍 | sessionId/mid/uid/requestId/roundId 五大核心标识 | ✅ |
| ├ 4.4 WebSocket语音通道总览 | 建联参数、对话模式、上下行事件全集、完整轮次序列 | ✅ |
| ├ 4.5 音频格式与分片 | PCM/Opus/mp3、切包规则、二进制传输 | ✅ |
| └ 4.6 服务端链路设计（进阶阅读） | ASR→Flow→TTS 三模块、roundId 排查、TTS 打断原理 | ✅ |
| 第 5 章 设备端适配 | 硬件准入基线、三种交互模式声学要求、设备端音频处理链路（PCM/Opus 切包）、芯片矩阵 | ✅ 已完成 |
| 第 6 章 业务场景接入 | 按硬件形态分层；IOT 控制、有声书（含三方内容资源）、魔法打印、视觉对话、闹钟 | ✅ 已完成 |
| ├ 6.1 指令与控制 | 分步配置指南、任务规划器、垫句、批量测试 | ✅ |
| ├ 6.2 媒体资源接入 | V1/V2 模式、开播停播心跳完播、串场词、三方内容资源对接 | ✅ |
| ├ 6.3 魔法打印接入 | 按键 A/B 三态机、PRINT 协议 8 事件 | ✅ |
| ├ 6.4 视觉对话接入 | needAsrPartial(开启ASR事件监听)、image/report API | ✅ |
| ├ 6.5 闹钟设置接入 | ALARM_CLOCK_EVENT（op=add/delete/clear_all）、提示音频 | ✅ |
| 第7章 三方能力接入 | 自定义技能与A2A协议、外部媒体资源接入、网易云音乐接入 | ✅ 已完成 |
| ├ 7.1 外部智能体接入 | 系统内置/自定义技能、A2A 流式响应、指令选择与自定义 | ✅ |
| ├ 7.2 外部媒体资源接入 | 三方资源检索与详情接口、Authorization 鉴权、多轮检索与续播机制 | ✅ |
| └ 7.3 网易云音乐接入 | 创建应用、应用/设备授权、网易云技能配置、小程序网易云账号绑定 API 对接 | ✅ |
第三部分 · 小程序接入
| 章节 | 一句话定位 | 状态 |
|---|---|---|
| 第 8 章 小程序接入方案 | 适配策略（自研/京东标准盒子/方案商小程序）、接入前置、接口总览 | ✅ 已完成 |
第四部分 · 联调与量产运维
| 章节 | 一句话定位 | 状态 |
|---|---|---|
| 第 9 章 联调与故障排查 | 按"故障现象"组织（不按技术概念）；建联失败/不说话/打断失效/有声书/IOT/音色 + 错误码速查 | ✅ 已完成 |
| 第 10 章 量产接入 | 从测试设备到生产设备、token 过期验证、产测烧录、灰度发布 | ✅ 已完成（产测/灰度部分待 JoyInside 团队补充） |
| 第 11 章 日常运维 | Token 刷新策略、日志监控、OTA 远程配置、联系支持规范 | ✅ 已完成（OTA/平台监控部分待 JoyInside 团队补充） |
| 第 12 章 上线验收 Checklist | 端侧自检、云端配置验收、上线前回归、上线后监控 | ✅ 已完成 |
第五部分 · 附录（查即止，字典式）
| 附录 | 内容 | 状态 |
|---|---|---|
| A. 服务端 HTTP API 参考 | 鉴权/设备管理/AI角色/音色/用户绑定/聊天记录/在线设备/视觉/网易云音乐,30 个接口 | ✅ 已完成 |
| B. WebSocket 语音协议全览 | 通用消息结构/错误码/事件协议明细(按功能维度聚合)/上下行消息一览表 | ✅ 已完成 |
| C. 术语表 | VAD/AEC/AGC/ANS/OTA/roundId/A2A/barge-in/双Token/拒识四层防护 | ✅ 已完成 |
| D. 数字音频基础 | 采样/量化/编码、PCM vs MP3 vs Opus 对比、Opus 拼包原理、JoyInside 音频实践 | ✅ 已完成 |
| E. 平台配置字段速查 | 企业型号/应用/技能指令/音色/设备/外部API 配置项清单 | ✅ 已完成 |
| F. 接入材料清单 | 企业资质/设备信息/技术对接人/凭证申请/时长预估 | ✅ 已完成 |
| G. 下载 Demo | 多语言 Demo（Java/Python/C++/Android）+ 芯片 SDK Demo（ESP32S3/BK7258/Linux） | ✅ 已完成 |
✅ 全手册已完成。第 11/12 章部分小节标注「待补充」，为平台侧能力（产测烧录、灰度发布、OTA、平台监控大盘），需与 JoyInside 团队对齐后填充。
第六部分 · 端侧程序设计（参考）
正常对接 JoyInside 时，若需参考理解端侧程序的设计准则（状态模型、线程模型、全双工对话链路、有声资源播放链路），读本部分。讲的是端侧架构与实现准则，不是云端协议对接。
| 章节 | 一句话定位 | 状态 |
|---|---|---|
| 端侧程序设计详解 | 端侧程序设计参考：设备状态模型、整体架构（分层/线程/数据流/WS连接管理）、全双工对话链路、有声资源播放链路、弱网暂态容忍、常见问题排查 | ✅ 已完成 |
这本手册不做什么
- 不讲 JoyInside 平台的后台架构细节（ASR 引擎实现/Flow 调度算法/TTS 模型），只讲端侧需要理解的"服务端为什么这么处理"
- 不替代 1 对 1 技术支持，复杂问题仍需通过第 9 章 §9.4 联系支持
- 不提供小程序：京东不提供小程序，小程序部分讲的是方案商自研小程序如何对接 JoyInside 接口
JoyInside 接入手册
给硬件厂商从零接入到量产运维的官网开发者手册。核心思路:跑通一个真实可听的语音对话，再按场景扩展——不要求读完，每一章都服务于让你尽快到达下一个可感知的里程碑。