# 自动化脚本 **Repository Path**: yuyalong/veison-desktop-runner ## Basic Information - **Project Name**: 自动化脚本 - **Description**: python自动化脚本 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-20 - **Last Updated**: 2026-08-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Vision Desktop Runner 一个用于学习和二次开发的 Windows 桌面视觉自动化基础引擎。 它只做下面这条公开、可观察的链路： ~~~ 截取目标窗口像素 → 用 OpenCV 匹配你自己准备的模板图片 → 根据 JSON 状态机选择规则 → 在安全授权下执行鼠标键盘动作 → 再截图验证结果 → 记录循环、恢复、心跳和报告 → 必要时由 Supervisor 重启引擎会话或恢复目标进程 ~~~ 项目不读取目标程序内存，不注入进程，不抓取网络协议，也不包含逆向功能。请只在你有权自动化的程序和场景中使用。 当前版本：1.2.0。 ## 当前自带真实案例 项目自带一个完全可控的 Tkinter 测试程序： ~~~powershell python examplesdungeon_demo_app.py ~~~ 窗口标题是“副本循环演示器”。 正常业务流程是： ~~~ 首页 → 自动点击“进入副本” → 加载 3 秒 → 副本运行 5 秒 → 结算页 → 自动点击“返回首页” → 加载 3 秒 → 首页 → 下一轮 ~~~ 右侧测试按钮可以制造： - L0：下一次进入点击无效； - L1：模拟断线； - L2：意外返回首页、未知页面、流程卡住； - L4：目标进程崩溃。 项目已经包含该案例需要的 7 张模板和完整状态机配置。 ## 安全默认值 当前 config/app_config.json 默认是： ~~~json "dry_run": true, "enable_actions": false ~~~ 因此普通运行只观察、判断并记录“本来要做什么”，不会真实点击。 真实动作必须同时满足三项： 1. application.dry_run=false； 2. application.enable_actions=true； 3. 命令包含 run --allow-actions 或 supervise --allow-actions。 目标进程启停另有独立授权：配置中的 allow_start / allow_terminate 和命令行 --allow-process-control 必须同时开启。 窗口最小化时不会自动恢复，而是立即安全停止。 ## 最短验证路径 ~~~powershell cd E:Project ision-desktop-runner ..venvScriptsActivate.ps1 # 1. 另开终端启动测试窗口 python examplesdungeon_demo_app.py # 2. 检查 JSON、模板和工作流 python main.py --config configapp_config.json check --strict # 3. 只截图识别一次 python main.py --config configapp_config.json once # 4. 汇总查看运行状态 python main.py --config configapp_config.json status # 5. Dry-run 会话，不会真实点击 python main.py --config configapp_config.json run ~~~ 真实测试前先阅读教程。真实动作完成后应立即把两个配置开关恢复为安全值。 ## 常用命令 | 命令 | 是否产生外部动作 | 用途 | |---|---:|---| | windows | 否 | 列出可见窗口标题 | | capture | 否 | 保存截图；不要求已有模板 | | extract-template | 否 | 从已有截图裁剪模板 | | match | 否 | 静态测试一张模板的匹配分数 | | check | 否 | 检查基础配置和分层就绪状态 | | check --strict | 否 | 要求模板、规则和长期运行配置全部就绪 | | once | 否 | 截图并识别一次 | | run | 默认否 | 运行一个有边界的引擎会话 | | state | 否 | 查看跨会话持久化状态 | | status | 否 | 汇总报告、心跳、停止文件和 Supervisor 状态 | | stop | 写停止文件 | 请求当前引擎安全停止 | | clear-stop | 删除停止文件 | 清理引擎停止请求 | | process-status | 否 | 只读查询目标进程 | | process-start | 需双重授权 | 受控启动目标进程 | | process-stop | 需双重授权和 PID 二次确认 | 精确停止一个目标 PID | | supervise | 默认否 | 运行多会话 Supervisor | | supervisor-status | 否 | 查看 Supervisor 最后状态 | Supervisor 停止命令： ~~~powershell python main.py --config configapp_config.json stop --scope supervisor python main.py --config configapp_config.json clear-stop --scope supervisor ~~~ 引擎停止命令： ~~~powershell python main.py --config configapp_config.json stop python main.py --config configapp_config.json clear-stop ~~~ stop 是幂等的：停止文件已经存在时不会报错。停止请求会保留，直到执行 clear-stop，避免程序自动重新启动后又继续操作。 ## 分级恢复 | 级别 | 当前实现 | 含义 | |---|---|---| | L0 | retry_count | 同一条规则的动作后验证失败，再重试有限次数 | | L1 | recovery_level: 1 | 处理已经明确配置的断线弹窗等已知界面 | | L2 | recovery + context_state | 放弃当前业务判断，回到上下文检测重新识别 | | L3 | Supervisor | 只重启引擎子会话，不碰目标程序 | | L4 | Supervisor + process | 目标进程消失后，按明确路径和授权恢复 | | L5 | 安全停止 | 最小化、前台不符、FailSafe、停止文件；永不自动绕过 | ## 输出文件 默认输出到 output/： ~~~ runner.log 普通文本日志，按体积轮转 run_report.json 最近一次引擎会话最终报告 heartbeat.json 当前/最近会话轻量心跳 cycles.jsonl 每成功完成一轮追加一行 runner_state.json 跨运行累计状态 last_debug.png 最后一帧识别框调试图 supervisor_status.json Supervisor 状态 supervisor_history.jsonl Supervisor 历史事件 supervisor.lock 单实例操作系统锁文件 ~~~ JSON 状态和报告采用“写临时文件 → 原子替换”，避免读取到半份 JSON。 日志和 JSONL 会轮转，磁盘空间低于配置下限时会停止写入任务。 ## 项目结构 ~~~ vision-desktop-runner/ ├─ main.py ├─ config/ │ └─ app_config.json ├─ templates/ │ └─ dungeon_demo/ ├─ examples/ │ └─ dungeon_demo_app.py ├─ desktop_runner/ │ ├─ cli.py │ ├─ config.py │ ├─ control.py │ ├─ capture.py │ ├─ vision.py │ ├─ rules.py │ ├─ actions.py │ ├─ engine/ │ ├─ recovery.py │ ├─ persistence.py │ ├─ telemetry.py │ ├─ processes.py │ ├─ supervisor.py │ └─ health.py ├─ tests/ ├─ requirements.txt ├─ requirements-build.txt ├─ run_supervisor.ps1 └─ build_exe.ps1 ~~~ ## 安装与测试 依赖由你手动安装： ~~~powershell python -m pip install -r requirements.txt ~~~ 测试： ~~~powershell python -m unittest discover -s tests -v ~~~ 构建 EXE 的依赖： ~~~powershell python -m pip install -r requirements-build.txt .\build_exe.ps1 ~~~ ## Vue 3 浏览器工作台 项目现在同时支持命令行和 Vue 3 可视化操作。工作台在本机浏览器中运行，不需要打包 EXE；它复用现有配置校验、CLI、安全停止和报告，不会建立第二套自动化逻辑。 Python Web 依赖和前端依赖仍由你手动安装： ~~~powershell python -m pip install -r requirements-studio.txt cd studio_web npm install npm run build cd .. python studio_main.py ~~~ 开发时可以分别运行 `python studio_main.py --dev` 和 `npm run dev`，访问 `http://127.0.0.1:5173`。构建后只需运行 `python studio_main.py`，访问 `http://127.0.0.1:8765`。 完整说明见 Vue3可视化工作台使用说明.md。 ## 进一步阅读 - 项目完整使用教程.md：从启动案例到 L0～L4、停止、报告和 EXE 的完整实战； - JSON配置文件使用说明.md：根配置、模板、规则、动作、安全、恢复、进程和 Supervisor 的逐字段解释； - 架构与扩展指南.md：模块边界、依赖注入和 OCR/YOLO/自定义动作扩展方式； - 五阶段优化与验证说明.md：窗口身份保护、引擎拆分、按状态识别、历史指标和质量工具； - 鼠标自然化配置说明.md：模板内部偏移、可见贝塞尔曲线、随机种子和安全限制。