MacroAI 设计者指南

一、简介

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

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

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

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

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

二、快速上手

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

1. 新建项目

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

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

2. 认识主界面

主界面中央是 10 个标签页：

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

3. 录制并回放宏

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

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

录制会自动区分点击与拖拽：按下后鼠标位移超过 8 像素记为一次拖拽（列表显示为 🖱 拖拽 (起点) → (终点)），小幅手抖仍算普通点击，滑动滑块、框选、拖动窗口这类操作不会再丢失。右键和中键同样支持。

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

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

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

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

5. 运行项目

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

三、设计模式与运行模式

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

3.1 两种模式

3.2 切换方式

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

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

3.3 设计模式（创作脚本）

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

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

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

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

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

3.5 分发包机制

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

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

四、核心能力

图像识别

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

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

图像管理中还提供匹配检测：选一张模板图对当前屏幕实际执行一次匹配，弹窗展示命中位置与相似度，用于快速验证模板质量。检测范围默认取当前校准区域（或全屏），Pro 用户可在下拉中改用运行区域库条目（多开时逐个验证各窗口的模板命中情况）。

节点类型：

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

OCR 文字识别

识别屏幕上的文字：

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

界面变化检测

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

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

颜色检测

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

键盘鼠标模拟

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

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

流程控制

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

变量与数据传递

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

变量分两种，靠"变量名"的填法区分，不需要切换开关：

局部变量的准确规则：

• 可见范围：同一块内随便用；循环/条件内部的变量，外面读不到（Lua 语法如此）。要循环外用，必须在循环外先建一个同名变量。
• 跨函数不可见：函数 A 里的局部变量，函数 B 读不到（会得到 nil）。函数之间传值请用参数和返回值，跨动作请用全局变量。
• 同一块内可重复赋值：生成的是 local count = 0（首次）后接 count = count + 1（后续），是更新同一个变量，不会出现"赋值后读不到旧值"。
• 别和函数参数重名：函数参数会遮蔽同名的局部变量。
• 代码预览里若出现 -- 警告: 局部变量 'x' 未在本作用域声明…，说明你引用了作用域外的变量，运行时会得到 nil。

局部变量可以跳过"读取变量"节点，直接在下游节点的 fx 表达式里写名字引用。

音频与通知

• 播放音效：系统提示音、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. 选择导出路径，导出为 .macroai 项目包
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）新建和编辑。可填写函数说明，函数列表和"调用函数"节点标题上会一并显示，方便区分用途相近的函数。

函数返回值：函数内用返回节点返回值。

• 调用函数节点的"返回值变量"（新建时默认填 call_result）决定是否接收返回值。留空则不接收；填了名字，同函数内的后续节点就按这个名字引用（fx 表达式、自定义代码、条件判断都行）。
• 返回值是 Lua 局部变量，仅在同一函数内可见。要跨函数或跨动作传递，请改用全局变量。
• 业务失败：任务直接调用的那个函数（入口函数）返回 false 时，判定为业务失败 —— 这次执行不计完成次数，并按失败重试机制自动重试。返回 true 或其他值算成功；不写返回节点（返回 nil）则维持原行为，按技术层判定（没报错就算成功）。

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

列表按"面板按钮 → 独立悬浮 → 不显示"分组展示（组内可拖拽排序）。动作改名会自动同步到引用它的周期任务；删除被任务引用的动作时会弹出确认提示。

周期任务系统（Pro）

在任务标签页定义项目内的周期任务（如"每日签到""每 2 小时提醒喝水"），运行期由浮动面板的任务区展示进度并按策略提醒：

• 任务定义：名称、关联的自定义动作（留空则为纯提醒任务）、启用开关
• 周期：每日 / 每周（可选重置日）/ 每月，并可设置重置时刻（如游戏日常设凌晨 4 点）；每日任务可单独设结束时刻
• 目标次数：每周期目标次数（0 = 不限，仅统计）
• 提醒：新周期开始提醒，以及固定时间点（如 08:00、20:00）或固定间隔（分钟）两种提醒模式
• 到期执行方式：仅提醒（默认）或自动执行——到点自动运行绑定的动作，使用者无需在场

