API 参考
Wingman 的脚本 SDK 以 Lua 为一等公民（默认启用，随主构建与 CI 测试），并提供 Python 作为可选后端（嵌入式 CPython + pybind11，默认关闭，需通过 WINGMAN_ENABLE_PYTHON=ON 显式启用）。两者共享同一套模块功能与 IScriptEngine 抽象。
为什么支持两种语言
Wingman 选择同时支持 Python 和 Lua，是为了满足不同用户的需求：
Python
适合用户：
- 有编程经验的开发者
- 需要处理复杂逻辑的自动化任务
- 需要调用第三方库（网络请求、数据处理等）
- 重视开发效率和代码可维护性
优势：
- 第三方库可直接经 pip 安装
- 类型友好：支持类型提示，IDE 自动补全完善
- 调试方便：成熟的调试工具和错误追踪
- 代码组织：支持模块、类、函数等完整面向对象特性
典型场景：
- 复杂的游戏辅助工具（需要网络同步、数据库存储）
- 需要调用 AI/视觉能力（OCR、ONNX 模型加载等）
- 团队协作开发的大型自动化项目
Lua
适合用户：
- 游戏玩家或轻度编程用户
- 需要快速编写简单脚本的场景
- 资源受限环境（嵌入式、低配置设备）
- 重视启动速度和内存占用
优势：
- 轻量级：解释器体积小（< 1MB），启动迅速
- 简单易学：语法简洁，上手快
- 部署方便：单文件脚本，无需依赖管理
- 游戏行业：许多游戏的宏系统使用 Lua，用户可能已熟悉
典型场景：
- 简单的挂机脚本
- 游戏内宏录制后的小幅修改
- 需要快速测试自动化想法
SDK 设计哲学
命名规范
两种语言遵循各自社区的最佳实践：
Python（snake_case）：
python
screen.get_pixel(x, y)
screen.find_image(path, region)
uia.find_button("确定")
http.post(url, data)Lua（camelCase）：
lua
screen.getPixel(x, y)
screen.findImage(path, region)
uia.find_button("确定")
http.post(url, data)注意：各模块以实际注册名为准。
screen/input/window等模块注册名为 camelCase，Python 绑层会自动提供 snake_case 别名；uia模块注册名本身为 snake_case（两种语言同名，Python 侧无 camelCase 形式）。
模块化设计
所有功能按模块划分，清晰明确：
| 模块 | 功能 | 典型用途 |
|---|---|---|
screen | 屏幕操作 | 截图、找图、取色 |
input | 输入模拟 | 鼠标点击、键盘输入 |
window | 窗口管理 | 查找窗口、激活窗口 |
process | 进程管理 | 启动游戏、检查进程 |
uia | UI Automation | 稳定的控件操作 |
http | 网络请求 | API 调用、数据同步 |
kv | 数据存储 | 保存脚本状态 |
一致性原则
两种语言的 API 在功能上完全对等，只是语法适应语言习惯：
相同功能，不同语法：
python
# Python
from wingman import screen
img = screen.capture()
result = screen.find_image("button.png", {"x": 0, "y": 0, "width": 1920, "height": 1080})
# result 为数组 [point, found]（point 为 {x, y} 对象）lua
local wingman = require("wingman")
-- Lua
local img = wingman.screen.capture()
local result = wingman.screen.findImage("button.png", {x = 0, y = 0, width = 1920, height = 1080})
-- result 为数组 {point, found}（point 为 {x, y} 对象）设计取舍
为什么不是 JavaScript / TypeScript
- 执行效率：V8 引擎体积大、启动慢
- 部署复杂：需要 node.js 环境，对普通用户门槛高
- 游戏冲突：许多游戏浏览器组件嵌入 JS 引擎，可能冲突
为什么不是 C# / .NET
- 运行时依赖：需要 .NET Runtime，部署不友好
- 编译步骤：用户需要编译，不符合脚本快速迭代的特性
- 学习曲线：对轻度用户过重
Python vs Lua 的性能
两种语言在实际使用中的特点：
Python 优势：
- 丰富的第三方库支持（numpy、pandas、requests 等）
- 成熟的开发工具和调试器
- 类型提示和 IDE 自动补全
- 适合处理复杂逻辑和大规模项目
Lua 优势：
- 解释器体积小，启动快
- 内存占用相对较低
- 语法简洁，脚本文件小
- 部署方便，无需额外依赖
建议：
- 简单脚本、快速原型 → Lua
- 复杂项目、需要第三方库 → Python
快速开始
Python
python
from wingman import screen, input
# 截屏（返回是否成功，图像存于内部缓冲区）
ok = screen.capture()
# 全屏找图（region 表；返回数组 [point, found]）
result = screen.find_image("button.png", {"x": 0, "y": 0, "width": 1920, "height": 1080})
if result[1]:
point = result[0]
input.click(point["x"], point["y"])Lua
lua
local wingman = require("wingman")
-- 截屏（返回是否成功，图像存于内部缓冲区）
local ok = wingman.screen.capture()
-- 全屏找图（region 表；返回数组 {point, found}）
local result = wingman.screen.findImage("button.png", {x = 0, y = 0, width = 1920, height = 1080})
if result[2] then
wingman.input.click(result[1].x, result[1].y)
end数据类型
查看 数据类型参考 了解 API 中使用的各种对象和数据结构。
API 模块
核心模块
基础操作模块，提供屏幕、输入、窗口、进程等核心功能。
- screen - 屏幕截图、像素查找、图像匹配
- input - 鼠标点击、移动、键盘输入
- window - 窗口查找、激活、获取信息
- process - 进程启动、查找、终止
- system - 系统信息获取
- uia - UI Automation 控件交互
视觉与 AI
计算机视觉与 AI 相关功能。
自动化系统
高级自动化编排功能。
- event - 事件订阅与发布系统
- fsm - 有限状态机（FSM）
- task - 任务编排与执行
- script - 脚本管理控制面（列举、启动/停止/重载、环境变量）
- notify - 通知系统（日志、Toast、Webhook、托盘意图）
- smarttrigger - 智能触发器
- bt - 行为树引擎
- hotkey - 全局热键监听（轮询式，Python 回调）
- systemwatch - 系统事件源：进程/窗口变化观察（轮询式，Python 回调）
网络
网络请求与通信。
序列化
数据序列化与格式转换。
数据存储
本地数据持久化与缓存。
辅助功能
辅助自动化脚本的工具模块。
- human - 人性化模拟（随机延迟、不规律输入）
- perf - 性能监控
- config - 配置管理
- verification - 验证码识别、TOTP
- gameprofile - 游戏配置档案
- debugger - 调试器
- util - 工具函数（sleep、随机数等）
- timer - 定时器（一次性/周期回调、sleep）
- file - 文件 IO（读写、移动复制、目录操作）
安全与加密
安全和加密相关功能。
- security - 安全模块
- crypto - 加密函数
- clipboard - 剪贴板读写
- macro - 宏录制与回放
- filewatcher - 文件系统监听
编排与协作
多实例协作和编排功能。
- orchestration - 编排控制
- inbox - 消息收件箱
- team - 组队编排
- node - 节点状态与心跳（文档在配置系统的「节点模块 (node)」节）
- script - 脚本管理控制面