MacroAI 使用说明

一、简介

MacroAI 是一款 Windows 桌面宏自动化工具。你可以通过录制操作、可视化节点编排或 Lua 脚本的方式，创建能自动执行鼠标点击、键盘输入、图像识别、OCR 文字识别、界面变化检测等操作的自动化流程。

适用场景： 办公自动化 · 软件测试 · 游戏辅助 · 运维管理 · RPA

二、快速上手 — 5 分钟体验

MacroAI 以项目为单位组织所有内容（节点、脚本、图片、录制的宏等），因此使用前必须先创建一个项目。

1. 新建项目

点击菜单 项目 → 新建项目（或按 Ctrl+N）：

1. 首次使用会引导选择工作目录（项目文件的存放位置）
2. 输入项目名称
3. 设定设计区域 — 宏操作的有效范围：
4. 全屏：以当前屏幕分辨率为范围
5. 自定义选择：鼠标拖拽框选一个窗口或区域

2. 认识主界面

主界面中央是 8 个标签页（Ctrl+1~Ctrl+8 切换），首次使用先关注这几个：

工具栏提供运行/停止、后台/前台模式切换、点击可视化（🔴）、调试模式（🐞）等控制项。底部状态栏显示运行状态。

3. 录制并回放宏

录制是创建宏最直接的方式——先录再改，快速出活：

1. 切换到宏管理标签页（Ctrl+7），点击 + 新建录制
2. 设计区域出现绿色边框，左下角有 「■ 停止录制」 按钮
3. 正常执行你想自动化的操作（点击、输入文字等）
4. 操作超出设计区域时边框闪烁红色提示，该操作不会被记录
5. 点击 「■ 停止录制」 结束录制
6. 弹出对话框，点击 保存到项目
7. 在宏列表中选中刚录制的宏，点击 ▶ 播放 即可回放

4. 用节点编辑器增强流程

录制的宏只能原样回放。想加入条件判断、循环、图像识别等逻辑？用节点编辑器：

1. 切换到节点编辑标签页（Ctrl+1）
2. 在左侧面板中点击 调用录制宏 节点，添加到流程中
3. 双击节点打开配置，选择刚才录制的宏
4. 在它前后添加其他节点（如等待、查找图像），打造更智能的自动化
5. 直接拖拽节点调整顺序，也可将节点拖入条件判断或循环中组合使用

节点编辑器的操作会自动生成脚本代码，可在代码编辑器中查看和手动修改。

5. 运行项目

点击 ▶ 运行（或按 F5）执行当前项目的节点工作流/脚本代码。点击 ■ 停止（或按 Shift+F5）随时终止。

提示：工具栏的 🐞 调试 模式开启后，日志会显示更详细的执行信息，方便排查问题。

三、核心能力

图像识别

在屏幕上查找指定图片并执行操作：

1. 在图像管理标签页（Ctrl+4）上传或截图保存模板图片
2. 在节点编辑器中添加 查找图像 节点
3. 配置：选择模板图片、搜索区域、匹配程度（默认 0.85）、匹配方式
4. 开启"启用点击"可在找到后自动点击；设置超时时间可让节点持续等待图像出现
5. 运行结果通过变量引用：result.center_x、result.center_y 等

OCR 文字识别

识别屏幕上的文字：

• OCR 识别：框选区域，识别其中的文字内容
• OCR 比对：判断指定文字是否出现在区域中，开启"启用点击"可自动点击
• 可在设置（Ctrl+,）中配置默认识别语言

界面变化检测

等待屏幕出现特定变化，常用于监控界面状态：

• 等待界面变化：检测指定区域内的内容变化。支持灵敏度调节、周期性变化过滤（如闪烁按钮）、超时设置
• 等待条块变化：追踪条块长短变化（血条、进度条）。支持自动识别横向/纵向、滚动条干扰过滤

键盘鼠标模拟

• 鼠标点击 / 鼠标移动 / 鼠标拖拽：支持坐标输入和变量引用，可直接框选获取坐标
• 按键 / 输入文本：模拟键盘操作，支持快捷键组合
• 坐标字段支持：直接输入数字、引用变量（如 result.center_x）、点击获取

流程控制

• 等待：在两个动作之间插入延迟（毫秒）
• 条件判断：根据条件（上一步成功/失败、自定义表达式）执行不同分支，可放入其他节点
• 循环：重复执行，可放入其他节点，支持跳出循环
• 调用函数：执行已定义的可复用子流程
• 调用录制宏：在节点流程中回放录制的宏

每个节点可设置执行条件（上一步成功时执行、上一步失败时执行、自定义表达式）。循环和条件判断可将其他节点放入其中组合使用，拖拽即可调整节点的层级和顺序。

变量与数据传递

在变量标签页（Ctrl+3）定义变量（名称、类型、默认值），节点配置中通过 ▼ 菜单插入引用：

音频与通知

