feat(linux): evdev input for side combos and mouse dictation (split from #724)

[HKLHaoBin]

User description

摘要

Completes #718（Linux 路径）。

由已关闭的 #724 拆分而来（第 3/3 部分）：linux_evdev_input + evdev 依赖；Linux 侧向组合与鼠标输入；prefs 变更时 refresh_linux_evdev_monitor；monitor 停止时清除 status_message。

堆叠 PR：含 #726 + #727 全部变更，用于 Linux 端到端验收。建议 #726/#727 合并后 rebase，或作为完整验收 PR 审查。

关联：#718、#724。

修复 / 新增 / 改进

• Linux evdev 输入层（侧向组合 + 鼠标）
• 热更新 monitor + input 组权限提示

兼容

• 依赖 PR1/PR2 的 side-aware 与 mouse 模块（本 PR 已 stack）

测试计划

Linux 实机验证（请维护者复测，回应 @jiangmuran）：

• 仅侧向组合：绑定 cmd-left+D / shift-left+D → evdev monitor 启动、听写触发
• 仅鼠标：开启中/侧键、无侧向组合 → 鼠标事件经 evdev
• Prefs 热更新：切换鼠标开关或改听写绑定 → monitor 重启，无需重启应用
• 权限提示：无 /dev/input/event* 读权限时出现 input 组提示；monitor 停止后清除
• 完整 [feature] 支持左/右修饰键快捷键与鼠标中键唤起语音识别 #718：侧向组合 + 鼠标 + Hold refcount 联合验收

本地已验证： npm run build、npm run check:hotkey-side-modifiers

---

PR Type

Enhancement, Tests

---

Description

• Support left/right modifier keys in dictation hotkeys

• Add independent mouse middle/side button dictation triggers

• Implement Linux evdev input for side combos and mouse events

• Track multiple hold sources for Hold mode with refcount

---

Diagram Walkthrough

flowchart LR
  Input["Input Events (Keyboard/Mouse)"]
  Platform["Platform Hooks\nWindows/macOS low-level\nLinux evdev"]
  SideCombo["SideAwareComboMonitor\n(Left/Right Modifier Matching)"]
  MouseDict["MouseDictationMonitor\n(Middle/Side Button Press)"]
  HoldTracker["HoldSourceTracker\n(Refcount Multiple Sources)"]
  Dict["Dictation Coordinator\n(Start/Stop Dictation)"]

  Input --> Platform
  Platform --> SideCombo
  Platform --> MouseDict
  SideCombo --> HoldTracker
  MouseDict --> HoldTracker
  HoldTracker --> Dict

Loading

File Walkthrough

	Relevant files
Tests	3 files mod.rs Add mouse_dictation_refreshes test counter                              +5/-0      mock-data.ts Add mock data for new dictation prefs                                        +2/-0      stylePrefs.test.ts Include new prefs fields in test data                                        +2/-0
Enhancement	12 files settings.rs Add refresh_mouse_dictation to settings persistence            +16/-0    coordinator.rs Integrate mouse/evdev/hold components and update hotkey binding +205/-3  dictation.rs Add TriggerSource parameter to edge handlers for hold mode +44/-16  hotkey_loops.rs Add mouse dictation and linux evdev supervision loops        +243/-6  hold_source_tracker.rs New HoldSourceTracker for refcounting multiple trigger sources +125/-0  hotkey.rs Add macOS mouse button dispatch for side and mouse dictation +12/-1    lib.rs Register new modules and start mouse dictation listener    +12/-0    linux_evdev_input.rs New Linux evdev monitor for side combos and mouse events  +481/-0  mouse_dictation.rs New mouse dictation monitor with platform hooks and update config +356/-0  types.rs Add mouse_middle_button_dictation and mouse_side_button_dictation prefs +16/-0    types.ts Update ShortcutBinding comments and add mouse dictation fields +6/-2      RecordingInputSection.tsx Add mouse dictation toggle UI components                                  +23/-0
Other	1 files *.rs Provide stub implementations for mobile platforms
Documentation	1 files en.ts, ja.ts, ko.ts, zh-CN.ts, zh-TW.ts Add i18n strings for mouse dictation settings
Dependencies	1 files Cargo.toml Add futures and evdev dependencies                                              +2/-0
Additional files	7 files linux_evdev_input.rs +32/-0    mouse_dictation.rs +38/-0    en.ts +4/-0      ja.ts +4/-0      ko.ts +4/-0      zh-CN.ts +4/-0      zh-TW.ts +4/-0

---

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit c98c801)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅ 724 - Fully compliant Compliant requirements: Support left/right modifier keys in dictation hotkeys via existing side_aware_combo module. Support mouse middle/side button dictation triggers with independent pref toggles. Implement Linux evdev input for side combos and mouse events. Hot-refresh Linux evdev monitor when prefs change. HoldSourceTracker for multiple hold sources. Mobile stubs for compilation. Tests for side modifiers, mouse dictation, etc. 718 - Fully compliant Compliant requirements: Support left/right modifier keys via side_aware_combo (already integrated). Support mouse middle button dictation with independent toggle. Settings UI for mouse middle and side button dictation added. Triggers coexist independently (side_combo and mouse are separate configs).

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ No major issues detected

