﻿龙虾鼠标快捷键映射器  v2.3.0
====================================================

一款轻量、中文、开箱即用的 Windows 鼠标按键映射工具。
不需要雷蛇 Synapse，也不限定鼠标品牌 —— 只要鼠标能发出标准的中键、
侧键 1、侧键 2 信号，就能直接映射。

【安装】
双击「安装.bat」。全程不需要管理员权限，不写系统目录，不联网。
安装位置：%LOCALAPPDATA%\Programs\LobsterMouseMapper
装完桌面和开始菜单里都会有快捷方式。卸载请双击「卸载.bat」。

也可以完全不安装 —— 直接双击「龙虾鼠标快捷键映射器.exe」就能用，
配置会保存在 exe 同目录的 lobster-mapper.ini 里。


【三步上手】
1. 第①步「识别设备」：确认认出了你的鼠标型号。
2. 第②步「配置按键」：先在图上标出按键位置，再点圆点填内容。
3. 第③步「配置方案」：方案管理和全局设置（阈值用滑杆拖，还有手感测试）。


【第②步：标记由你自己标】
打开第②步，鼠标图上**一个标记也没有** —— 程序不再自动生成任何热区，
位置全部由你决定。两种加法：

  A. 「＋ 识别新按键」（推荐，最准）
     ① 点左下角这颗按钮
     ② 按下鼠标上那个键（程序会认出来是什么键）
     ③ 回到图上，在它的位置点一下 —— 在那个点生成标记，落点会记住

  B. 「一键放置 5 个标准键位」
     一次把 左键/右键/中键/侧键1/侧键2 各放一个点，
     然后直接**拖动圆点**挪到你鼠标上对应的位置。

标记长这样：一个小圆点 + 旁边一行名字。

  · 没绑过的键：灰色圆点
  · 绑过的键：  珊瑚红圆点
  · 正在编辑：  深红圆点
  · 按真实按键：会闪一下，用来确认信号有没有进来

  单击圆点或它的名字 = 选中这个键
  按住圆点拖动         = 挪到别的位置（立刻保存）
  右键圆点             = 重命名 / 从图上删掉

滚轮上 / 滚轮下（以及横向滚轮的左右）不是「按键」，是滚动方向，
放在图下方的「滚动手势」一栏里，不混在图上。


【第②步：右侧编辑区】
只有三件事，从上到下：

  触发方式   单击 / 双击 / 长按      —— 什么时候触发
  执行内容   [输入框]  [按一下来学]  —— 触发后做什么
             [选常用组合键 ▾]        —— 常用组合，直接选，不用手打
  执行状态   单次点击 / 一直长按      —— 点一下，还是按住不放

「执行内容」不用选类型，程序会看着你写的内容自动判断，下面那行
「识别为：…」会告诉你它认成了什么；认错了点那一行就能手动改。

自动判定规则：
  含 http:// 或 https:// 或 www.  → 打开网址
  形如 run=…; wait=…; keys=…; click=… → 多步动作
  以 .exe/.bat/.cmd/.lnk 结尾，或形如 C:\… 或 \\server\… → 启动程序
  含中文（或像一句话）        → 一句话，交给 AI 转
  其余                        → 按键 / 组合键

按键写法与 SendKeys 一致：
  ^c = Ctrl+C      ^+s = Ctrl+Shift+S      %{F4} = Alt+F4
  {MEDIA_PLAY_PAUSE} 播放暂停   {VOLUME_UP} 音量加

「选常用组合键」里预置了 37 条常用组合（复制粘贴、撤销重做、Alt+F4、
方向键、音量、播放暂停等），点一下就填好。

不想手点就点「按一下来学」，直接按键录入 —— 按 Ctrl+C 就会录到完整的
Ctrl+C（上一版这里只录得到 Ctrl，已修）。

写完点底部那颗红按钮「✔ 确认更改到「侧键 1 · 单击」」写入。
按钮上方那行「已保存：…」随时告诉你这个键这一档现在绑的是什么。
忘了点也没关系 —— 去点别的键、切档位、切方案或关窗口时会自动先写入。

把输入框清空再点确认 = 取消这个键在这一档的绑定。


【执行状态：「一直长按」是什么】
想要「按住侧键 1 就等于一直按着 Ctrl，松开侧键才放开」，
就在「执行状态」选「一直长按」，内容填 ^（或在常用组合里选「只按 Ctrl」）。

  · 只有长按档能承载它。单击/双击/滚轮没有「按住多久」的概念，
    绑了会退化成按一下
  · 长按阈值到了才按下；松开鼠标键立刻释放
  · 防卡键有三道保险：松开鼠标键即释放；暂停映射 / 切方案 / 关程序时
    全部释放；钩子被系统摘掉需要重装时先无条件释放
    所以不会出现 Ctrl 卡在按下状态、怎么都松不开的情况


【多步动作】
一行写完一串动作，步骤之间用 ; 分隔：

  run=C:\Program Files\JianYing\JianYing.exe; wait=2500; keys=^e

  run=   启动某个程序
  wait=  等待多少毫秒
  keys=  发送一次按键
  click= 在屏幕坐标点一下，例如 click=640,360

「点软件里某个按钮」在完全离线的前提下只能靠模拟按键或定点点击实现；
写入后会立刻生效，不需要点确认。


【一句话（交给 AI 转）】
输入框里可以直接写人话，比如「打开剪映然后点导出」。
程序会原样记住这句话，但不会执行它 —— 它是「待提取」状态，
按下去不会有反应（信号监视器里会写明）。

想让它真的能用，把这句话告诉 AI（在 WorkBuddy 里说一声），
AI 读配置后把它翻译成上面那种「多步动作」写回来。


【全局设置与手感测试（第③步）】
  · 长按阈值、双击间隔：拖滑杆，立刻生效并保存，右边显示当前毫秒数
  · 手感测试：按住那块区域，实时显示「已按住 xxx ms」，到阈值会变色提示；
    松开后给结论，比如「按住 1023 ms · 会触发长按 —— 如果嫌太灵敏，
    把滑杆往右拉」。调参不用来回试，拖一下、按一下就知道顺不顺手。


【场景预设 · 一键套用（v2.4.0 新增）】
第③步「场景预设」区有 6 套现成配置，点一下整套按键就配好，并自动切过去：

  微信语音输入   长按侧键 1 说话，松开即结束并整理
  浏览器冲浪     侧键 1 后退、侧键 2 前进、中键 关闭标签页
  办公效率       中键 粘贴、侧键 1 复制、侧键 2 撤销
  媒体控制       侧键 1 上一首、侧键 2 下一首、中键 播放/暂停
  音量调节       侧键 1 减小、侧键 2 增大、中键 静音
  设计与课件     中键 撤销、侧键 1 保存、侧键 2 全屏（F5）

它不会动你已有的方案，只新建（或按你的确认重置）一个同名方案。想切回原来的，
在顶栏「配置方案」下拉里选回去就行。同名方案里已经有你配好的按键时，会先问你
要不要覆盖。

配好之后建议点顶栏的「导出」，把整份配置存成一个文件。换电脑时在新电脑上点
「导入」，所有方案一次性回来，不用重新配一遍。

程序每次启动还会自动留一份 lobster-mapper.bak（和配置文件同目录），万一配置
写坏了，把它的名字改回 lobster-mapper.ini 就能捞回来。


【常驻保活：为什么它会被"清理掉"，以及怎么让它自己回来（v2.4.0 新增）】
「早上打开电脑，发现程序不见了」不是错觉。后台的「电脑管家 · 内存清理」这类工具
会主动结束它认为闲置的进程。程序一旦被结束，如果没有保护，就再也不会自己回来 ——
而映射不生效，用起来就像「配好的东西全没了，得重新配」。

第③步的「常驻保活」区让程序能自己回来，就两件事：

  登录 Windows 后自动启动     写一条启动项，开机自动起来（不需要管理员权限）
  被结束后自动拉起            守护脚本每 15 秒看一次，不在就立刻拉起来

两个默认都开。状态行会直接告诉你结果：
  绿色「当前状态：已保活 ✓」  = 都到位了
  黄色「只做了一半」          = 点下面的「立即写入 / 修复保活设置」补齐
  红色「未保活」              = 重启后不会自动启动，被结束也不会回来

守护脚本在 %APPDATA%\LobsterMouseMapper\guard.vbs，是纯文本，可以自己打开看。
把「被结束后自动拉起」的勾去掉，它会自动删除，不留垃圾。

另外两点：
  · 勾了保活之后，登录时程序静默进托盘，不会弹窗打扰。
  · 如果连守护脚本也被清掉了，把这两个加进清理软件的白名单：
    程序在 %LOCALAPPDATA%\Programs\LobsterMouseMapper\


【识别新按键的两种通道】
· 鼠标通道（绝大多数情况）：按下鼠标上的键，直接就能认出来。
· 键盘通道：有些鼠标的多余按键被厂商驱动改写成键盘按键了，程序挨个按下时
  收不到鼠标信号，会转而看键盘。只接管 F13–F24 这类正常键盘上没有的键；
  普通字母数字键不接管（否则你打字就乱套了），按到时会提示你改按鼠标上的键。

左键与右键不参与映射，也不会被识别进来。


【微信输入法 · 语音输入联动（v2.3.0 新增）】
微信输入法的语音输入是「按住某个键说话」。本工具的「一直长按」正好是同一个语义 ——
按住鼠标键就替你按住那个键、松手才放。所以不用改微信输入法的任何设置，只要在我们这边
把「长按鼠标键」映射成「按住语音键」，联动就成了。

用法（第③步，往下滚到最下面那张卡片）：
  1. 卡片第一行会显示检测结果，例如「微信输入法 v2.1.4.6 · 正在运行」
  2. 触发键：默认「左 Alt（实测推荐）」，一般不用改
  3. 接到哪个鼠标键上：默认「侧键 1」
  4. 点「⚡ 一键对接」→ 状态栏回显「✔ 已对接」
  5. 切到微信输入法，按住侧键说一句话，松开 —— 文字自动落进光标处

没反应时按顺序查：
  · 当前输入法是不是微信输入法（任务栏右下角）
  · 换一个触发键（右 Alt / Ctrl+Win）再点一次「一键对接」
  · 鼠标厂商驱动（雷蛇 Synapse / 罗技 G HUB）是不是退出干净了
  · 点左下角「信号监视器」，看按住侧键时有没有记录

为什么不做「自动改微信输入法里的快捷键」：实测它的设置不写注册表，存在加密的本地库里
还有云端同步会覆盖，外部程序硬改有把它改坏的风险。所以本工具只做我们这边的一键对接，
微信输入法用它自己的默认键就行 —— 这样它升级也不影响你用。

实测记录（本机跑的，可复现）：按住左 Alt 1.2/3/5 秒每次都触发；按住右 Alt 与 Ctrl+Win 不触发；
用鼠标侧键（映射成按住左 Alt）能触发。所以默认给的是左 Alt，不行就换。

详细图文步骤见仓库里的《教程_微信输入法语音输入.md》。


【防多开（v2.4.0 新增）】
程序现在只允许一个实例。重复双击时，如果它已经在托盘里运行，会把已有窗口叫到
前台，而不是再起一个。以前多开会同时挂两套钩子，同一次按键被处理两遍。

从守护脚本自动拉起时则是静默的，不会抢你的焦点。


【重要提醒】
如果按下侧键后，界面上的圆点不闪红、下面的信号监视器（点左下角
「信号监视器」展开）也什么都不出现，说明信号根本没到本程序 ——
最常见的原因是被鼠标厂商驱动抢走了。雷蛇 Synapse、罗技 G HUB 这类
软件会在系统钩子链里排在前面，把侧键信号吃掉。请先从托盘彻底退出它们，
再回到第①步点「重新检测设备」。

左键与右键强制保留原功能，不参与映射（否则鼠标将无法正常点击）。


【版本说明】
v2.4.0（常驻保活 + 场景预设）
- 新增「常驻保活」：登录自动启动 + 守护脚本每 15 秒检查一次，被清理软件结束后
  最多 15 秒自己回来。实测强杀主进程后 8 秒被拉回，且是静默的、不抢焦点
- 新增「场景预设 · 一键套用」：6 套现成配置（微信语音、浏览器、办公、
  媒体、音量、设计与课件），点一下就配好并切过去，不影响你原有的方案
- 新增防多开：重复双击把已有窗口叫到前台，不再起第二个实例
- 新增配置自动备份 lobster-mapper.bak
- 说明：计划任务（schtasks）方案实测被拒 —— 即使账号属于 Administrators 组，
  未提权时 schtasks /Create 一律返回「拒绝访问」，所以保活改用不需要权限的
  启动项 + 守护脚本实现

v2.3.0（微信输入法语音输入联动）
- 第③步新增「微信输入法 · 语音输入联动」：自动检测版本与运行状态，
  选触发键与目标鼠标键，点「⚡ 一键对接」一次写好「长按侧键 = 按住语音键」
- 新增《教程_微信输入法语音输入.md》，含三步对接、排错表与实测记录
- 修：keybd_event 送右 Alt / 右 Ctrl / Win / 方向键这类「扩展键」时没带
  KEYEVENTF_EXTENDEDKEY 标志，会被程序认成坏键（实测微信输入法就不认右 Alt）
- 新增 {RALT} {LALT} {RCTRL} {WIN} 等写法，可以按住左右分开的修饰键

v2.2.0（标记自己做主 + 修组合键识别）
- 图上不再自动生成任何热区。要配哪个键，先用「＋ 识别新按键」认出它、
  再在图上点它的位置；或者用「一键放置 5 个标准键位」一次放好再拖
- 标记改成一个能拖动的小圆点 + 一行名字，右键可重命名或删除
- 去掉图下方那份「全部按键」列表（和图上重复，没必要）
- 「＋ 识别新按键」按钮移到左栏底部，就手
- 编辑区加回下拉框「选常用组合键」，预置 37 条常用组合；弹层向上展开，
  不会像上一版那样盖住「确认更改」按钮
- 修：按 Ctrl+C 只录得到 Ctrl（低级钩子里 Ctrl 报的是 0xA2 左Ctrl，
  和代码里查的 0x11 对不上，导致修饰键状态永远为假）—— 现在能录到 ^c
- 修：识别出的按键没落点就丢了；现在识别后引导你落位并立刻保存

v2.1.0（界面重做）
- 鼠标图改成「所见即所得」；滚轮上/下 从图上移走单独成栏
- 右侧编辑区精简成三行 + 一颗确认按钮
- 执行内容不再选类型，改为自动判定（可手动改）
- 长按阈值、双击间隔改成拖拽滑杆；新增「手感测试」

v2.0.2
- 新增「按住不放」型动作；恢复「识别新按键」入口；修合成按键缺扫描码、
  键名表缺修饰键

v2.0.1
- 修「全新配置下整个编辑区被禁用 / 内置动作写不进去 / 钩子自检每 15 秒
  误判重装」三个 Bug；新增「确认更改」按钮

【系统要求】
Windows 10 / 11 64 位。免安装、免运行库、完全离线、不上传任何数据。