• 播放音效：系统提示音、do~si 蜂鸣、自定义音频文件
• 播放音乐：常见格式的背景音乐，浮动面板自动显示控制按钮（暂停/继续/静音），播放音效时自动降低背景音乐音量
• 弹出提示：执行到指定步骤时显示通知消息

四、进阶功能

函数与自定义动作

函数：将一组节点打包成可复用的子流程，支持参数传递。在函数标签页（Ctrl+5）新建和编辑。

自定义动作：将函数绑定到浮动面板的一键按钮。在自定义动作标签页（Ctrl+6）中设置，运行宏时面板自动显示对应按钮。

区域与多分辨率适配

区域是屏幕上的命名矩形范围：

• 设计区域：创建项目时设定的基准坐标空间
• 运行区域：运行时实际对应的屏幕区域（可与设计区域不同）
• 自定义区域：自行命名的区域，可在节点配置中引用
• 坐标策略：决定坐标从设计区域映射到运行区域的方式

坐标策略

通过 项目 → 设置 → 区域设置（Ctrl+,）切换：

• 等比缩放 (uniform) — 游戏、全屏应用：坐标按设计/运行区域的宽高比例缩放。校准时自由框选，保持与设计区域相同的宽高比
• 平移适配 (desktop) — 浏览器、Office 窗口：坐标仅做平移偏移，不做缩放。校准时仅能调整位置，宽高固定等于设计区域

切换策略会影响所有已有坐标点的解释方式，切换时会有警告提示，可能需要重新调节已有坐标点。

校准运行区域

当脚本在一个分辨率下制作、在另一个分辨率下运行时（或窗口位置偏移时），点击菜单 项目 → 设置 → 区域设置 → 校准 重新设定运行区域：

1. 如果设计区域是全屏：自动将运行区域设为当前屏幕全屏，无需手动框选
2. 如果设计区域是自定义框选：
3. 等比缩放模式：拖拽框选运行区域，保持与设计区域相同的宽高比
4. 平移适配模式：鼠标点击或拖拽指定运行区域的位置（左上角），宽高固定等于设计区域

校准后，所有坐标自动按当前坐标策略重新计算，无需手动调整。

节点级覆盖

每个查找图像节点可独立设置坐标策略（Pro 功能）： - 跟随项目（默认） — 继承全局坐标策略 - 等比缩放 — 强制使用缩放模式 - 平移适配 — 强制使用平移模式

用于项目整体使用一种策略、个别节点因界面特性需要另一种策略的情况。

调试工具

• 🔴 点击可视化：开启后每次点击位置显示红色圆点（0.5 秒后消失），用于验证坐标
• 🐞 调试模式：开启后日志显示更详细的执行信息
• 日志输出 节点：在关键步骤后输出自定义日志信息

设置

点击菜单 项目 → 设置（Ctrl+,）打开设置面板：

• 工作目录：项目文件的默认保存位置
• 界面语言：中文 / English
• OCR 语言：选择文字识别的默认语言
• 自动保存：内容变化时自动写入磁盘

五、界面参考

浮动控制面板

运行宏时自动弹出，始终置顶，可拖拽移动：

系统托盘

关闭窗口时最小化到系统托盘，双击图标显示主窗口。托盘菜单：显示主窗口 / 运行当前宏 / 停止 / 退出。

快捷键速查

六、常见问题

录制的宏总是点偏位置？

创建项目时确保框选了正确的设计区域。换了显示器或调整了分辨率后，使用校准功能重新设定运行区域。

图像查找总是失败？

• 降低匹配阈值（默认 0.85，可试 0.7）
• 缩小搜索区域，提高查找速度和准确率
• 确保模板图片来源与运行环境一致
• 适当降低匹配阈值，找到准确率和宽容度之间的平衡

后台模式和前台模式有什么区别？

• 后台模式（默认）：在后台模拟操作，不干扰正常使用
• 前台模式：真实控制鼠标键盘，会抢占控制权

后台模式无效时可切换为前台模式，结合 🔴 点击可视化 验证坐标。

如何调试？

开启工具栏的 🐞 调试 模式查看详细日志，在关键步骤后添加日志输出节点，开启 🔴 点击可视化 观察点击位置。

代码编辑器和节点编辑器什么关系？

节点编辑器的操作自动生成 Lua 脚本代码，代码编辑器中可查看和手动编辑，两者双向同步。

Pro 功能如何激活？

当前所有 Pro 功能（高级视觉、通知与听觉、自定义代码）免费使用。状态可在"关于"页面查看。

七、演示项目

MacroAI 安装包内置了演示项目，帮助你快速了解软件功能。

内置演示项目：

导入方式：

• 首次设置工作目录时：系统会自动询问是否导入演示项目
• 手动导入：点击菜单 帮助 → 导入演示项目，随时将演示项目导入到当前工作目录

导入后，通过 项目 → 打开项目 即可查看和运行演示项目。你可以自由修改演示项目的脚本和节点，作为学习和二次开发的起点。

详细 API 参考请见菜单 帮助 → API 参考。