# 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 控制、游戏控制等可切换交互模式    |
| 场景演示/视频录制    | 准备真实交互展示视频，用于演示或上线宣传        |



------

## 八、结语

本轮迭代成功实现了从手势识别到控制动作的完整闭环，扩展支持了游戏角色控制（多方向移动与跳跃），并在操作流畅性、准确性与系统解耦方面都取得实质进展。后续可以围绕用户可配置性、语音识别联动与多场景适配进一步扩展系统能力。