Skip to content
atoubootPublic

About

Visual, millisecond-precise cross-platform mouse macro automation for Windows and macOS

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

MouseFlow

可视化、多步骤、毫秒级精度的跨平台鼠标自动化工具。

CI Release License: MIT

MouseFlow 是一个开源桌面自动化工具,面向不写代码的用户。你可以通过可视化时间线添加鼠标点击、等待、移动、长按、滚轮和键盘步骤,设置每个步骤的独立延迟,保存、导入、导出并反复执行任务。

核心输入模拟、坐标采集、全局快捷键、宏录制和任务执行引擎全部由 Rust 实现。前端只负责编辑和展示,因此长时间等待不会阻塞界面。

截图

MouseFlow 任务编辑器

MouseFlow 快捷键设置

截图来自浏览器预览模式,因此顶部显示“浏览器预览”提示。桌面版本会启用真实系统输入。

功能

可视化任务编辑器

  • 任务库:新建、重命名、复制、删除、搜索、导入 JSON、导出 JSON。
  • 步骤时间线:拖动排序、启用/禁用、复制、删除、在任意位置插入、单独测试。
  • 七种步骤:
    • 鼠标点击:X/Y、左/右/中键、点击次数、点击间隔、前置/后置等待。
    • 等待:1 ms 到 24 小时,支持常用预设和任意毫秒值。
    • 鼠标移动:目标坐标、持续时间、平滑插值。
    • 鼠标按下 / 松开:长按、拖拽和跨步骤组合。
    • 滚轮:可选坐标、垂直和水平滚动。
    • 键盘:按下、松开、Unicode 文本输入、组合键。
  • 属性面板:所有字段实时写回当前任务内存状态。
  • 底部执行控制台:开始、暂停、恢复、停止、循环设置、启动延迟、定时启动、执行进度和毫秒日志。

任务执行引擎

  • 严格按时间线顺序执行。
  • 每个点击步骤拥有独立的前置等待、点击间隔和后置等待。
  • 启动延迟与任务内部 Delay 完全独立。
  • 单次、指定次数、无限循环。
  • 循环间固定休息 + 可选随机额外休息。
  • 可选总执行时长上限。
  • 可取消的异步执行,不阻塞 UI。
  • 暂停会冻结当前步骤和剩余等待时间;恢复后继续。
  • 停止会立即取消后续步骤,并释放所有由 MouseFlow 按下的鼠标键和键盘修饰键。
  • 单实例执行保护:运行期间再次启动会被拒绝。
  • 异常自动停止并输出错误日志。
  • 应用关闭时安全终止任务并释放输入。
  • 最小化或切到后台后继续执行;macOS 使用 App Nap 活动断言,Windows 在任务期间请求 1 ms 定时器分辨率。
  • 关闭窗口前执行最终保存,避免最后几毫秒的编辑丢失。

坐标采集

  • 在任意支持坐标的步骤中点击“采集当前鼠标坐标”。
  • 进入采集模式后,将鼠标移动到目标位置并按 F8。
  • 自动读取坐标和所在显示器,并写回当前步骤。
  • 支持多显示器、负坐标、不同 DPI、Retina 缩放。
  • 内置桌面坐标预览图,显示显示器布局、目标点、当前指针和缩放信息。

宏录制

  • 录制鼠标左键、右键、中键、滚轮、键盘按下/松开和动作间隔。
  • 自动把短按合并为点击,把长按转换为 MouseDown → Delay → MouseUp。
  • 合并双击和相邻滚轮事件。
  • 停止后生成与手动创建完全相同的任务数据结构。
  • 录制结果可以继续拖动排序、修改坐标、插入等待或调整按键。

快捷键

默认快捷键:

功能 默认快捷键
开始 / 恢复 F6
暂停 F7
采集坐标 F8
停止 F9
开始 / 停止录制 F10
紧急停止 CommandOrControl+Shift+F9

所有快捷键都可以在“设置 → 快捷键”中自定义。快捷键冲突或格式错误会在界面中显示具体原因。

数据安全

  • 版本化 JSON 数据格式(当前 version: 1)。
  • 原子写入,避免半写入文件。
  • 自动备份,默认保留最近 30 份。
  • 主数据损坏时自动尝试从最新有效备份恢复。
  • 恢复备份前保留当前数据副本。
  • 导入时逐步骤容错:无效步骤被跳过并显示警告,不会导致整个应用崩溃。
  • 导入的任务不会自动执行。

安装

