# 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) 准备配置

复制配置模板：

```bash
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) 安装依赖

```bash
pip install -r requirements.txt
```

### 3) 编译 Rust 扩展（open_xiaoai_server）

推荐使用 maturin：

```bash
pip install maturin
maturin develop --release
```

### 4) 运行

```bash
python hass_assistant.py
```

## API 调用示例

### Home Assistant conversation.process（curl）

```bash
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 时）