open-xiaoai/examples/hass/README.md

Open-XiaoAI x Home Assistant Assist

该示例用于将小爱音箱接入 Home Assistant 的对话/语音助手能力，支持文本对话与上下文会话，并提供可选的语音输入管线对接能力。

功能说明

• 文本对话：对接 Home Assistant conversation.process API，支持自然语言控制设备/查询信息
• 实时打断：接收到新用户消息时先中断当前播报，再处理新输入，避免并发播报
• 连续对话会话管理：默认开启连续对话；当命中结束词或语音静默超时时自动结束并重建 conversation_id
• 区域上下文注入：支持客户端 IP 到 Home Assistant 区域映射，命中后在每次请求前注入区域前置提示词
• 小爱音箱 I/O：从小爱音箱事件中提取最终识别文本（ASR），将回复通过小爱本机 TTS 播放
• 可选音频能力（扩展点）：支持接收小爱录音流 record，用于后续对接 Assist pipeline（STT→Intent→TTS）

使用场景

• 用中文/英文自然语言控制 Home Assistant：开灯、关灯、调亮度、问温度/天气、查询传感器状态
• 把小爱音箱作为 Home Assistant 的“外置麦克风 + 扬声器”（局域网内运行）

架构概览

• 小爱音箱 →（WebSocket 4399）→ Rust 网关（open_xiaoai_server）→ Python 回调
• 文本链路（默认，低延迟）：
  • 设备事件 instruction/NewLine → 抽取 SpeechRecognizer.RecognizeResult 文本
  • 调用 HA /api/conversation/process
  • 把返回的 response.speech.plain.speech 交给小爱 TTS 播报

目录结构

本目录包含：

• hass_assistant.py：主入口
• config.example.json：配置模板
• requirements.txt：Python 依赖
• src/：Rust(PyO3) 扩展模块（小爱音箱 I/O 网关）
• hass/：Python 实现（HA 客户端、对话编排、上下文记忆）
• tests/：单元测试
• scripts/：集成测试脚本

安装与运行

前置条件

• 你的小爱音箱已刷机并运行 Rust 客户端补丁（否则服务端收不到事件/音频流）
• Home Assistant 已启用 conversation（默认配置一般已启用）并生成 Long-Lived Access Token
• 本机具备 Python（建议 3.10+）与 Rust 工具链（用于编译 PyO3 扩展）
• 可选：如果你希望使用 webrtcvad（更好的语音端点检测），Windows 需要安装 MSVC Build Tools

1) 准备配置

复制配置模板：

cd examples/hass
cp config.example.json config.json

编辑 config.json：

• homeassistant.url：HA 地址（例如 http://192.168.1.10:8123）
• homeassistant.access_token：HA Long-Lived Access Token
• homeassistant.assistant_entity_id：对话助理 ID（对应 agent_id，默认 home_assistant）

配置新增项说明

xiaoai 段新增以下关键配置：

• interrupt_on_new_input：是否在收到新消息时立即执行打断，默认 true
• interrupt_command：打断命令，默认使用 ubus call mibrain ai_service 触发中断
• continuous_conversation_enabled：是否开启连续会话，默认 true
• session_idle_timeout_seconds：连续会话静默超时秒数，默认 15
• session_end_keywords：结束词列表，默认包含 再见 拜拜 滚 退下，按包含匹配
• client_ip_area_mapping：客户端 IP 到区域名称映射，仅在命中时注入区域提示词

区域提示词注入内容为：

当前用户对话所在区域：<区域名称>，如后续对话未明确指定区域，则默认为此区域

2) 安装依赖

pip install -r requirements.txt

3) 编译 Rust 扩展（open_xiaoai_server）

推荐使用 maturin：

pip install maturin
maturin develop --release

4) 运行

python hass_assistant.py

API 调用示例

Home Assistant conversation.process（curl）

curl -X POST \
  -H "Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  http://HOME_ASSISTANT:8123/api/conversation/process \
  -d '{"text":"打开客厅灯","language":"zh-cn","agent_id":"home_assistant"}'

Python 调用（不连接小爱，仅验证 HA）

可参考 scripts/integration_text.py。

故障排除

• 401/403：检查 access_token 是否正确、是否完整复制
• 连接超时：检查 homeassistant.url 是否可达、是否被防火墙/反代阻断
• 无语音输入：确认小爱已运行客户端补丁且能连到本机 4399 端口
• 无语音输出：确认小爱系统 ubus/mibrain 可用（或改用 play_url 播放 URL）
• 对话不连贯：确认 state.json 能写入（用于持久化 conversation_id），或删除它重置会话
• 打断不生效：检查 xiaoai.interrupt_command 是否可在设备上执行，以及日志中是否出现 xiaoai_interrupt_failed
• 区域提示词未注入：检查 client_ip_area_mapping 是否包含当前客户端 IP，并查看 area_mapping_hit/area_mapping_miss 日志

部署说明

• 建议仅在局域网内部署运行，避免将 4399 暴露到公网
• 如果 HA 与运行本示例的机器不在同一网段，确保 HA 的 URL 在设备侧可访问（尤其是播放 URL 时）