## 一、业务功能
### 1. 立项背景与目标
游戏/模拟器场景存在大量重复性、节奏性、高频率的界面操作,人工执行反应慢、易疲劳、难一致。本项目目标是落地一条完整视觉自动化链路:**全屏截帧 → 图像识别 → 判定 → 自动化响应**,并解决高 DPI 坐标偏移、颜色漂移、抖动误判等真实精度问题,以「第五人格·作曲家」修机节奏场景作为可视化示例。
### 2. 核心功能与模块
视觉采集 mss 全屏毫秒级截帧,60fps 不卡顿
目标识别 OpenCV HSV 颜色空间检测,亮度无关抗明暗变化
采样判定 带状区域双窗口统计像素数,抗抗锯齿/抖动
响应触发 跨进程键鼠模拟,220ms 冷却防重复
配置持久化 JSON 落盘,坐标/阈值跨会话复用
手动标注 鼠标点击 3 点完成校准,含坐标校验
诊断调参 峰值检测 + 连拍留痕,调参数据化
运行控制 热键状态机:1启 2停 3标 4退 5诊 6拍
### 3. 业务流程路径
**首次校准**:启动 → 进入画面 → 按 3 → 依次点击判定线/红轨道/蓝轨道 → 自动校验并保存 JSON。
**日常运行**:按 1 启用 → 200Hz 抓帧 → HSV 采样 → 超阈值且冷却超时 → 模拟按键,触发瞬间自动截图留痕。
**异常排查**:按 5 诊断报告红/蓝峰值 → 判断坐标/阈值问题 → 按 6 连拍离线调参。
### 4. 整体架构
五段式数据流:**采集→识别→判定→响应**,全程 JSON 配置驱动,外加留痕层(触发截图+日志),单文件约 450 行。
```
交互层(热键) → 主循环(200Hz)
→ 采集层(mss截帧) → 识别层(HSV采样)
→ 判定层(阈值+冷却) → 响应层(键鼠模拟)
→ 留痕层(触发截图) 配置层(JSON)
```
设计取舍:配置驱动一切(零硬编码);状态机管理运行态;调试能力内建(诊断+连拍+留痕)。
### 5. 模块技术栈
- 截帧:mss(Win32 GDI,低延迟低占用)
- 图像:OpenCV + NumPy(向量化 HSV 转换与统计)
- 输入:keyboard / mouse(跨进程全局模拟)
- DPI:ctypes 设置进程 DPI 感知
- 配置:json 标准库;环境:Python 3.10+ / Windows
### 6. 我负责的模块
独立开发完成全部模块:采集识别算法、判定策略、标注交互、配置容错、调试工具链、DPI 适配与热键状态机。
### 7. 坑与解决方案
1. **高 DPI 坐标错位**:鼠标坐标与截图物理坐标差 1.5 倍 → `SetProcessDpiAwareness(2)` 统一为物理像素。
2. **单像素抖动误判**:抗锯齿导致时有时无 → 改带状区域统计像素数阈值。
3. **RGB 亮度漂移**:画面明暗变化误判 → 改 HSV 色相判定,红色双区间处理色相环回绕。
4. **连续误触**:同色目标重复按键 → 220ms 冷却,按颜色分别记时。
5. **标注错位**:y 为 0 或红蓝间距异常 → 自动校验并提示重新标注。
6. **配置损坏崩溃**:手动改错 JSON 程序崩溃 → 容错回退默认配置合并兜底。
7. **BGRA 四通道**:OpenCV 接口不兼容 → 统一截取前 3 通道,避免每帧全量转换。