GestureMouse 手势控制电脑

     ______                __                  __  ___                  
    / ____/_  _____  _____/ /________  _____  /  ^|/  /___  __  __________ 
   / / __/ / / / _ \/ ___/ __/ ___/ / / / _ \/ /^|_/ / __ \/ / / / ___/ _ \ 
  / /_/ / /_/ /  __(__  ) /_/ /  / /_/ /  __/ /  / / /_/ / /_/ (__  )  __/ 
  \____/\__,_/\___/____/\__/_/   \__,_/\___/_/  /_/\____/\__,_/____/\___/

用安卓手机摄像头识别手势、通过 USB 远程控制电脑鼠标的开源方案。

定位

纯本地：全部处理在本机完成，零云端依赖，数据不出设备
架构：手机 USB 推视频流 → PC 推理 → PC 控制 + 回传关键点 → 手机渲染 21 点骨骼 Overlay
技术栈：Android（Camera2 + MediaCodec H.264 硬编）+ Python（MediaPipe + PyAV + PyQt6 + pynput）

目录结构

手势控制电脑demo/
├── android-app/                 # Android 推流 + 预览 + Overlay App
│   └── app/src/main/
│       ├── java/com/gesturemouse/
│       │   ├── cam/Camera2Streamer.kt        # Camera2 采集 + 推流
│       │   ├── media/                        # 编解码 / 分类 / 跟踪
│       │   │   ├── GestureClassifier.kt
│       │   │   ├── H264Encoder.kt
│       │   │   ├── H264PreviewDecoder.kt
│       │   │   └── HandTracker.kt
│       │   ├── net/                          # 配置 + 关键点客户端
│       │   │   ├── Config.kt
│       │   │   ├── AppConfig.kt
│       │   │   └── KeypointClient.kt
│       │   ├── overlay/SkeletonOverlay.kt    # 21 点骨骼渲染
│       │   ├── tunnel/StreamServer.kt        # 视频流 TCP 服务
│       │   ├── usb/UsbConnectionReceiver.kt  # USB 插拔广播
│       │   └── MainActivity.kt
│       ├── res/                              # 布局 / 主题 / 图标
│       └── AndroidManifest.xml
├── pc/                          # PC 端
│   ├── server/                  # 主服务
│   │   ├── main.py              # 入口 (解码 / 推理 / 映射 / 鼠标注入 / 关键点回传)
│   │   ├── adb_tunnel.py        # ADB reverse 端口映射
│   │   ├── video_decoder.py     # PyAV 解码 (adb/webcam/video 多源)
│   │   ├── hand_tracker.py      # MediaPipe 21 关键点封装
│   │   ├── gesture_mapper.py    # 手势→动作映射 (fingertip 策略)
│   │   ├── dual_hand_mapper.py  # 双手模式映射
│   │   ├── quad_map.py          # 四边形控制区域双线性映射 (纯数学)
│   │   ├── mouse_controller.py  # pynput + Win32 鼠标注入
│   │   ├── keypoint_server.py   # 关键点回传 + 命令服务 (port 15101)
│   │   ├── frame_enhance.py     # 夜间视觉增强 (gamma + CLAHE)
│   │   ├── gesture_voter.py     # 滑动窗口手势投票 (防抖)
│   │   ├── ml_classifier.py     # ML 几何手势分类器
│   │   ├── gui.py               # Qt 入口辅助
│   │   ├── selftest.py          # 样例图片自检
│   │   ├── test_mapper.py       # 单元测试 (映射 / 连续性 / 防抖 / 吸附)
│   │   ├── test_quad_map.py     # 四边形映射单元测试
│   │   ├── test_align.py        # 对齐单元测试 (13 项)
│   │   ├── analyze_metrics.py   # 指标分析 (FPS / 延迟 / 连续性)
│   │   ├── capture_stream.py    # 流捕获工具
│   │   └── diag_stream.py       # 流诊断工具
│   ├── overlay/                 # PyQt6 叠层
│   │   ├── cursor_state.py      # 光标状态管理
│   │   ├── gaze_overlay.py      # 圆环光标 + 注视轨迹拖尾
│   │   ├── video_window.py      # 视频画面 + 状态窗口 + 四边形校准 UI
│   │   └── smoke_test.py        # 叠层冒烟测试
│   └── models/
│       └── gesture_recognizer.task   # MediaPipe 手势识别模型
├── config/                      # 运行时热加载配置 (JSON)
│   ├── gesture_map.json         # 手势→动作映射 / 平滑 / 死区 / 四边形 / 吸附 / 手机参数
│   └── overlay.json             # 圆环 / 涟漪 / 拖尾参数
├── docs/                        # 文档
│   ├── images/                  # 测试截图与样例图片
│   ├── DEVELOPMENT_PLAN.md      # 完整开发计划
│   ├── requirements.md          # 需求规格说明书
│   ├── HAND_TRACKING_SYSTEM_FIX.md          # 手跟踪修复方案
│   ├── FEASIBILITY_PHONE_SIDE_TRACKING.md   # 手机端计算迁移可行性
│   ├── TEST_REPORT_TEMPLATE.md  # 测试报告模板
│   ├── REVISION_GUIDE.md        # 版本控制与回退指南
│   ├── gesture_optimization_report.md      # 手势优化报告
│   ├── 手势控制电脑开源调研与落地分析.md     # 开源调研与可行性
│   ├── 拍照指南.md                # 手势动作训练图拍摄指南
│   └── superpowers/plans/       # 功能实现计划 (2026-08-07-*.md)
├── crash_traceback.log          # 崩溃日志 (全局异常钩子写入, 诊断用)
├── metrics/                     # 性能指标采集
│   ├── phase1_smoke/            # 冒烟测试 JSONL
│   └── *.csv                    # 逐帧指标 CSV
├── tools/                       # 分析 / 测试 / 验证脚本
│   ├── analyze_phone_log.py
│   ├── analyze_v4_results.py
│   ├── compare_gesture_log.py
│   ├── debug_test.py
│   ├── test_angle_classifier.py
│   ├── test_gesture_v4.py
│   ├── test_v4_precise.py
│   ├── test_v4_simple.py
│   ├── test_v4_unit.py
│   ├── verify_optimization.py
│   └── verify_pinch_detection.py
├── dev/                         # 开发 / 验证 / 启动辅助脚本
│   ├── _build_console_icon.py   # GM_LOGO.png → GM_LOGO.ico
│   ├── _set_console_icon.py     # Win32 设置 CMD 窗口图标
│   ├── _validate_encoding.py    # 编码安全验证 (GBK 兼容)
│   ├── _validate_logo.py        # LOGO 加载验证
│   ├── _validate_logo_topleft_only.py
│   ├── _validate_no_watermark.py
│   ├── _lat_validate_v5.bat     # USB 延迟验证
│   ├── _lat_webcam_v6.bat       # Webcam 延迟验证
│   ├── _test_crlf_v4.bat        # 批处理 CRLF 解析测试
│   ├── _run_bat_syntax_check.ps1
│   └── logs/                    # 运行日志 (_last_run.log 等) + 历史归档
├── 启动电脑端.bat                # CMD 启动器 (5 模式, 预检, 日志)
├── 启动电脑端.ps1                # PowerShell 启动器
├── GM_LOGO.png / GM_LOGO.ico    # 项目图标
├── requirements.txt             # Python 依赖
├── .gitignore
└── README.md

