Hex Linux Beta 实战指南:单进程架构、安装集成、快捷键与原生 Wayland 粘贴
Hex Linux Beta 实战指南:单进程架构、安装集成、快捷键与原生 Wayland 粘贴
Hex 是一个本地优先的语音听写工具,Linux 版本目前以 Beta 形式发布。本文以仓库中的 Linux 使用文档为主线,结合 Rust 源码、systemd 单元与验证脚本,完整说明 Beta 的支持范围、一用户一进程的运行模型、三种安装渠道、快捷键的三种来源,以及原生 Wayland 下剪贴板与按键注入的决策路径;读完后你可以独立完成安装、桌面集成、快捷键绑定与故障定位。
1. Beta 的支持契约:先确认边界再动手
Linux Beta 的支持面是刻意收窄的,docs/plans/linux.md 用一张表把契约写清楚了:
| 领域 | 契约 |
|---|---|
| 分发 | 签名的用户级直接安装,或由 Nix 拥有的包更新 |
| 主机 | x86_64 Linux(参考环境 Arch/i3),并提供 NixOS 打包 |
| 桌面 | i3/X11,或兼容的 wlroots Wayland 合成器(Hyprland、Sway、niri 等) |
| 音频 | 通过 ALSA 的 CPAL,通常由 PipeWire 提供 ALSA 兼容层 |
| 推理 | 有 Vulkan 时用 Vulkan,可回退到 CPU |
| 快捷键 | 可配置、必须包含非修饰键的组合,默认 Alt+Space |
| 插入 | 剪贴板 + Ctrl-V,终端场景可切换为 Ctrl-Shift-V |
| UI | 单进程:按需打开的 Rune 窗口 + Rune 悬浮 HUD(Wayland 用 layer-shell,X11 用 override-redirect),有托盘宿主时提供 StatusNotifierItem 图标 |
几个容易被忽略、但会直接卡住首次运行的前提:
- 窗口本身也需要 Vulkan 驱动,即使推理回退到 CPU。只装
vulkan-icd-loader不算驱动,必须为你的 GPU 安装驱动,或安装软件 Vulkan 驱动(如 Mesa 的 lavapipe)。 - 发行版二进制在 Ubuntu 24.04 上构建,要求 glibc 2.39 或更新:Ubuntu 24.04、Debian 13、Fedora 40、当前 Arch 及更新版本可用。
- 明确不提供的能力:语音命令(command grammar)、网站模式规则(website mode rules)、会议(meetings)、通用 Wayland 支持。这些在 docs/plans/linux.md 中被列为“Beta 不声称”的范围。
- Wayland 下没有隐藏的 XWayland、直接打字(direct-typing)、uinput 或特权注入兜底方案。
2. 一用户一进程:Hex 在 Linux 上的运行模型
2.1 谁拥有什么
Linux 上的 Hex 是每用户(以及每个数据目录)一个进程,不是系统级/root 守护进程。它拥有麦克风、快捷键、模型下载与推理 worker、提示音、粘贴、History、录音胶囊(recording pill)以及窗口。窗口是可选的:关闭窗口既不会停止听写,也不会中断模型下载;再次启动 Hex 只会把窗口重新打开。
有托盘宿主(Wayland 上的 StatusNotifierItem,如 Waybar、KDE 或 Omarchy 的 bar)时,Hex 显示托盘图标,点击打开窗口,菜单提供 Show Hex 与 Quit Hex(实现见 src/linux_tray.rs)。没有托盘时,用窗口侧栏底部的 Quit Hex、启动器的 Quit Hex 动作,或 hex quit 退出。
2.2 固定尺寸窗口与“自动浮动”
Linux 窗口固定为 980×760 逻辑像素,不可调整大小——这样分数缩放(fractional scaling)下依然清晰。Wayland 没有 API 要求平铺合成器浮动某个窗口,但 sway、Hyprland、niri 会浮动“最小尺寸等于最大尺寸”的 toplevel;X11 下 i3 等窗口管理器也会浮动尺寸提示固定的窗口。因此窗口默认以浮动形式出现,而不是被塞进一个 tile。macOS 与 Windows 仍保持可调整大小的窗口。
2.3 命令行入口
hex # open the window, starting Hex if needed
hex start # start Hex in the background; no window
hex status # query the running Hex, not an old log entry
hex quit # finish accepted work, release the microphone, exit
hex restart # restart the systemd unit in this desktop's environment
# (over SSH: the one it last ran in)
journalctl --user -u hex.service # diagnostics of the supervised process
兼容别名:hex app 等价于 hex,hex app --hidden 等价于 hex start,hex stop 等价于 hex quit。这让旧的桌面项和自启动项在“更新只替换可执行文件”的情况下继续可用。hex status --lines 40 保留显式的诊断日志视图。
2.4 启动决策顺序
一次启动会先通过 Unix socket 询问正在运行的 Hex:
- 有实例应答:把
Activate连同启动器提供的XDG_ACTIVATION_TOKEN或DESKTOP_STARTUP_ID转发过去,然后以 0 退出;运行中的进程打开或聚焦窗口。 - 没有实例在跑,且安装器(或 Home Manager)的
hex.service用户单元已加载:写入仅属主可读的session.env,启动该单元;单元在 socket 能应答后向 systemd 报告就绪(Type=notify),随后转发Activate。 - 其他情况(自定义数据目录、
cargo run、没有 systemd 的桌面):启动进程自己成为 Hex。
两个同时发起的启动只会产生一个 Hex,输的那一方转发请求并以 0 退出。这套逻辑集中在 src/linux_service.rs 的 launch() 中,其中 supervised() 通过 systemctl --user show hex.service --property=LoadState 判断单元是否已加载。
一个关键细节:从另一个桌面会话启动时,如果 Hex 受 systemd 单元监管,启动会重启该单元以接手新会话;如果是不受监管的实例,则拒绝接管并提示先 hex quit。
2.5 session.env 为什么必须存在
systemd 用户管理器继承的环境经常是登录时(甚至上一个桌面)的旧值。Hex 的做法是把当前桌面环境的显示与会话变量写进 session.env,由单元用 EnvironmentFile=-%h/.local/share/hex/session.env 读取:
- 总是写入(缺失时写空值,用于显式清除陈旧的 Wayland/X11 值):
DISPLAY、WAYLAND_DISPLAY、XAUTHORITY、XDG_RUNTIME_DIR、DBUS_SESSION_BUS_ADDRESS、XDG_CURRENT_DESKTOP、XDG_SESSION_TYPE,以及光标主题与输入法相关的XCURSOR_THEME、XCURSOR_SIZE、XMODIFIERS、GTK_IM_MODULE、QT_IM_MODULE。 - 仅在已设置时写入(清空会破坏用户管理器自身的 locale 与数据目录):
XDG_DATA_DIRS、LANG、LANGUAGE、LC_ALL、LC_CTYPE、LC_MESSAGES。
对应常量见 src/linux_service.rs,写入时会把值中的双引号与反斜杠转义,并拒绝包含换行或 NUL 的值(environment_line),避免注入 EnvironmentFile。该文件以 0600 权限创建、sync_all 后原子 rename,且不授予任何权限。
2.6 systemd 用户单元
安装器写入的单元(模板见 packaging/hex.service)很短,但每一行都有用途:
[Unit]
Description=Hex background dictation
PartOf=graphical-session.target
After=graphical-session.target
StartLimitIntervalSec=60
StartLimitBurst=5
[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/bin/hex service
EnvironmentFile=-%h/.local/share/hex/session.env
Restart=on-failure
RestartSec=3
TimeoutStopSec=30
UMask=0077
[Install]
WantedBy=graphical-session.target
Type=notify+NotifyAccess=main:Hex 在 socket 可应答后发送READY=1(notify()支持抽象命名空间@形式的NOTIFY_SOCKET)。旧安装器写的Type=simple单元仍然可用,此时启动方会轮询等待(READY_TIMEOUT为 10 秒)。PartOf=graphical-session.target:单元生命周期跟随图形会话;管理自定义 session target 的桌面必须自行把它的生命周期绑定到登录/登出。Restart=on-failure:崩溃后由 systemd 重启,且不打开窗口;在窗口内点击 Update 后重启的 Hex 会重新打开窗口。UMask=0077:与数据目录0700、socket0600的私有化策略一致。
2.7 私有 IPC:不是网络 API
socket 位于 Hex 数据目录下的 service.sock,与 service.lock 相邻,由 src/instance.rs 的实例锁保证排他。协议约束如下(见 src/linux_service.rs):
- 仅属主可用:目录
0700、socket0600,连接时通过SO_PEERCRED校验对端 UID 与当前有效 UID 相同。 - 帧格式:4 字节大端长度 + JSON 负载,单帧上限 128 KiB,读写各有 2 秒截止时间;8 个工作线程,队列满则快速失败。
- 协议版本为 2;版本 1(旧的 service/Settings 客户端)会收到版本错误并退出。
- 只承载
Activate、快捷键命令(Shortcut)、Status、Quit(以及capture实验的录制动作)。快捷键命令直接从 socket worker 进入监听器命令队列,永不经过窗口线程。
这就是“关闭窗口不影响听写”的结构性原因:窗口与听写共享同一进程,但走不同的线程与队列。
3. 安装:四条渠道
3.1 安装脚本(自动更新的用户级布局)
curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh
脚本把对应架构的裸可执行文件装进用户级目录布局(~/.local/share/hex),该布局支持应用内自更新。默认安装 stable 版本;尚无 stable 发布时安装最新的 dev 构建(并停留在 Dev 通道)。可用 HEX_INSTALL_CHANNEL=stable 或 =dev 显式选择。
安装完成后从应用启动器打开 Hex,或运行 ~/.local/bin/hex;首次运行会下载语音模型。
若缺少运行库,安装器会给出需要安装的包名(含 Arch 名称)。要提前装依赖,或先审阅脚本再执行:
sudo pacman -S --needed alsa-lib curl jq \
libxkbcommon libxkbcommon-x11 libx11 libxcb openblas openssl util-linux \
vulkan-icd-loader wl-clipboard wtype xxd
curl --proto '=https' --tlsv1.2 -fsSLO \
https://anoma.ly/hex/files/install-linux.sh
less install-linux.sh
sh install-linux.sh
~/.local/bin/hex model install
~/.local/bin/hex
安装器会校验签名发布源、产物精确大小与 SHA-256,不需要 root。它创建受管版本布局(versions/<version>/hex 加 current 符号链接)、~/.local/bin/hex、桌面启动器、XDG 自启动项与 hex.service 用户单元;安装过程中不会开始录音。
卸载应用但保留日志与设置:
sh install-linux.sh uninstall
从源码构建时,仓库里的 scripts/install-linux.sh 是个薄包装:它先 cargo build --locked --release,取出版本号,再以 HEX_INSTALL_SOURCE=1 调用真正的安装器 scripts/install-linux-release.sh,因此源码安装与官方安装在目录布局上完全一致,只在版本目录里留下 source-build 标记。
3.2 Debian / Ubuntu / Fedora / openSUSE
hex 包安装 /usr/bin/hex、桌面项与 systemd 用户单元(与 AUR 包内容相同)。按架构下载 .deb / .rpm 后:
sudo apt install ./hex.deb # Debian, Ubuntu
sudo dnf install ./hex.rpm # Fedora (zypper install on openSUSE)
systemctl --user enable hex.service # optional: start Hex at login
目前没有 apt/dnf 仓库。Hex 永不替换由包管理器安装的可执行文件:有新 stable 版本时,Settings 只显示下载并安装该包的命令。包安装跟随 stable 通道,因此 dev 通道的包只会感知到下一个 stable 版本。
3.3 AUR
AUR 包 hex-bin 会安装 /usr/bin/hex、桌面项与 hex.service,覆盖 x86_64 与 aarch64,来自与直装渠道相同的发布可执行文件。请注意文档写明:它尚未发布到 AUR。模板已存在于仓库 packaging/aur/PKGBUILD。
yay -S hex-bin
systemctl --user enable hex.service # optional: start Hex at login
pacman 负责更新,Settings 会显示 “Updated by your package manager”。它与官方 hex 包(一个安装 /usr/bin/hx 的 hex dump 工具)无关。
3.4 从源码安装
sudo pacman -S --needed base-devel git rustup python alsa-lib curl jq openssl xxd \
util-linux libxkbcommon libxkbcommon-x11 libx11 libxcb openblas \
vulkan-headers vulkan-icd-loader \
shaderc spirv-headers clang cmake pkgconf wl-clipboard wtype
rustup default stable
然后以桌面用户身份构建安装:
git clone https://github.com/anomalyco/hex.git
cd hex
./scripts/install-linux.sh
~/.local/bin/hex model install
~/.local/bin/hex
不要以 root 运行安装器。 源码安装会被标记为源码构建(可执行文件旁的 source-build),应用内更新器永不替换它,Settings 显示 “Updated from your source checkout”,升级方式是 git pull 后重新运行安装器。之后安装官方发布版会切回签名更新。
配合自定义 HEX_APPLICATION_SUPPORT_DIR 时,cargo run --release 运行的是一个不受管的开发版 Hex;不设置该变量时,它会转发给已安装的 Hex。这也是 scripts/test-linux-service.py 隔离测试的基础:它用一个假的 systemctl 放在 PATH 最前面,断言自定义数据目录从不调用 systemctl。
Nix/NixOS 用户请改用 Nix 指南:Nix 拥有该安装的更新权,Hex 的签名更新器只负责上面这种直装布局。
4. 听写的基本用法
4.1 按住说、松开出字
按住 Alt-Space,说话,松开。双击快捷键可锁定录音,再按一次同样的组合结束;按 Escape 取消当前录音。Double-tap only 会等待两次完整敲击后才开始录音,Toggle 模式则用单击开始与结束。Ctrl-Alt-V 重新粘贴上一条听写。Settings 会显示监听器状态、Start/Stop 以及运行错误。
修改快捷键,或修改监听器启动时读取的某个设置,会临时停止监听,并在编辑后恢复之前的运行状态。
4.2 模式与前台应用识别
Modes 按应用应用纠错、OpenCode 改写与转换:
- X11:从活动窗口的进程名读取前台应用(如
code、firefox),应用选择器列出.desktop条目。 - Wayland:合成器不报告焦点窗口,因此只有 Global 模式生效。
已完成的听写会保留在 History 中。
4.3 Voice Action
启用后,按住 Ctrl-Alt-I 录一条指令,它与你选中的文本(primary selection)配对后发给 OpenCode,再把回复粘贴出来。选中文本的读取方式与平台相关:X11 走 x11_clipboard 的 PRIMARY,Wayland 走 wl-paste --primary(见 src/linux_paste.rs)。
需要区分的是:Voice Action 可用,而“语音命令”(把口述内容解析成 Hex 命令的 command grammar)、网站模式规则与会议在 Linux 上不可用。
4.4 麦克风模式与录音时的音频抑制
- Microphone mode 可以在两次听写之间释放麦克风;此后按下快捷键时才打开设备,且没有 pre-roll。
- While dictating 可以通过
wpctl(PipeWire)或pactl(PulseAudio)静音默认输出,或经 D-Bus 暂停正在播放的 MPRIS 播放器;只在按住超过 300 ms 后触发,因此普通的快捷键组合与短敲不会触发。Hex 只恢复自己改动过的部分。
这两条的实现依据很明确:MINIMUM_HOLD_DURATION 为 300 ms(src/dictation.rs),become_intentional() 返回真时才调用 suppressor.suppress()(src/linux_dictation.rs)。音频控制在独立 worker 线程里执行,避免听写循环等待慢速播放器;RESTORE_GRACE 为 300 ms,恢复时也只在输出重新可听后才执行后续动作(src/linux_audio_control.rs)。
5. 快捷键:一条状态机,三种输入源
5.1 统一的状态机
无论来源如何,快捷键最终都进入同一个 ShortcutState(src/linux_input.rs),输出统一的 HotkeyEvent(Start、Finish、Cancel、PasteLast、VoiceStart/VoiceFinish、Capture)。其中几个时间常量决定行为:
| 常量 | 值 | 作用 |
|---|---|---|
DOUBLE_TAP_WINDOW |
300 ms | 两次敲击被视为双击的间隔 |
KEY_REPEAT_GAP |
1 s | 按键重复与“新的一次按下”的分界(KWin 的重复更快) |
RELEASE_GRACE |
50 ms | X11 自动重复会先发 release 再发 press,release 需静默 50 ms 才生效 |
MODIFIER_GRACE |
250 ms | Wayland 下未知按键状态的保守等待 |
HELD_LIMIT |
2 s | 按下但永不到达 release 时的上限 |
PORTAL_READY_TIMEOUT |
65 s | 经 portal 注册快捷键可能需要用户批准对话框 |
一个健壮性细节:如果合成器始终没有送出本该锁定录音的 release(Hyprland 的 Lua 绑定在修饰键先松开时会丢),下一次按下会把这次录音结束掉,而不是永久卡在录音中。
5.2 X11:抓取 Settings 记录的按键
Hex 在根窗口上做被动抓取(grab_key / grab_button),并为 Caps Lock 与 Num Lock 生成四种掩码变体(lock_variants),这样开着大写锁定也能触发。抓取失败(BadAccess)会报告“已被其他 X11 客户端占用”。鼠标按键做了逻辑编号映射:X11 保留 4–7 给滚轮,辅助键从 8 开始(mouse_button / mouse_name)。
Escape 的处理更细:先尝试抓取任意修饰键下的 Escape;如果某个应用已占用带修饰的 Escape,则回退到裸 Escape(含 Caps/Num Lock 变体);如果裸 Escape 也被占用,则听写继续,但 Settings 与 hex status 显示:
Escape cancel unavailable: another application holds Escape
每个冲突周期只记录一次日志,下次捕获时重试,抓取成功后清除警告。
5.3 Wayland(有 GlobalShortcuts portal)
niri 配 xdg-desktop-portal-gnome、GNOME、KDE 等提供 portal 时,Hex 向桌面申请 Settings 里记录的快捷键。桌面有最终决定权:可以授予、改派另一个键,或拒绝已被占用/禁止的组合。Settings 在 Desktop shortcuts 下列出桌面实际授予的组合,被拒绝的会带错误说明。KDE 等桌面在你录制新快捷键时可能保留旧绑定;portal 支持时,Desktop shortcuts > Open 会打开桌面自己的对话框,Settings 随之同步。
portal 通过已安装的 hex.desktop 以及检查 Hex 进程来识别应用。下载的裸可执行文件没有桌面项,因此 Hex 会写一个最小的 ~/.local/share/applications/hex.desktop(受管安装会替换它)。如果 portal 仍找不到,重启 portal:
systemctl --user restart xdg-desktop-portal
还要注意:直接运行 hex service,不要套 newgrp 之类的 setgid 包装(历史上用于获取输入设备权限),否则 portal 会拒绝 Hex。
5.4 Hyprland:portal 存在,但必须自己绑定
Hyprland 有 portal,却不带键地接收所有快捷键——所以在配置里绑定之前什么都不会发生,Settings 记录的键也不被使用。Hex 无法判断你的配置是否绑定了它。优先使用无修饰键,因为 Hyprland 会把你仍按住的修饰键叠加到 Hex 的粘贴上:
hl.bind("End", hl.dsp.global("hex:dictation"))
hl.bind("F9", hl.dsp.global("hex:paste-last"))
更旧的配置写作 bind = , End, global, hex:dictation。Escape 取消无法这样绑定,请把 hex dictation cancel 绑到某个键。Hyprland 0.56 的 Lua 绑定在修饰键先于按键松开时(Alt 先于 Z)不发送 release,0.57 修复了该问题;在 0.56 上 Toggle 不受影响(下一次按下仍会结束),而 Hold 模式下录音会持续到下一次按下并松开,因此要么先抬键,要么改用 Toggle。
5.5 Wayland(无 portal,如 Sway):绑定 hex 命令
此时没有任何全局快捷键注册,Settings 会列出这些命令,请绑定到桌面自己的键盘配置:
hex dictation start # bind to a key's press: start recording
hex dictation stop # bind to the same key's release: stop and transcribe
hex dictation toggle # one key: start, then stop and transcribe
hex dictation cancel # discard the recording
hex paste-last # paste the last dictation again
hex voice-action start # Voice Action, when enabled: press
hex voice-action stop # and release
hex voice-action toggle
例如在 Sway 中实现 F9 按住说话,以及在任意“只在按下时执行命令”的桌面上实现切换:
bindsym F9 exec hex dictation start
bindsym --release F9 exec hex dictation stop
bindsym Ctrl+Alt+d exec hex dictation toggle
这些命令只与运行中的 Hex 通信,永不主动启动它:没有实例,或 Hex 未在监听时,打印一行错误并以非零码退出(EXIT_NOT_RUNNING = 3,见 src/control/cli.rs)。录音中再 start、空闲时 stop、空闲时 cancel 都是无操作,所以按键重复是安全的。start/stop 会绕过 Hold、Toggle 与 double-tap 语义:start 就是开始,stop 就是结束。快捷键的按下同样能结束由命令开始的录音。
Escape 只在有东西正在录音时取消。有 portal 时,Hex 只在录音期间绑定 Escape 以及带录音快捷键修饰键的 Escape,桌面因此不会把该 Escape 转给焦点应用;没有 portal 时,请绑定 hex dictation cancel。
快捷键必须包含非修饰键:Linux 不支持仅修饰键的快捷键(例如单独 Super)。
5.6 提示音
录音提示音默认以 50% 音量启用(升级旧设置时同样如此):
- 快捷键开始捕获时立即排队播放开始音;
- 停止音标记一次保留录音的结束(不是转写或粘贴完成);
- 取消音确认取消了一次进行中的捕获。
短敲仍会播放开始音,但短于 300 ms 的录音会被丢弃且不播放停止音。Settings 中的 Sound volume 提供 Off、25%、50%、75%、100%;修改立即保存、无需重启监听器,并在非 Off 时预览开始音。hex dictate 使用同一份保存的音量。播放走有界的后台 worker,音频输出不可用不会阻止听写。
6. 窗口、HUD 与托盘
关闭窗口后,X11 与 Wayland 上的 Hex 都继续运行。录音/处理胶囊从不获取焦点、也不拦截点击:Wayland 上是 layer-shell surface,X11 上是 override-redirect 窗口。它依赖窗口的事件循环,因此在窗口无法启动时(没有 display 或 GPU)以及 hex dictate 中不可用。Recording indicator 可把它放在屏幕顶部或底部,或关闭。
窗口本身跑在 Rune 的应用生命周期(rune::App)上:Hex 启动时不带窗口,每次 Activate 用转发的 token 打开或聚焦窗口(Wayland 上经 xdg_activation_v1;没有 token 时多数合成器只会标记为 urgent),关闭窗口会保留窗口状态供下次打开。
插入文本默认使用剪贴板 + Ctrl-V;对需要 Ctrl-Shift-V 的目标(终端),在 Settings 中开启 Terminal paste shortcut。已有的 X11 设置会保留其原来的 Ctrl-Shift-V 行为直到被修改。目标是应用必须接受所选的组合。Beta 会把转写文本留在剪贴板上,不恢复之前任意的剪贴板格式;粘贴后有一个短暂的稳定延迟,用于防止连续替换,但它不是来自卡住的目标应用的确认。
7. 原生 Wayland 的硬性要求
- 启动环境必须导出非空的
WAYLAND_DISPLAY。Hex 与其窗口(winit)会选择同一个原生后端,即使同时存在 XWayland 的DISPLAY。仅设置XDG_SESSION_TYPE不会选中 Wayland——这条规则在代码里就是LinuxSession::detect()只看WAYLAND_DISPLAY(src/linux_session.rs)。 - 安装
wl-clipboard。Hex 先把每段转写复制到剪贴板,再通过两条通用路径之一发送 Ctrl+V(或终端的 Ctrl+Shift+V),路径在第一次粘贴时选定:wtype:合成器提供虚拟键盘协议zwp_virtual_keyboard_manager_v1(wlroots 系列与 niri),且wtype已安装;- 否则用桌面的 RemoteDesktop portal(
org.freedesktop.portal.RemoteDesktop;KDE、GNOME):首次粘贴会请求你允许 Hex 控制键盘,Hex 把 portal 的恢复令牌保存在数据目录的remote-desktop-token中,因此只问一次;撤销请在桌面设置里操作; - 两者都没有:听写以 “Copied to the clipboard; press Ctrl+V to paste” 结束,转写留在剪贴板上。
- 没有静默的 XWayland、直接打字、uinput 或特权注入兜底。转写文本经 stdin 传递,不作为命令行参数(
run_helper的注释与测试helper_can_read_a_large_transcript_without_argv_or_files都在验证这一点)。 - 悬浮 HUD 需要 layer-shell。不可用时 Settings 会如实报告,而不是拿一个会抢焦点的普通窗口冒充 HUD。
- 快捷键来自 GlobalShortcuts portal,或来自你自己的
hex命令绑定。Hex 不读取任何输入设备,不需要input组或其他设备权限。若桌面关闭了 portal 会话,监听器带错误停止、进行中的录音被取消;需要在 Settings 或hex start重新启用。 - Hex 在 Wayland 上看不到哪些键处于按下状态,某些合成器会把仍按住的物理修饰键合并进它的粘贴:Hyprland 上,Alt+Z 残留的 Alt 会把
wtype的 Ctrl+V 变成 Ctrl+Alt+V,而绑定在 Ctrl+Alt+V 的 paste-last 又会被 Hyprland 再匹配一次、永远到不了应用。RemoteDesktop portal 同样共享桌面键盘。因此当带修饰键的快捷键请求粘贴时,Hex 会等待其松开(portal 的 Deactivated)再加 250 ms,若按下后始终收不到释放则最多等 2 秒;来自hex命令(Hex 看不到其键绑定)则固定等 250 ms。超过这个时间仍按住修饰键就会改变粘贴,因此绑定无修饰键(End、F 键)或在转写到达前松开修饰键。Hex 在发出粘贴快捷键后就记为“已粘贴”,它无法确认目标应用接受。
这些等待参数就是前面表中的 MODIFIER_GRACE 与 HELD_LIMIT,由 ShortcutKeys::settle() 实现(src/linux_input.rs)。粘贴侧的常量同样可核对:HELPER_TIMEOUT 3 秒、PASTE_SETTLE 100 ms、PORTAL_FOCUS_SETTLE 250 ms(src/linux_paste.rs)。wtype 的参数刻意在按键后追加一个 VoidSymbol 释放,因为 GTK 3 的反向键位查找会跳过最后一个键码;修饰键严格成对按下与释放。
8. 更新与验证
受管安装会在 Hex 启动时及之后每 24 小时检查签名更新,直到有可用更新;Hex 会下载、校验并激活更新,然后在窗口中提供 Update 按钮,点击后重启单元并重开窗口。下一次通过 ~/.local/bin/hex 启动也会使用已激活的版本。
需要如实说明的是:签名更新路径已实现,但仍未在受支持的 Arch/i3 主机上完成完整的跨版本验证。这也是 docs/plans/linux.md 把“验证签名更新路径”列为第一项待办的原因——它挡住的是“直装更新通道可被称为已验证”这一结论,而不是功能本身的不存在。
三个脚本覆盖了不同层面的回归:
cargo fmt --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
./scripts/test-install-linux-release.sh
nix flake check
- scripts/test-wayland-paste.sh:在隔离的无头 Sway 合成器下,用真实的粘贴助手对 GTK 目标做测试。第一次粘贴发生在另一个虚拟键盘仍按住 Ctrl 与 Alt 时。它还会启动隔离的 Hex,通过第二个
hex app打开窗口(窗口必须属于同一进程),窗口打开时重复粘贴,关闭窗口后检查同一进程仍有应答,再重新打开窗口(HEX_WAYLAND_REOPEN=0可跳过),最后退出。需要 GTK 开发库、Sway、wl-clipboard、wtype、dbus-run-session和 Vulkan 驱动(Mesa 软件驱动即可),且必须以非 root 用户运行。测试本体是native_wayland_clipboard_shortcut(标了#[ignore])。 - scripts/test-linux-dictation.sh:用私有的 PulseAudio 虚拟麦克风与 Xvfb 覆盖完整的 X11 应用听写路径——通过第二个
hex app打开窗口、回放 whisper.cpp 的公开 JFK 样音、按住并松开真实快捷键、在 GTK 编辑器中校验转写词、检查有序退出与麦克风释放。需要 PulseAudio 及其 ALSA 插件、xdotool、Xvfb、GTK 开发库与 Vulkan 驱动,以普通用户和临时设置运行,不使用物理音频设备或个人录音。 - scripts/test-linux-service.py:无显示、无设备的单实例检查——没有 Hex 时命令快速失败、
hex start变成 Hex、第二次启动(start、app --hidden、service、app)转发并以 0 退出、无 display 的窗口请求只让窗口失败、同用户 socket 权限、版本 1 客户端收到错误、非法/超大/停滞帧、崩溃或陈旧 socket 恢复、两个并发启动只得到一个 Hex、hex quit排空并移除 socket,以及自定义数据目录从不运行systemctl。
即便如此,物理设备、合成器与目标应用的冒烟测试在发布前仍然必要——自动化检查不能替代它们。
9. 故障排查清单
| 现象 | 排查方向 |
|---|---|
Hex is not running; run \hex start`` |
命令只与运行中的实例通信;先 hex start,或检查 systemctl --user status hex.service |
An older Hex is running; quit it or run \hex restart`` |
socket 上是版本 1 的旧协议;退出或重启 |
Refusing an insecure Hex socket |
socket 类型/属主/权限不符(需属主所有、0600);检查数据目录是否被替换 |
| 快捷键注册失败 | X11:组合已被其他客户端抓取;portal:桌面拒绝或改派,见 Settings 的 Desktop shortcuts |
| Escape 无法取消 | 检查 Settings 与 hex status 的 Escape cancel unavailable 警告;改用听写快捷键结束 |
| Wayland 粘贴没反应 | 确认非空 WAYLAND_DISPLAY、已装 wl-clipboard、wtype 或 RemoteDesktop portal 是否可用;HUD 是否需要 layer-shell |
| 窗口起不来但听写正常 | 窗口需要显示与 Vulkan 驱动;hex status 与日志会区分窗口失败与进程失败 |
| 服务启动失败 | journalctl --user -u hex.service;确认从图形登录会话启动、session.env 与当前桌面一致 |
| 从另一个桌面会话启动被拒 | 无人监管的实例需先 hex quit;受管实例会自动为新会话重启单元 |
| 安装后无桌面项/portal 找不到 Hex | 检查 ~/.local/share/applications/hex.desktop;必要时 systemctl --user restart xdg-desktop-portal |
10. 开发与调试入口
cargo run --release # 无受管布局的开发运行
hex dictate # 显式的前台诊断监听器:无窗口、无 HUD
HEX_APPLICATION_SUPPORT_DIR=/tmp/hex-dev # 自定义数据目录:启动不再触碰已安装的用户单元
HEX_SYSTEMD_UNIT=hex-test.service # 隔离测试用的另一个单元名
hex dictate 不能与 Hex 的监听器共存。设置 HEX_APPLICATION_SUPPORT_DIR 时,启动永不启动、停止或重启已安装的用户单元,而是转发给使用该数据目录的 Hex,或自己成为它。
延伸阅读:Linux 工程契约与验证计划、Nix 安装指南、CLI 参考。所有平台共用的便携核心(音频采集与有界投递、听写 pre-roll、转写模型与推理、命令文法、粘贴续接状态机、会议清单与恢复)不应按平台分叉——平台适配层只拥有原生句柄、权限与清理逻辑,这是 docs/plans/linux.md 明确要求保持的结构。