MagicMouseHelper

免费开源的 macOS 鼠标增强工具。Swift / SwiftUI，无第三方依赖，MIT 许可证。

功能

• 菜单栏面板与独立设置窗口
• 垂直、水平滚动分别反转与调速（0.25–4 倍）
• 禁用水平滚动，减少误触
• Option + 左键模拟中键，支持配对拖动、松开
• Shift 临时绕过增强，保留原始输入
• 根据前台应用 Bundle ID 排除增强
• 总开关、暂停监听、重试、恢复默认
• 自动保存本地设置
• 权限提示、观察事件计数、最近事件类型

开始使用

1. 使用 Xcode 27.1 打开 MagicMouseHelper.xcodeproj，选择 My Mac 运行。
2. 在设置窗口调整所需功能。首次运行所有转换默认关闭，速度为 1 倍。
3. 点击「辅助功能设置」，自行将当前运行的 MagicMouseHelper 添加到辅助功能列表并授权。
4. 回到应用点击「启动 / 重试」。状态显示「事件监听已运行」后生效。
5. 点击菜单栏鼠标图标也能打开控制面板；退出应用即可停止监听。

目前沿用 macOS 27.0 部署目标，仅验证 Apple Silicon。本地运行无需付费开发者订阅。尚未提供经过公证的发布安装包。

范围与限制

公开事件 API 无法提供本工具所需的可靠物理设备区分，因此增强可能同时影响触摸板、其他鼠标与惯性滚动。 不使用私有 Multitouch API，不提供手指数、触摸区域或任意轻点手势识别。 滚动倍率处理系统输出的滚动值；不额外叠加平滑或惯性算法。 速度低于 1 倍时，整数滚动值可能出现取整；具体应用响应仍需实机验证。 系统禁用事件监听时会停止增强，并提示重试，不会静默重新开启。

为实现全局事件修改，本项目关闭 App Sandbox；仍须通过 macOS 辅助功能授权。应用仅观察滚动、左键点击与拖动，不记录键盘文字，不联网。 排除应用按 Bundle ID 完整匹配，支持换行、空格或逗号分隔。

验证

见 VALIDATION.md。Tests/EngineChecks.swift 可独立编译并验证逻辑与构造的 CGEvent；测试不会安装全局监听或向系统发送输入。 已在本机开启辅助功能权限，并验证监听启动、暂停与重试。自动化工具直接投递给应用的输入未经过系统事件监听；独立 CGEvent 注入程序在当前执行环境中无发送权限。因此真实硬件的滚动与中键效果仍需验证。

GitHub

项目包含本地 Git 历史和 .gitignore，不提交用户设置、Xcode 缓存或构建产物。