[!note] ✏️ 路径稳定性 pc/server/main.py 通过 os.path.dirname(os.path.dirname(os.path.abspath(__file__))) 解析项目根目录，因此 pc/ 与 config/、pc/models/ 的相对位置不可变动。dev/ 内的脚本均已适配 dev/ 子目录（解析父目录为项目根）。

技术路线

核心技术栈

PC 端（Python 3.10+）

组件	库 / API	用途
手势识别	MediaPipe Tasks (`gesture_recognizer.task`)	21 关键点检测 + 7 类手势分类
视频解码	PyAV (`av>=13`)	H.264 硬解 (adb / webcam / video 多源)
GUI 渲染	PyQt6 (`>=6.6`)	VideoWindow 画面 + 状态; GazeOverlay 圆环光标
鼠标注入	pynput (`>=1.7`) + Win32 `SetCursorPos`	移动 / 点击 / 滚动 / 拖拽
图像处理	OpenCV (`>=4.9`) + NumPy (`>=1.24`)	格式转换 / 矩阵运算

Android 端（Kotlin, minSdk 26+）

组件	API	用途
摄像头采集	Camera2 API	YUV 帧捕获
视频编码	MediaCodec H.264 硬编	低延迟推流编码
USB 通信	Socket + ADB reverse	视频流推送 + 关键点回传
骨骼渲染	自定义 View (`SkeletonOverlay`)	21 点骨骼 Overlay 绘制
USB 监听	`BroadcastReceiver`	插拔事件 → 自动唤醒界面

