aispea / cyberbase 设备接入
把现有 aispea/cyberbase 设备直接指向 Hearo——沿用其 MQTT 对话协议，由 mqtt-gateway 适配
如果你已有跑 cyberbase MQTT 对话协议的设备（/chat/<dev_id>/up|down、JSON||<opus>、连续 cloud-VAD），无需改固件：把卡片配置里的对话 MQTT 指向 Hearo 的 mqtt-gateway 即可。mqtt-gateway 内的 aispea 适配器会把该协议翻译到 Hearo 的房间 + AI 智能体（ASR→LLM→TTS）。
💡 先读统一模型：客户端 Token / 设备接入密码的签发、API Key、房间分配（client→room）集中在 客户端与接入模型。本页是 aispea/cyberbase 兼容协议（连续 cloud-VAD 对话、JSON||opus 帧）的具体接入；它正是统一模型在 MQTT 上的推荐形态（凭据鉴权 + client→room 实时切房）。
1. 把设备指向 Hearo（CONNECT 鉴权）
设备的卡片/产品配置里，把对话 MQTT 字段改为 Hearo 部署：
| 字段 | 说明 |
|---|---|
| mqtt_chat_broker | 124.174.6.145（本部署的 mqtt-gateway） |
| mqtt_chat_port | 2883 |
| mqtt_chat_password | 推荐：设备接入密码（hkd_ 开头的短密码，控制台 → 设备 页生成/复制，可随时重置）；也可用客户端 Token（JWT，较长，注意固件密码字段长度） |
| mqtt_chat_username | 用设备接入密码时任意（建议 deviceId）；用 Token 时留空或与 Token 的 sub（clientId）一致 |
| chat_sequential | true（连续 cloud-VAD 对话） |
Client ID 沿用 chat_<dev_id>；topic 沿用 /chat/<dev_id>/up 与 /chat/<dev_id>/down——适配器按 topic 里的 <dev_id> 识别设备（与 MQTT Client ID 无关）。进入哪个房间由设备的房间绑定决定（见第 3 节）。协议逐字段细节见仓库 docs/aispea-mqtt-protocol.md。
2. 对话时序（适配器已实现）
设备 -> 后端 session.update(cloud_vad=1, conversation_id=A)
后端 -> 设备 session.updated(A) # 适配器进房（+ 房间默认 AI 自动就位）
设备 -> 后端 input_audio_buffer.append||opus # 持续上行
后端 -> 设备 input_audio_buffer.speech_start(A)
后端 -> 设备 input_audio_buffer.speech_stopped(A)
后端 -> 设备 response.asr.result(text=..., A)
后端 -> 设备 response.text(..., A) # 可多条
后端 -> 设备 response.audio||opus(A) # 多条，16k 单声道 Opus（60ms/帧）
后端 -> 设备 response.audio.done(vad_off=false, A)已映射的事件
| 设备事件 | 适配器行为 | |
|---|---|---|
| session.update | → | 进入绑定的房间（未绑定则私有房 aispea-<dev_id>）；回 session.updated。同房间重复发送只刷新会话，不重进房 |
| input_audio_buffer.append||opus | → | 解 Opus → 进房（喂 AI 的 ASR/VAD） |
| （AI 识别中） | → | speech_start / speech_stopped / response.asr.result |
| （AI 回复） | → | response.text + response.audio||opus + response.audio.done |
| input_audio_buffer.clear | → | 打断当前回复 + 回 input_audio_buffer.cleared |
| input_audio_buffer.commit | → | 回 input_audio_buffer.committed（PTT 兼容） |
| （空闲超时，可选） | → | session.clear（设了 HEARO_AISPEA_IDLE_SEC 时；默认关闭） |
| （设备未登记） | → | {"type":"error","error":"device_not_registered"} |
音频编码默认 Opus 16k 单声道（input_audio_format/output_audio_format 填 pcm 系列值可切 PCM）；下行按 60ms 一帧发送，匹配设备的播放缓冲。
3. 设备入库与房间（设备→房间）
设备必须先在设备管理入库（控制台 → 设备，或运营中心 → 设备管理）才允许接入，未入库一律拒绝（收到 device_not_registered 错误）。每台设备有一个房间号：连接时按 deviceId 解析到它的房间，改绑定实时生效（在线秒切，无需重连）。
| 房间号 | 效果 | 说明 |
|---|---|---|
| 留空 | 私有房 | 该设备独享房间 aispea-<dev_id>（一对一对话） |
| 多台填同一房间号 | 群聊 / 通话 | 这些设备进入同一房间、实时互通 |
要让 A、B 两台设备通话，把它们的房间号都设成同一个值（如 call-1）即可——无需配对接口，改设备的房间号就是路由。改绑定用控制台「房间 / 分组」页或 PATCH /api/v1/clients/{id}（见 REST API）。
4. AI 配置
推荐给房间配置默认智能体（房间与分组）：任何设备进入该房间，AI 自动就位、空闲自动撤走；智能体的提示词 / Provider / 音色在「智能体管理」里配。私有房场景给设备的私有房间登记默认智能体即可。另有开关 HEARO_AISPEA_IDLE_SEC（静默 N 秒后自动结束会话，默认关闭）。请确保所选厂商可用，否则 AI 不会出声。
5. 联调
任何标准 MQTT 客户端都可模拟设备联调。先在设备管理登记 testdev01 并复制它的设备接入密码，然后用 mosquitto 观察下行：
# 订阅下行（观察 session.updated / response.* 事件）
mosquitto_sub -h 124.174.6.145 -p 2883 -u testdev01 -P 'hkd_...' \
-i chat_testdev01 -t '/chat/testdev01/down' -v
# 发起会话（另开一个终端）
mosquitto_pub -h 124.174.6.145 -p 2883 -u testdev01 -P 'hkd_...' \
-i chat_testdev01_pub -t '/chat/testdev01/up' \
-m '{"type":"session.update","session":{"conversation_id":"test-1"}}'音频上行是 JSON头||Opus包 的二进制拼接，脚本化联调建议用任意 MQTT 库照 docs/aispea-mqtt-protocol.md 组包；端到端验证最直接的方式是用一台真实设备，或在控制台房间的「演示」页与设备同房间对话。