MacroAI 设计者指南

一、简介

MacroAI 是一款支持脚本创作与分发的 Windows 宏自动化平台。

通过可视化节点编辑器（20+ 种节点，树形容器架构）或 Lua 脚本搭建自动化流程，覆盖鼠标键盘、图像识别、OCR 文字识别、屏幕变化检测等操作。内置多分辨率适配机制，同一脚本可在不同屏幕和缩放比的设备上稳定运行——这是脚本可分发给他人使用的核心能力。

支持后台输入模拟（不抢占焦点）、Windows OCR（零安装）、屏幕变化检测和多线程并发执行。基础功能永久免费，无广告。

核心流程：设计者制作脚本 → 导出分发包 → 使用者导入运行。

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

二、快速上手

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

1. 新建项目

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

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

2. 认识主界面

主界面中央是 9 个标签页（Ctrl+1~Ctrl+9 切换）：

工具栏提供模式切换（🔧设计/🏃运行）、运行/停止、后台/前台、点击可视化（🔴）和日志级别控制等。

3. 录制并回放宏

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

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

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

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

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

节点编辑器的操作会自动生成脚本代码，可在代码预览中查看（当前为只读，由节点编辑器单向同步）。

5. 运行项目

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

三、设计模式与运行模式

MacroAI 引入双模式机制，将设计者和使用者的界面彻底分离。

3.1 两种模式

3.2 切换方式

工具栏上的 模式切换下拉菜单（🔧 设计 / 🏃 运行）一键切换，两种模式始终可见。

• 新建项目 → 默认进入设计模式
• 导入普通项目 → 恢复上次使用的模式
• 导入分发包 → 自动进入运行模式（设计模式入口灰色不可点击）

3.3 设计模式（创作脚本）

设计模式拥有完整的编辑能力：

• 9 个标签页覆盖节点编辑、代码、变量、图像、函数、自定义动作、宏、区域、用户配置
• 菜单 项目 → 项目设置 打开设置对话框
• 日志以独立窗口显示

3.4 运行模式（使用者视角）

运行模式为使用者提供精简的运行界面，隐藏所有编辑工具：

• 项目信息区：显示项目名称、设计分辨率、坐标策略和项目描述（可折叠）
• 区域校准卡片：醒目显示运行区域状态，提供校准按钮（始终可见）
• 个性化配置区：使用者填写设计者定义的用户配置变量（详见第五章）
• 配置完整度指示器 🟢🟡🔴：在工具栏实时反映配置状态
• 运行日志：底部可折叠面板，运行时自动展开

3.5 分发包机制

设计者导出项目时，可选择标记为分发包：

• 分发包导入后默认进入运行模式，设计模式入口灰色不可点击
• 此标记用于标识项目来源，为未来功能（如加密导出、权限控制）预留
• 设计者在自己机器上创建的项目无此标记

四、核心能力

图像识别

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

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

节点类型：

三种匹配模式：灰度（经典，速度快）、感知亮度（抗光照变化）、OKLab 色彩（抗色偏，模板无需重新截图）。

OCR 文字识别

识别屏幕上的文字：

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

界面变化检测

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

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

颜色检测

• 获取颜色：获取指定位置的颜色值
• 查找颜色：在区域内搜索指定的颜色
• 主色调检测：分析指定区域的主色调

键盘鼠标模拟

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

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

流程控制

每个节点可设置执行条件（上一步成功/失败、自定义表达式）。拖拽即可调整节点顺序和层级。

变量与数据传递

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

变量作用域分为 local（当前脚本可见）和 global（跨脚本共享）。

音频与通知

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

五、用户配置变量

设计者通过用户配置变量，让使用者在无需接触脚本的情况下完成个性化设置。

5.1 概念

用户配置变量（UserConfigVar）允许设计者定义一些"空位"，使用者在运行前填入自己的值：

5.2 定义变量

在用户配置标签页（Ctrl+9）中管理变量定义：

1. 点击 + 新增 打开编辑对话框
2. 填写变量ID（自动添加 uc_ 前缀）、标题、说明文字
3. 选择类型：文本或图像
4. 设置默认值（作为使用者的参考示例）
5. 对于图像类型，可勾选"允许多图"

5.3 在节点中引用

在节点配置对话框中，通过 ◎ 按钮弹出三段式菜单：

变量段
  my_var (变量)
  other_var (变量)
───
参数段
  param1 (参数)
───
用户配置段
  🖼 你的头像 (uc_avatar)
  📝 消息内容 (uc_message)

选中后字段中插入 u|var_id 格式的引用，运行时引擎自动解析为使用者配置的实际值。

5.4 类型详解

5.5 使用者视角

使用者在运行模式的个性化配置区中看到这些变量：