通信层

通道	端口	方向	协议
视频流	tcp:27183	手机 → PC	H.264 裸流 (Socket 长连接)
关键点 / 命令	tcp:15101	PC ↔ 手机 (双向)	JSON 行协议 + ACK + 1s 心跳

[!tip] 💡 低延迟优化控制链路启用 TCP_NODELAY（关闭 Nagle），socket buffer 设为 16KB，确保心跳 / 命令小包立即到达。

架构设计

整体数据流：手机 USB 推视频流 → PC 推理 → PC 控制 + 回传关键点 → 手机渲染骨骼 Overlay

┌─────────────────────── Android Phone (USB) ────────────────────────┐
│  Camera2 → MediaCodec H.264 ──► Socket :27183 ──► ADB reverse ──►  │
│                                          ▲                          │
│  SkeletonOverlay ◄── KeypointClient ◄───┘  (JSON 21 pts :15101)     │
│  UsbConnectionReceiver → 触发 pc_start_stream                       │
└────────────────────────────────────────────────────────────────────-┘
                                ▲ ▼ USB
┌─────────────────────────── PC (Windows) ───────────────────────────-┐
│  AdbTunnel (reverse tcp:27183 + tcp:15101)                           │
│       │                                                             │
│       ▼                                                             │
│  VideoDecoder (PyAV) → HandTracker (MediaPipe 21 pts)              │
│       │                                                             │
│       ▼                                                             │
│  GestureMapper (fingertip + 四边形吸附) → MouseController (pynput+Win32) │
│       │                                                             │
│       ▼                                                             │
│  KeypointServer :15101 (JSON + ACK + 心跳)                          │
│       │                                                             │
│       ▼                                                             │
│  VideoWindow (PyQt6, deque maxlen=1, 30ms timer)                   │
└────────────────────────────────────────────────────────────────────-┘

线程模型

线程	职责	容错
主线程	Qt 事件循环（VideoWindow`paintEvent` / GazeOverlay）	—
Worker 线程	解码 → 推理 → 映射 → 鼠标注入	每帧`try/except`，单帧错误不崩溃
KeypointServer	`accept_loop` + 每客户端独立 `_serve` 线程	JSON 解析异常静默跳过
AdbTunnel	阻塞等待 USB 设备（`wait_for_device`）	超时 / 中断可恢复

关键技术实现

1. 手势映射（fingertip 策略）

gesture_mapper.py 实现基于关节几何的判定，不依赖模型分类：

指尖伸直判定：MCP-PIP-DIP 三点夹角 > 125° = 伸直（与 Android 端 GestureClassifier.kt 阈值对齐）
拇指独立判定：角度 > 155° 且拇指尖到食指根归一化距离 > 0.35（两者同时满足）
3 帧确认（~100ms）：弯曲/捏合动作需连续 3 帧稳定才触发，防误触
单指弯曲控制：无名指弯曲 → 持续向下滚动、小拇指弯曲 → 持续向上滚动（60ms 节流，最高 ~16 次/秒）；中指弯曲 → 单击右键
安全释放：张开手掌或手离开画面 → 强制释放所有按住的键

2. USB ADB reverse 双通道

adb_tunnel.py + keypoint_server.py：

视频流：adb reverse tcp:27183 tcp:27183（手机 → PC 单向推送 H.264 裸流）
控制链路：adb reverse tcp:15101 tcp:15101（双向 JSON 行协议）
命令集：pc_start_stream / pc_status_query / pc_status_ack / pc_stop_stream
心跳：每 1 秒发送，超时检测连接断开 → 双端自动重连
ACK 确认 + 重试：命令送达由 handler 返回 ack payload 回传手机

3. DPI 感知（PerMonitorV2）

main.py enable_dpi_aware()：

SetProcessDpiAwareness(2)  →  PerMonitorV2 (Win10+, 主屏副屏都对)
        ↓ 失败
SetProcessDpiAwareness(1)  →  PerMonitor V1 (Win8 fallback)
        ↓ 失败
SetProcessDPIAware()       →  System DPI Aware (Win7 fallback)

保证 SetCursorPos / GetCursorPos / GetSystemMetrics / Qt geometry 全部使用同一套物理像素坐标，杜绝 125%/150% 缩放导致的光标↔光圈固定偏移。

4. 编码安全（GBK CMD 兼容）

[!warning] ⚠️ 乱码根因 Python print('写入→SetCursorPos') 输出 UTF-8 3 字节（→ = E2 86 92），外层 CMD 按 GBK(CP936) 双字节组合 → 产生乱拼中文（漩濊 / 浼斅欑）+ U+FFFD。

三层最小化修复：

Python 侧：sys.stdout.reconfigure(errors="backslashreplace", line_buffering=True) —— 非 ASCII 字符自动转 \xXX / \uXXXX
输出标签：所有 print 使用 ASCII 标签（[OK] / [WARN] / [CURSOR] / [LAT] / [SCREEN] / [FPS] / [WAIT] / [WORKER_ERR] / [USB] / [SOURCE] / [CMD] / [OVERLAY] / [EXIT] / [ARGS] / [MODEL] / [DPI] / [FLIP] / [DUAL]）
环境兜底：启动电脑端.bat 设置 PYTHONIOENCODING=ascii:backslashreplace + chcp 65001（老系统静默失败）

5. VideoWindow 渲染优化

video_window.py：

措施	数值	解决问题
帧队列	`deque(maxlen=1)`	防积压（旧方案 50-80ms/帧 → 4 秒延迟）
渲染定时器	30ms	避免渲染瓶颈
解码策略	只解码最新帧	跳过积压帧
socket buffer	64KB	控制内存占用

6. 动态平滑（EMA）

gesture_mapper.py 自适应 EMA：

快速移动：alpha=0.85（几乎只看最新坐标，跟手）
慢速移动：alpha=0.35（历史权重，防抖）
速度阈值：0.03（低于此判为慢速，进入防抖模式）

7. 坐标映射（absolute 模式）

screen_x = nx * screen_w          # 1:1 铺满全屏
screen_y = ny * screen_h
# 可选 abs_gain (>1): 以屏幕中心为锚放大 (config 实际 1.8)
x = screen_w/2 + (x - screen_w/2) * abs_gain
y = screen_h/2 + (y - screen_h/2) * abs_gain

避免多重坐标变换（letterbox 缩放 + gain 放大）叠加产生不可预测偏移。

8. 四边形控制区域 + 吸附瞄准（snap_targeting）

解决"光标太灵敏选不准对象"：磁铁网格治"抖"，停留点击治"瞄不准"，四边形控制区提升舒适度与可控性。

quad_map.py 用双线性反解（Newton 迭代）把手在用户自定义四边形内的归一化坐标映射到全屏。4 个锚点（TL/TR/BR/BL）在视频窗口内校准，gesture_mapper.py 内核对齐后启用：

