[feature] 支持左/右修饰键快捷键与鼠标中键唤起语音识别

[Maple0517]

背景

当前语音识别唤起方式里，有两个触发入口不太方便自定义：

1. 快捷键无法区分左 / 右侧修饰键，导致一些常用按键无法配置，例如 Fn、左侧 Command。
2. 鼠标中键（滚轮按下）不能作为独立的语音识别唤起方式开启 / 关闭。

需求

1. 支持配置左 / 右侧修饰键

希望语音识别唤起快捷键支持区分左右侧修饰键，至少包括：

• 左侧 Command
• 右侧 Command
• Fn
• 如平台支持，也可扩展到 Left/Right Ctrl、Alt、Shift

期望：设置快捷键时能识别并保存具体侧别，而不是统一映射成同一个修饰键。

2. 增加“鼠标中键唤起识别”开关

希望在设置里增加一个独立开关：

• 开启后：按下鼠标中键（滚轮按下）触发语音识别
• 关闭后：鼠标中键不触发语音识别
• 该开关应独立于键盘快捷键配置，不影响现有快捷键

使用场景

• 笔记本或外接键盘上，右侧修饰键不方便使用，左侧 Command / Fn 更顺手。
• 鼠标中键适合作为低打扰、单手可用的语音输入入口。
• 用户可以按自己的硬件习惯选择键盘或鼠标触发方式。

期望结果

• 快捷键设置能正确识别左 / 右侧修饰键，至少支持左侧 Command、Fn。
• 设置页提供“鼠标中键唤起识别”的独立开关。
• 两种触发方式可以共存，也可以分别关闭。

[HKLHaoBin]

没想到你这个还蛮难写的。

[HKLHaoBin]

---

name: Input Trigger Enhancement
overview: 为桌面端（Windows / macOS / Linux）扩展语音识别触发能力：修复并补全左右侧修饰键（含组合键侧别），新增鼠标中键/侧键独立开关，并在多触发源并存时正确处理 Hold 模式。
todos:

• id: model-recorder
  content: 扩展 HotkeyTrigger / ShortcutBinding 侧别 tag；修复 ShortcutRecorder；补 formatPrimary 与 Fn chip UI
  status: completed
• id: modifier-hooks
  content: hotkey.rs + linux_fcitx + capability 补全 LeftCommand/LeftShift/RightShift 单键监听
  status: completed
• id: side-aware-combo
  content: 新增 side_aware_combo.rs，Win/macOS 物理键状态机；combo supervisor 路由分流
  status: completed
• id: mouse-prefs-ui
  content: UserPreferences 增加 mouseMiddleButtonDictation / mouseSideButtonDictation；RecordingInputSection 两个 Toggle
  status: completed
• id: mouse-hooks
  content: 新增 mouse_dictation.rs：Win WH_MOUSE_LL、macOS CGEventTap 鼠标事件
  status: completed
• id: linux-evdev
  content: 新增 linux_evdev_input.rs（evdev 依赖）：Linux 鼠标触发 + 侧别组合键
  status: completed
• id: hold-tracker
  content: hold_source_tracker：多触发源 Hold refcount；dictation bridge 接入 TriggerSource
  status: completed
• id: tests
  content: shortcut_binding / side_aware_combo / hold_tracker 单元测试 + 关键平台手工验证清单
  status: in_progress
  isProject: false

---

语音识别触发方式增强

现状与缺口

当前听写触发采用双轨模型（见 hotkey_loops.rs）：

flowchart LR
  subgraph keyboard [键盘]
    ModOnly["单独修饰键\nRightOption / Fn 等"]
    Combo["组合键\nCtrl+Shift+D"]
  end
  ModOnly --> hotkey_rs["hotkey.rs\nCGEventTap / WH_KEYBOARD_LL / fcitx5"]
  Combo --> global_hotkey["combo_hotkey.rs\nglobal-hotkey"]
  hotkey_rs --> bridge["handle_pressed_edge"]
  global_hotkey --> bridge
  bridge --> dictation["dictation.rs\nbegin_session / end_session"]

Loading

已确认的问题：

缺口	位置	影响
MetaLeft 被录成 RightCommand	ShortcutRecorder.tsx:229	左 ⌘ 无法正确保存
无 LeftCommand / LeftShift / RightShift trigger	types.rs HotkeyTrigger	后端无法监听左 ⌘、左右 Shift 单键
组合键 modifiers 只有 cmd/ctrl 等泛化 tag	ShortcutBinding.modifiers + parse_global_hotkey	global-hotkey 无法区分左/右
Fn 在 WebView 录制无 keydown	ShortcutRecorder 仅键盘事件	用户无法通过「录制」配 Fn
鼠标中键/侧键无全局监听	hotkey.rs 仅键盘；Mouse4/5 仅类型/标签	需求 2/3 完全缺失
Linux 无 evdev 输入层	仅 fcitx5 键盘 DBus	鼠标 + 侧别组合键在 Linux 无落点

用户已确认：组合键也要区分左右侧；Linux 也要支持鼠标触发（可接受 evdev 依赖）。

