Skip to content

[windows] QA hotkey 跨平台配置未归一,cmd 语义漂移为 Win 键 #148

@Cooper-X-Oak

Description

@Cooper-X-Oak

现象

  • 当前 Windows 本地偏好文件里,qaHotkey 存的是 {"primary":";","modifiers":["cmd","shift"]},而不是 Windows 语义更符合预期的 ctrl + shift + ;
  • openless-all/app/src-tauri/src/qa_hotkey.rsparse_binding() 会把 cmd / command / super / meta / win 全部映射到 Modifiers::SUPER
  • 结果是在 Windows 上,这个 QA hotkey 实际被注册成 Win+Shift+;。本地运行态验证时,发送 Win+Shift+; 可以打开 QA panel,并在日志里看到 QA hotkey edge / QA panel opened
  • 这说明跨平台偏好在 Windows 上没有做 semantic normalization,macOS 的 cmd 语义被 literal 地落成了 Windows Win 键。

问题层面 / Problem layer

  • 层面判定:跨平台配置语义层 / config normalization + OS mapping bug
  • 根因不只是 Windows 热键库行为,而是共享的 QaHotkeyBinding 持久化模型没有区分“产品语义层 modifier”与“平台运行时 modifier”。
  • 更准确的判断是:跨平台配置设计问题,在 Windows 上出现了最具体、最可见的错误表现

证据

  • 偏好文件证据:C:\Users\luoxu\AppData\Roaming\OpenLess\preferences.json
    • "qaHotkey": { "primary": ";", "modifiers": ["cmd", "shift"] }
  • 代码证据:openless-all/app/src-tauri/src/qa_hotkey.rs
    • cmd/command/super/meta/win -> Modifiers::SUPER
  • 运行态证据(Windows)
    • 发送 Win+Shift+; 后,日志命中:
      • [coord] QA hotkey edge (panel_visible=false)
      • [coord] QA panel opened (awaiting Option to record)

与 macOS 原始设计意图的偏差

  • macOS 原始产品语义里,Cmd+Shift+; 表达的是“主平台默认主修饰键 + Shift + primary key”。
  • 在 Windows 上,对等语义通常应是 Ctrl+Shift+;,而不是把 Cmd 字面映射成 Win
  • 当前实现没有区分“语义层 modifier”与“物理/平台层 modifier”,导致 macOS 偏好迁移到 Windows 后行为偏离了产品意图。
  • 这类问题本质上是 cross-platform lifecycle + config migration 问题:同一份 persisted preference 穿过不同系统时,缺少 load-time normalization / migration。

生命周期差异 / Platform lifecycle notes

  • 问题发生在配置生命周期:persisted preference 从磁盘读回运行态时,没有根据当前 OS 做语义归一。
  • Windows 之所以特别明显,是因为 SUPER 在用户认知上是 Win 键,和产品默认期望差距最大。
  • macOS 上同一份配置可能“看起来没坏”,但那只是因为平台解释碰巧与 token 一致,不代表配置模型本身设计正确。

5 Whys

  1. 为什么 Windows 上会出现 Win+Shift+; 这种 QA hotkey?
    • 因为偏好里存的是 cmd + shift + ;
  2. 为什么偏好会在 Windows 上保留 cmd
    • 因为 QaHotkeyBinding 是跨平台原样持久化的,没有在读取或迁移时做 OS-aware normalization。
  3. 为什么 cmd 会落成 Win 而不是 Ctrl
    • 因为 parse_binding()cmd 映射成了 Modifiers::SUPER,这在 Windows 上就是 Win
  4. 为什么实现会接受这种字面映射?
    • 因为当前代码把 modifier 当成底层库的直接输入,而不是产品语义的一部分。
  5. 为什么这与 macOS 原始设计产生偏差?
    • 因为 macOS 原始设计关注的是“用户认知上的主修饰键体验”,不是 modifier token 的字面重放;跨平台移植时没有把这种语义差异纳入 preference lifecycle 设计。

影响

  • Windows 用户可能以为默认 / 当前 QA hotkey 是 Ctrl+Shift+;,实际却需要 Win+Shift+; 才能触发。
  • 文档、设置 UI、运行态行为三者可能出现不一致,提升支持与排障成本。
  • 后续任何从 macOS 导入或共享的偏好,都可能继续触发同类问题。

建议接受标准

  • 在 Windows 上加载 qaHotkey 时,对 cmd 这类跨平台语义 modifier 做 normalization / migration。
  • Windows 默认与回显语义明确对齐 Ctrl,除非产品明确要求支持 Win
  • 对历史偏好提供兼容迁移,避免旧 cmd 配置静默变成 Win hotkey。
  • 补充一条跨平台配置验证,覆盖 macOS persisted binding -> Windows runtime binding
  • 在 issue / PR 结论里明确:这是跨平台配置层问题,Windows 是当前显性暴露面。

TODO / 不确定项

  • TODO: 需要确认主听写 hotkey 是否也存在类似的跨平台语义漂移,但目前证据只覆盖 QA hotkey。
  • TODO: 需要确认这是“用户历史偏好迁移”还是“某条设置路径直接写入了 macOS token”。

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingwindowsWindows-specific issue

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions