zWGestures 0.3.0

原生 Apple Silicon 鼠标手势工具。按住鼠标右键画一个形状，就执行你为它配置的动作。

这一版的主题是 英文用户也能用：界面支持中英双语（设置里可切换或跟随系统），
顺手把「从原版导入后满屏英文手势名」这件事处理掉了。没有新增手势类功能。

---

⚠️ 更新之后第一件事：重新授权辅助功能

这个版本没有 Apple 开发者签名，macOS 按构建指纹识别它，所以每更新一版都要重新授权一次。

更新后如果画手势没反应，几乎一定是这个原因。应用会弹一次说明并给出「打开系统设置」按钮，
菜单栏也会写「辅助功能权限：已失效（点击重新授权）」。到
系统设置 › 隐私与安全性 › 辅助功能 里把 zWGestures 取消勾选再勾上即可，不需要重启应用。

---

下载

文件	说明
zWGestures-arm64.dmg	推荐。打开后把应用拖进「应用程序」
zWGestures-arm64.zip	同样内容，解压即可
SHA256SUMS	校验和，用来确认下载完整

要求：Apple Silicon（M 系列）的 Mac，macOS 14 Sonoma 或更高。

首次安装仍需放行一次（见下），已经装过旧版的按上面那节重新授权即可。

---

这一版改了什么

1. 界面中英双语，随时可切

设置 › 偏好设置 › 界面语言：跟随系统 / 简体中文 / English。切换后菜单栏与窗口立刻重建。

• 英文界面不是机翻：命令编辑器、手势编辑器、各类弹窗与错误提示都逐条译过。
• 只有日志与调试面板保持中文 —— 那是排查问题用的，不是给用户看的。
• 英文文案比中文长，所以顺便放宽了排版：主设置窗口 900×560 → 1060×700，
  手势编辑器 560×640 → 780×740，并去掉了若干按中文长度写死的宽度
  （原先英文的「Command type」会被断成两行）。

2. 从原版导入的英文手势名，可以一键改成中文

原版配置里手势名存的就是英文（Close、Web Search…）。这一版：

• 菜单栏新增「把英文手势名改为中文」，点一下逐条对应成中文；
• 首次启动若发现 5 条以上已知英文名，会问一次（改 / 不改，答完不再打扰）；
• 用的是原版自带的那张中文译名表，只改表里查得到的名字 —— 你自己起过名字的手势一个字都不动；
• 改写前 ConfigStore 会自动备份到配置目录的 Backups/，随时可回退。

3. 出厂默认手势备了两份，按界面语言播种

中文界面装完看到「拷贝 / 粘贴 / 关闭」，英文界面看到 Copy / Paste / Close。
两份包除手势名外逐键一致（笔画与命令完全相同）—— 有测试钉住，免得中英文用户的手势行为不一样。

4. 系统权限弹窗也跟着语言走

NSAppleEventsUsageDescription（允许 zWGestures 用 AppleScript / Shell 脚本控制其它应用）现在有
中英两份 InfoPlist.strings，CFBundleLocalizations 同时声明 zh-Hans 与 en。

---

⚠️ 首次安装需要放行一次

这个版本没有 Apple 开发者签名，也没有公证（公证需要 99 美元/年的付费开发者账号）。
所以下载之后 macOS 会拦你一次 —— 这是预期行为，不是文件损坏。

1. 打开 dmg，把 zWGestures.app 拖进「应用程序」。

   不要在 dmg 卷里直接双击运行。 dmg 卷是只读的、随时会被卸载，而且系统会把卷内运行的应用
   移置到一个随机只读路径 —— 后果是开机自启注册的是那个临时路径，重启后就失效了。

2. 双击打开。它会好像启动了一下又马上退出 —— 那是系统在后台评估之后把它结束了（实测约 20 秒）。

3. 打开 系统设置 › 隐私与安全性，往下找到 安全性 一节，会看到
   「已阻止“zWGestures”以保护Mac。」，点它右边的 「仍要打开」。

   在 Finder 里双击时如果弹的是对话框，那个对话框上的按钮放行不了 ——
   macOS Sequoia 起苹果已经移除了「按住 Control 点按 → 打开」这条老路，必须去系统设置。

4. 回到「应用程序」再双击一次 zWGestures。

5. 到 系统设置 › 隐私与安全性 › 辅助功能 里勾选 zWGestures。
   没有这个权限，全局手势拦截和合成按键都无法工作。勾选之后不需要重启应用 ——
   它会自己发现并把引擎拉起来。

6. 完成 —— 开箱就有 48 条手势（名字跟着界面语言走）。

习惯命令行的话，第 3 步也可以用：