---

目标架构

flowchart TB
  prefs["UserPreferences\n- dictationHotkey\n- mouseMiddleButtonDictation\n- mouseSideButtonDictation"]
  router["binding_router\n(shortcut_binding.rs)"]
  modHook["hotkey.rs\nmodifier-only"]
  sideCombo["side_aware_combo.rs\n物理键状态机"]
  genericCombo["combo_hotkey.rs\nglobal-hotkey\n(泛化 modifiers)"]
  mouseHook["mouse_dictation.rs\nevdev / WH_MOUSE_LL / CGEventTap"]
  bridge["hotkey_bridge_loop\n(复用 HotkeyEvent)"]
  hold["hold_source_tracker\n多触发源 Hold  refcount"]
  dictation["dictation.rs"]

  prefs --> router
  router -->|legacy modifier| modHook
  router -->|含侧别 modifiers| sideCombo
  router -->|泛化 combo| genericCombo
  prefs --> mouseHook
  modHook --> bridge
  sideCombo --> bridge
  genericCombo --> bridge
  mouseHook --> bridge
  bridge --> hold --> dictation

Loading

---

一、左右侧修饰键（单键 + 组合键）

1.1 扩展数据模型

HotkeyTrigger 新增：

• LeftCommand（macOS keycode 55 / Windows VK_LWIN / Linux Super_L）
• LeftShift、RightShift（单键触发；Shift 组合键走 modifiers 侧别 tag）

ShortcutBinding.modifiers 扩展侧别 tag（向后兼容旧值）：

新 tag	含义
cmd-left / cmd-right	左/右 Command（Windows 映射为 Win）
ctrl-left / ctrl-right	左/右 Control
alt-left / alt-right	左/右 Alt/Option
shift-left / shift-right	左/右 Shift

旧 tag（cmd、ctrl 等）保持不变，继续走 global-hotkey。

在 shortcut_binding.rs 增加：

• binding_requires_side_aware_hook(binding) -> bool
• legacy_modifier_trigger() 补全 leftcommand、leftshift、rightshift
• 侧别 tag 校验与规范化（Windows 下 cmd-left → 仍存为语义 tag，监听层映射 VK）

1.2 修复录制 UI

ShortcutRecorder.tsx：

• Bug 修复：MetaLeft → LeftCommand，MetaRight → RightCommand
• Shift 单键：modifierPrimaryFromCode 区分 ShiftLeft / ShiftRight（不再统一 Shift）
• 组合键侧别：modifiersFromKeyboardEvent(e) 改为读取 e.code（如 MetaLeft → cmd-left），主键仍用现有 primaryFromKeyboardEvent
• Fn 快捷选择：在录制区下方增加「常用单修饰键」chip 列表，数据来自 capability.availableTriggers（macOS 含 Fn）；点击直接 finish({ primary: 'Fn', modifiers: [] })，解决 WebView 捕不到 Fn 的问题

hotkey.ts 的 formatComboLabel / formatPrimary 补 LeftCommand、LeftShift、RightShift 及侧别 modifier 显示（如 左 ⌘+D）。

i18n：在现有 locale 资源中补 hotkey.triggers.leftCommand 等键（与现有 hotkey.triggers.* 模式一致）。

1.3 后端监听补全

单修饰键路径 — hotkey.rs：

Trigger	macOS keycode	Windows VK	Linux fcitx
LeftCommand	55	VK_LWIN	Super_L
LeftShift	56	VK_LSHIFT	Shift_L
RightShift	60	VK_RSHIFT	Shift_R

同步更新 linux_fcitx.rs、hotkey_loops.rs window fallback 的 window_key_matches_trigger、HotkeyCapability.available_triggers。

侧别组合键 — 新模块 side_aware_combo.rs：

• 维护物理修饰键按下状态（MetaLeft、ControlRight 等）
• 主键 down 时精确匹配 ShortcutBinding（含侧别 modifiers + primary）
• 主键 up / 修饰键全释放时发 Released（Hold 模式）
• 平台实现：
  • Windows：扩展现有 WH_KEYBOARD_LL 回调（与 dictation modifier hook 同线程/同 hook 过程）
  • macOS：扩 CGEventTap 为 KEY_DOWN | KEY_UP | FLAGS_CHANGED，在 flags 变化时更新侧别状态
  • Linux：见第三节 evdev 统一输入层

combo_hotkey_supervisor_loop 路由调整：

if legacy_modifier_trigger(&binding).is_some() { /* 卸载 combo */ }
else if binding_requires_side_aware_hook(&binding) { SideAwareComboMonitor::start(...) }
else { ComboHotkeyMonitor::start(...) } // 现有 global-hotkey

---

二、鼠标中键 / 侧键独立开关

2.1 偏好字段

在 UserPreferences / types.ts 新增（默认 false，不影响现有用户）：

mouseMiddleButtonDictation: boolean;  // 中键（滚轮按下）
mouseSideButtonDictation: boolean;    // 侧键（Mouse4 后退 + Mouse5 前进）