[HKLHaoBin]

稍等，我处理一下ci问题。

[Felix201209]

Linux evdev 这层本身写得不错（见下），但这个 PR 现在还不能合，需要先 rebase 瘦身 🙏

现状问题：diff 累计回到了整个 #724

本 PR 的分支叠在 feat/718-side-modifiers(#726) 和 feat/718-mouse-dictation(#727) 之上，所以对 beta 的 diff 累计成了 ~2788 行 / 38 文件——等于把已经拆开的 #724 又整体带了回来。这里面包含了 #727 那个会让听写卡死到重启的 HIGH bug（详见 #727 的 review），所以现在合等于把那个 bug 也合进去。

正确路径

1. 等 feat(hotkey): side-specific modifier combos for dictation (split from #724) #726 合并；
2. feat(dictation): mouse middle/side buttons with Hold refcount (split from #724) #727 修好 HIGH bug + 去掉与 feat(hotkey): side-specific modifier combos for dictation (split from #724) #726 重复的 types.ts/语言文件改动后合并；
3. 把本 PR rebase 到最新 beta —— diff 会瘦到只剩 linux_evdev_input.rs + mobile_stubs/linux_evdev_input.rs + Cargo.toml/lock(evdev 依赖) + 少量 Linux #[cfg] 接线，那时单独审查、单独合很干净。

对 Linux evdev 增量的审查（rebase 后即可落地）

• 无阻断问题：权限不足时能给出 udev 提示、不 panic；监视器生命周期 OK；非 Linux 构建不受影响（mobile stub 与 API 对齐）。
• evdev = "0.12" 依赖合理（社区事实标准、维护活跃，风险低）。
• ⚠️ 建议跟进（不阻断）：读取循环是 fetch_events() + sleep(10ms) 轮询，空闲时会持续吃满约一个 CPU 核，对笔记本是功耗回退。建议改成 epoll(nix 已是传递依赖) 或 evdev 的异步 EventStream，让线程在有事件时才唤醒。
• 小点：is_available() 只判断 /dev/input 目录存在，并不代表有读权限；udev 提示串在两处略有出入，建议统一成一个常量。

先留开着，按上面顺序 rebase 后再推进。

[github-actions]

Persistent review updated to latest commit 0bac973

[HKLHaoBin]

@Felix201209 已按 review 处理 rebase 瘦身 🙏

分支结构

• 基于最新 feat/718-mouse-dictation（含 feat(dictation): mouse middle/side buttons with Hold refcount (split from #724) #727 review 修复：sync_release_mouse_hold_sources、TOCTOU、回归测试）
• 合并 feat/718-side-modifiers（feat(hotkey): side-specific modifier combos for dictation (split from #724) #726）作为 evdev 依赖
• 本 PR 新增增量：linux_evdev_input.rs + stub + Cargo evdev = "0.12" + Linux #[cfg] 接线 + Linux 恢复鼠标听写 UI

相对 feat/718-mouse-dictation 的 evdev 增量：~680 行 / 8 文件（commit 23a4f692）

合并顺序（与 review 一致）：#726 → #727 → 本 PR。待前两 PR 进 beta 后，对 beta 的 diff 会自然瘦到 evdev-only。

本次未做（review 标注不阻断）：epoll/EventStream 空闲 CPU、udev 提示常量统一。

请 re-review。

[github-actions]

Persistent review updated to latest commit 23a4f69

[github-actions]

Persistent review updated to latest commit 6ea63bb

[github-actions]

Persistent review updated to latest commit ebc9fe7

[github-actions]

Persistent review updated to latest commit 5cf792d

[github-actions]

Persistent review updated to latest commit a997cd1

[github-actions]

Persistent review updated to latest commit a5871ee

[github-actions]

Persistent review updated to latest commit d22ded2

[github-actions]

Persistent review updated to latest commit 9fb62f3

[github-actions]

Persistent review updated to latest commit 0331833

[github-actions]

Persistent review updated to latest commit 4fa244f

[github-actions]

Persistent review updated to latest commit 5ac029d

[github-actions]

Persistent review updated to latest commit c98c801

[appergb]

请你说清楚，你为什么写了 1,000 多行出来？又不是什么大的改变，也不是什么严重的改变，你写一千多行出来要把我看死。我也不敢直接给你合并，你等我一下，我 @ 一下 Claude。

[appergb]

@claude Review.

[appergb]

感谢实现鼠标键听写 + Linux evdev 输入,这块工作量不小。经维护者审阅 + 两轮独立代码审查,此 PR 暂打回搁置,主要两个原因:

① 架构方向 —— 往 god-file 增量过多

本 PR 约 458 行加进了 coordinator.rs(3407 行)、hotkey_loops.rs(1439 行)、dictation.rs(3440 行)等本就远超维护上限、正在 issue #697 治理拆分的大文件,进一步加剧了臃肿。鼠标/evdev 的桥接与协调逻辑应尽量抽到独立模块,而不是继续堆进这些 god-file。这个方向目前无法接受。

② 运行时 2 个 CRITICAL 缺陷(CI 的 cargo check + 单测覆盖不到,两轮独立审查一致确认):

• block_on_async(futures::executor::block_on)驱动 tokio 的 end_session:Hold 模式录音时改热键绑定 / 前端设置自动保存,会 panic(there is no reactor running, must be called from the context of a Tokio 1.x runtime),整个 app 崩溃。应改用 async_runtime::block_on(同文件其余 13 处都是这么用的);测试里的 nested-runtime 问题请另行解决,不要用 futures::executor::block_on 兜。
• Linux evdev 用阻塞 fetch_events() 顺序遍历设备,会卡在第一个空闲设备(如电源键 event0)上收不到鼠标事件;且 LinuxEvdevMonitor::Drop 只设 AtomicBool、不 join reader 线程,反复切换设置会累积阻塞线程 + 泄漏 /dev/input fd。需改 poll/epoll + 超时轮询,并让 Drop 能真正唤醒/停止线程。

需要说明:核心逻辑本身是干净的 —— HoldSourceTracker 引用计数正确、serde 向后兼容做得很到位、macOS CGEventTap 扩展也简洁,方向有价值。欢迎在 ①尽量少动 god-file、②修掉上述 CRITICAL、③真机 Linux 验证 之后重新提 PR。感谢理解与投入。

[appergb]

@jiangmuran 这个 PR 我之前想 @claude 审但没响应（自动审核已移除），我自己看完先打回搁置了。如果你对 Linux evdev 这块有不同看法，麻烦也过目一下。（PR 目前已关闭）