xattr -dr com.apple.quarantine /Applications/zWGestures.app

（实测：浏览器下载的文件会带 com.apple.quarantine 标记，而 curl -L 下载的不会 ——
原因与完整实测记录见仓库里的 docs/INSTALL.md。）

---

开箱就有 48 条手势

没装过原版 WGestures 的话，首次启动会载入内置的 48 条手势（全局 45 + Finder 3），
取自原版自己的出厂手势集：画「上」拷贝 · 画「下」粘贴 · 向左后退 · 向右前进 · L 形关闭窗口 ·
C 形切换 App · 「上→下」闭合回路打开 Web 搜索 · 还有音量/亮度/静音/全屏/最小化/睡眠/关机等。

可以直接用，也可以在设置界面里随便改 —— 改名、重画形状、换动作、调优先级、临时禁用，
都不用再手改 JSON。

---

已经装了原版 WGestures？

首次启动会自动导入你现有的手势，并在弹窗里报告迁移了哪些内容。你的手势、按应用分组、
触发矩阵都会带过来。

原版的配置目录只被读取，绝不会被改写。 zWGestures 的配置写在它自己的
~/Library/Application Support/zWGestures/，并且每次覆盖前都会自动备份（各留最近 10 份）。
你原来的 WGestures 可以继续照常使用；菜单栏里也随时可以重新导入一次。

---

已知限制

• 仅支持 Apple Silicon。 不做 Intel / Universal 支持 —— 这正是这个项目存在的理由之一：
  原版是 x86_64 应用、依赖 Rosetta，而
  macOS 27 是最后一个支持 Rosetta 的版本。
• 触发矩阵编辑、边角与滚轮触发尚未实现（这类手势在列表里默认隐藏）。
• 手势分组、动画回放尚未实现。
• 日志与调试面板仍只有中文。
• 已知的既存重复形状（原版配置里就有，任何匹配算法都分不开）：
  Close/Sleep、Terminal/Activity Monitor、重新打开/Shut Down/退出。
  同形状的哪一条生效由列表顺序决定，设置界面里会标出冲突。

---

许可与致谢

以 MIT 许可证发布。

WGestures 2 是一款出色的鼠标手势工具，它的「手势＝操作步骤之和」「手势修饰键」「继承与重载」等
设计是这个项目的直接灵感来源。原版 macOS 版最后一个版本是 2021 年 12 月的 2.3.3。

zWGestures 是独立的重新实现，不是官方版本，与原项目及作者 yingdev（Ying Yuandong）
没有任何隶属关系，也未获其背书；不包含原版的任何二进制、字体、图标或激活码，
兼容性仅限于配置文件格式。（中英双语界面里的中文译名取自原版自带的名字表，
与原版做法一致，只为让导入的手势名与用户在原版里看到的一致。）

如果你还在用原版并且觉得它好用，请去
yingdev.com/projects/wgestures2 支持原作者。

zWGestures 0.2.0

原生 Apple Silicon 鼠标手势工具。按住鼠标右键画一个形状，就执行你为它配置的动作。

这一版是 0.1.0 之后的第一次更新，主题是「把识别和稳定性上暴露出来的问题修干净」：
手势不再被笔画的长短左右；两次导致界面卡死/崩溃的缺陷已修复。没有新增功能。

---

⚠️ 更新之后第一件事：重新授权辅助功能

这个版本没有 Apple 开发者签名，macOS 按构建指纹识别它，所以每更新一版都要重新授权一次。

更新后如果画手势没反应，几乎一定是这个原因。应用会弹一次说明并给出「打开系统设置」按钮，
菜单栏也会写「辅助功能权限：已失效（点击重新授权）」。到
系统设置 › 隐私与安全性 › 辅助功能 里把 zWGestures 取消勾选再勾上即可，不需要重启应用。

---

下载

文件	说明
zWGestures-arm64.dmg	推荐。打开后把应用拖进「应用程序」
zWGestures-arm64.zip	同样内容，解压即可
SHA256SUMS	校验和，用来确认下载完整

要求：Apple Silicon（M 系列）的 Mac，macOS 14 Sonoma 或更高。

首次安装仍需放行一次（见下），已经装过 0.1.0 的按上面那节重新授权即可。

---

这一版修了什么

1. 手势识别改成「按形状」判断，不再被笔画长短左右

上一版匹配时会把整条笔画按总弧长缩放到同一长度再逐点比距离 —— 等于把「每一段占全长的比例」
当成了形状本身。结果是：

• 一条「竖明显更长、横很清楚」的 下→右（一眼就是关闭窗口那个形状）不会被识别，
  因为它「横还没画到存储定义那么长」；
• 而横画得比竖长时，同一条两段的 L 会被认成三段的 Enter —— 中间那段越长越像；
  三段手势也因此会按中间横的长短在 Enter / Minimize 之间跳。

现在折线类手势按拐角结构判断（每段的方向占 0.85 的权重 + 相对长度），
方向和段数说了算：下→右 就是 下→右，横画多长都算；两段的 L 也不会再被当成三段手势。
「画出去再原路返回」的闭环手势（Web 搜索、退格、删除）保留原来的容差，行为不变。

实测：截图那条竖横比 2.2:1 的 L，到「关闭」的距离从 0.109（不命中）降到 0.063；
竖横比 0.4~4.0 全部命中；真正不同的形状之间仍有 0.283 的余量。

2. 画完手势界面卡死、应用随后退出

两个独立缺陷叠在一起，都在「Web 搜索」这条路径上：

• 每次执行手势都在主线程同步调用辅助功能 API 去取目标窗口标题。这是跨进程调用，
  前台应用（浏览器）一旦短暂无响应，就把主线程卡住 —— 实测卡了 47 秒，
  期间手势都被识别了，但一个动作都没执行。
  现在窗口标题只在 shell 脚本真正需要时才去取，并且在后台取、单次询问限时 0.25 秒。
• 随后在状态栏菜单上崩溃（SerialExecutorRef::isMainExecutor，与 0.1.0 修复的那两次
  是同一族）。根因是菜单栏实现了 NSMenuDelegate.menuWillOpen，而这个协议实现继承了主 actor
  隔离、入口被插了运行时检查，AppKit 从菜单呈现路径调用它时那个检查自己 fault。
  现在菜单改成状态变化时推送刷新，不再实现这个协议回调。

3. Web 搜索手势卡约一分钟 + 崩溃

• 卡死：Web 搜索为了读「选中文字」，会先深拷贝整个剪贴板；而 NSPasteboardItem.copy()
  会把每一项的每个数据表示都实体化。如果剪贴板里是一张截图（TIFF + BMP + PSD + PNG，
  几十 MB），主线程就会卡上一分钟。现在优先用辅助功能 API 读选中文字（后台、限时、
  完全不碰剪贴板）；兜底才用 ⌘C，而且只在剪贴板本来就装着文本时才用 ——
  你复制过的图片从此不会被这个手势碰。
• 崩溃：急停快捷键 ⌃⌥⌘⎋ 的全局按键监听，处理器写在主 actor 上下文里，
  于是被插了同样的运行时检查；而点燃它的是 Web 搜索自己合成的 ⌘C。
  现在处理器改成不继承隔离的函数，并且忽略我们自己合成的按键。

4. 顺带：动作不再偶尔「慢半拍」

识别索引原来每 3 秒会跟着应用目录刷新重建一次、还跑在主线程 —— 那正是识别结果交接给命令执行
的那条路。现在只有配置变化才重建，且构建移出主线程。调试面板也新增了两行读数
（idx rebuilds、交接 ms / 最差），方便你自己看到「有没有卡」。

---

⚠️ 首次安装需要放行一次

这个版本没有 Apple 开发者签名，也没有公证（公证需要 99 美元/年的付费开发者账号）。
所以下载之后 macOS 会拦你一次 —— 这是预期行为，不是文件损坏。

1. 打开 dmg，把 zWGestures.app 拖进「应用程序」。

   不要在 dmg 卷里直接双击运行。 dmg 卷是只读的、随时会被卸载，而且系统会把卷内运行的应用
   移置到一个随机只读路径 —— 后果是开机自启注册的是那个临时路径，重启后就失效了。

2. 双击打开。它会好像启动了一下又马上退出 —— 那是系统在后台评估之后把它结束了（实测约 20 秒）。

3. 打开 系统设置 › 隐私与安全性，往下找到 安全性 一节，会看到
   「已阻止“zWGestures”以保护Mac。」，点它右边的 「仍要打开」。

   在 Finder 里双击时如果弹的是对话框，那个对话框上的按钮放行不了 ——
   macOS Sequoia 起苹果已经移除了「按住 Control 点按 → 打开」这条老路，必须去系统设置。

4. 回到「应用程序」再双击一次 zWGestures。

5. 到 系统设置 › 隐私与安全性 › 辅助功能 里勾选 zWGestures。
   没有这个权限，全局手势拦截和合成按键都无法工作。勾选之后不需要重启应用 ——
   它会自己发现并把引擎拉起来。

6. 完成 —— 开箱就有下面那 48 条中文手势。

习惯命令行的话，第 3 步也可以用：

xattr -dr com.apple.quarantine /Applications/zWGestures.app

（实测：浏览器下载的文件会带 com.apple.quarantine 标记，而 curl -L 下载的不会 ——
原因与完整实测记录见仓库里的 docs/INSTALL.md。）

---

开箱就有 48 条中文手势

没装过原版 WGestures 的话，首次启动会载入内置的 48 条中文手势（全局 45 + Finder 3），
取自原版自己的出厂手势集、名字用原版自带的中文译名表：

画「上」拷贝 · 画「下」粘贴 · 向左后退 · 向右前进 · L 形关闭窗口 · C 形切换 App ·
「上→下」闭合回路打开 Web 搜索 · 还有音量/亮度/静音/全屏/最小化/切换 App/睡眠/关机/播放暂停等等。

可以直接用，也可以在设置界面里随便改 —— 改名、重画形状、换动作、调优先级、临时禁用，
都不用再手改 JSON。

---

已经装了原版 WGestures？

首次启动会自动导入你现有的手势，并在弹窗里报告迁移了哪些内容。你的手势、按应用分组、
触发矩阵都会带过来。

原版的配置目录只被读取，绝不会被改写。 zWGestures 的配置写在它自己的
~/Library/Application Support/zWGestures/，并且每次覆盖前都会自动备份（各留最近 10 份）。
你原来的 WGestures 可以继续照常使用；菜单栏里也随时可以重新导入一次。

---

已知限制

• 界面目前仅中文。 英文界面仍在路线图上（0.1.0 时写的「排在 v0.2.0」没能兑现，
  这一版把力气全用在修复上了），见 docs/ROADMAP.md 第 15 节。
• 仅支持 Apple Silicon。 不做 Intel / Universal 支持 —— 这正是这个项目存在的理由之一：
  原版是 x86_64 应用、依赖 Rosetta，而
  macOS 27 是最后一个支持 Rosetta 的版本。
• 触发矩阵编辑、边角与滚轮触发尚未实现（这类手势在列表里默认隐藏）。
• 手势分组、动画回放尚未实现。
• 已知的既存重复形状（原版配置里就有，任何匹配算法都分不开）：
  Close/Sleep、Terminal/Activity Monitor、重新打开/Shut Down/退出。
  同形状的哪一条生效由列表顺序决定，设置界面里会标出冲突。

---

许可与致谢

以 MIT 许可证发布。

WGestures 2 是一款出色的鼠标手势工具，它的「手势＝操作步骤之和」「手势修饰键」「继承与重载」等
设计是这个项目的直接灵感来源。原版 macOS 版最后一个版本是 2021 年 12 月的 2.3.3。

zWGestures 是独立的重新实现，不是官方版本，与原项目及作者 yingdev（Ying Yuandong）
没有任何隶属关系，也未获其背书；不包含原版的任何二进制、字体、图标或激活码，
兼容性仅限于配置文件格式。

如果你还在用原版并且觉得它好用，请去
yingdev.com/projects/wgestures2 支持原作者。

zWGestures 0.1.0

原生 Apple Silicon 鼠标手势工具。按住鼠标右键画一个形状，就执行你为它配置的动作。

用 Swift 从头写成，不依赖 Rosetta；兼容 WGestures 2 的配置文件格式，可以直接导入你已有的手势。

---

下载

文件	说明
zWGestures-arm64.dmg	推荐。打开后把应用拖进「应用程序」
zWGestures-arm64.zip	同样内容，解压即可
SHA256SUMS	校验和，用来确认下载完整

要求：Apple Silicon（M 系列）的 Mac，macOS 14 Sonoma 或更高。

---

⚠️ 首次打开需要放行一次

这个版本没有 Apple 开发者签名，也没有公证（公证需要 99 美元/年的付费开发者账号）。
所以下载之后 macOS 会拦你一次 —— 这是预期行为，不是文件损坏。

1. 打开 dmg，把 zWGestures.app 拖进「应用程序」。

   不要在 dmg 卷里直接双击运行。 dmg 卷是只读的、随时会被卸载，而且系统会把卷内运行的应用
   移置到一个随机只读路径 —— 后果是开机自启注册的是那个临时路径，重启后就失效了。

2. 双击打开。它会好像启动了一下又马上退出 —— 那是系统在后台评估之后把它结束了（实测约 20 秒）。

3. 打开 系统设置 › 隐私与安全性，往下找到 安全性 一节，会看到
   「已阻止“zWGestures”以保护Mac。」，点它右边的 「仍要打开」。

   在 Finder 里双击时如果弹的是对话框，那个对话框上的按钮放行不了 ——
   macOS Sequoia 起苹果已经移除了「按住 Control 点按 → 打开」这条老路，必须去系统设置。

