JoyInside 产品使用文档

主题

设备管理 ​

「设备管理」用于管理接入 JoyInside 平台的设备。每台设备在平台中有唯一记录,包含设备的身份信息、所属应用、音色配置等。

范围界定

这里管理的是端侧直接WS接入 JoyInside 的设备。其他 IoT 联动设备(小家 / 集贤)在对应的 IoT 平台中管理,不在此登记。

1. 设备与其他模块的关系 ​

平台侧的资源依赖链为「型号 → 应用 → 设备」三层:

型号库(定义产品是什么)
   ↓
产品管理(为这个产品配置智能体 AI 能力)
   ↓
设备管理(登记每一台具体的设备)

关键关系:

  • 一个型号可以对应多个应用(1:N)
  • 一个应用下可以有多台设备
  • 每台设备属于一个产品,拥有独立的设备 ID

详细型号定义与配置见 型号库,产品配置见 产品管理。

2. 两种设备类型 ​

类型说明如何创建
实体设备真实的硬件产品,出厂后通过接口自动注册通过接口自动创建(不支持手动创建)
虚拟设备用于开发调试的模拟设备支持在平台手动创建

重要区分

在设备管理页面手动点击「+ 新建」时,只能创建虚拟设备。正式的实体设备必须通过接口自动创建(即硬件设备首次联网时自动注册到平台)。

3. 新建虚拟设备 ​

手动新建虚拟设备时,需要填写:

配置项是否必填说明
类型必填固定选「虚拟设备」
所属应用必填该设备归属哪个应用(下拉选择已创建的应用)
名称必填设备名称,方便识别
SN 编码必填设备 ID 或序列号,用于唯一标识这台设备,不可重复
音色选填为该设备指定专属音色(即「设备音色」,详见 §5 设备音色 优先级说明)
描述选填补充说明

4. 设备列表字段说明 ​

字段说明
名称设备名称
应用名该设备所属的应用
应用 ID所属应用的唯一标识
ID(用于对话使用)系统自动生成的设备唯一 ID,调用对话接口时需传入此 ID
SN 编码设备序列号
类型实体设备 / 虚拟设备
音色该设备配置的专属音色
描述设备描述信息
创建人创建该设备记录的人
创建时间设备注册时间

SN 编码 vs ID vs 短码 —— 三种标识各司其职

  • SN 编码:由品牌方/厂商侧提供,相当于设备的「身份证号」,通常来自硬件出厂序列号;
  • ID(用于对话使用):平台自动生成的 32 位十六进制 botid,是平台内部的唯一标识,调用对话 API 时必须传入这个 ID(不是 SN);
  • 短码:7 位纯数字,与 botid 一对一绑定,用户按需触发生成(通过 设备码查询 系统指令),专门用于用户口述反馈问题;运营通过 §9 短码查询 反查设备。

5. 设备音色 —— 优先级最高之一 ​

在设备上配置的音色,就是音色四级优先级中的「设备音色」:

用户主动切换 > 设备音色 > 人设音色 > 应用音色

含义:如果您为某台设备单独配置了音色,该设备说话时会优先使用这个音色,而不是应用或人设中设置的默认音色。

典型场景:同一款产品的不同设备需要不同声音(比如「家庭版」用温柔女声,「儿童版」用活泼童声),即可在设备层做区分,而无需为每种声音单独建应用。

音色管理详见 音色库。

6. 调试说明 ​

创建虚拟设备后,可以在 产品管理 的预览调试窗口中进行对话测试。

调试对象可选:

调试对象支持范围使用方式
虚拟设备所有 IoT 平台的设备均支持直接选择平台创建的虚拟设备
真实设备小家 / 集贤 IoT 平台的设备支持输入真实设备的 device_id + token

真机联调说明

小家、集贤 IoT 平台的实体设备可通过 device_id + token 直连做真机联调;若尚未生产实体设备,或调试环境无法接入线上真机,统一走「虚拟设备」方式即可。

7. 典型使用场景 ​

场景说明
开发阶段调试创建虚拟设备,在产品管理智能体调试窗中测试对话效果
为特定设备定制音色在设备上配置专属音色,区别于其他同型号设备
批量设备管理通过应用筛选、SN 编码搜索,查看和管理所有已接入的设备
正式产品上线实体设备通过接口自动注册,无需手动逐台添加

8. 注意事项 ​

  1. 实体设备不能手动创建:页面上只能手动创建虚拟设备,正式设备需通过接口自动注册;
  2. SN 编码是设备的唯一标识:相当于设备的「身份证号」,不可重复;
  3. ID(用于对话使用)由平台生成:创建设备后自动分配,调用对话 API 时需要传入的是这个 ID,不是 SN;
  4. 设备音色是独立配置的:同一个应用下的不同设备可以设置不同的音色,优先级高于应用/人设级别。

9. 短码查询 —— 通过短码定位设备 ​

当用户反馈问题时,32 位十六进制的 botid 太长,用户根本记不住、也无法准确报出——运营侧可以让用户反馈 7 位数字短码,再通过设备管理页面的「短码查询」按钮一键反查该短码绑定的设备详情。

短码由用户主动向设备发问(如「我的设备编码是多少」「查一下设备码」)触发,由 设备码查询 系统指令生成并播报,与 botid 一对一永久绑定。

9.1 使用步骤 ​

  1. 进入【设备管理】页面,列表顶部找到「短码查询」按钮:

    短码查询入口

  2. 点击后弹窗提示输入短码,填入用户反馈的 7 位纯数字并确认:

    短码查询-输入弹窗

  3. 查询成功后展示该短码对应的设备详情——botid、所属应用、设备名称、SN 编码等,并可一键复制 botid:

    短码查询-结果弹窗

9.2 使用场景 ​

场景说明
用户反馈问题定位设备用户在电话/工单里反馈 7 位短码 → 运营输入 → 精准定位到具体设备与应用
售后排障收到设备异常反馈时,凭短码快速拉取该设备的所属应用、音色配置、SN 等上下文
多设备账号内定位同一账号下有多台设备时,凭短码直接定位到用户所指的具体那一台

9.3 注意事项 ​

  • 短码需要用户先在设备上触发过:短码是按需生成的,只有当用户对设备说过「设备码是多少」等触发语后才会存在;若查询提示"未找到对应设备",说明该设备尚未生成短码,请引导用户先向设备索要
  • 短码全局唯一:不会出现两台设备共用一个短码的情况;
  • 只能查看、不能修改:短码与 botid 的绑定关系不可通过运营侧修改,如需重置请联系平台管理员

10. 相关链接 ​