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 状态: 已批准