从 Releases 下载:

  • macOS Apple Silicon:MouseFlow_*_aarch64.dmg
  • macOS Intel:MouseFlow_*_x64.dmg
  • macOS Universal:MouseFlow_*_universal.dmg
  • Windows x64:NSIS .exe 安装程序
  • Windows x64:MSI 安装程序(构建环境支持时)

macOS 首次打开

当前 Release 没有 Apple Developer 签名和公证。首次打开可能被 Gatekeeper 阻止:

  1. 在 Finder 中右键 MouseFlow.app,选择“打开”。
  2. 如果仍被阻止,进入“系统设置 → 隐私与安全性”,选择“仍要打开”。
  3. 也可以移除下载隔离标记:
xattr -dr com.apple.quarantine /Applications/MouseFlow.app

Windows SmartScreen

未签名安装包可能触发 SmartScreen。点击“更多信息 → 仍要运行”。企业设备上的安全软件也可能拦截全局钩子或 SendInput,请按组织策略处理。

系统权限

macOS

MouseFlow 需要:

  • 辅助功能(Accessibility):发送鼠标和键盘事件。
  • 输入监控(Input Monitoring):录制全局鼠标和键盘事件。

授权路径:

  1. 打开 MouseFlow。
  2. 进入“设置 → 权限”。
  3. 点击“请求系统权限”或“打开系统设置”。
  4. 在“系统设置 → 隐私与安全性”中勾选 MouseFlow。
  5. 输入监控权限变更后通常需要重启 MouseFlow。

MouseFlow 当前不捕获屏幕内容,因此不需要“屏幕录制”权限。

Windows

  • 普通桌面无需额外权限。
  • MouseFlow 使用 Per-Monitor DPI Awareness 和 Windows 虚拟桌面坐标。
  • 如果目标程序以管理员身份运行,Windows UIPI 会阻止普通权限进程向它发送输入。请以相同权限运行 MouseFlow。
  • 部分安全软件可能拦截 SendInput 或低级输入钩子。发生错误时 MouseFlow 会显示系统错误码和权限建议。

更详细说明见 docs/PERMISSIONS.md。

快速使用

创建一个三点点击任务

  1. 点击“新建任务”。
  2. 点击“添加步骤 → 等待”,设为 500 ms。
  3. 添加“鼠标点击”,点击“采集当前鼠标坐标”,将鼠标移到 A 点,按 F8。
  4. 继续添加等待 2000 ms 和 B 点点击。
  5. 再添加等待 3000 ms 和 C 点点击。
  6. 在底部控制台设置循环次数、循环休息和启动延迟。
  7. 点击“开始”,或按 F6。

执行顺序严格为:

Delay 500ms
Click A
Delay 2000ms
Click B
Delay 3000ms
Click C

暂停与停止

  • F7:暂停。当前步骤和剩余等待会冻结。
  • F6:恢复。
  • F9:停止。立即取消后续步骤并释放按下的鼠标键。
  • CommandOrControl+Shift+F9:紧急停止。

录制宏

  1. 点击右上角“录制宏”或按 F10。
  2. 执行鼠标点击、滚轮和键盘操作。
  3. 按 F10 或点击停止按钮。
  4. MouseFlow 会创建一个新的可编辑任务。

建议使用 F10 停止录制,以避免把停止按钮本身的点击录入任务。

坐标系统

MouseFlow 不假设所有平台使用同一种坐标单位。它使用统一的“平台原生桌面坐标”抽象:

  • macOS:CoreGraphics 全局显示坐标,单位为逻辑点;Retina 缩放由系统处理。
  • Windows:虚拟桌面物理像素;进程使用 Per-Monitor V2 DPI Awareness。
  • 坐标采集和输入模拟调用同一平台的同一套 API。
  • 负坐标和副屏坐标原样保存,不做不安全的归一化转换。

详细设计、测试点和手动验证矩阵见 docs/COORDINATES.md。

数据存储

任务数据保存在应用数据目录:

mouseflow-data.json
backups/
  mouseflow-YYYYMMDD-HHMMSS-mmm.json

可以在“设置 → 数据与备份”中打开数据目录、立即备份或恢复历史备份。

单任务导出格式:

{
  "version": 1,
  "exportedAt": "2026-11-11T12:00:00Z",
  "task": {
    "id": "uuid",
    "name": "示例任务",
    "steps": [],
    "execution": {
      "startMode": "immediate",
      "loopMode": "once"
    }
  }
}

导入器兼容旧版 snake_case 字段,并会为导入任务生成新的任务 ID,避免覆盖现有任务。

技术架构

React + TypeScript + Tailwind
          │ Tauri IPC
          ▼
Rust commands / hotkeys / storage
          │
          ▼
Rust execution engine (Tokio)
          │ InputSink
          ▼
