面向 Windows 的 Python 视觉自动化运行时：截屏、识别、脚本化调度与键鼠执行可在同一套引擎里组合使用。
设计包含捕获与识别、键鼠执行两大形态；脚本采用「项目目录 + manifest.json」结构；核心与界面通过 EventBus 解耦（见 core/event_bus.py、core/visionscript_events.py）。
VisionScript 将截屏、识别、键鼠执行与脚本调度整合为一套引擎，各模块通过 EventBus 松散耦合。
- Engine 主循环：固定 FPS 驱动，支持暂停 / 继续 / 停止 / 动态脚本切换。
- ScriptContext：脚本唯一入口对象
ctx，整合截图、感知、键鼠执行与日志。 - EventBus：同步 / 异步事件总线，解耦核心、脚本、UI 与识别模块。
- WorldState：全局单例状态（暂停标志、停止请求、扩展数据字典）。
- ScriptRuntimeModule：运行时脚本宿主，支持
tick(ctx)约定与模块级状态持久化。
- 窗口截图：BitBlt 窗口客户区捕获，支持标题匹配与 HWND 指定。
- 全屏截图：
ScreenCapture直接抓取整个屏幕。 - Win11 兼容：提供 BitBlt 黑屏注册表修复与 DwmGetDxSharedSurface 回退。
- 区域裁剪：支持从大图中按 ROI 裁剪子区域。
- 模板匹配：OpenCV
matchTemplate，支持多尺度与 NMS。 - YOLO 检测：ONNX Runtime 推理，实时目标检测。
- OCR 识别：PaddleOCR 文字识别，支持中英文与多语言。
- 感知流水线：
PerceptionPipeline串接多种识别器，统一输出结构化结果。 - UI 识别器：专门识别游戏内固定 UI 元素（按钮、对话框等）。
- 鼠标控制：Windows API 注入，支持贝塞尔曲线路径、随机延迟、相对/绝对移动。
- 键盘控制：支持单键、组合键、文本输入、长按与快捷键。
- ActionExecutor：高层封装（
click_at、navigate_click、shortcut、combo_action等）。 - 人性化模式：默认启用随机偏移与延迟，模拟真实人类操作。
- 清单格式：支持
manifest.json与 YAML / JSON 清单文件。 - 配置嵌套：运行时配置（capture / perception）统一放在
visionscript键下（兼容旧键vhsr）。 - 动态加载：UI 中双击脚本列表即可热切换，无需重启程序。
- 目录扫描：自动扫描
scripts/目录，实时更新可用脚本列表。 - 热键绑定：每个脚本可独立配置全局快捷键（如
F5、Ctrl+F9），一键启动；支持manifest.json声明或config.json集中管理。 - 约定入口：脚本模块实现
def tick(ctx): ...，由 Engine 每帧调用；任务完成时可ctx.finish()或return False结束运行（脚本队列自动衔接下一项，见 docs/script_queue.md）。
- PyQt6 主窗口：日志面板、脚本列表、控制按钮。
- 脚本面板：右侧 QListWidget 展示可用脚本，双击加载；QFileSystemWatcher 实时刷新。
- 日志通道：
visionscript.*级别日志自动转发到ui.log事件，实时显示在日志面板。 - 全局热键：支持为每个脚本绑定独立启动快捷键（
manifest.json/config.json双源配置，组合键可用），并可通过通用停止键（默认F6）一键终止当前脚本。 - 待机启动：UI 启动时不自动运行引擎，等待用户手动选择脚本后启动。
- 统一配置目录：
config/存放config.json等运行时配置（如WINDOW_TITLE、UI_THEME、LOG_FLOAT_ENABLED、LOG_FLOAT_BG_ALPHA、LOG_FLOAT_TEXT_ALPHA悬浮日志窗、SCRIPT_HOTKEYS）。 - 脚本清单配置：
manifest.json的visionscript键下可配置 capture、perception。 - 输入录制：GUI「录制」页可在
scripts/下自动生成record_*项目目录与清单；详见 docs/core.md。
更细的 API、配置项与限制见 文档索引 与 ScriptContext API 参考。
- 操作系统：Windows（
capture/、executor/依赖 Win32）。 - Python：建议 3.10+（与
requirements.txt中依赖一致即可）。
cd <本仓库根目录>
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt使用 WGC / DwmGetDxSharedSurface 捕获（create_capture 模式 1/2/3）时，额外安装：
pip install -r requirements-capture-ext.txtpython main.py --script <路径>
# 带 PyQt6 界面（与引擎同进程）
python main.py --script <路径> --gui<路径> 可以是：
- YAML 清单文件（入口字段
entry或main） - JSON 清单文件（
name、version、main，扩展配置在visionscript中，兼容vhsr） - 脚本项目目录（内含
manifest.json）
不传 --script 时，仅启动空引擎主循环（一般用于扩展自定义模块后再接入）。
| 命令 | 作用 |
|---|---|
python main.py --script scripts/example.yaml |
最简 YAML + example_tick.py |
python main.py --script scripts/example_project |
manifest.json + tick.py |
python main.py --script scripts/input_example |
ctx.actions 键鼠 API 说明（默认不落键鼠；实机微动见该目录 tick.py） |
用户脚本约定：在入口模块中实现 def tick(ctx): ...，ctx 为 ScriptContext（捕获、感知、执行器、ctx.bus 等）。说明见 docs/core.md。
VisionScript/
├── main.py # CLI 入口
├── requirements.txt
├── core/ # 引擎、状态、脚本宿主、EventBus
├── capture/ # 屏幕/窗口捕获
├── perception/ # 识别与流水线
├── executor/ # 键鼠与 ActionExecutor
├── scripts/ # 仅脚本：YAML、manifest 项目目录与入口 .py
├── ui/ # PyQt6 界面（EventBus 桥接）
├── examples/ # 非 --script 的辅助示例（如 EventBus 终端订阅）
├── docs/ # Markdown 文档
└── utils/ # 日志等工具
| 文档 | 内容 |
|---|---|
| docs/README.md | 文档总索引 |
| docs/core.md | 脚本清单、tick(ctx)、EventBus、键鼠 |
| docs/capture.md | 捕获模式与限制 |
| docs/perception.md | 识别流水线与模型 |
| docs/packaging.md | Windows 打包与 Setup.exe（PyInstaller、Inno Setup） |
本项目用于技术研究与个人自动化学习。请遵守游戏与服务条款，勿用于作弊或未授权场景；键鼠与截图能力具有真实系统影响，仅在可信环境与可信脚本下使用。
以仓库根目录 LICENSE 为准（GPL-3.0）。