子特性	配置键	当前 config	作用
四边形控制区	`quad_enabled`	true	手只在四边形内活动，映射到全屏，操控更舒适
死区防抖	`dead_zone`	0.004	手位移小于阈值时光标不动，抑制微抖
磁铁网格	`magnet_enabled` / `magnet_grid_px`	false / 4	光标吸附到最近网格，稳定点选
停留自动点击	`dwell_enabled` / `dwell_ms` / `lock_radius_px`	true / 600 / 18	光标锁圈内停留 0.6s 自动左键
跟踪点选择	`control_point` / `control_point_options`	4 / [4,8,12,16,20]	用哪个关键点控制光标

校准流程（--show-window 模式）：

空格进入校准模式（同时暂停所有鼠标动作，防止停留误触）
用跟踪点（默认拇指尖 KP4）依次移到 4 个角落，每个停留 1 秒逐个录入
绿色虚线四边形框好 → 回车保存 → 自动写回 gesture_map.json 并热刷新映射器
此后光标只在四边形内映射到全屏

[!note] 🛡️ 校准防误触进入校准模式时通过 mapper.set_suppress_actions(True) 丢弃所有鼠标动作，只保留光标预览，避免停留自动点击误触屏幕元素。退出/保存后自动恢复。

9. 夜间视觉增强（frame_enhance）

frame_enhance.py 自适应低光增强：按亮度估计选择 gamma 区间（gamma_min~gamma_max）+ CLAHE 对比度，提升暗光下手势识别率。配置在 gesture_map.json 的 frame_enhance 段。

10. PC→手机配置下发

PC 连接时把 gesture_map.json 的 mobile 段（分辨率 / 帧率 / 码率 / 摄像头参数）推给手机，KeypointClient.kt 写入 gesturemouse_config.conf，重启后自动生效。支持 5 个摄像头参数：camera_facing / focus_mode / exposure_compensation / mirror / zoom。

开发流程

5 种启动模式（默认 mode 2）

模式	参数	用途
1	`--source adb --headless`	USB 仅控制鼠标，无窗口
2	`--source adb --show-window`	默认推荐：USB + 视频/状态窗口
3	`--source webcam --headless`	本机摄像头，无窗口
4	`--source webcam --show-window`	本机摄像头 + 窗口
5	`--source adb --overlay --show-window`	调试：USB + 蓝色光圈叠层

启动脚本预检

启动电脑端.bat / 启动电脑端.ps1：

where python —— 验证 Python 在 PATH
python -V —— 排除 Windows Store 0KB 桩
main.py 存在性检查
错误日志写入 dev/logs/_last_run.log（含 cwd / exe / args + 退出码 + 最后 40 行）
错误码分析：9009=Python 不在 PATH / 2=argparse 错误 / 1/-1=运行时错误
窗口不自动关闭：需按两次 ENTER（防信息丢失）
控制台窗口挂 GM_LOGO.ico 图标（dev/_build_console_icon.py + dev/_set_console_icon.py）

技术难点与解决方案

