一个 Windows 桌面自动化流水线：录一段操作 → 多模态模型看懂界面 → 生成步骤清单 → 你在对话里逐条确认 → 产出可离线回放的脚本配置 → 在带 GUI 的「游戏实验室」里运行。
运行时 0 token —— 识别与生成阶段用大模型，回放阶段是纯本地的模板匹配 + 键鼠回放。
定位：这是一个工具（把任意游戏的录屏变成脚本），不是"某个游戏的脚本"。 仓库里的
profiles/是示例配置，换游戏要自己录。
① 录制 录屏（只存变化帧）+ 同步采集真实鼠标键盘（毫秒级时间戳）
↓
② 视觉分析 多模态模型分段理解 + 控件定位 → 操作清单 JSON + 自动裁模板图
↓
③ 讨论确认 在对话里逐条核对（"清单可改"），AI 不会闷头写代码
↓
④ 生成配置 config.json（步骤 + 模板 + 延时 + 循环段）+ 自动做需求对账 + 模板体检
↓
⑤ 运行 离线模板匹配 + 键鼠回放；F8 强停、暂停/继续、切页自动暂停
还支持：视频直接投喂（不用录制窗口，甩个 mp4 走另一条流水线）、 OCR 文本定位（按钮带中文时比像素模板稳）、反应式闭环 （如塔防"巡检补塔"、钓鱼"溜鱼"这类需要看状态做动作的场景）、 拖动/长按（含用录制真值自动校准坐标）。
也内置了一套开发工具（改代码时用，不是运行时）：模板体检、按钮定位、 代码快照/回滚、模型代码审查、机械门禁、发布前体检。
📖 完整执行逻辑、19 个踩过的坑与解法、15 项优化的实测收益 → 见 PIPELINE.md
一句话：三条链路，一份 config，同一个引擎回放。
链路 A（主线）录制会话线 —— 有真实点击坐标，定位最准
录制（变化帧 + 真实键鼠）
→ 选帧（事件锚点 + 画面突变 + 阶段覆盖，≤18 张）
→ 第一问「分段理解」：阶段划分 + 漏段自查
→ 第二问「控件定位」：对每个点击单独求 bbox + 推荐模板帧
→ 自动裁模板 → analysis.json
→ 讨论确认（人工逐条核对清单）
→ 生成 config.json（真值校准 + 需求对账 + 自动模板体检）
→ 离线回放（0 token）
链路 B（支线）视频投喂线 —— 手上只有 mp4 时用
mp4 → 登记(sha256 内容寻址) → ffmpeg 切片(≤60s, 360p)
→ 逐片视频理解 → 回原片按时间戳抽帧取证 → 问 bbox → 裁模板
→ OpenCV 复核命中率（并区分"常驻 HUD"）→ 只放行复核通过的步骤 → config.json
链路 C（支线）反应式闭环 —— 无法用固定步骤表达时用
固定周期截屏 → 局部视觉判定 → 按键/点击 → 直到满足结束条件
例：fight_control（钓鱼溜鱼：HSV 找蓝区+小柱子 → 点 A/D）
guard_repair（塔防巡检：逐格判空 → 选塔 → 左键放置）
运行期 0 token：识别与生成用大模型，回放是纯本地的模板匹配 + 键鼠回放。
📖 详细版见 PIPELINE.md —— 逐阶段输入/输出/失败处理、 19 个踩过的坑（现象→根因→解法→验证）、15 项优化的实测收益、质量保证体系、已知限制。
🆕 第一次用（从 GitHub 下载/克隆的）→ 看 QUICKSTART.md —— 从解压到跑通的完整步骤、Key 去哪申请、常见问题（装依赖失败 / 录不到键鼠 / 点不到按钮）。 下面是速查版。
解压后双击 setup.bat —— 它会自动完成：
1) 检测 Python 3.12（没装就用 winget 装，或提示你手动装）
2) 建虚拟环境 agent_env/
3) 装依赖（直连失败会自动切清华镜像）
4) 生成 .env 并问你要不要现在填 Key
5) 跑 274 项自检 ← **全绿就是装好了**
:: 1) 装环境（需要 Python 3.12）
python -m venv agent_env
agent_env\Scripts\python.exe -m pip install -r requirements.txt
:: 2) 配 Key（填你自己的，见 .env.example 里的说明）
copy .env.example .env
notepad .env
:: 3) 自检（**强烈建议先跑这个**）
agent_env\Scripts\python.exe tools\run_all.py自检会跑 274 项验收（合成窗口/合成帧，不碰真实游戏、不消耗 API）。 全绿 = 环境没问题，可以开始用。
:: 启动对话 Agent（推荐入口）
agent_env\Scripts\python.exe vision_script_writer.py
:: 或直接开「游戏实验室」GUI
scripts\YourLab\启动游戏实验室.bat
:: 或单独开录制窗口（游戏是管理员权限时，必须用这个）
启动录制窗口(管理员).bat| 系统 | 仅 Windows（深度依赖 ctypes 取客户区 / pygetwindow 找窗口 / UIPI 提权读键鼠） |
| Python | 3.12（已在 3.12.7 验证） |
| API Key | 视觉 Key 必填（推荐阿里云百炼「按量计费」）；写手 Key 可选 |
| 其他 | 目标游戏建议窗口化 1280×720；游戏若是管理员启动，录制/运行也需管理员 |
- 客户区坐标系：全项目统一用「游戏画面那块」（客户区），不含标题栏和边框。
Windows 上
pygetwindow给的是外框（实测异环外框 1296×759，客户区正好 1280×720）—— 用外框会导致点击位置线性偏移（屏幕底部偏 ~38px）。项目已修正，见screen_geom.py。 - 模板体检：坏模板（纯色块/裁错）会让"点击位置不对"。生成配置时会自动体检，
报
bad_template（匹配不上）或not_discriminative（到处都命中）都必须处理。 - 平坦区域陷阱：
TM_CCOEFF_NORMED在低对比度区域会病态虚高（纯色块能到 1.000）， 所以判据模板要裁有纹理/边框的局部。 - 管理员权限：游戏以管理员启动时，普通权限程序采不到键鼠（Windows UIPI）——
录制窗口必须提权，否则
inputs.jsonl里点击坐标是空的。
vision_script_writer.py 对话 Agent（入口）：21 个工具，编排整条流水线
screen_capture.py 录屏采集（变化帧去重 + 操作瞬间强制补帧）
input_logger.py 键鼠采集（与帧时间轴对齐）
record_gui.py 录制按钮窗口
vision_analysis.py 两段式视觉分析（分段理解 → 控件定位）
screen_agent_generator.py 步骤 → config.json（含需求对账 + 真值校准）
requirement_gate.py 需求对账门禁（需求 vs 产物的机器化校验）
profile_notes.py 游戏档案（跨会话记住坑/标定值/失败记录）
template_check.py 模板体检
locate_button.py 按钮定位（OCR + 颜色连通域 + 邻帧验证）
snapshot.py 代码快照/回滚（改代码前的后悔药）
code_review.py 模型代码审查（带项目坑清单）
tools/ 验收测试 + 开发门禁（run_all.py 一把跑完）
scripts/YourLab/ 引擎（runner/actor/locate/ocr）+ GUI + 交付产物
├─ engine/ 步骤解释器、键鼠执行、找图、OCR
└─ profiles/<游戏>/ config.json + assets/ + requirement.json + notes.json
captures/ 录制会话（已 gitignore）
work/ 分析产物（已 gitignore）
:: 全部验收（改代码后必跑）
agent_env\Scripts\python.exe tools\run_all.py
:: 只跑相关验收（按改动文件自动挑）
agent_env\Scripts\python.exe tools\verify_change.py
:: 模板体检 / 按钮定位
agent_env\Scripts\python.exe template_check.py 异环_咖啡店营业
agent_env\Scripts\python.exe locate_button.py --frame frame_0191.jpg --session 20260914_181442 --text 领取
:: 代码快照（改核心代码前）
agent_env\Scripts\python.exe snapshot.py create "改 XXX 之前"
agent_env\Scripts\python.exe snapshot.py diff --lines 60
agent_env\Scripts\python.exe snapshot.py restore <快照id>
:: 发布前体检
agent_env\Scripts\python.exe tools\pre_release.py- 只支持 Windows，没有跨平台计划（桌面自动化的前提就是真实桌面）。
- 运行时要和游戏同一台机器（这不是云端服务）。
- 长录制有上限：喂给模型的日志约 10 万字符，密集操作约 9 分钟；超过会被截断
（会打警告）。建议按"一个可复现的闭环"录（几十秒~几分钟），循环用
config.loop。 - 需要 Key 才能用识别功能；录制、回放、OCR 是纯本地的，不需要 Key。
- 游戏自动化请遵守目标游戏的服务条款，自用风险自负。
MIT（见 LICENSE）