sprint3

sprint3/sprint3.md

@@ -0,0 +1,146 @@
+# Sprint 3 技术文档
+
+**识别到控制闭环打通 + 支持游戏操作**
+
+------
+
+## 一、概述
+
+本阶段实现了一个运行于浏览器端的手势识别系统，结合 MediaPipe 和 WebSocket，打通从摄像头手势识别 → 系统控制（鼠标、滚动、键盘） → 控制小游戏角色的全流程。
+
+新增支持多种系统控制动作和游戏动作，包括：左右移动、跳跃、组合跳跃等。
+
+------
+
+## 二、模块结构概览
+
+模块分工如下：
+
+- **Detector.ts**
+   加载并初始化 MediaPipe 手势模型，检测手部关键点与手势状态，并调用 `GestureHandler`。
+- **GestureHandler.ts**
+   将识别出的手势映射为系统操作（鼠标、滚动、键盘指令等），支持连续确认、平滑处理、动作节流。
+- **TriggerAction.ts**
+   封装 WebSocket 通信，向后端发送 JSON 格式的控制命令。
+
+```
+[摄像头视频流]
+     ↓
+[VideoDetector.vue]
+  - 捕捉视频帧
+  - 显示实时画面
+     ↓
+[Detector.ts]
+  - 使用 MediaPipe Tasks WASM 模型进行手势识别
+  - 返回关键点、手势类型
+     ↓
+[GestureHandler.ts]
+  - 将识别结果转为行为
+  - 识别特定组合，如食指 + 拇指 → 滚动
+     ↓
+[TriggerAction.ts]
+  - 向 WebSocket 发送控制指令
+  - 控制鼠标/键盘/后端动作
+     ↓
+[后端 Python]
+  - WebSocket 接口接收指令
+  - 准备语音接口/控制中枢
+
+```
+
+------
+
+## 三、识别手势说明（扩展后）
+
+每帧识别手指竖起状态（拇指到小指，0 或 1），组合为状态串，查表识别对应手势：
+
+| 状态串      | 手势名              | 动作描述                  |
+| ----------- | ------------------- | ------------------------- |
+| `0,1,0,0,0` | only_index_up       | 鼠标移动                  |
+| `1,1,0,0,0` | index_and_thumb_up  | 鼠标点击                  |
+| `0,0,1,1,1` | scroll_gesture_2    | 页面滚动                  |
+| `1,0,1,1,1` | scroll_gesture_2    | 页面滚动（兼容变体）      |
+| `0,1,1,1,1` | four_fingers_up     | 发送快捷键（如播放/全屏） |
+| `1,1,1,1,1` | stop_gesture        | 暂停/开始识别             |
+| `1,0,0,0,1` | voice_gesture_start | 启动语音识别              |
+| `0,0,0,0,0` | voice_gesture_stop  | 停止语音识别              |
+| `0,1,1,0,0` | jump                | 小人跳跃（上键）          |
+| `1,1,1,0,0` | rightjump           | 小人右跳（右+上组合）     |
+| 自定义判断  | direction_right     | 小人右移（长按右键）      |
+| 自定义判断  | delete_gesture      | 小人左移（长按左键）      |
+
+
+
+------
+
+## 四、控制行为逻辑说明
+
+### 鼠标控制
+
+- **移动**：基于食指指尖位置映射至屏幕坐标，支持平滑处理，减少抖动。
+- **点击**：食指与拇指同时上举，节流处理防止重复点击。
+- **滚动**：捏合（拇指+食指）后上下移动控制滚动方向，带阈值判断。
+
+### 快捷键/系统操作
+
+- 四指上举 → 发送自定义按键（如全屏、暂停、下一集等）。
+- 五指上举 → 暂停/开始识别。支持进度提示。
+- 删除手势（右手拇指伸出，其余收起）→ 连续发送 Backspace/方向键。
+- 自定义 holdKey 方法支持模拟长按。
+
+### 游戏控制扩展（键盘模拟）
+
+| 手势名          | 动作                 |
+| --------------- | -------------------- |
+| delete_gesture  | 向左移动（左键长按） |
+| direction_right | 向右移动（右键长按） |
+| jump            | 向上跳跃（上键）     |
+| rightjump       | 右跳（右后延迟上）   |
+
+
+
+------
+
+## 五、性能与稳定性处理
+
+| 问题               | 解决方案                                               |
+| ------------------ | ------------------------------------------------------ |
+| 手势误判           | 连续帧确认（minGestureCount ≥ 5）                      |
+| 鼠标抖动           | 屏幕坐标引入平滑系数 `smoothening`                     |
+| 动作重复触发       | 节流控制点击/滚动/快捷键/方向键（如 `CLICK_INTERVAL`） |
+| WebSocket 中断重连 | 异常断线后自动重连，带重试时间间隔                     |
+| 滚动误触           | 拇指与食指距离阈值控制是否处于“捏合”状态               |
+| UI 状态提示不同步  | 使用全局 store（如 `app_store.sub_window_info`）更新   |
+
+
+
+------
+
+## 六、技术特性总结
+
+- 支持 MediaPipe WASM 模型在前端本地运行，低延迟识别
+- 所有动作模块化封装，便于未来扩展新手势、新控制指令
+- 手势控制与后端通过 WebSocket 实时交互，接口稳定
+- 支持游戏场景（虚拟角色）控制，具备实际互动展示能力
+- 控制逻辑可配置：如识别区域、快捷键内容、手势灵敏度
+
+------
+
+## 七、后续优化建议（下一阶段）
+
+| 方向                 | 目标                                            |
+| -------------------- | ----------------------------------------------- |
+| 增加左手手势组合识别 | 允许双手协同控制，比如捏合+四指等               |
+| 提升模型识别精度     | 支持定制 MediaPipe .task 文件、自采样训练       |
+| UI 设置面板          | 提供手势→动作自定义、阈值调节、快捷键修改       |
+| 引入语音控制         | Whisper/Vosk 实现语音命令解析，结合手势联动使用 |
+| 多模式切换           | 视频控制、PPT 控制、游戏控制等可切换交互模式    |
+| 场景演示/视频录制    | 准备真实交互展示视频，用于演示或上线宣传        |
+
+
+
+------
+
+## 八、结语
+
+本轮迭代成功实现了从手势识别到控制动作的完整闭环，扩展支持了游戏角色控制（多方向移动与跳跃），并在操作流畅性、准确性与系统解耦方面都取得实质进展。后续可以围绕用户可配置性、语音识别联动与多场景适配进一步扩展系统能力。