Skip to content

fix(linux): 稳定全局快捷键与 Wayland 面板唤起 - #1

Merged
KroMiose merged 1 commit into
NekroAI:mainfrom
yang208115:codex/linux-global-shortcuts
Oct 19, 2026
Merged

KroMiose merged 1 commit into
NekroAI:mainfrom
yang208115:codex/linux-global-shortcuts

Conversation

@yang208115

Copy link
Copy Markdown
Contributor

What and why

Linux 快捷键可能在 Portal 信号监听失败后仍显示注册成功,X11 换键冲突会丢失旧绑定,Xwayland 连接也可能被误判为覆盖所有 Wayland 应用的全局能力。此 PR 统一后端生命周期和事件语义,并完善失败后的手动唤起路径。

  • 分离 Portal/X11/Manual 候选后端、已验证能力、运行状态和错误原因;Portal 完成绑定及必要订阅后才报告可用,管理取消、重试、旧请求、服务断线与会话清理。
  • X11 复用原连接,动态处理锁定键/修饰键映射、按下/释放和长按重复;串行注册避免阻塞 GTK,换键失败回滚,保留录制与排除应用的暂停行为。
  • Linux 默认改为 Ctrl+Shift+Q,保留已保存的自定义组合与系统绑定;设置、首次引导和桌面元数据同步更新。
  • 继续使用 qantrip toggle 与 GApplication/D-Bus 单实例分发,传递激活上下文;提供 niri/Sway/Hyprland 配置及禁止长按重复的说明,不新增 UDS。
  • 集成 Wayland 面板的固定尺寸 GTK CSD 窗口,交给合成器管理位置;补齐中英文安装说明、D40/D41 决策和验证矩阵。
  • CI 显式安装 fake Portal 测试需要的 dbus-daemon。不升级现有依赖版本,不修改共享核心或其他平台业务代码。

How it was tested

在最新 main(0.5.0)基线上重新通过:

cargo check --locked --manifest-path apps/linux/Cargo.toml
cargo check --locked --manifest-path apps/linux/Cargo.toml --all-features
cargo test --locked --manifest-path apps/linux/Cargo.toml
cargo test --locked --manifest-path apps/linux/Cargo.toml --all-features
cargo clippy --locked --manifest-path apps/linux/Cargo.toml --all-targets --all-features -- -D warnings
cargo build --locked --manifest-path apps/linux/Cargo.toml --features debug-hooks
uv run tests/linux/hotkeys_smoke.py
cargo build --release --locked --manifest-path apps/linux/Cargo.toml
cargo test --locked --manifest-path core/Cargo.toml
git diff --check
  • Linux:25 项测试通过;默认忽略的 1 项 X11 server 测试由隔离 smoke 显式运行并通过。core:118 项通过。
  • fake Portal 覆盖授权取消、订阅失败、系统改键、旧异步结果、断线与清理;mock/Xwayland 覆盖冲突回滚、重复事件、暂停/恢复与共用连接。隔离 smoke 验证 CLI 转发、并发启动及 toggle 次数。
  • 本机 niri 的原生绑定已由用户确认 Ctrl+Shift+Q 可开关面板;命令唤起与焦点正常。Portal 失败定位为 GNOME 后端调用缺失的 GlobalShortcutsProvider 服务,未将此结果泛化为所有 niri 版本都不支持。
  • niri 和 Hyprland 示例通过本机配置校验;其他完整桌面授权、原生 Xorg 物理键盘和最低版本发行版验证仍待执行,详见 验证矩阵。
  • 格式检查:本 PR 修改的 Rust 文件 rustfmt --check 通过。全量 cargo fmt -- --check 在上游已有的 sync.rs / sync_ui.rs 两处格式差异处失败,未混入无关格式化。

Checklist

  • Tests added or updated for behavior changes
  • cargo test passes locally (Linux and core); cross-platform/cloud checks run in CI
  • Docs updated (docs/ and Linux desktop metadata)
  • No secrets, personal data or machine-specific absolute paths in the diff

KroMiose added a commit that referenced this pull request Oct 19, 2026
- X11: a key still held when a new shortcut is grabbed no longer
  swallows the next press (its release never reaches us; poll the
  keymap until it is released).
- Portal: a press 400ms after the previous one counts as new, so a
  backend that never sends Deactivated doesn't leave the shortcut dead.
- X11: pausing keeps a failed registration visible with Retry.
- Wayland panel: GNOME and KDE keep the transparent maximized window
  measured in D37; other compositors use the fixed-size CSD window.
- Docs: install guide back to a short user version; shortcut setup and
  manual bindings in docs/linux-shortcuts.md; build notes in
  apps/linux/README.md; decisions renumbered to D41 / D42.
- README, website and llms text: Linux shortcut is Ctrl+Shift+Q.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@KroMiose
KroMiose merged commit 0762134 into NekroAI:main Oct 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants