Licoy/StrokeMouse
GitHub: Licoy/StrokeMouse
StrokeMouse 是一款 macOS 鼠标手势自定义工具，通过绘制轨迹匹配后执行快捷键、脚本、应用打开等多种操作，帮助用户高效完成日常任务。
Stars: 94 | Forks: 4
macOS 鼠标手势自定义工具。按住**该手势的触发键**（默认右键，也可中键 / 侧键）绘制轨迹，匹配后执行快捷键、打开应用、窗口操作、媒体键、Shell / AppleScript 等。支持**全局或指定 App** 生效，手势配置可**导入导出**，本地运行、菜单栏常驻。
## 界面预览
| 手势配置列表 | 手势测试 |
|:---:|:---:|
| 
| 
|
| 通用设置 | 权限与引擎状态 |
|:---:|:---:|
| 
| 
|
| 新建手势 · 录制轨迹 | 应用范围 |
|:---:|:---:|
| 
| 
|
## 功能
- **菜单栏常驻**：启停手势、打开设置、权限状态、退出
- **手势库管理**：搜索 / 筛选 / 排序；多选后批量启用、禁用、删除；**JSON 导入导出**（重复项可跳过或强制导入）
- **每条手势独立触发键**：默认右键；中键 / 侧键可选；只监听已启用触发键
- **自由轨迹识别**：有序弧长重采样 + 1D/2D 归一化 + 有限旋转；显著转折结构门控；按住触发键时实时轨迹 HUD
- **App 作用域**：全局，或从已安装应用中选图标添加（支持搜索 / 浏览 `.app`）
- **多种动作**：快捷键、打开 App、URL、媒体键、窗口操作、Shell、AppleScript
- **体验**：中英界面、深浅色（跟随系统 / 强制）、登录启动、隐藏 Dock 图标、Sparkle 应用内更新（失败可回落 GitHub Releases）
## 系统要求
- macOS 14 Sonoma 或更高
- Xcode 16+（开发构建）
- 任意鼠标即可（默认手势使用右键触发；可在手势编辑中改为中键等）
## 权限
| 权限 | 用途 |
|------|------|
| **辅助功能（Accessibility）** | 全局鼠标事件监听（CGEventTap）、快捷键注入、窗口 AX 操作 |
| **自动化（Automation）** | 可选；AppleScript 控制其他 App 时按需授权 |
首次启动后请到 **设置 → 权限** 完成辅助功能授权，否则手势引擎无法监听。
## 构建与运行
### 依赖
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 与产物完整性（默认用固定自签身份 **`StrokeMouse Release`**，便于辅助功能跨 Sparkle 更新保留）：
# 首次本地：./scripts/generate-codesign-cert.sh --import
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
## 使用说明
1. 启动应用，菜单栏出现鼠标图标
2. 授予 **辅助功能** 权限，并在菜单栏选择「恢复手势」/ 确认已启用
3. 打开 **设置 → 手势**，查看默认手势或新建
4. 按住该手势的 **触发键**（默认右键；可在编辑手势时改为中键等），画出路径后松开
5. 匹配成功后执行绑定动作
默认手势示例（均默认右键触发；不同手势可绑定不同按键）：
| 手势 | 动作 |
|------|------|
| ↑ | Mission Control（⌃↑） |
| ↓ | 应用程序窗口（⌃↓） |
| ↓← | 最小化窗口 |
| ↓→ | 关闭窗口 |
| ↑→ | 打开 Safari |
| →← | 播放 / 暂停 |
| ↑← | 打开 GitHub |
## 配置文件
路径：
~/Library/Application Support/StrokeMouse/gestures.json
日常可用 **设置 → 手势** 多选后导出 / 导入 JSON 包。整库可复制上述文件备份或手工编辑（需保持结构合法）。设置页可「在 Finder 中显示」。
## 技术栈
- Swift / SwiftUI（macOS 14+）
- 轻量 MVVM + Service
- `CGEventTap` 全局鼠标事件
- JSON 配置持久化
- [LaunchAtLogin-Modern](https://github.com/sindresorhus/LaunchAtLogin-Modern) 登录启动
- [Sparkle](https://github.com/sparkle-project/Sparkle) 签名校验与应用内更新
- XcodeGen 管理工程
## 社区支持
- [LinuxDO](https://linux.do)
## 许可与免责
本项目采用 [GNU Affero General Public License v3.0 (AGPL-3.0)](./LICENSE) 开源。
本地工具，全局事件与脚本动作具有系统级能力。请仅添加你信任的 Shell / AppleScript。作者不对误操作或权限滥用负责。
| |
| 通用设置 | 权限与引擎状态 |
|:---:|:---:|
| | |
| 新建手势 · 录制轨迹 | 应用范围 |
|:---:|:---:|
| | |
## 功能
- **菜单栏常驻**：启停手势、打开设置、权限状态、退出
- **手势库管理**：搜索 / 筛选 / 排序；多选后批量启用、禁用、删除；**JSON 导入导出**（重复项可跳过或强制导入）
- **每条手势独立触发键**：默认右键；中键 / 侧键可选；只监听已启用触发键
- **自由轨迹识别**：有序弧长重采样 + 1D/2D 归一化 + 有限旋转；显著转折结构门控；按住触发键时实时轨迹 HUD
- **App 作用域**：全局，或从已安装应用中选图标添加（支持搜索 / 浏览 `.app`）
- **多种动作**：快捷键、打开 App、URL、媒体键、窗口操作、Shell、AppleScript
- **体验**：中英界面、深浅色（跟随系统 / 强制）、登录启动、隐藏 Dock 图标、Sparkle 应用内更新（失败可回落 GitHub Releases）
## 系统要求
- macOS 14 Sonoma 或更高
- Xcode 16+（开发构建）
- 任意鼠标即可（默认手势使用右键触发；可在手势编辑中改为中键等）
## 权限
| 权限 | 用途 |
|------|------|
| **辅助功能（Accessibility）** | 全局鼠标事件监听（CGEventTap）、快捷键注入、窗口 AX 操作 |
| **自动化（Automation）** | 可选；AppleScript 控制其他 App 时按需授权 |
首次启动后请到 **设置 → 权限** 完成辅助功能授权，否则手势引擎无法监听。
## 构建与运行
### 依赖
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 与产物完整性（默认用固定自签身份 **`StrokeMouse Release`**，便于辅助功能跨 Sparkle 更新保留）：
# 首次本地：./scripts/generate-codesign-cert.sh --import
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
## 使用说明
1. 启动应用，菜单栏出现鼠标图标
2. 授予 **辅助功能** 权限，并在菜单栏选择「恢复手势」/ 确认已启用
3. 打开 **设置 → 手势**，查看默认手势或新建
4. 按住该手势的 **触发键**（默认右键；可在编辑手势时改为中键等），画出路径后松开
5. 匹配成功后执行绑定动作
默认手势示例（均默认右键触发；不同手势可绑定不同按键）：
| 手势 | 动作 |
|------|------|
| ↑ | Mission Control（⌃↑） |
| ↓ | 应用程序窗口（⌃↓） |
| ↓← | 最小化窗口 |
| ↓→ | 关闭窗口 |
| ↑→ | 打开 Safari |
| →← | 播放 / 暂停 |
| ↑← | 打开 GitHub |
## 配置文件
路径：
~/Library/Application Support/StrokeMouse/gestures.json
日常可用 **设置 → 手势** 多选后导出 / 导入 JSON 包。整库可复制上述文件备份或手工编辑（需保持结构合法）。设置页可「在 Finder 中显示」。
## 技术栈
- Swift / SwiftUI（macOS 14+）
- 轻量 MVVM + Service
- `CGEventTap` 全局鼠标事件
- JSON 配置持久化
- [LaunchAtLogin-Modern](https://github.com/sindresorhus/LaunchAtLogin-Modern) 登录启动
- [Sparkle](https://github.com/sparkle-project/Sparkle) 签名校验与应用内更新
- XcodeGen 管理工程
## 社区支持
- [LinuxDO](https://linux.do)
## 许可与免责
本项目采用 [GNU Affero General Public License v3.0 (AGPL-3.0)](./LICENSE) 开源。
本地工具，全局事件与脚本动作具有系统级能力。请仅添加你信任的 Shell / AppleScript。作者不对误操作或权限滥用负责。标签：效率工具, 桌面定制, 网络调试, 自动化, 鼠标手势