macOS CoreGraphics          Windows SendInput + hooks

关键设计:

  • 引擎只依赖 InputSink 和 RunObserver trait,可用模拟输入和观察者做确定性测试。
  • 输入模拟、坐标采集、显示器枚举、全局录制分别放在平台模块中。
  • 暂停/恢复/停止使用取消令牌、原子状态和异步通知,不使用阻塞主线程的 sleep。
  • 日志与状态通过 Tauri 事件推送到前端;前端不会参与真实步骤计时。

更多细节见 docs/ARCHITECTURE.md。

从源码构建

依赖

  • Node.js 22+
  • Rust 1.90+
  • macOS:Xcode Command Line Tools
  • Windows:Visual Studio 2022 Build Tools(Desktop development with C++)
  • Tauri 2 所需系统依赖

安装与开发

npm ci
npm run tauri:dev

仅预览 UI:

npm run dev

浏览器预览模式不会发送真实输入,也不能录制宏。

构建安装包

npm run tauri:build

macOS 构建 Apple Silicon、Intel 或 Universal:

rustup target add aarch64-apple-darwin x86_64-apple-darwin
npm run tauri:build -- --target aarch64-apple-darwin --bundles app dmg
npm run tauri:build -- --target x86_64-apple-darwin --bundles app dmg
npm run tauri:build -- --target universal-apple-darwin --bundles app dmg

Windows:

npm run tauri:build -- --bundles nsis msi

测试

# 前端状态、坐标预览
npm test

# 格式、静态检查和构建
npm run lint
npm run format:check
npm run build

# Rust 单元测试 + 集成测试
cd src-tauri
cargo test --all-targets

# 严格 lint
cargo clippy --all-targets -- -D warnings

实际鼠标测试是独立、显式启用的硬件冒烟测试:

cd src-tauri
cargo run --example hardware_smoke
cargo run --example hardware_smoke -- --execute

该测试不会替你选择危险目标;只有同时传入 --execute --click 才会点击当前指针位置。测试分类和手动验证矩阵见 docs/TESTING.md。

CI / Release

  • .github/workflows/ci.yml:每次推送和 PR 运行前端检查、Rust 格式检查、Clippy、单元/集成测试,并编译 macOS/Windows 桌面应用。
  • .github/workflows/release.yml:推送 v* 标签时并行构建 macOS ARM64、Intel、Universal DMG 和 Windows NSIS/MSI,并上传到 GitHub Release。

版本号同步:

npm run version:set -- 0.2.0

该命令同步 package.json、package-lock.json、Cargo.toml、Cargo.lock 和 tauri.conf.json。

已知限制

  • 当前 Release 未签名、未公证,首次打开需要手动允许。
  • macOS 输入监控权限修改后可能需要重启应用。
  • Windows 无法向更高权限进程注入输入,除非 MouseFlow 也以相同权限运行。
  • 录制是全局输入监听,不同操作系统的权限模型不同;权限不足时会返回具体错误。
  • 当前不包含屏幕捕获、图像识别或 OCR。
  • 自动化任务可能点击真实桌面上的危险控件。请在受控环境中测试任务,并使用停止/紧急停止快捷键。

项目结构

.
├── src/                         React UI
│   ├── components/              editor, inspector, console, dialogs
│   ├── hooks/                   autosave, events, desktop snapshot
│   ├── lib/                     API adapter, task IO, coordinates, steps
│   └── store/                   Zustand editor state
├── src-tauri/
│   ├── src/
│   │   ├── engine.rs            async execution engine
│   │   ├── models.rs            versioned task data + validation
│   │   ├── platform/            macOS CoreGraphics / Windows SendInput
│   │   ├── recording.rs         raw input -> editable steps
│   │   ├── storage.rs           atomic JSON + backups
│   │   └── hotkeys.rs           global shortcuts
│   ├── examples/hardware_smoke.rs
│   └── tests/                   Rust integration tests
├── docs/                        architecture, permissions, testing
└── .github/workflows/           CI and release pipelines

开源协议

MIT © 2026 MouseFlow Contributors


English summary

MouseFlow is an MIT-licensed, visual desktop macro automation tool for Windows 10/11 and macOS 12+. It provides a drag-and-drop multi-step editor, per-step millisecond delays, global hotkeys, multi-monitor coordinate capture, macro recording, safe cancelable execution, versioned JSON persistence, and automatic backups. The Rust engine owns timing and native input; React never blocks on long waits. Release installers are unsigned and may require first-launch approval.

About

Visual, millisecond-precise cross-platform mouse macro automation for Windows and macOS

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages