dsh-aiui

讯飞语音背包（iFlytek AIUI 语音背包 / ZC-H358S）DSH 插件：把背包的语音识别、语义理解与机器人运动控制封装为 7 个 agent 工具。

协议实现依据 TcpDemo_1.3.0 内 UARTKit 源码逐字节还原，并经真机联调验证（完整过程见工作区《分析报告-语音控制机器人.md》）。

接口一览（4 层 7 工具）

层	工具	作用
连接层	aiui_status	连接背包，返回设备信息（唤醒词/端口/版本）、speech/mmsp 参数、健康度
连接层	aiui_config	查询/下发 speech 运行参数（固件可能强制覆盖，工具内已说明）
语音层	aiui_listen	监听 N 秒语音：唤醒、识别文本、AiChain 大模型回答（可先 TTS 提示）
语音层	aiui_say	TTS 播报一句话（经典云 TTS 通道；AiChain 应答播报由设备端自动完成）
语音层	aiui_control	远程唤醒 / 休眠 / 停止播报 / 查询状态机
控制层	aiui_motion	机器人运动：forward/backward/left/right/stop（webhook 转发或模拟）
运维层	aiui_device	网络诊断、引擎日志、禁用/恢复厂商演示程序（经网络 ADB + adbutils）

典型用法

用户：你听一下背包说什么
agent：→ aiui_listen { seconds: 20, prompt: "请说指令" }
       ← 识别：「向前走」 / 语义答「2 times 6 equals 12.」
agent：→ aiui_motion { action: "forward", seconds: 2 }

唤醒词 「小飞小飞」，休眠词 「休眠一下」。唤醒后背包进入"工作中"才接受指令。

配置项

键	默认	说明
host	192.168.0.153	背包 IP
port	19199	AIUI 控制通道（单会话，后被连者踢前者）
adbSerial	192.168.0.153:5555	网络 ADB（aiui_device 用）
motionWebhookUrl	空	运动 HTTP 转发（POST JSON {action,seconds,vx,wz,…}）；留空=模拟
autoMotion	true	语音说"向前走/停"等自动转发运动指令
maxListenSeconds	120	aiui_listen 上限
adbTimeoutMs	30000	aiui_device 单次 ADB 操作超时（超时杀整棵进程树）
autoReconnect	true	断线自动重连（含 5s 心跳、12s 静默重连）

底盘接入

把底盘控制做成一个 HTTP 服务，配置 motionWebhookUrl 即可：

// 示例（Node）：接收 dsh-aiui 的运动指令 → 转成你的底盘协议
http.createServer((req, res) => {
  let body = ''
  req.on('data', c => body += c)
  req.on('end', () => {
    const { action, seconds, vx, wz } = JSON.parse(body)
    // ROS: 发布 geometry_msgs/Twist(linear.x=vx, angular.z=wz) 到 /cmd_vel
    // 串口底盘: 发运动帧；持续 seconds 后自动停
    res.end('ok')
  })
}).listen(8266)

已知固件行为（真机实测）

• 本批固件走 AiChain 全双工云管线（云端 STT + 大模型 NLU + TTS），work_mode 被引擎强制 rec_only，经典 iat/nlp 事件基本不再出现；上位机收到的是 iat_aichain / nlp_aichain / tts 事件
• 唤醒后"秒睡" = 背包外网不通/弱网（云端 WebSocket 建不起来），可用 aiui_device check_net 诊断；建议给背包插网线
• 19199 单会话互斥：厂商演示程序会抢占连接并回滚配置，可 aiui_device disable_demo 禁用（enable_demo 恢复）
• 引擎 com.iflytek.aiuiservice 与协议桥 com.iflytek.aiui.devboard.uartservice 勿停

依赖

• 宿主：@deepseek-ai/dsh-tools、@deepseek-ai/schemastery（peer，随宿主/profile 安装）
• aiui_device：本机 python + adbutils（pip install adbutils），无需 adb 可执行文件

离线/断连时的行为

背包未连接（关机、换网段、19199 被演示程序占用）时，语音类工具都会快速返回 ok:false 与可读提示，不会挂起：

• aiui_status / aiui_listen / aiui_say / aiui_control / aiui_config：连接或握手失败立即返回，提示检查 IP、网段与会话占用
• aiui_device：先做 ADB 端口预检（1.5s 超时），不可达直接返回，不拉起 python/adb 服务
• 断线自动重连为退避重试：1.5s → 2.4s → 3.8s → … → 15s 封顶，连上即复位
• aiui_motion 与背包无关：未配置 motionWebhookUrl 时只做模拟执行

自检与测试

npm test                 # 协议单测 + 宿主契约/离线测试（不需要背包）
npm run test:protocol    # 帧编解码与事件解析（以真机抓包字节为基准向量）
npm run test:contract    # 用宿主真实 defineTool 加载插件 + 离线降级 + webhook 转发
npm run smoke            # 真机烟雾测试（需背包在线，可传 IP 参数）

已知环境坑（本机 Windows 实测）

• Node fs.cpSync 与中文路径：目标路径含中文时静默不复制；源路径含中文时直接崩进程（exit 127）。测试脚手架因此改用手写 copyTree，插件运行时不受影响
• webhook 用 node:http 而非全局 fetch：避免 undici 保活 socket 在进程退出时触发 libuv 断言崩溃
• 本机 CLI 直接 dsh web 起不来（应用内置 node shim 在应用外无法执行），插件加载验证请以 DSH Desktop 实际启动为准

License

MIT