SorcRR/MacRazer

# macOS 上的 Razer 鼠标控制 一款原生的菜单栏应用，用于在 macOS 上控制 Razer 鼠标。Razer 现在确实发布了 Mac 版的 Synapse， 但其 [支持的设备列表](https://mysupport.razer.com/app/answers/detail/a_id/14809/~/razer-synapse-for-mac-supported-and-compatible-devices) 很短，且不包括 Cobra HyperSpeed 或 Atheris —— 本应用正是为了填补这一空白。它通过 USB HID 直接与鼠标进行通信（无需内核扩展，无需安装驱动），使用的协议是从 [OpenRazer](https://github.com/openrazer/openrazer) 移植而来的。 在 **Razer Cobra HyperSpeed** 和 **Razer Atheris** 上效果最好，这两款也是实际经过测试的设备。它会通过名称检测任何 Razer 鼠标，并且应该适用于其他使用相同 HID 协议系列的 Razer 鼠标，但这些尚未经过测试，因此在有人于真实硬件上确认之前，请将其支持视为“可能可用，但未经验证”。 ## 功能 - 菜单栏中的**电池**百分比、充电状态，以及学习估算的剩余可用时间。历史记录和估算值会根据每个物理设备（通过序列号）单独保存。 - **电池使用图表**：电池百分比旁边的图表按钮可打开当前的放电曲线、放电速率、距离上次充满电的时间，以及过去充电周期及其平均时长的趋势图。 - **DPI**：带有滑块（限制为每个型号的实际最大值），可读取设备上鼠标自带的预设档位，以及可随时调用的自定义值（基于每个设备）。 - **回报率**：125 / 500 / 1000 Hz。 - **RGB 灯光**：通过内联色相/饱和度色轮选择静态颜色，此外还有光谱、波浪、关闭模式，以及亮度滑块。 - **按键重映射**：适用于侧面的后退/前进按钮（通过 CGEvent tap 实现的软件层面的重映射）：键盘快捷键（预设或自定义录制器）、鼠标点击以及媒体键。基于每个设备保存。 - **检测并命名任何 Razer 鼠标。** 某个型号不支持的控件会自动隐藏（例如 Atheris 没有灯光，仅限有线的鼠标没有电池 UI）。 - 在支持的情况下，设置会写入鼠标的**板载内存**中，因此即使应用未运行，设置也会保留。 设置在应用重启和重新连接后依然保留，并且当鼠标连接、断开连接或进入休眠状态时，菜单栏会自动更新。 ## 支持的鼠标 | 鼠标 | 状态 | |---|---| | Razer Cobra HyperSpeed (有线 + 无线) | 已测试，效果最好 | | Razer Atheris | 已测试，效果最好 | | Razer Basilisk V3 | 在注册表中；用户反馈可用 | | Razer Cobra, Cobra Pro (有线 + 无线) | 协议相同，此处尚未进行硬件验证 | | 任何其他 Razer 鼠标 | 已被检测并命名；应该可用，但未测试 | 添加型号只需对注册表进行微小更改并进行硬件验证。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ### 已知限制：没有硬件序列号的两只相同鼠标 特定设备的设置（自定义 DPI、按键重映射、电池历史记录）在鼠标报告了自身的序列号时，会以该序列号为键进行存储；否则将使用其 USB 产品 ID 作为键。如果您拥有**两只完全相同型号的鼠标，且该型号不提供序列号**，那么两者都会回退到使用同一个基于 PID 的键，并将共享同一个设置/历史记录文件：没有其他稳定的标识符可以区分它们。这不会影响混合使用的情况（不同型号，或者会报告序列号的型号）。 ## 要求 macOS 14 或更高版本（Apple Silicon）。 **请通过 2.4 GHz 接收器或 USB-C 线缆连接，而不是蓝牙。** Razer 仅通过 USB 公开其控制协议（电池、DPI、灯光）；通过蓝牙连接时，鼠标只是一个普通的指针，因此 MacRazer 无法读取或更改任何内容。如果您的鼠标有模式切换开关，请将其设置为 2.4 GHz。（当 MacRazer 检测到您的鼠标处于蓝牙连接时，会提醒您。） ## 安装 从 [最新发布版本](../../releases/latest) 下载 `MacRazer.dmg`，打开它，然后将 **MacRazer** 拖入“应用程序”中。 此构建版本未签名（没有付费的 Apple Developer ID），因此首次启动时，Gatekeeper 会提示该应用“无法打开，因为它来自身份不明的开发者”或“已损坏，无法打开”。这两者都是针对未签名应用的标准警告，并不是真正的问题。要强制打开，请执行以下**任一**操作： - 在 Finder 中右键点击（或按住 Control 点击）**MacRazer.app**，选择**打开**，然后在对话框中确认**打开**。（只需操作一次。） - 或者，在“系统设置”>“隐私与安全性”中，滚动到底部，点击 MacRazer 警告旁边的**仍要打开**。 - 或者，在终端中运行：`xattr -cr /Applications/MacRazer.app`，然后正常打开它。 之后它就可以像任何其他应用一样启动了。接着它会请求**输入监控**权限（如果您使用按键重映射功能，还会请求**辅助功能**权限）；请参阅下方的[权限](#permissions)。 ## 构建与运行 要从源代码构建：Xcode 16 / Swift 6.1。 ``` # 直接运行 menu bar app（开发时最简单；使用你的 Terminal 权限）： swift run MacRazer # 或者构建一个独立的 .app： ./Scripts/setup-signing.sh # one-time: a stable self-signed identity (see Permissions) ./Scripts/build-app.sh # produces "MacRazer.app" open "MacRazer.app" ``` ## 权限 - 需要**输入监控**权限以向鼠标发送和接收 HID 报告。应用会在启动时请求此权限；请在“系统设置”>“隐私与安全性”>“输入监控”中授予。 - **辅助功能**仅在按键重映射（event tap）时需要。重映射界面提供了一个按钮，可以直接打开正确的设置面板。 ## 命令行诊断 当给定子命令时，同一个二进制文件会运行只读探测（方便用于验证新鼠标）。请在终端中运行以下命令： ``` swift run MacRazer info # list the mouse's HID interfaces swift run MacRazer battery # read battery % swift run MacRazer dpi [x] [y] # read or set DPI swift run MacRazer poll [125|500|1000] # read or set polling rate swift run MacRazer rgb static ff0000 # static colour (or: spectrum | wave | off) swift run MacRazer brightness [0-100] # read or set LED brightness ``` ## 工作原理 鼠标使用 Razer 的 HID 协议进行通信。我们没有对其进行逆向工程：命令字节是从 OpenRazer 的 Linux 驱动程序移植过来的，并在 Apple 的 IOKit HID Manager 上使用 Swift 重新实现。因为 Razer 鼠标响应任何用户空间进程都能发送的标准 USB HID 特征报告，所以不需要内核扩展。 完整详情，包括协议、每个设备的硬件特性以及逐文件的代码说明，都在 [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md) 中。完整的功能历史记录请见 [CHANGELOG.md](CHANGELOG.md)。 ## 许可证 GPL-2.0-or-later，请参阅 [LICENSE](LICENSE)。该项目采用 GPL 许可证，因为其 HID 协议派生自 OpenRazer。完整的归属说明和商标声明请见 [NOTICE.md](NOTICE.md)。