难点	根因	解决方案	验证方式
CMD 乱码（U+FFFD + 乱拼中文）	Python UTF-8 输出 → CMD GBK 双字节错拼	`backslashreplace` + ASCII 标签 + `PYTHONIOENCODING` 兜底	`dev/_validate_encoding.py` 全通过
光标↔光圈固定偏移	Windows DPI 缩放（非 100%）坐标系不一致	进程启动时`SetProcessDpiAwareness(2)`	`[DPI]` 日志 + 多缩放比实测
光标跟踪 4 秒延迟	VideoWindow 渲染 50-80ms/帧导致帧积压	`deque(maxlen=1)` + 30ms timer + 只解码最新帧	`[LAT] p50=30-60ms`
USB 断连需手动干预	无自动重连机制	双端自动重连 + 1s 心跳超时检测	拔插 USB 实测
手势误触	单帧判定不稳定	3 帧确认（~100ms）+ 滚动 60ms 节流	连续手势测试
坐标系错位	letterbox 缩放 + gain 放大叠加	absolute 模式 1:1 铺满 + 中心锚定 `abs_gain`	`[CURSOR] delta=(0,0)`
批处理窗口闪退	`python -c` 分号在 CP936 解析失败 + `pause >nul` 被回车绕过	`where python` + `python -V` 预检 + 强制双 ENTER	`dev/_test_crlf_v4.bat` → `dev/logs/_test_crlf_v4_run.log`
骨骼方向不对	手机镜像显示 vs PC 推理坐标	`SkeletonOverlay` x 坐标翻转对齐	`test_align.py` 13 项通过
模型路径含中文	MediaPipe 加载非 ASCII 路径失败	`safe_model_path()` 复制到 `%TEMP%` 临时目录	`[MODEL]` 日志
单帧异常崩线程	外层 try/except 包整个 worker 循环	每帧独立 try/except	`[WORKER_ERR] streak=` 日志
启动闪退（TypeError）	`set_calibration_callbacks` 缺少 `on_calib_toggle` 参数	补齐方法签名参数	启动后窗口正常显示
启动闪退（UnboundLocalError）	worker 内重赋值 `tracker` 未声明 `nonlocal` 遮蔽闭包变量	移除无效的跟踪器重建逻辑，`tracker` 保持只读闭包	`FPS=` / `gesture=` 正常输出
设死点后误触屏幕元素	校准停留与停留自动点击(600ms) 冲突	校准模式 `set_suppress_actions(True)` 丢弃所有鼠标动作	校准/保存无点击
设死点后崩溃（鼠标转圈）	GUI 重建 mapper 与 worker 并发读写，拿到半初始化对象	`threading.Lock` 保护 mapper + 全局 `sys.excepthook` 写崩溃日志	多帧稳定运行 + `crash_traceback.log`

快速开始（PC 端，webcam 兜底模式）

pip install -r requirements.txt
# 视频源：adb(手机推流) / webcam(本机摄像头) / video(视频文件)
python pc/server/main.py --source webcam

按 Enter 或 Ctrl+C 退出。

连接手机（USB 推流）

# 手机通过 USB 连接并开启 USB 调试，App 启动推流后：
python pc/server/main.py --source adb --serial <SERIAL>

调试模式：显示视频画面 + 骨骼网格窗口

# 在正常命令基础上追加 --show-window，弹出 PC 端窗口：
# 实时显示手机画面 + 21 点骨骼绑定渲染，用于验证识别与对齐
python pc/server/main.py --source adb --show-window

--show-window 与 --headless 互斥。正常使用时无需开窗，仅测试/调试时启用。

无界面自检

# 手势识别 + 状态机（传入样例图片）
python pc/server/selftest.py pointing_up.jpg victory.jpg

# 叠层渲染冒烟测试（合成光标轨迹，2.5s 自动退出）
python pc/overlay/smoke_test.py

常用命令行参数

参数	说明
`--source`	视频源：`adb` / `webcam` / `video`（默认 `webcam`）
`--serial`	adb 模式下指定设备序列号
`--video`	`--source video` 时指定视频文件路径
`--camera`	`--source webcam` 时指定摄像头索引（默认 0）
`--mirror`	水平镜像画面（默认关闭，前摄场景可启用）
`--show-window`	显示视频画面 + 骨骼网格窗口（调试用，与`--headless` 互斥）
`--headless`	无窗口模式，仅运行解码 + 推理 + 鼠标控制
`--overlay`	开启蓝色圆环光标叠层（默认关闭，调试定位用）
`--no-mouse`	不注入鼠标事件（仅观察/采集指标）
`--config-dir`	配置目录（默认`config/`）
`--model`	MediaPipe 模型路径（默认`pc/models/gesture_recognizer.task`）
`--keypoint-port`	关键点回传端口（默认 15101）
`--stream-port`	视频流端口（默认 27183）
`--frames`	限制处理帧数（0 表示不限）
`--metrics-out`	写入逐帧指标 CSV，用于稳定性/延迟/连续性测试

配置

