常见问题#
手势不触发#
先在普通、非全屏浏览器窗口试一个简单内置手势。
检查托盘／菜单栏。Windows 显示“恢复手势”时点它恢复；Mac 的“暂停手势”被勾选时，再点一次恢复。也检查“偏好设置 → 暂停 / 恢复快捷键”，确认没有误按暂停。
退出全屏。即使没有手动暂停，全屏自动抑制也可能停止鼠标手势和边角动作。
在设置中选中程序，检查“禁用手势”；同时检查单条手势的“启用”／“已停用”、“也使用通用手势”、触发按钮和附加步骤。
按下后尽快移动，并画长一些。可调整偏好设置中的“按住多久不动算普通点击”和“笔画灵敏度”。
没有视觉反馈时，检查“显示轨迹”和“画的时候显示手势名”。隐藏轨迹不等于没有识别。
Windows 使用 SendInput。普通权限启动的 Mousetroke 可能因为 Windows UIPI 无法向管理员窗口发送按键／点击。先在普通权限程序中测试；确需控制管理员窗口时，以对应权限运行 Mousetroke。这不代表能向安全桌面发送输入。
Mac 请为已安装的那份应用开启“辅助功能”。引导仍要求“输入监控”时，也开启它。权限变更可能需几秒才被检测到；仍无法启动时，用引导提供的“重启 Mousetroke”。不需要屏幕录制权限。移动副本或通过浏览器重新下载替换后，可能需要重新批准首次打开。
首次打开被 SmartScreen 或 Gatekeeper 拦截#
Windows 从官方发布页下载并校验后，选“更多信息 → 仍要运行”。Mac 安装到“应用程序”后，到“系统设置 → 隐私与安全性 → 仍要打开”；较旧系统也可“右键 → 打开”。完整流程见安装。
程序收不到按键#
先用真实键盘测试快捷键。检查程序是否已激活，或开启“先激活鼠标下的窗口再发送”。核对手势目标设置及按键语法：^ 是 Control，Mac 的 # 才是 Command。程序打开菜单或对话框需要时间时，可以在相关步骤之间加短暂的 {SLEEP 100}。
Mac 按键序列会跳过鼠标／滚轮、媒体／音量键、Insert、Print Screen、Break 和 F21–F24。媒体和音量请使用“媒体与系统”动作。不支持的选项会在编辑器提示，也应检查日志。
Ctrl+Alt+Del 属于 Windows 安全注意序列，普通模拟输入不能发送。可用 Ctrl+Shift+Esc 打开任务管理器，Win+L 锁屏，或 shutdown /l 注销。详见按键语法。
输入法或输出文字不正确#
普通按键序列字符代表美式键盘位置，不能直接表达任意 Unicode 文字。单独写大写字母也不会自动按 Shift。Lua 的 ms.keys(text, true) 能输出 Unicode 文本，但仍会解释 ^、{ 等语法字符。
标点较多、非拉丁文字或输入法处理特殊的程序，建议使用剪贴板粘贴并恢复示例。这些 API 只能恢复文字，不保留图片等其他剪贴板格式。部分程序需要增加恢复前的等待时间。
Lua 错误#
确认代码定义了 function ms_action(...) ... end。加载和执行错误写入运行日志，可用“关于 → 打开日志”查看。用 ms.log 记录值，用 ms.show_toast 显示短提示，判断脚本走到哪一步。Mac 上未实现的函数可能只记警告并返回 nil，不要把空值当成功。
Mac 窗口查找／状态操作需要辅助功能权限，按键状态查询缺少权限时返回 false；结果缺失时先检查该权限。跨应用置顶和数值亮度仍不支持，内建亮度键动作不能提供百分比。两平台的 ms.get_brightness／ms.set_brightness 失败均返回 nil。
Lua 分配内存上限为 8 MiB，没有脚本执行超时。避免无限循环，阻塞行为见 Lua 入门。
远程桌面与游戏冲突#
远程桌面、虚拟机、3D／游戏程序可能需要同一鼠标按钮拖拽，也可能以不同方式处理模拟输入。可为该程序禁用手势，或使用期间暂停。窗口模式游戏不一定触发全屏检测，应明确添加排除规则。在普通本地程序测试快捷键，有助于区分语法问题与应用输入处理问题。
报告问题#
使用“关于 → 反馈 → 打开”，或前往 GitHub Issues。提供程序版本、系统版本、相关应用、手势和动作、预期结果及复现步骤。附上“关于 → 打开日志”中的相关日志，必要时附最小导出配置。分享前检查附件中的私人文字、窗口标题、路径和命令参数。