一、本轮迭代目标
本 Sprint 主要目标是完成 基于浏览器端的手势控制系统雏形，实现如下基础功能：
- 搭建前端 Web 应用结构与 UI 页面
- 集成 MediaPipe 手势识别模型，完成实时手势检测
- 映射部分手势为系统控制行为（鼠标移动、点击等）
- 搭建基础手势处理逻辑与组件封装结构
- 支持语音识别指令发送流程（准备后端对接）
二、本轮主要完成内容
| 类别 |
工作内容 |
| 前端搭建 |
基于 Vite + Vue 3 + TypeScript 完成项目结构、模块划分、页面初始化 |
| 手势识别 |
集成 Google MediaPipe WASM 模型，完成实时检测与渲染 |
| 控制逻辑 |
封装 GestureHandler、TriggerAction，实现手势到系统操作的映射 |
| UI设计 |
完成仪表盘式主界面设计，支持响应式、自定义手势预览等 |
| 模型结构 |
初步梳理 Detector 识别流程，统一封装初始化与推理逻辑 |
| 后端准备 |
初始化 Python 接口 WebSocket 构建，支持语音识别交互 |
三、系统结构设计
[用户摄像头]
↓
[VideoDetector.vue] → 捕捉视频帧，传入检测器
↓
[Detector.ts] → 调用 MediaPipe 识别手势
↓
[GestureHandler.ts] → 映射行为（鼠标/键盘/语音）
↓
[TriggerAction.ts] → 向后端/系统发出控制指令
↓
[Python 后端]（语音识别/扩展指令） ← WebSocket 接入
四、核心技术栈与理由
| 技术 |
用途 |
原因 |
| Vue 3 + Vite |
前端框架 + 构建工具 |
快速开发，热更新快，Composition API 更灵活 |
| TypeScript |
增强类型约束 |
减少运行时错误，提升可维护性 |
| MediaPipe Tasks |
手势识别模型 |
体积小，支持浏览器部署，准确率高 |
| WebSocket |
前后端实时通信 |
保持实时交互流畅 |
| Python + FastAPI |
后端扩展接口（语音） |
快速搭建接口，后续支持 Py 模型运行 |
五、主要功能点与说明
1. Detector 类封装
- 初始化 WASM 模型与识别器
- 封装
detect() 每帧调用逻辑
- 支持获取
landmarks, gestures, handedness
2. 手势识别与映射
- 仅识别食指 → 鼠标移动
- 食指 + 中指 → 鼠标点击
- 食指 + 拇指捏合 → 滚动
- 四指竖起 → 发送快捷键
- 小指+拇指 → 启动语音识别（前端 WebSocket）
3. UI 界面模块
- 实时视频预览窗口
- 子窗口：手势反馈 / 执行动作提示
- 配置面板：开关检测 / 配置行为映射
六、识别代码示例（关键手势）
if (gesture === HandGesture.ONLY_INDEX_UP) {
this.triggerAction.moveMouse(x, y)
}
if (gesture === HandGesture.INDEX_AND_THUMB_UP) {
this.triggerAction.scrollUp()
}
- 每种手势匹配后，调用封装的 WebSocket + 系统接口发送动作
TriggerAction 支持复用
七、问题与解决方案
| 问题描述 |
解决方法 |
| WebSocket 连接后反复断开 |
增加连接状态判断 readyState !== OPEN，避免提前发送 |
Tauri 插件调用 invoke undefined |
使用 npm run tauri dev 启动，而非普通浏览器启动 |
| 页面刷新后路由丢失（404） |
Vue Router 改为 createWebHashHistory() 模式 |
| 模型未加载或报错提示 |
增加 loading 控制，捕捉初始化异常 |
八、未来规划（Sprint 2 预告）
| 方向 |
说明 |
| 多手势拓展 |
三指滚动、多指触发多功能、多手联合判断 |
| 自定义 .task 模型 |
支持用户采集数据，自定义模型替换现有 MediaPipe 模型 |
| 后端语音指令集成 |
Vosk 模型识别语音，触发系统控制 |
| 设置项管理 |
实现用户自定义快捷键、手势配置界面 |
