HyperPilot

HyperPilot 是一个免费的 macOS 菜单栏快捷键增强器，用 Swift/AppKit 实现。

它的目标不是一次性完整复制 Karabiner-Elements，而是先用一个轻量、可读、可自定义的本机 App 覆盖最常用的效率键盘层：

项目主页：https://luolaoshi.club/hyperpilot

• Caps Lock 作为 Hyper 模式键
• Hyper + F/S/E/D 控制方向
• Hyper + J/L/K/I 做选择移动
• Option + J/L/I/K/H/;/8/, 控制鼠标移动
• Option + U 鼠标左键点击
• 菜单栏启用/停用、重载配置、打开配置文件

当前状态

• 已实现 macOS 菜单栏常驻 App。
• 已实现 JSON 配置文件。
• 已实现键盘 Event Tap 和鼠标事件模拟。
• 已实现诊断脚本和真实输入自测脚本。
• 当前 Caps Lock 默认是 toggle 模式：按一下进入 Hyper，再按一下退出 Hyper。

系统要求

• macOS 14 或更新版本
• Xcode Command Line Tools
• Swift 6 工具链

配置文件

首次启动会生成：

~/.config/hyperpilot/config.json

配置示例：

{
  "enabled": true,
  "hyperKey": "caps_lock",
  "hyperMode": "toggle",
  "bindings": [
    {
      "trigger": "hyper+f",
      "action": { "type": "key", "key": "right_arrow" }
    }
  ]
}

hyperMode 当前支持：

• toggle：按一次 Caps Lock 开启 Hyper，再按一次关闭。
• hold：为后续 F18/底层键方案准备；Caps Lock 在普通 Event Tap 下不能保证完整按住体验。

构建和运行

一键安装成本机服务：

./script/install_service.sh

它会：

• 构建并测试 HyperPilot
• 安装到 /Applications/HyperPilot.app
• 写入 ~/Library/LaunchAgents/club.luolaoshi.hyperpilot.plist
• 启动当前 App
• 后续登录自动启动

安装后需要在 macOS 系统设置中授予：

• Privacy & Security -> Accessibility
• Privacy & Security -> Input Monitoring

诊断：

./script/diagnose.sh

真实输入自测：

./script/self_test.sh

它会模拟两条路径：

• Command+Control+Option+Shift+F
• Caps Lock 进入 Hyper 后触发 Hyper+F

然后检查 ~/.config/hyperpilot/status.log 是否出现执行记录。

卸载：

./script/uninstall_service.sh

开发期构建和运行：

./script/build_and_run.sh --verify

授权完成后，日常启动尽量不要重新构建，使用：

./script/open_existing_app.sh

原因：macOS 的辅助功能/Input Monitoring 权限和 App 签名、路径有关。开发期每次重新构建都可能让系统把它当成一个新程序，从而需要重新授权。

如果第一次使用没有权限，请点菜单栏 HP：

请求辅助功能权限

然后在系统设置里授予 HyperPilot 辅助功能/Input Monitoring 相关权限。

如果授权后仍显示“监听失败”，建议在系统设置里把 HyperPilot 从辅助功能/Input Monitoring 列表中删除，再重新添加这个路径：

/Applications/HyperPilot.app

运行状态日志：

~/.config/hyperpilot/status.log

回滚

退出菜单栏 App 即可。它不会修改 Karabiner 或 Keyboard Maestro 配置。

如需完全移除：

./script/uninstall_service.sh

用户配置仍会保留在 ~/.config/hyperpilot/，方便之后恢复。

路线图

• 图形化配置面板
• 更接近 Karabiner 的按住式 Hyper
• 导入 Karabiner/Keyboard Maestro 配置
• 更好的菜单栏状态与诊断信息
• DMG 打包和正式签名

License

MIT