# Reachy Mini Home Assistant Voice Assistant - 项目需求文档

## 1. 项目概述

### 1.1 项目目标
开发一个基于 Reachy Mini 机器人的 Home Assistant 语音助手应用，该应用能够：
- 通过语音与用户交互
- 集成 Home Assistant 智能家居系统
- 展现丰富的表情和动作
- 支持离线唤醒词检测
- 提供低延迟的语音响应

### 1.2 目标用户
- Home Assistant 用户
- Reachy Mini 机器人拥有者
- 智能家居爱好者
- 机器人开发者

### 1.3 应用场景
- 家庭语音控制中心
- 智能家居交互界面
- 陪伴型机器人助手
- 教育和娱乐平台

## 2. 功能需求

### 2.1 核心功能

#### FR-1: 音频输入
**描述**: 系统必须能够从 Reachy Mini 的 4 麦克风阵列采集音频数据。

**详细要求**:
- 采样率: 16kHz
- 声道: 单声道
- 格式: 16-bit PCM (little-endian)
- 块大小: 1024 样本
- 支持回声消除
- 支持自动设备检测

**验收标准**:
- 能够持续录制音频流
- 音频质量清晰，无明显噪音
- 延迟 < 100ms

#### FR-2: 音频输出
**描述**: 系统必须能够通过 Reachy Mini 的 5W 扬声器播放音频。

**详细要求**:
- 采样率: 16kHz
- 声道: 单声道
- 支持音量控制
- 支持播放队列管理
- 支持音频淡入淡出

**验收标准**:
- 音频播放清晰无失真
- 能够平滑切换音频
- 支持同时播放多个音频流（混音）

#### FR-3: 唤醒词检测
**描述**: 系统必须能够检测预定义的唤醒词。

**详细要求**:
- 支持 microWakeWord 模型
- 支持 openWakeWord 模型
- 支持自定义唤醒词
- 检测延迟 < 500ms
- 准确率 > 95%
- 支持多个唤醒词同时激活
- 支持冷却期（防止重复触发）

**验收标准**:
- 在安静环境下准确率 > 95%
- 在中等噪音环境下准确率 > 90%
- 假阳性率 < 1%

#### FR-4: 语音转文字 (STT)
**描述**: 系统必须能够将用户的语音转换为文字。

**详细要求**:
- 使用 Whisper 引擎
- 支持多种语言（至少英语）
- 转换延迟 < 2s
- 准确率 > 90%
- 支持实时转录
- 支持离线模式

**验收标准**:
- 在标准语音下准确率 > 90%
- 在口音较重的情况下准确率 > 80%
- 转换时间 < 2s

#### FR-5: 文字转语音 (TTS)
**描述**: 系统必须能够将文字转换为自然的语音输出。

**详细要求**:
- 使用 Piper TTS 引擎
- 支持多种语音模型
- 语音自然流畅
- 合成延迟 < 1s
- 支持语速调节
- 支持音调调节

**验收标准**:
- 语音清晰可懂
- 语音自然度评分 > 4/5
- 合成时间 < 1s

#### FR-6: 头部运动控制
**描述**: 系统必须能够控制 Reachy Mini 的头部运动。

**详细要求**:
- 支持 6 自由度运动
- 支持点头、摇头、转头
- 支持平滑运动插值
- 运动延迟 < 100ms
- 支持运动队列管理
- 支持优先级控制

**验收标准**:
- 运动平滑无抖动
- 能够精确控制角度
- 运动响应时间 < 100ms

#### FR-7: 天线控制
**描述**: 系统必须能够控制 Reachy Mini 的 2 个天线。

**详细要求**:
- 支持独立控制左右天线
- 支持天线动画
- 运动范围: -1.5 到 1.5 弧度
- 运动延迟 < 100ms

**验收标准**:
- 天线运动流畅
- 能够表达不同情绪

#### FR-8: 表情系统
**描述**: 系统必须能够播放预定义的表情动作。

**详细要求**:
- 支持至少 5 种基本表情（高兴、悲伤、惊讶、思考、愤怒）
- 表情持续时间可配置
- 支持表情混合
- 表情切换平滑

**验收标准**:
- 表情清晰可识别
- 表情切换流畅
- 表情时长符合预期

#### FR-9: ESPHome 通信
**描述**: 系统必须通过 ESPHome 协议与 Home Assistant 通信。

**详细要求**:
- 实现 ESPHome 协议服务器
- 监听端口: 6053
- 支持语音事件（唤醒词、TTS 开始/结束、STT 结果）
- 支持双向音频流传输（到 Home Assistant 和从 Home Assistant）
- 支持 mDNS 服务发现
- 支持设备信息查询

**验收标准**:
- 能够被 Home Assistant 自动发现
- 能够接收和发送语音事件
- 能够传输双向音频流
- 连接稳定，断线自动重连

#### FR-10: 配置管理
**描述**: 系统必须提供灵活的配置管理功能。