config/gesture_map.json：手势→动作映射、平滑系数、死区、映射模式（absolute / relative）
- snap_targeting：四边形控制区（quad）、死区（dead_zone）、磁铁网格（magnet_enabled / magnet_grid_px）、停留点击（dwell_enabled / dwell_ms / lock_radius_px）、跟踪点（control_point）
- frame_enhance：夜间视觉增强（gamma + CLAHE）
- mobile：PC 下发到手机的推流参数（分辨率 / 帧率 / 码率 / 摄像头参数）
config/overlay.json：圆环、涟漪、注视轨迹拖尾的颜色/粗细/消散速度等参数，运行时实时生效

手势映射（默认 fingertip 策略）

默认跟踪点 control_point=4（拇指尖），实际生效控制方式如下：

手势	动作
☝️ 拇指（跟踪点 KP4）移动	移动光标
🤏 食指+中指捏合	按住左键（拖动）
🤏 中指+无名指捏合	单击右键
🙆 中指弯曲	单击右键
💍 无名指弯曲	持续向下滚动
🤙 小拇指弯曲	持续向上滚动
🏠 光标停留（dwell_ms）	自动单击左键
🖐️ 五指全部张开	释放所有按住的键（取消）

捏合为"按下-保持-释放"语义：保持捏合即持续按住左键拖动，只有张开手掌（或手离开画面）才释放。旧策略（食指独伸左键 / 中指独伸右键 / 握拳双击）可通过 config/gesture_map.json 的 control_strategy: "model_gesture" 回退启用。

测试

# 单元测试（手势映射 / 连续性 / 防抖 / 回退 / 吸附）
python pc/server/test_mapper.py

# 四边形映射单元测试
python pc/server/test_quad_map.py

# 对齐单元测试（13 项）
python pc/server/test_align.py

# 实机指标采集（生成 CSV）
python pc/server/main.py --source adb --serial <SERIAL> --no-mouse --metrics-out metrics/run.csv

# 指标分析（FPS / 延迟 P50 P95 / 连续性 / 动作统计）
python pc/server/analyze_metrics.py metrics/run.csv

开发验证脚本（dev/）

脚本	用途
`dev/_validate_encoding.py`	编码安全验证（GBK 兼容，0 残留中文常量）
`dev/_validate_logo.py`	LOGO 加载验证（QPixmap 解析）
`dev/_validate_no_watermark.py`	验证水印移除
`dev/_lat_validate_v5.bat`	USB 延迟验证（mode 2）
`dev/_lat_webcam_v6.bat`	Webcam 延迟验证（400 帧）
`dev/_test_crlf_v4.bat`	批处理 CRLF 解析测试
`dev/_run_bat_syntax_check.ps1`	批处理语法检查

文档

docs/DEVELOPMENT_PLAN.md：完整开发计划（架构、分阶段、风险与验证）
docs/requirements.md：需求规格说明书
docs/手势控制电脑开源调研与落地分析.md：开源社区调研与可行性分析
docs/HAND_TRACKING_SYSTEM_FIX.md：手跟踪系统修复方案（问题分析 / 调研 / 设计 / 测试）
docs/FEASIBILITY_PHONE_SIDE_TRACKING.md：手机端计算迁移可行性分析与延迟根因排查
docs/TEST_REPORT_TEMPLATE.md：测试报告模板
docs/REVISION_GUIDE.md：版本控制、回退与可回溯操作指南
docs/gesture_optimization_report.md：手势优化报告
docs/superpowers/plans/：功能实现计划（等腰四边形吸附点击、可配置推流质量、配置下发与摄像头参数）

许可

项目本体 MIT 许可证。依赖均为宽松开源许可（Apache 2.0 / LGPL / GPL）。

Name		Name	Last commit message	Last commit date
.trae		.trae
android-app		android-app
config		config
dev		dev
docs		docs
metrics		metrics
pc		pc
tools		tools
.gitignore		.gitignore
GM_LOGO.ico		GM_LOGO.ico
GM_LOGO.png		GM_LOGO.png
README.md		README.md
requirements.txt		requirements.txt
启动电脑端.bat		启动电脑端.bat
启动电脑端.ps1		启动电脑端.ps1

Latest commit

History

Folders and files

Repository files navigation