docs: Update PROJECT_PLAN.md - add face tracking, update Phase 14/17

PROJECT_PLAN.md

@@ -16,10 +16,11 @@
 2. **使用 Reachy Mini 原生硬件** - 使用机器人自带的麦克风和扬声器
 3. **Home Assistant 集中管理** - 所有配置在 Home Assistant 端完成
 4. **运动反馈** - 语音交互时提供头部运动和天线动画反馈
-5. 整个项目需要严格遵循 [Reachy Mini SDK](reachy_mini) 的架构设计与约束
-6. 严格遵循Python开发的标准，并做到代码风格一致，代码结构清晰，注释完整，文档完善，测试覆盖率高，代码质量高，代码可读性高，代码可维护性高，代码可扩展性高，代码可复用性高
-7. 与home assistant的语音对话为最高优先级，任何其它的功能都是辅助功能，不能影响语音对知的功能，响应速度
-8. LED都被隐藏在了机器人内部，所有的LED控制全部都忽略，不要使用LED控制
+5. **项目约束** - 整个项目需要严格遵循 [Reachy Mini SDK](reachy_mini) 的架构设计与约束
+6. **代码质量** - 严格遵循Python开发的标准，并做到代码风格一致，代码结构清晰，注释完整，文档完善，测试覆盖率高，代码质量高，代码可读性高，代码可维护性高，代码可扩展性高，代码可复用性高
+7. **功能优先级** - 与home assistant的语音对话为最高优先级，任何其它的功能都是辅助功能，不能影响语音对话的功能和响应速度
+8. **不调用任何LED功能** - LED都被隐藏在了机器人内部，所有的LED控制全部都忽略，不要使用LED控制
+9. **保留功能优先** - 任何代码修改都应该在保留已完成功能的前提下优化，不能以去除功能的方式来解决问题。当有问题发生时，应该充分参考案例之后以解决问题为优先级，而不是添加各种日志输出为优先级
 
 ## 技术架构
 
@@ -37,12 +38,18 @@
 │  └─────────────┘  └─────────────┘                          │
 │                                                             │
 │  ┌─────────────────────────────────────────────────────┐   │
-│  │ Motion Controller (Head + Antennas)                 │   │
-│  │ - on_wakeup: 点头确认                                │   │
-│  │ - on_listening: 注视用户                             │   │
-│  │ - on_thinking: 抬头思考                              │   │
-│  │ - on_speaking: 说话时微动                            │   │
-│  │ - on_idle: 返回中立位置                              │   │
+│  │ Camera + Face Tracking (YOLO)                       │   │
+│  │ - 15Hz 人脸检测与追踪                                │   │
+│  │ - look_at_image() 计算目标姿态                       │   │
+│  │ - 人脸丢失后平滑回中性位置                            │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Motion Controller (Head + Antennas) - 5Hz           │   │
+│  │ - Face tracking offsets (secondary pose)            │   │
+│  │ - Speech sway (语音驱动微动)                         │   │
+│  │ - Breathing animation (空闲呼吸)                     │   │
+│  │ - on_wakeup → on_listening → on_speaking → on_idle  │   │
 │  └─────────────────────────────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────┘
                               │
@@ -73,6 +80,8 @@
 - [x] 头部运动控制（点头、摇头、注视）
 - [x] 天线动画控制
 - [x] 语音状态反馈动作
+- [x] YOLO 人脸追踪（替代 DOA 声源定位）
+- [x] 5Hz 统一运动控制循环
 
 ### 应用架构
 - [x] 符合 Reachy Mini App 架构
@@ -86,12 +95,13 @@
 reachy_mini_ha_voice/
 ├── reachy_mini_ha_voice/
 │   ├── __init__.py             # 包初始化
-│   ├── __main__.py             # 命令行入口
+│   ├── __main__.py  py         # 命令行入口
 │   ├── main.py                 # ReachyMiniApp 入口
 │   ├── voice_assistant.py      # 语音助手服务
 │   ├── satellite.py            # ESPHome 协议处理
 │   ├── audio_player.py         # 音频播放器