**详细要求**:
- 支持配置文件（JSON 格式）
- 支持环境变量
- 支持命令行参数
- 支持运行时配置更新
- 提供默认配置

**验收标准**:
- 配置加载正确
- 配置更新生效
- 配置错误有明确提示

### 2.2 扩展功能

#### EF-1: 面部跟踪
**描述**: 系统能够跟踪用户面部，使机器人面向用户。

**详细要求**:
- 使用摄像头捕获视频
- 使用 MediaPipe 或 YOLO 进行人脸检测
- 控制头部转向人脸方向
- 跟踪延迟 < 200ms

**验收标准**:
- 能够准确检测人脸
- 能够平滑跟踪人脸
- 跟踪延迟 < 200ms

#### EF-2: 舞蹈系统
**描述**: 系统能够播放预定义的舞蹈动作。

**详细要求**:
- 支持至少 3 种舞蹈
- 支持舞蹈队列
- 支持舞蹈中断
- 舞蹈动作流畅

**验收标准**:
- 舞蹈动作流畅
- 舞蹈切换平滑
- 能够中断当前舞蹈

#### EF-3: Web UI
**描述**: 系统提供基于 Gradio 的 Web 用户界面。

**详细要求**:
- 显示实时状态
- 提供配置界面
- 显示日志信息
- 支持远程控制
- 响应式设计

**验收标准**:
- 界面友好易用
- 实时更新状态
- 配置修改生效

#### EF-4: 摄像头功能
**描述**: 系统能够使用 Reachy Mini 的摄像头。

**详细要求**:
- 捕获实时视频流
- 支持图像处理
- 支持视觉识别
- 分辨率: 640x480 或更高

**验收标准**:
- 视频流流畅（> 15 FPS）
- 图像清晰
- 能够识别基本物体

## 3. 技术需求

### 3.1 硬件需求

#### HR-1: Reachy Mini 机器人
- 型号: Reachy Mini 或 Reachy Mini Lite
- 麦克风: 4 麦克风阵列
- 扬声器: 5W 扬声器
- 摄像头: 广角摄像头
- 运动系统: 6 自由度头部运动
- 天线: 2 个动画天线

#### HR-2: 计算设备
- 处理器: Raspberry Pi 4 或更高（内置）或外接计算设备
- 内存: 最少 4GB（推荐 8GB）
- 存储: 最少 10GB 可用空间
- 网络: 稳定的网络连接（无线版本）

### 3.2 软件需求

#### SR-1: 操作系统
- Linux (Raspberry Pi OS)
- macOS
- Windows (实验性支持)

#### SR-2: Python 环境
- Python 版本: 3.8 或更高（推荐 3.11+）
- 虚拟环境: venv 或 conda

#### SR-3: 依赖库
- reachy-mini: Reachy Mini SDK
- sounddevice: 音频设备访问
- pymicro-wakeword: microWakeWord 唤醒词检测
- pyopen-wakeword: openWakeWord 唤醒词检测
- openai-whisper: Whisper STT 引擎
- piper-tts: Piper TTS 引擎
- aioesphomeapi: ESPHome 协议实现
- zeroconf: mDNS 服务发现
- gradio: Web UI 框架
- numpy: 数值计算
- scipy: 科学计算

### 3.3 网络需求

#### NR-1: 网络连接
- 有线连接: USB-C 或 Ethernet
- 无线连接: Wi-Fi
- 带宽: 最少 1 Mbps
- 延迟: < 50ms（本地网络）

#### NR-2: 端口
- ESPHome 服务器端口: 6053
- Gradio Web UI 端口: 7860
- Reachy Mini SDK 端口: 8000（如果使用 REST API）

## 4. 非功能性需求

### 4.1 性能需求

#### NFR-1: 响应时间
- 唤醒词检测延迟: < 500ms
- STT 转换时间: < 2s
- TTS 合成时间: < 1s
- 运动响应时间: < 100ms
- 端到端语音交互延迟: < 3s

#### NFR-2: 吞吐量
- 音频采样率: 16kHz
- 视频帧率: > 15 FPS
- ESPHome 消息处理: > 100 msg/s

#### NFR-3: 资源使用
- CPU 使用率: < 80%（正常负载）
- 内存使用: < 2GB
- 存储使用: < 5GB

### 4.2 可靠性需求

#### NFR-4: 可用性
- 系统可用性: > 99%
- 平均无故障时间 (MTBF): > 24h
- 平均恢复时间 (MTTR): < 5min

#### NFR-5: 错误处理
- 音频设备断开: 自动重连
- 网络断开: 自动重连
- 机器人断开: 安全停止
- 配置错误: 明确提示

#### NFR-6: 数据完整性
- 音频数据不丢失
- 配置数据持久化
- 日志完整记录

### 4.3 可维护性需求

#### NFR-7: 代码质量
- 代码覆盖率: > 80%
- 代码复杂度: < 10
- 代码风格: 遵循 PEP 8