• 与 dictationHotkey 独立；共用现有 hotkey.mode（Toggle / Hold）
• 持久化走现有 persist_settings 路径，变更时刷新监听器

2.2 全局鼠标监听 — 新模块 mouse_dictation.rs

平台	机制	映射
Windows	WH_MOUSE_LL（可与键盘 hook 合并）	WM_MBUTTON* → Middle；WM_XBUTTON* → Side
macOS	CGEventTap 增加 OtherMouseDown/Up	buttonNumber 2=中键，3/4=侧键
Linux	evdev 读 /dev/input/event*	BTN_MIDDLE、BTN_SIDE、BTN_EXTRA

• 产出与键盘相同的 HotkeyEvent::Pressed / Released，接入现有 hotkey_bridge_loop
• 仅在对应 pref 为 true 时响应；prefs 变更时 hot-reload
• Android / mobile stub：字段 serde 默认值即可，UI 不展示（沿用 showDesktopHotkey 门控）

2.3 设置 UI

在 RecordingInputSection.tsx 的「录音方式 / 快捷键模式」下方新增两行 SettingRow + Toggle：

• 「鼠标中键唤起识别」
• 「鼠标侧键唤起识别」（覆盖前进/后退两键）

Linux 若 evdev 权限不足（非 input 组成员），Toggle 旁显示 capability 提示（类似现有 hotkey 权限 hint），不阻止保存偏好。

---

三、Linux evdev 输入层

新增 linux_evdev_input.rs，依赖 evdev crate（仅 [target.'cfg(target_os = "linux")'.dependencies]）。

职责：

1. 鼠标听写触发（中键/侧键）— 当任一 mouse pref 开启
2. 侧别组合键 — 当 dictation binding 含侧别 modifiers 时，与 fcitx5 并行或替代 combo 路径
3. 设备热插拔：轮询或 inotify 重扫 input* 节点；失败时 supervisor 重试（对齐现有 hotkey supervisor 模式）

权限：文档/设置 hint 说明需将用户加入 input 组或使用 udev 规则；运行时检测失败时在 HotkeyStatus 或 platform capability 中返回可读错误。

fcitx5 路径保留用于：泛化 combo、modifier-only（无 evdev 时降级提示）。

---

四、多触发源 Hold 模式

现有单一 latch hotkey_trigger_held 在键盘 + 鼠标并存时会误结束会话。

改为 Hold 源计数 / 位掩码（新 helper hold_source_tracker.rs）：

• 源类型：KeyboardDictation | MouseMiddle | MouseSide
• Hold 模式：Pressed 对应源 +1；Released 对应源 -1；计数 0→1 调 begin_session，1→0 调 end_session
• Toggle 模式：保持现有 per-edge 行为（任一源 press 切换）
• handle_pressed_edge / handle_released_edge 增加 TriggerSource 参数；bridge loop 传入来源

---

五、测试与验证

层级	内容
单元测试	shortcut_binding.rs 侧别 tag 解析；ShortcutRecorder 侧别录制逻辑（Vitest）；side_aware_combo 状态机；hold_source_tracker
Rust 集成	扩展现有 hotkey.rs tests 覆盖 LeftCommand；mouse 事件 mock（Windows message / macOS flag mock）
手工	macOS：左 ⌘ 单键、左 ⌘+D combo、Fn chip、中键/侧键 toggle 与键盘 combo 共存；Windows：左 Ctrl / 侧键；Linux：evdev 权限 + 三键

---

关键文件清单

文件	变更
ShortcutRecorder.tsx	侧别录制 + Fn chip
hotkey.ts / types.ts	标签、新 pref 字段
shortcut_binding.rs	侧别 tag + 路由判定
hotkey.rs	LeftCommand/Shift + 键盘 hook 扩展
side_aware_combo.rs (新)	侧别组合键
mouse_dictation.rs (新)	鼠标触发
linux_evdev_input.rs (新)	Linux 输入
hold_source_tracker.rs (新)	多源 Hold
RecordingInputSection.tsx	两个 Toggle
hotkey_loops.rs	supervisor 路由 + mouse monitor 生命周期
dictation.rs	Hold 源追踪接入

---

实施顺序

1. 数据模型 + 录制修复 + 单修饰键 LeftCommand/Shift — 低风险、可独立验证
2. 侧别组合键 side_aware_combo — Win/macOS 先通，再接 Linux evdev 键盘部分
3. 鼠标 pref + mouse_dictation — Win/macOS → Linux evdev
4. Hold 源追踪 — 在鼠标与键盘可并存后接入
5. UI/i18n/文档 hint — 与功能同步收尾

---

风险与约束

• Fn（Windows）：硬件 Fn 仍可能无法被 OS 暴露为独立 VK；保持现有「Fn 复用 RightControl」别名，UI 标注平台限制
• Linux evdev：需 input 组权限；应在设置页给出明确指引，避免 silent failure
• global-hotkey 限制：仅泛化 combo 继续使用；含侧别 modifiers 的 binding 不得注册到 global-hotkey，避免误匹配
• Android：本需求范围外；mobile stub 保持 Unavailable，不展示桌面 hotkey/鼠标开关