• ✅ 已个性化：使用者已填写自己的值
• ⚠️ 使用默认值：未修改，使用设计者的示例值
• ❌ 未设置：无值且无默认值（仅影响必填项）

所有修改实时保存。

六、导出与分发

6.1 导出项目

点击菜单 项目 → 导出（Ctrl+E）：

1. 选择导出路径
2. 填写版本号
3. 勾选"标记为分发包"：导出的项目导入后默认进入运行模式
4. 不勾选则导出普通项目，使用者导入后可切换设计模式查看编辑

6.2 分发包 vs 普通项目

6.3 分发最佳实践

1. 撰写详细的项目描述：在项目设置中填写说明文字，帮助使用者了解脚本用途
2. 设计友好的用户配置变量：使用清晰的显示名和说明，提供合理的默认值
3. 测试分发包：导出前先在本地测试，确保所有 u| 引用正确
4. 注意图片资源：确保分发包包含所有必需的模板图片
5. 版本管理：导出时填写版本号，方便使用者识别更新

七、日志级别控制

工具栏提供三级日志控制，帮助排查问题：

追踪模式输出示例：

[图像查找] 找到「头像」位置=(520,340) 相似度=0.95
[鼠标点击] 点击 (520,340) 左键
[鼠标移动] 移动到 (100,200)
[输入文本] 输入「你好」
[等待]     等待 500ms
[条件判断] 条件: result.success → true
[循环]     循环开始 (次数: 10)
[OCR识别]  识别结果: "hello" 置信度: 0.92
[颜色检测] ✓ 找到匹配颜色
[设置变量] my_var = hello
[弹出提示] 操作完成 (3s)
[等待界面变化] ✓ 检测到变化 3 处

设计模式下日志以独立窗口显示，运行模式下日志以底部折叠面板显示，运行时自动展开，运行结束后可手动收起。

八、进阶功能

函数与自定义动作

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

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

区域与多分辨率适配

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

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

坐标策略

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

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

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

校准运行区域

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

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

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

每个查找图像节点可独立设置坐标策略，覆盖项目全局设定（跟随项目/等比缩放/平移适配）。

调试工具

• 🔴 点击可视化：开启后每次点击位置显示红色圆点（0.5 秒后消失），用于验证坐标
• 日志级别控制：切换简洁/追踪/调试三级
• 日志输出 节点：在关键步骤后输出自定义日志信息

设置

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

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

九、界面参考

工具栏

[ 🔧 设计 ▼ ]  [▶ 运行]  [■ 停止]  [🔄 后台]  [🔴 点击可视化]  [🐞 调试: 简洁 | 追踪 | 调试]

• 模式切换：下拉菜单，设计模式/运行模式一键切换
• 运行/停止：执行或终止当前项目
• 后台/前台：切换输入模拟方式
• 点击可视化：显示点击位置的红色圆点
• 日志级别：三段按钮控制日志输出详细程度
• 配置完整度指示器（运行模式）：🟢 就绪 / 🟡 部分默认 / 🔴 待校准

9 个标签页

浮动控制面板

运行宏时自动弹出，始终置顶，支持拖拽。提供暂停/继续、自定义动作按钮、背景音乐控制（播放音乐时显示），可关闭面板停止执行。

系统托盘

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

快捷键速查

十、常见问题

录制的宏总是点偏位置？

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

图像查找总是失败？

• 降低匹配阈值（默认 0.85，可试 0.7）
• 缩小搜索区域，提高查找速度和准确率
• 确保模板图片来源与运行环境一致
• 尝试切换匹配模式（灰度/感知亮度/OKLab 色彩）

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

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

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

如何调试？

使用工具栏的日志级别控制切换到追踪或调试级别查看详细日志，在关键步骤后添加日志输出节点，开启 🔴 点击可视化 观察点击位置。

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

节点编辑器的操作自动生成 Lua 脚本代码，可在代码预览中查看（只读），由节点编辑器单向同步。

如何让使用者可以个性化配置？

在用户配置标签页（Ctrl+9）中定义配置变量，在节点配置中通过 ◎ 菜单引用（格式为 u|var_id），导出时标记为分发包。使用者在运行模式中即可填写。

分发包和普通项目有什么区别？

分发包导入后默认进入运行模式（设计模式入口灰色不可点击），普通项目恢复上次使用的模式（可自由切换）。导出时通过勾选"标记为分发包"决定。

十一、演示项目

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

内置演示项目：

首次设置工作目录时系统会自动询问是否导入，或通过菜单 帮助 → 导入演示项目 随时导入。

导入后通过 项目 → 打开项目 即可查看和运行，可作为学习和二次开发的起点。

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

问题反馈： 使用中如遇到程序报错或有任何建议，请发送邮件至 macroai@sowe.com。我们期待您的反馈！