第 10 章量产

从 1 台到万台。第 3 章你跑通了测试设备(APP_ROBOT),量产前需切换为生产设备(PHYSICAL_ROBOT),验证 token 过期处理,完成产测烧录与灰度发布。
⚠ 设备注册是单设备维度——每台设备开机配网后单独创建,不存在"量产批量注册"接口。注册接口参数见 4.2 设备注册与绑定。

10.1 测试设备 → 生产设备(type 转换)

设备注册时通过 type 字段区分测试与生产:

type 取值	含义	用途
`APP_ROBOT`	测试设备	第 3 章的跑通验证、研发调试、预览
`PHYSICAL_ROBOT`	生产设备	量产出货、正式商用

切换方式:注册设备时将 type 从 APP_ROBOT 改为 PHYSICAL_ROBOT。

python

params = {
    "vendorId": "填入您的企业ID",
    "appId": "填入您的APP_ID",
    "deviceId": "建议使用设备SN编码",
    "type": "PHYSICAL_ROBOT",  # 生产设备(测试阶段用 APP_ROBOT)
    "name": "量产设备-批次001"
}

⚠ 测试设备与生产设备共用同一个 vendorId / appId,但 botId 不同。测试设备用于研发,生产设备用于出货,不要用测试设备 botId 投产。
注册接口完整参数(vendorId/appId/deviceId/deviceModel 等)见 4.2 设备注册三要素。

10.2 token 过期验证

token 过期处理是方案商最常未做好的环节。设备长期运行(尤其跨夜休眠唤醒)后,若 token 过期处理缺位,会出现「设备开机正常,放一夜第二天就不说话」的典型故障。本节是量产前必做的验证项,token 刷新机制本身见 11.1 Token 刷新策略。

token 校验时机

JoyInside 的 token 校验发生在 WS 建联时:

场景	token 是否影响	说明
WS 建联	✅ 校验	建联时校验 accessToken,过期返回 40104(见 9.7)
WS 已连接未断开	❌ 不影响	token 过期不影响已建立的 WS 连接,对话照常进行
WS 断开后重连	✅ 校验	重连时重新校验 token,若已过期需先刷新

核心结论:token 过期只在「建联」这个时机咬人。已连上的 WS 不会因 token 过期中断,但设备一旦断开重连(休眠唤醒、网络抖动),过期 token 会导致重连失败、设备「不说话」。

量产验证场景

验证场景	为什么必测	预期行为
跨夜唤醒(超过 8 小时)	accessToken 有效期 2h,设备休眠跨夜后 token 必然过期	唤醒后重连前检测 token 过期 → 用 refreshToken 刷新 → 重连成功 → 正常对话
长时间在线(>2h)	accessToken 到期,但 WS 未断	对话不受影响(已连接不校验);断开重连时需刷新
refreshToken 过期(>7 天)	设备长期离线/休眠超 7 天	refreshToken 失效 → 需重新签名 getToken(非刷新)→ 重连
网络抖动重连	WS 断开后 token 已过期	重连前先刷新 token,避免 40104 重连失败

跨夜唤醒验证方法

这是最关键的一项——直接对应「放一夜就不说话」的典型故障:

python

def test_overnight_wakeup():
    """模拟设备休眠跨夜(>8h)唤醒后的 token 处理"""
    # 1. 设备休眠前:正常对话(WS 连接已建立)
    # 2. 设备休眠 8 小时(accessToken 2h 已过期,WS 断开)
    # 3. 唤醒:重连前必须检测 token
    if token_expired(access_token):          # accessToken 已过期(必然)
        if refresh_token_valid(refresh_token):  # refreshToken 7d 内仍有效
            access_token = refresh_access_token(refresh_token)
        else:                                     # 超 7d,refreshToken 也过期
            access_token = get_token()            # 重新签名获取
    # 4. 用新 token 建联 → 正常对话
    ws_connect(access_token)

验证通过的判据:设备休眠跨夜唤醒后,无需人工干预即可恢复对话。若唤醒后「不说话」,查重连日志是否走了 token 刷新分支(见 11.1 端侧刷新建议)。

常见未处理好导致的故障