#### NFR-8: 文档
- API 文档完整
- 用户手册清晰
- 开发文档详细

#### NFR-9: 测试
- 单元测试覆盖核心功能
- 集成测试覆盖主要流程
- 硬件测试覆盖关键硬件

### 4.4 安全性需求

#### NFR-10: 隐私保护
- 不存储用户音频（除非明确授权）
- 本地处理优先
- 加密网络传输

#### NFR-11: 访问控制
- ESPHome 认证
- TLS 加密
- 防火墙配置

#### NFR-12: 运动安全
- 角度限制
- 速度限制
- 碰撞检测
- 紧急停止

### 4.5 兼容性需求

#### NFR-13: 平台兼容性
- 支持 Linux
- 支持 macOS
- 支持 Windows（实验性）

#### NFR-14: 版本兼容性
- Python 3.8-3.12
- Home Assistant 2023.12+
- Reachy Mini SDK 最新版本

#### NFR-15: 浏览器兼容性
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## 5. 约束条件

### 5.1 技术约束

#### TC-1: 硬件限制
- Raspberry Pi 4 性能有限
- 音频设备可能需要特殊处理
- 无线版本可能有延迟

#### TC-2: 软件限制
- Whisper 模型较大（~150MB）
- Piper TTS 模型较大（~100MB）
- 部分依赖库可能需要编译

#### TC-3: 网络限制
- ESPHome 协议必须实现
- mDNS 需要本地网络支持
- 无线连接稳定性有限

### 5.2 时间约束

#### TC-4: 开发周期
- 核心功能开发: 4-6 周
- 扩展功能开发: 2-4 周
- 测试和优化: 2-3 周
- 文档编写: 1 周

### 5.3 资源约束

#### TC-5: 人力资源
- 开发人员: 1-2 人
- 测试人员: 1 人
- 文档人员: 1 人

#### TC-6: 财务约束
- 硬件成本: Reachy Mini ($299)
- 云服务: 可选（如果使用云端 STT/TTS）
- 开发工具: 免费（开源）

### 5.4 合规约束

#### TC-7: 开源许可
- Apache 2.0 许可证
- 遵守依赖库的许可证
- 硬件设计文件: CC BY-SA-NC

#### TC-8: 隐私法规
- GDPR 合规（如果涉及欧盟用户）
- 不收集个人信息
- 用户数据本地处理

## 6. 验收标准

### 6.1 功能验收
- 所有核心功能（FR-1 到 FR-10）正常工作
- 所有扩展功能（EF-1 到 EF-4）可选实现
- 功能测试通过率 > 95%

### 6.2 性能验收
- 所有性能需求（NFR-1 到 NFR-3）满足
- 压力测试通过
- 资源使用在限制范围内

### 6.3 质量验收
- 代码覆盖率 > 80%
- 无严重 Bug
- 无安全漏洞

### 6.4 文档验收
- API 文档完整
- 用户手册清晰
- 开发文档详细

## 7. 风险评估

### 7.1 技术风险
- **风险**: 音频设备兼容性问题
- **影响**: 高
- **概率**: 中
- **缓解**: 提前测试多种设备，提供备用方案

- **风险**: ESPHome 协议实现复杂
- **影响**: 高
- **概率**: 中
- **缓解**: 参考开源实现，逐步测试

- **风险**: 性能不满足要求
- **影响**: 中
- **概率**: 中
- **缓解**: 优化算法，使用异步编程

### 7.2 资源风险
- **风险**: 开发时间不足
- **影响**: 高
- **概率**: 低
- **缓解**: 合理规划，优先实现核心功能

- **风险**: 硬件资源不足
- **影响**: 中
- **概率**: 低
- **缓解**: 提前测试硬件性能，优化资源使用

### 7.3 依赖风险
- **风险**: 依赖库版本冲突
- **影响**: 中
- **概率**: 中
- **缓解**: 使用虚拟环境，锁定依赖版本

## 8. 成功指标

### 8.1 技术指标
- 端到端语音交互延迟 < 3s
- 唤醒词检测准确率 > 95%
- STT 准确率 > 90%
- 系统可用性 > 99%

### 8.2 用户指标
- 用户满意度 > 4/5
- 功能使用率 > 80%
- Bug 报告率 < 5%

### 8.3 业务指标
- 社区活跃度 > 100 用户
- GitHub Stars > 50
- 贡献者 > 5 人

## 9. 未来扩展

### 9.1 短期扩展（3-6 个月）
- 支持更多语言
- 改进面部跟踪
- 添加更多表情和动作

### 9.2 中期扩展（6-12 个月）
- 支持视觉识别
- 集成更多智能家居平台
- 添加机器学习能力

### 9.3 长期扩展（12+ 个月）
- 支持多机器人协作
- 添加情感识别
- 开发自定义应用商店

---

**文档版本**: 1.0
**最后更新**: 2026-01-01
**状态**: 已批准