-│   ├── camera_server.py        # MJPEG 摄像头流服务��
+│   ├── camera_server.py        # MJPEG 摄像头流服务器 + 人脸追踪
+│   ├── head_tracker.py         # YOLO 人脸检测器
 │   ├── motion.py               # 运动控制 (高层 API)
 │   ├── movement_manager.py     # 统一运动管理器 (20Hz 控制循环，优化以防止 daemon 崩溃)
 │   ├── models.py               # 数据模型
@@ -407,19 +417,56 @@ automation:
           option: "Happy"
 ```
 
-### Phase 14 - 智能声源追踪增强 (未实现) ❌
+### Phase 14 - 人脸追踪（替代 DOA 声源追踪）✅ **已完成**
 
-**目标**: 利用 DOA (Direction of Arrival) 实现更自然的声源追踪和多人对话支持。
+**目标**: 实现自然的人脸追踪，让机器人在对话时注视说话人。
 
-**当前实现**: ✅ 唤醒时转向声源 (`motion.py:on_wakeup()`)
-**未实现增强**:
+**设计决策**: 
+- ❌ 原计划使用 DOA (Direction of Arrival) 声源追踪
+- ✅ 改用 YOLO 人脸检测，更稳定、更准确
+- 原因：DOA 在唤醒时判断不够准确，且频繁查询会导致 daemon 崩溃
 
-| 功能 | 说明 | SDK API | 实现状态 |
+**已实现功能**:
+
+| 功能 | 说明 | 实现位置 | 实现状态 |
 |------|------|---------|---------|
-| 持续声源追踪 | 对话过程中持续跟踪说话人位置 | `media.get_DoA()` | ❌ 未实现 |
-| 多人对话切换 | 检测到新说话人时平滑转向 | `goto_target(head=..., method=MIN_JERK)` | ❌ 未实现 |
-| 声源可视化 | ~~LED 指示当前声源方向~~ | ~~`LED_DOA_COLOR` 参数~~ | ❌ 已取消（LED 不可见） |
-| 语音活动检测 | 只在检测到语音时追踪 | `DoAInfo.speech_detected` | ✅ 已暴露为实体 |
+| YOLO 人脸检测 | 使用 `AdamCodd/YOLOv11n-face-detection` 模型 | `head_tracker.py` | ✅ 已实现 |
+| 15Hz 人脸追踪 | 摄像头帧处理 + 人脸检测 | `camera_server.py` | ✅ 已实现 |
+| look_at_image() | 根据人脸位置计算目标姿态 | `camera_server.py` | ✅ 已实现 |
+| 平滑回中性位置 | 人脸丢失后 1 秒内平滑回归 | `camera_server.py` | ✅ 已实现 |
+| face_tracking_offsets | 作为 secondary pose 叠加到运动控制 | `movement_manager.py` | ✅ 已实现 |
+| 语音活动检测 | DOA 实体仍可用于检测语音 | `DoAInfo.speech_detected` | ✅ 已暴露为实体 |
+
+**代码位置**:
+- `head_tracker.py` - YOLO 人脸检测器 (`HeadTracker` 类)
+- `camera_server.py:_face_tracking_loop()` - 15Hz 人脸追踪循环
+- `movement_manager.py:set_face_tracking_offsets()` - 人脸追踪偏移量 API
+
+**技术细节**:
+```python
+# head_tracker.py - YOLO 人脸检测
+class HeadTracker:
+    def __init__(self):
+        self.model = YOLO("AdamCodd/YOLOv11n-face-detection")
+    
+    def detect_faces(self, frame) -> list[FaceDetection]:
+        # 返回检测到的人脸列表，包含 bbox 和置信度
+
+# camera_server.py - 人脸追踪循环
+async def _face_tracking_loop(self):
+    while self._running:
+        frame = self._reachy_controller.get_camera_frame()
+        faces = self._head_tracker.detect_faces(frame)
+        if faces:
+            # 选择最大/最近的人脸
+            target_u, target_v = faces[0].center
+            pose = self._reachy_controller.look_at_image(target_u, target_v)
+            self._motion.set_face_tracking_offsets(pose)
+        else:
+            # 平滑回归中性位置
+            self._motion.clear_face_tracking_offsets()
+        await asyncio.sleep(1/15)  # 15Hz
+```
 
 ### Phase 15 - 卡通风格运动模式 (部分实现) 🟡