4. 回到「应用程序」再双击一次 zWGestures。

5. 到 系统设置 › 隐私与安全性 › 辅助功能 里勾选 zWGestures。
   没有这个权限，全局手势拦截和合成按键都无法工作。勾选之后不需要重启应用 ——
   它会自己发现并把引擎拉起来。

6. 完成 —— 开箱就有下面那 48 条中文手势。

习惯命令行的话，第 3 步也可以用：

xattr -dr com.apple.quarantine /Applications/zWGestures.app

（实测：浏览器下载的文件会带 com.apple.quarantine 标记，而 curl -L 下载的不会 ——
原因与完整实测记录见仓库里的 docs/INSTALL.md。）

---

更新之后画手势没反应？

几乎一定是辅助功能授权失效了。这个版本没有 Developer ID 签名，macOS 按构建指纹识别它，
所以每更新一版都要重新授权一次。

这次会明确告诉你：应用会弹一次说明并给出「打开系统设置」按钮，菜单栏也会写
「辅助功能权限：已失效（点击重新授权）」。到辅助功能列表里把 zWGestures 取消勾选再勾上即可，
不需要重启应用。

---

开箱就有 48 条中文手势

没装过原版 WGestures 的话，首次启动会载入内置的 48 条中文手势（全局 45 + Finder 3），
取自原版自己的出厂手势集、名字用原版自带的中文译名表：

画「上」拷贝 · 画「下」粘贴 · 向左后退 · 向右前进 · L 形关闭窗口 · C 形切换 App ·
「上→下」闭合回路打开 Web 搜索 · 还有音量/亮度/静音/全屏/最小化/切换 App/睡眠/关机/播放暂停等等。

可以直接用，也可以在设置界面里随便改 —— 改名、重画形状、换动作、调优先级、临时禁用，
都不用再手改 JSON。

---

已经装了原版 WGestures？

首次启动会自动导入你现有的手势，并在弹窗里报告迁移了哪些内容。你的手势、按应用分组、
触发矩阵都会带过来。

原版的配置目录只被读取，绝不会被改写。 zWGestures 的配置写在它自己的
~/Library/Application Support/zWGestures/，并且每次覆盖前都会自动备份（各留最近 10 份）。
你原来的 WGestures 可以继续照常使用；菜单栏里也随时可以重新导入一次。

---

已知限制

• 界面目前仅中文。 英文界面排在 v0.2.0 的路线图上。
• 仅支持 Apple Silicon。 不做 Intel / Universal 支持 —— 这正是这个项目存在的理由之一：
  原版是 x86_64 应用、依赖 Rosetta，而
  macOS 27 是最后一个支持 Rosetta 的版本。
• 触发矩阵编辑、边角与滚轮触发尚未实现（这类手势在列表里默认隐藏）。
• 手势分组、动画回放尚未实现。

---

这个版本里有一件值得单独说的事

开发期间发现并修掉了一个会让整台 Mac 输入冻结、只能按住电源键强制关机的缺陷。

事件拦截器原来会捕获键盘事件，而拦截器的回调是同步的：系统必须等回调返回才投递该事件。
鼠标移动可以被合并，回调慢一点只是轨迹变粗；键盘事件无法合并，所以回调一旦错过系统的截止时间，
打字就会整机失效。更糟的是旧实现在系统因超时禁用它之后立刻无条件重新启用，把系统反复拖回
一个跟不上的拦截器 —— 实测日志里它在一节课的时间里被系统摘掉了 42 次。

现在拦截器完全不碰键盘（急停快捷键改用不吞事件的监听实现），超时后退避 0.5 秒再启用，
并且在一段窗口内超时过多时主动停用自己并弹窗说明，而不是无限重试。这两条都有单元测试守着。

完整的证据链、根因与「为什么偏偏那次会话」的诚实结论，见仓库里的 docs/ROADMAP.md §13。

---

许可与致谢

以 MIT 许可证发布。

WGestures 2 是一款出色的鼠标手势工具，它的「手势＝操作步骤之和」「手势修饰键」「继承与重载」等
设计是这个项目的直接灵感来源。原版 macOS 版最后一个版本是 2021 年 12 月的 2.3.3。

zWGestures 是独立的重新实现，不是官方版本，与原项目及作者 yingdev（Ying Yuandong）
没有任何隶属关系，也未获其背书；不包含原版的任何二进制、字体、图标或激活码，
兼容性仅限于配置文件格式。

如果你还在用原版并且觉得它好用，请去
yingdev.com/projects/wgestures2 支持原作者。