任务在 空闲 → 等待中 → 待运行 → 运行中 → 已完成/结束未完成 之间流转，界面遵循"实心 = 有结果，空心 = 没结果"的形态语义。任务绑定的动作被删除后进入动作缺失警示覆盖态（红色空心 + ⚠）：进度保留、提醒暂停、不自动删除，重选动作后无缝恢复。

任务标签页提供执行日志（保留 2 天），记录每次到期触发、排队与执行结果，便于回答"到点为什么没执行"。使用者侧的运行体验见《使用者手册》第五章。

区域与多分辨率适配

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

• 设计区域：创建项目时设定的基准坐标空间
• 运行区域：运行时实际对应的屏幕区域（可与设计区域不同）
• 自定义区域：自行命名的区域，可在节点配置中引用
• 运行区域库（Pro）：保存多套命名运行区域（如多个模拟器窗口），供自定义动作和匹配检测绑定引用
• 坐标策略：决定坐标从设计区域映射到运行区域的方式

坐标策略

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

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

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

校准运行区域

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

1. 如果设计区域是全屏：自动将运行区域设为当前屏幕全屏，无需手动框选
2. 如果设计区域是自定义框选：
3. 等比缩放模式：拖拽框选运行区域，选框自动锁定与设计区域相同的宽高比
4. 平移适配模式：自由框选运行区域的位置和大小

框选选框全程白色高亮，支持 8 个控制点调整大小、框内拖动移动、框外点击重框。所有框选入口（校准、区域库、自定义动作区域、修改区域）交互一致。

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

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

自动识别运行区域

不想手动框选？软件可基于项目中的模板图片自动识别当前界面上的运行区域：

• 三处入口：菜单 工具 → 自动识别运行区域、项目 → 设置 → 区域设置、区域标签页的 ⌖ 自动识别入库（直接存入运行区域库）
• 置信度较低时会给出警告式提示，建议人工确认结果
• 识别结果可用于校准运行区域，或作为运行区域条目入库

运行区域库与区域引用（Pro，多开场景）

在区域标签页管理运行区域库（免费版可见但锁定编辑）：

• + 运行区域：框选并命名保存一组屏幕区域
• ⊞ 网格生成：按行列批量生成等分区域（如 4×2 生成八个模拟器窗口区域）
• ⌖ 自动识别入库：自动识别当前界面并保存为条目
• 条目支持修改（预置原选框）与删除

运行区域条目可被自定义动作和图像管理的匹配检测绑定引用——同一项目在多个窗口运行（多开）时，各自动作可使用各自的运行区域。

调试工具

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

设置

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

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

九、界面参考

工具栏

[ 🔧 设计 ▼ ]  [▶ 运行]  [■ 停止]  [🔄 后台模式]  [🔴 点击可视化]  [🐞 简洁调试 ▼]  [🎬 录制脚本]

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

10 个标签页

浮动控制面板

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

系统托盘

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

快捷键速查

十、常见问题

录制的宏总是点偏位置？

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

图像查找总是失败？

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

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

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

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

如何调试？

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

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

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

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

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

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

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

任务系统为什么是锁定的？

任务系统和运行区域库均为 Pro 功能：免费版中「任务」标签页与区域标签页的运行区域库按钮呈锁定占位，已创建的定义数据保留，升级后无缝续用。

改了或删了自定义动作，任务会受影响吗？

动作改名会自动同步到引用它的任务；删除被任务引用的动作时会弹出确认提示。删除后任务进入"动作缺失"警示态（红色空心 + ⚠）：进度保留、提醒暂停、不自动删除，重新绑定动作后无缝恢复，也可在编辑对话框中改为纯提醒任务。

同一脚本想适配多个模拟器窗口（多开）怎么办？

使用运行区域库（Pro）：把每个窗口的屏幕区域保存为条目（可框选、网格生成或自动识别入库），再在自定义动作和匹配检测中分别绑定引用，各窗口按各自的运行区域执行。

十一、演示项目

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

内置演示项目：

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

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

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

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