fix(hotkey): Wayland 下用 CLI 触发录音，修复 #420

[appergb]

User description

摘要

修复 #420 — Debian/Wayland 桌面环境下录音快捷键不可用。

Wayland 协议禁止应用监听非聚焦窗口的键盘事件，原 rdev 路径在 Wayland 必然失效，之前代码硬拒绝并报 wayland_unsupported。本 PR 保留 X11 rdev 路径不动；Wayland 下改走 stub HotkeyAdapter（不监听键盘），通过 tauri-plugin-single-instance 把 openless --toggle-dictation 等 CLI 命令的 argv 转给主实例 coordinator，由桌面环境快捷键设置绑定该命令实现全局触发。

Issue 用户原话方案："建议补充对应的脚本或者命令让用户去系统设置中配置快捷键即可" — 本 PR 落地的就是这个方案。

改动文件

文件	改动
src-tauri/src/cli.rs（新建）	CLI intent 解析 + 10 个单测，零新依赖
src-tauri/src/hotkey.rs	Linux 分支：Wayland 命中走 WaylandCliAdapter stub（不再硬拒绝）
src-tauri/src/lib.rs	single-instance 回调路由 argv → dispatch_cli_intent；删一次性 emit，改 IPC pull
src-tauri/src/commands.rs	新增 is_wayland_cli_mode IPC command
src-tauri/src/coordinator.rs	dictation_phase_for_cli + cli_toggle_qa_panel 暴露 CLI 入口
src/pages/Settings.tsx	WaylandHotkeyCallout 组件 + invoke pull 模型
src/lib/ipc.ts	isWaylandCliMode wrapper（mock 返回 false）
src/i18n/{zh-CN,en,zh-TW,ja,ko}.ts	settings.recording.wayland.* 共 14 个键
docs/issue-420-wayland-hotkey-research.md（新建）	方案调研文档

平台影响

• ✅ Linux Wayland：从无法使用 → 可通过桌面环境快捷键 + CLI 触发
• ✅ Linux X11：rdev 路径未触碰
• ✅ macOS：CGEventTap 路径零改动
• ✅ Windows：RegisterHotKey 路径零改动

测试

• cargo check --manifest-path src-tauri/Cargo.toml: 0 error
• npm run build: 通过
• cargo test --lib: 243 passed / 0 failed（含 cli 模块 10 个新测试）

用户使用方式（Wayland）

PR 合并并发版后，用户在 Wayland 下打开 Settings → 录音 会看到引导 callout，按 GNOME / KDE / Hyprland / sway 各自步骤把 openless --toggle-dictation 绑到桌面环境的自定义快捷键即可。

遗留

• LOW：WaylandCliAdapter 的空跑 channel tx 让 bridge thread 空等（不影响功能，留后续 issue）
• 后续可考虑接入 xdg-desktop-portal GlobalShortcuts（GNOME 已支持，KDE Plasma 6 已支持）作为更原生的方案；本期先 CLI 兜底

---

PR Type

Bug fix, Enhancement, Tests, Documentation

---

Description

• Route Wayland shortcuts through CLI

  • Parse --toggle-dictation, --toggle-qa, --cancel
  • Dispatch intents via single-instance

• Replace Wayland hotkey failure

  • Use a stub hotkey adapter
  • Expose Wayland mode to frontend

• Show setup guidance in Settings

  • Add copyable shortcut command
  • List GNOME, KDE, Hyprland, sway steps

• Add tests and research docs

  • Cover CLI parser behavior
  • Document Wayland shortcut strategy

---

Diagram Walkthrough

flowchart LR
  A["Desktop shortcut / app launch"]
  B["single-instance callback"]
  C["CLI intent parser"]
  D["Coordinator actions"]
  E["Wayland session"]
  F["Stub hotkey adapter"]
  G["Settings callout"]
  H["Translations and docs"]

  A -- "argv" --> B
  B -- "dispatch intent" --> C
  C -- "toggle / cancel / QA" --> D
  E -- "skip rdev" --> F
  F -- "pull mode status" --> G
  G -- "localized guidance" --> H

Loading

File Walkthrough

	Relevant files
Enhancement	11 files cli.rs Adds CLI intent parsing and tests                                                +119/-0  commands.rs Exposes Wayland session detection                                                +12/-0    coordinator.rs Routes CLI intents through coordinator                                      +16/-0    lib.rs Dispatches CLI intents from startup                                            +94/-1    en.ts Adds English Wayland setup text                                                    +15/-0    ja.ts Adds Japanese Wayland setup text                                                  +15/-0    ko.ts Adds Korean Wayland setup text                                                      +15/-0    zh-CN.ts Adds Simplified Chinese setup text                                              +15/-0    zh-TW.ts Adds Traditional Chinese setup text                                            +15/-0    ipc.ts Adds Wayland mode IPC wrapper                                                        +6/-0      Settings.tsx Shows Wayland shortcut setup callout                                          +142/-0
Bug fix	1 files hotkey.rs Stubs Wayland hotkey listener path                                              +60/-5
Documentation	1 files issue-420-wayland-hotkey-research.md Documents Wayland hotkey research                                                +401/-0

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 420 - Partially compliant Compliant requirements: 提供 openless --toggle-dictation 作为可绑定的触发命令 在 Settings 中加入 Wayland 下的引导文案和桌面环境配置步骤 为 Wayland 路径增加解析、转发与相关单元测试 Non-compliant requirements: 无 Requires further human verification: 需要在 Debian/Wayland 桌面环境中实际验证桌面快捷键绑定后能否稳定触发录音 需要确认 GNOME/KDE/Hyprland/sway 的引导步骤在真实环境中可执行

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

🧪 PR contains tests

🔒 No security concerns identified

⚡ No major issues detected