Seekey 文档总览
Wayland 按键可视化工具 Seekey 的使用、配置、兼容性和开发文档入口。
Seekey 是一个面向 Linux Wayland 的按键可视化工具。它通过 libevdev
读取键盘事件，把快捷键、连续输入和可选的鼠标操作显示成屏幕边缘的临时气泡。
浮层不会获取键盘焦点，并通过空输入区域实现鼠标点击穿透。
这本笔记以 Seekey 当前 main 分支为准。稳定包可能晚于本文档；排查功能差异时，
先运行 seekey --version，再确认安装的是 seekey 还是 seekey-git。
阅读顺序#
- 安装与权限：AUR、源码安装和输入设备权限。
- 配置与编辑器：配置查找顺序、GUI/TUI 和样式字段。
- 显示逻辑与桌面兼容：按键合并、 layer-shell、GNOME/KDE 和单实例行为。
- Matugen 动态配色：生成
colors.json并让气泡跟随壁纸。 - 问题排查：没有气泡、位置错误、配置未生效等问题。
- 开发与测试：源码结构、测试和贡献流程。
最短使用路径#
Arch Linux 可以从 AUR 安装：
paru -S seekey安装后从桌面菜单启动，或直接运行：
seekey --xdg --config-gui
seekey --xdg第一次没有按键气泡，通常不是 Wayland 协议问题，而是当前用户无法读取
/dev/input/event*。处理方式见安装与权限。
功能边界#
- niri、Hyprland、Sway、river、Wayfire、labwc 可通过 layer-shell 跨工作区常驻。
- GNOME/KDE 会使用普通透明窗口，需要桌面窗口规则来实现跨工作区固定。
- 普通浮层全局唯一，重复启动不会增加输入读取器。
- GUI/TUI 使用独立预览子进程，不读取真实 evdev，也不会与主浮层重复显示按键。
- Seekey 只保留短时间内用于展示的按键，不提供历史记录或日志存储。
源码位于 GitHub ↗，采用 MIT 许可证。