Wingman游戏自动化可编程控制引擎

简介 ​

Wingman 是一个跨平台的游戏自动化工具。

• 基于 C++ 开发核心引擎，屏幕捕获与输入注入在原生层实现
• 支持 Lua 和 Python 两种脚本引擎，同一套 API
• 纯用户态运行，使用合法平台 API，安全可靠
• 支持远程编排，runtime agent 主动连接 Go server，由 Go server 统一中控
• 支持本地单机 UI，Tauri 通过本地 IPC 控制 runtime，不通过 runtime WebSocket/HTTP server

核心特性 ​

• 屏幕操作 - 截图、像素检测、颜色匹配、图像查找
• 输入模拟 - 鼠标点击/移动、按键发送、文本输入
• 窗口管理 - 查找窗口、激活窗口、获取位置
• UI Automation - 直接操作 Windows 控件，无需坐标定位
• 进程管理 - 启动/等待/终止进程
• 宏录制 - 录制鼠标键盘操作，自动回放
• 触发器系统 - 像素触发、定时触发、条件组合
• 编排层 - Runtime agent 主动连接 Go server，Dashboard 只连接 Go server
• 调试器 - VS Code 插件，断点调试、变量查看
• 拟人化输入 - 贝塞尔曲线、随机延迟、自然操作
• 存储系统 - 四层存储架构，支持本地和远程数据持久化
• 版本管理 - 动态版本信息，支持 nightly 构建

快速开始 ​

Lua 脚本 ​

local wingman = require("wingman")

-- hello.lua
-- 截图（capture 返回布尔：是否成功）
local ok = wingman.screen.capture()

-- 查找颜色（返回 {point, found} 两元组；区域用表：{x=, y=, width=, height=}）
local pt, found = wingman.screen.findColor(0xFF0000, {x = 0, y = 0, width = 1920, height = 1080}, 10)
if found then
    wingman.input.click(pt.x, pt.y)
end
-- 多点查找用 findColors（返回点数组）：wingman.screen.findColors(0xFF0000, region, 10, 0)

Python 脚本 ​

# hello.py
from wingman import screen, input

# 截图（capture 返回布尔：是否成功）
ok = screen.capture()

# 查找颜色（返回 [point, found] 两元组；区域用字典）
pt, found = screen.findColor(0xFF0000, {"x": 0, "y": 0, "width": 1920, "height": 1080}, 10)
if found:
    input.click(pt["x"], pt["y"])
# 多点查找用 find_colors（返回点数组）：screen.find_colors(0xFF0000, region, 10, 0)

Android Agent ​

Android 端侧 Agent（实验性，arm64 / Android 9.0+）：出站 TCP 连 Go 中控， 脚本 API 与桌面 runtime 同名同形（wingman.input / wingman.screen / wingman.vision），Dashboard 统一下发与查看。

能力清单

获取 APK

nightly Release 的 wingman-*-android-arm64.apk（debug 签名）： releases/tag/nightly 页 Assets 取最新一组的 wingman-<date>-nightly-<sha>-android-arm64.apk （每日构建仅保留当日最新；直链匿名下载，无需登录 GitHub）。

快速上手

1. 启动 Go server（orchestrator/server，Dashboard 端口 9527、agent 端口 8888）。

2. 手机安装 APK（与 server 同网段）→ 打开 App → 填服务器 IP / 端口 / 设备 ID → 「启动 Agent」。首次启动创建常驻通知（前台服务要求）；server 若配置了 WINGMAN_AGENT_TOKENS，需同时填入注册 Token。

3. Dashboard 的 Agent 列表出现该设备（platform=android），新建脚本 print('hello android') 运行到该设备，实时日志回传。

4. 启用 A2 能力：App 内「无障碍设置」打开注入服务 +「开启投屏」授权 （Android 14+ 每次重开投屏都会再弹授权，系统约束），随后下发找色/手势脚本：

   lua

   local pt = wingman.vision.findColor(0xE23B3B, 10)
   if pt then wingman.input.tap(pt.x, pt.y) end
   wingman.input.swipe(540, 1800, 540, 600, 400)

5. 远程截图：Dashboard workflow 加 screenshot 步骤选该设备 → 截图上屏。

6. Android 13+ 侧载无障碍被「受限设置」默认屏蔽：系统设置 → 应用 → Wingman Agent → ⋮ → 允许受限制的设置，或 scripts/android-restricted-settings.sh allow 预授权（App 内也有引导）。

详细验收步骤与已知边界见 apps/android/README.md， 设计与协议见 Android Agent 设计， 机型保活见 Android Agent 保活， 受限设置见 Android Agent 受限设置。

编译项目 ​

# 克隆仓库
git clone https://github.com/cuihairu/wingman.git
cd wingman

# Windows (MSVC + Ninja + vcpkg)
build-scripts\build-runtime-msvc-ninja.bat

# Linux (GCC/Clang)
cmake -B build -S . -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake \
    -DVCPKG_TARGET_TRIPLET=x64-linux

# macOS (Intel 用 x64-osx，Apple Silicon 用 arm64-osx)
cmake -B build -S . -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake \
    -DVCPKG_TARGET_TRIPLET=x64-osx

运行示例 ​

# CLI 运行时（Python 脚本同理，需启用 WINGMAN_ENABLE_PYTHON）
./build/apps/agent/wingman-agent script examples/lua_scripts/hello.lua

系统要求 ​

Windows ​

• Windows 10/11 (x64)
• Visual Studio 2022

macOS ​

• macOS 12+ (Monterey 或更高)
• Xcode 14+ 或 Clang

Linux ​

• Ubuntu 22.04+ 或等效发行版
• GCC 11+ 或 Clang 14+

通用 ​

• CMake 3.20+
• vcpkg

许可证 ​

Apache-2.0 License