现象	根因	修复
设备开机正常,跨夜后不说话	唤醒重连未检测 token 过期,40104 重连失败	重连前先 `token_expired` 检测,过期则 refreshToken 刷新
设备运行 2h 后断连再连不上	accessToken 到期,重连用旧 token	同上,重连前刷新
设备长期离线后无法激活	refreshToken 7d 也过期,仍尝试 refresh	检测 refreshToken 失效 → 走 getToken 重新签名
WS 连接中 token 过期设备断连	误以为已连接也需刷新,主动断连	已连接的 WS 不需要因 token 过期断连,保持连接即可

token 刷新机制(双 Token/refreshToken 接口/刷新时机)的完整定义见 11.1 Token 刷新策略,本节只讲量产前如何验证该机制做对了。

10.3 产测烧录

⚠ 本节待补充:官网和知识库暂无完整产测烧录文档,以下为基于设备注册流程的产测建议框架,具体烧录工具链与 JoyInside 团队对齐。

产测流程建议

SN 分配:产线为每台设备分配唯一 SN;
设备注册:每台设备开机配网后调用注册接口(见 4.2),拿到 botId;
凭证烧录:将 botId + vendorId + appId + AccessKey(或派生凭证)烧录到设备固件;
产测自检:设备上电后完成跑通验证(见 12.1 端侧自检);
入仓记录:登记 SN ↔ botId ↔ 批次号对应关系,便于售后追溯。

凭证安全

SecretKey 不入设备:SecretKey 仅用于服务端签名,不烧录到客户端(见附录 F);
accessToken 不硬编码:accessToken 有效期仅 2h,设备应在运行时通过 getToken 获取,不硬编码;
botId 可固化:botId 是设备身份,可安全固化。

10.4 设备分组与灰度发布

⚠ 本节待补充:灰度发布、设备分组、版本管理的具体平台能力与 JoyInside 团队对齐。以下为量产灰度建议框架。

分组建议

量产设备建议按以下维度分组管理:

维度	示例	用途
批次号	`BATCH-2026-07-001`	产线批次追溯、批次召回
产品型号	不同型号对应不同应用	型号隔离配置
灰度阶段	`canary` / `10%` / `100%`	灰度发布控制
地域	`cn-east` / `cn-north`	区域化运维

灰度发布建议

小批量灰度:新版本(固件 / 人设 / 技能配置)先在 1-5% 设备验证;
监控核心指标:WS 建联成功率、对话完成率、TTS 播放成功率、互踢率;
逐步放量:灰度无异常后逐步放量到 10% → 50% → 100%;
回滚预案:保留旧版本配置,异常时可快速切回。

10.5 量产 checklist

上线前

[ ] 测试设备(APP_ROBOT)已跑通(见第 3 章);
[ ] 切换为 PHYSICAL_ROBOT 生产设备;
[ ] 设备注册(单设备)调用通过,SN ↔ botId 一一对应(见 4.2);
[ ] token 过期验证通过(跨夜唤醒可正常对话,见 11.2);
[ ] botId 烧录到设备固件,SecretKey 未入设备;
[ ] 产测自检通过(见 12.1);
[ ] NTP 校准机制就绪(见 11.2);
[ ] Token 刷新机制就绪(见 12.1);
[ ] 心跳保活机制就绪(见 4.4 WebSocket语音通道 · 心跳保活)。

上线后

[ ] 核心指标监控就绪(见 11.4);
[ ] 灰度发布计划就绪;
[ ] 售后追溯链路(SN ↔ botId ↔ 批次)就绪;
[ ] 对接技术群与京东技术支持沟通渠道就绪。

下一步

量产设备运维:读第 11 章运维
上线验收:读第 12 章验收
接入材料清单:读附录 F

第 10 章 量产 ​

目录 ​

10.1 测试设备 → 生产设备(type 转换) ​

10.2 token 过期验证 ​

token 校验时机 ​

量产验证场景 ​

跨夜唤醒验证方法 ​

常见未处理好导致的故障 ​

10.3 产测烧录 ​

产测流程建议 ​

凭证安全 ​

10.4 设备分组与灰度发布 ​

分组建议 ​

灰度发布建议 ​

10.5 量产 checklist ​

上线前 ​

上线后 ​

下一步 ​