Licoy/StrokeMouse
Licoy/StrokeMouse has 247 GitHub stars and 17 forks. GitHot measured 0 stars in 24 hours and +6 in 7 days. Last checked 2026-11-15 13:56 UTC. Last push 2026-11-12.
可以做什么
- Menu bar app: enable/disable gestures, open settings, quit; icon tints by status (normal / paused / needs permission); optional hide menu bar icon (confirm if Dock is also hidden; reopen via Dock or relaunch to open settings)
- Gesture library: sidebar by Global / per-app (new gestures inherit the selected scope); search / filter / sort; multi-select batch enable, disable, delete; JSON import/export (skip or force-import duplicates); turn off global gestures in chosen apps from General → Apps Without Global Gestures or each app's sidebar entry
- Mouse drawing: each gesture can independently use the right, middle, or a side button; only buttons referenced by enabled profiles are monitored; optionally add a left-click secondary action—click the left button once while drawing and only that action runs on release
- Mouse combinations: hold right and scroll up/down, click left, or drag to scroll; at any display’s top/bottom/left/right edge, right-click or scroll to run an action without drawing, or draw a Right-button gesture that starts at the edge. Configure these under Gestures → Add → Mouse Combinations; app scopes and existing actions apply. Details.
实测星标增长
- 24小时
- 0
- 7天
- +6
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
macOS 鼠标/触控板手势自定义工具。按住该手势的触发键(默认右键,也可中键 / 侧键)绘制轨迹,匹配后执行快捷键、打开应用、窗口操作、媒体键、Shell / AppleScript 等 | A macOS mouse gesture customization tool. Hold down the trigger key to execute shortcuts, open applications, shell/AppleScript, etc. after matching.
效率工具README_zh-Hans.md
原文English · 简体中文 · 繁體中文 · 한국어 · 日本語 · Русский · Français
macOS 鼠标与触控板手势自定义工具。可按住鼠标键绘制轨迹、按住单个修饰键进行触控板绘制,也可使用实验性的多指触控手势;匹配后执行快捷键、打开应用、窗口操作、媒体键、Shell / AppleScript 等。支持全局或指定 App 生效,手势配置可导入导出,本地运行、菜单栏常驻。
界面预览
| 手势配置列表 | 手势测试 |
|---|---|
![]() |
![]() |
| 通用设置 | 权限与引擎状态 |
|---|---|
![]() |
![]() |
| 新建手势 · 录制轨迹 | 应用范围 |
|---|---|
![]() |
![]() |
功能
- 菜单栏常驻:启停手势、打开设置、退出;图标随状态变色(正常 / 暂停 / 缺权限);可隐藏菜单栏图标(与隐藏 Dock 同时开启会二次确认;隐藏后点 Dock 或再开 App 进入设置)
- 手势库管理:侧栏按全局 / 各 App 组织(新建时预填作用域);搜索 / 筛选 / 排序;多选批量启停删除;JSON 导入导出(重复项可跳过或强制导入);可在通用 → 停用全局手势的应用或侧栏各 App 中停用全局手势
- 鼠标绘制:每条手势可独立选择右键、中键或侧键,只监听已启用配置用到的按钮;可另设 第二动作,绘制中点击一次左键,松开后只执行第二动作
- 鼠标组合:按住右键并向上 / 向下滚动、点击左键或拖动滚动,也可在屏幕上下左右边缘点击右键或滚动滚轮(无需绘制轨迹),或从边缘开始绘制「右键手势」。在「手势 → 添加 → 鼠标组合」中设置,可复用所有动作和应用作用域,详见使用说明。
- 鼠标按键映射:单击侧键或中键直接执行动作(如侧键后退 → ⌘[),无需绘制,也可要求同时按住某个修饰键(如仅 ⌘ + 侧键后退触发);同一按键也用于鼠标绘制时,未达到最小滑动距离按单击处理、超过则识别为绘制,不会重复触发;沿用全局 / 按应用作用域,目标应用没有映射时保留原生按键行为
- 触控板绘制:按住一个 Fn / Control / Option / Shift / Command(默认 Fn)后移动指针绘制;必须精确按住单个支持键,额外修饰键会取消本次识别
- 实验性触控手势:内置触控板支持 40 类三至五指轻点 / 轻点两下 / 点按 / 点按两下 / 四向滑动,以及二至五指捏合 / 张开 / 顺逆时针旋转
- 触控手势总开关:可随时关闭触控手势通道而不删除已配置手势;私有后端故障只降级触控通道,不影响鼠标与触控板绘制
- 滚动增强:鼠标滚轮与触控板 / 妙控鼠标的纵向、横向可分别反向,普通滚轮还可选平滑滚动(柔和 / 标准 / 灵敏,或自定义速度、时长与加速);排除列表按前台应用判断,设置只留在本机,不进入备份同步;与其他滚动工具同时运行可能被处理两次,只读取整数行增量的应用(部分游戏、虚拟机、远程桌面)请加入排除列表
- 每条手势独立目标:可选按下触发键时的当前前台应用或指针位置所属应用;若存在普通窗口则同时锁定精确窗口,应用范围判断与目标相关动作始终复用该目标
- 自由轨迹识别:每条手势可录制 1–5 个样本(建议 3 个),匹配时取最高分样本;使用弧长弹性对齐,以笔画方向为主、位置为辅,容忍曲线、抖动与端点小钩,拒绝反向、镜像、截断或明显多画的轨迹;可在通用设置调整全局匹配阈值,按住触发键时显示实时轨迹 HUD,并在笔尖旁提示此刻松手将执行的手势
- App 作用域:全局,或从已安装应用中选图标添加(支持搜索 / 浏览
.app) - 多种动作:系统动作(调度中心、应用程序窗口、上一个 / 下一个空间,可自定义绑定的系统快捷键)、快捷键(支持单独使用 Fn/地球仪或与其他按键组合,可追加依次按下的后续按键,如 ⌘V 后按回车)、打开 / 切换 App、URL、媒体键、窗口操作、Shell / AppleScript(语法高亮;AppleScript 含睡眠、锁屏、清废纸篓等预设与自定义)
- 体验:界面支持英语、简体中文、繁体中文、韩语、日语、俄语、法语(也可跟随系统语言),深浅色(跟随系统 / 强制)、登录启动、隐藏 Dock / 菜单栏图标、Sparkle 应用内更新(失败可回落 GitHub Releases)
系统要求
- macOS 14 Sonoma 或更高
- Xcode 16+(开发构建)
- 鼠标或触控板均可完成绘制手势;直接多指触控优先支持 Mac 内置触控板
- 外接 Magic Trackpad 为 best-effort 支持,可能因机型或系统版本而异
安装
Homebrew(推荐)
通过 StrokeMouse 项目维护的 Licoy Homebrew Tap 安装:
brew install --cask licoy/tap/strokemouse
StrokeMouse 同时支持应用内更新;如希望通过 Homebrew 强制检查并升级,请使用:
brew upgrade --cask --greedy strokemouse
卸载应用时默认保留配置,添加 --zap 可同时移除配置:
brew uninstall --cask strokemouse
brew uninstall --cask --zap strokemouse
也可前往 官网下载页 手动下载对应架构的 DMG。自 0.0.40 起,发行版使用 Apple Developer ID 签名并经过 Apple 公证;从 0.0.39 及更早版本升级时需重新授权一次辅助功能:在权限页点击 重置授权,再重新打开 StrokeMouse 的开关即可。
权限
| 权限 | 用途 |
|---|---|
| 辅助功能(Accessibility) | 全局鼠标 / 修饰键 / 滚动事件监听(CGEventTap)、快捷键注入、窗口 AX 操作 |
| 自动化(Automation) | 可选;AppleScript 控制其他 App 时按需授权 |
首次启动或 设置 → 权限 可使用应用内引导授权:打开系统设置并拖入 StrokeMouse 完成开关。未授权时引擎不会假装在监听。
实验性触控手势
触控手势通过运行时 dlopen / dlsym 加载 Apple 未公开的 MultitouchSupport,不静态链接该私有框架。它可能在 macOS 更新后失效;缺少框架、符号、设备或设备启动失败都会显示为触控通道故障,鼠标与触控板绘制仍可继续使用,不会模拟回退或静默重试。
StrokeMouse 不会拦截触控板原生手势,因此系统手势可能与绑定动作同时发生。唯一的例外是点按:用已配置点按手势的手指数按下触控板时,这次点击由手势接管,不会再传给应用。按下过触控板的触点序列不会再识别为轻点或滑动。应用也不会保存或记录原始触点轨迹。第一次保存、启用或导入已启用的触控手势配置时会显示实验风险确认;之后可用总开关暂停触控手势而不删除配置。
支持的 40 类触控手势:
| 类别 | 手指数 | 变体 | 数量 |
|---|---|---|---|
| 轻点 | 三 / 四 / 五指 | 轻点、轻点两下 | 6 |
| 点按 | 三 / 四 / 五指 | 点按、点按两下 | 6 |
| 滑动 | 三 / 四 / 五指 | 上、下、左、右 | 12 |
| 缩放 | 二 / 三 / 四 / 五指 | 捏合、张开 | 8 |
| 旋转 | 二 / 三 / 四 / 五指 | 逆时针、顺时针 | 8 |
| 合计 | 40 |
首版不支持两指轻触 / 滑动、修饰键组合、特定手指身份、连续重复动作或用户调整识别阈值。
构建与运行
依赖
brew install xcodegen
生成工程并打开
./scripts/generate_project.sh
open StrokeMouse.xcodeproj
或在 Xcode 中直接 Run(Scheme: StrokeMouse)。
命令行构建(推荐)
固定产出到仓库下 output/StrokeMouse.app,路径稳定,减少重复授权辅助功能。
Debug 显示名为 StrokeMouse Dev(Bundle ID com.strokemouse.app.dev),与正式版 StrokeMouse 可同时在辅助功能中授权,互不冲突:
./scripts/build.sh # Debug → output/StrokeMouse.app(辅助功能中显示 StrokeMouse Dev)
./scripts/build.sh --open # 编译完成后自动打开
./scripts/build.sh --release # Release(显示名 / Bundle ID 与正式包一致)
发布打包
按架构生成 ZIP、TAR.GZ 和 DMG,并验证签名、entitlements 与产物完整性(默认用钥匙串中的 Developer ID Application 身份签名,提供公证凭据时同时公证,下载可通过 Gatekeeper,辅助功能也能跨 Sparkle 更新保留):
# 公证:追加 NOTARY_KEYCHAIN_PROFILE=<xcrun notarytool store-credentials 保存的配置名>
SPARKLE_PUBLIC_KEY="..." ARCH=arm64 ./scripts/package-app.sh
SPARKLE_PUBLIC_KEY="..." ARCH=x86_64 ./scripts/package-app.sh
发布与 CI secrets 说明见 RELEASING.md / certs/README.md。
版本发布使用 ./bump.sh -v x.y.z [-p];同版本重打 tag 并推送用 ./bump.sh -v x.y.z --force。
测试
xcodebuild -scheme StrokeMouse -configuration Debug test
使用说明
- 启动应用,菜单栏出现鼠标图标
- 授予 辅助功能 权限,并在菜单栏选择「恢复手势」/ 确认已启用
- 打开 设置 → 手势,查看默认手势或新建
- 选择一种输入方式:按住鼠标触发键绘制、按住单个修饰键进行触控板绘制,或完成已配置的触控手势
- 匹配成功后执行绑定动作
短按 vs 手势:触发键的按下与松开由手势引擎暂时捕获;未达到「最小滑动距离」便松开时会回放为正常点击,右键菜单仍可用。所有鼠标移动与拖动事件都会直接交给系统更新光标,手势引擎通过定时采样记录轨迹;前台 App 收不到配对的触发键按下与松开,因此绘制时不会打开或选中右键菜单。未配置为触发键的鼠标按钮不受影响;左键默认同样放行,仅当目标应用可用的手势设置了 第二动作 时,按住触发键期间的左键点击会被吞掉,松开后只执行匹配手势的第二动作(该手势未设置第二动作则不执行,未画出轨迹则取消)。若目标应用为该按键设置了 鼠标按键映射,短按改为执行映射动作,不再回放点击。按住右键时,鼠标组合 优先接管滚轮或左键(先于第二动作),触发后松开右键既不回放点击,也不识别轨迹。目标应用可用右键「拖动滚动」时,短按阈值改为固定的 10 点,不跟随「最小滑动距离」;指针移动不足 10 点便松开仍会回放右键点击,开始滚动后松开既不回放点击,也不识别轨迹。
触控板绘制:修饰键监听为 listen-only,不吞键盘事件;短路径不会执行动作。轨迹来自系统指针位置,因此可以用触控板或鼠标移动指针。StrokeMouse 不会阻止修饰键本身对当前 App 的影响。
快捷键会先激活锁定应用;若锁定了精确窗口,也会将该窗口置前,因此可能切换焦点或桌面空间。Finder 桌面等没有普通窗口的位置仍可执行快捷键和「隐藏应用」;关闭、最小化、缩放、最大化窗口、全屏、居中仍需要精确窗口。短按不会激活目标。
在手势编辑器中选择 打开 URL → 使用选中文本,输入 https://www.baidu.com/s?wd={0} 这样的模板。触发手势后,StrokeMouse 从捕获的窗口复制文本,将其留在剪贴板,并用默认浏览器打开生成的地址。
默认手势示例(均默认右键触发;不同手势可绑定不同按键):
| 手势 | 动作 |
|---|---|
| ↑ | Mission Control(⌃↑) |
| ↓ | 应用程序窗口(⌃↓) |
| ↓← | 最小化窗口 |
| ↓→ | 关闭窗口 |
| ↑→ | 打开 Safari |
| →← | 播放 / 暂停 |
| ↑← | 打开 GitHub |
配置文件
路径:
~/Library/Application Support/StrokeMouse/gestures.json
日常可用 设置 → 手势 多选后导出 / 导入 JSON 包。整库可复制上述文件备份或手工编辑(需保持结构合法)。设置页可「在 Finder 中显示」。
含屏幕边缘「右键手势」的手势库、导出和备份使用手势配置 v7;其余配置中,「使用选中文本」需要 v6,最大化窗口需要 v5,系统动作和拖动滚动需要 v4,Fn 快捷键需要 v3,其他配置使用 v2。旧格式仍可读取,旧版本应用无法读取更新的格式。
系统动作支持调度中心、应用程序窗口和上一个 / 下一个空间,默认使用与 macOS 一致的 ⌃↑ ⌃↓ ⌃← ⌃→,可在动作编辑器中录制其他快捷键或恢复默认,并需与系统设置保持一致;编辑器会读取「系统设置 › 键盘 › 键盘快捷键 › 调度中心」,对应的系统快捷键已关闭或与此处不一致时会提示,并可点击「改用系统快捷键」采用系统设置,StrokeMouse 不会修改系统设置;使用默认快捷键但系统中已关闭该快捷键时,执行会提示错误而不是静默无效;应用程序窗口先激活锁定的应用 / 窗口,调度中心和空间切换作用于当前桌面,不激活锁定的窗口;这些是离散命令,不提供原生四指连续动画。
开始录制快捷键前请先松开所有修饰键,再按希望回放的顺序依次按键;Fn 需实际按下,在系统设置中改为 Fn 的按键(如大写锁定键)也可以,松开大写锁定键后大写锁定可能仍保持开启。
技术栈
- Swift / SwiftUI(macOS 14+)
- 轻量 MVVM + Service
CGEventTap全局鼠标 / 修饰键事件dlopen/dlsym动态加载MultitouchSupport(实验性触控手势,不静态链接)- JSON 配置持久化
- LaunchAtLogin-Modern 登录启动
- Sparkle 签名校验与应用内更新
- XcodeGen 管理工程
许可与免责
本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 开源。
本地工具,全局事件与脚本动作具有系统级能力。请仅添加你信任的 Shell / AppleScript。作者不对误操作或权限滥用负责。





