Hex Linux Beta 实战:原生 Wayland 听写、GlobalShortcuts 授权与 Nix 打包边界

原创2026-11-02 16:14:502,262 阅读
文章标签:语音桌面应用本地部署人工智能音频

Hex Linux Beta 实战:原生 Wayland 听写、GlobalShortcuts 授权与 Nix 打包边界

本文以 Hex 的 Linux Wayland / Nix Beta 说明为骨架,拆解这套 beta 到底交付了什么:在兼容 wlroots 的合成器上实现原生 Wayland 听写(不读输入设备、不需要 input 组),快捷键由桌面 GlobalShortcuts portal 授权或由用户绑定 hex 命令,录音指示器为点击穿透的 layer-shell 覆盖层,同时提供 Nix 打包、开发 shell 与可选的 Home Manager 用户级自启动。读完后你应当能够在 Sway、Hyprland、niri、i3/X11 或 NixOS 上完成安装、快捷键绑定、粘贴链路排错,并清楚哪些行为属于本 beta 的明确承诺、哪些仍处于未验证状态。

Beta 的现状:实现了什么,什么还不是事实

原始发布说明的第一句话就是最重要的边界声明:

Unreleased. Physical input, microphone, and supported-host validation remain release gates; passing container tests alone does not establish those behaviors.

也就是说,功能代码已落地,但发布门槛是真实物理输入、真实麦克风、真实受支持宿主机上的验证。容器或 CI 里跑通的自动化测试,不能替代“在 Arch/i3 上按住快捷键说一句话,文字出现在 GTK 编辑器里”这类端到端确认。这一点在工程计划文档 docs/plans/linux.md 中被重复强调:x86_64 X11 beta、wlroots 兼容的原生 Wayland 路径与 Nix 打包均已实现,而物理桌面/输入验证和一次真正的签名升级仍是发布闸门。

因此本文的表述边界如下:

结论类型 依据
功能行为、命令、配置项 docs/releases/linux-wayland-beta.md、docs/linux.md、docs/nix.md
实现细节、常量、协议交互 仓库源码(下文标注路径)
未验证项 文档中显式写明的 “remain release gates” / “awaiting validation”

beta 说明本身列出六条能力,构成了全文的目录骨架:

  1. 在兼容 wlroots 合成器上新增原生 Wayland 听写,带点击穿透的录音/处理指示器;
  2. 快捷键来自桌面 GlobalShortcuts portal,Settings 显示桌面授予了什么;
  3. 没有 portal 时,在合成器里绑定 hex dictation …、hex voice-action …、hex paste-last;
  4. 不需要输入设备访问权限,也不需要 input 组;
  5. 快捷键修改、取消、无托盘场景下的监听器恢复都能在 Settings 中处理;
  6. 取消一次新采集时,Settings 中较早的待处理转录仍然可见;
  7. 新增 Nix 打包、对应的开发 shell,以及可选的 Home Manager 用户级自启动;Nix 安装的更新交给 Nix。

支持契约:一条刻意收窄的边界

Linux beta 并不声称“支持所有 Wayland 桌面”。原始说明明确写道:它不声称支持 GNOME 或 KDE,也不读取任何输入设备。工程计划里的契约表把范围写得更清楚:

维度 契约
发行方式 签名的用户级直接安装,或由 Nix 拥有更新
宿主 x86_64 Linux;Arch/i3 为参考环境,NixOS 提供打包
桌面 i3/X11,或兼容 wlroots 的 Wayland 合成器(如 Hyprland、Sway)
音频 通过 ALSA 使用 CPAL,通常由 PipeWire 支撑
推理 优先 Vulkan,可回退 CPU
快捷键 含非修饰键的组合,默认 Alt+Space
插入 剪贴板 + Ctrl-V,可切换为终端用的 Ctrl+Shift-V
UI 单进程:按需打开 Rune 窗口 + Rune 覆盖层 HUD(Wayland 用 layer-shell,X11 用 override-redirect);存在托盘宿主时提供 StatusNotifierItem 托盘图标

有两点容易误读,需要单独指出:

  • ARM64 与 x86_64 的差别:已发布的二进制构建覆盖 x86_64 与 ARM64(.deb、.rpm、裸可执行文件),但 Nix flake 只打包 x86_64-linux,两个 Nix 模块里都有断言:The Hex Nix package supports x86_64-linux only.(见 nix/module.nix 与 nix/hm-module.nix)。
  • Vulkan 是窗口的硬需求:即使推理回退到 CPU,窗口仍需要可用的 Vulkan 驱动;只装 vulkan-icd-loader 不算驱动。Nix 包在 LD_LIBRARY_PATH 中加入了 vulkan-loader,详见 nix/package.nix。

单进程模型:窗口、托盘与 session.env

Hex 在 Linux 上是每用户一个进程(且每个数据目录一个),不是系统级/root 守护进程。它持有麦克风、快捷键、模型下载与 worker、声音、粘贴、History、录音胶囊和窗口。窗口是可选的:关掉窗口不会停止听写或模型下载,再次启动 Hex 只会重新打开窗口。

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;旧桌面项与自启动项在更新只替换可执行文件后仍可用。

启动时的三条路径

一次启动先通过 socket 询问正在运行的 Hex:

  1. 已有实例应答:转发 Activate,携带启动器的 XDG_ACTIVATION_TOKEN 或 DESKTOP_STARTUP_ID,然后以 0 退出;运行中的进程打开或聚焦窗口。
  2. 没有实例,但 hex.service 用户单元已加载:写入仅属主可读的 session.env 并启动单元;单元在 socket 应答后向 systemd 报告就绪(Type=notify),随后转发 Activate。
  3. 其他情况(自定义数据目录、cargo run、没有 systemd 的桌面):发起启动的进程自己变成 Hex。

两个并发启动只会产生一个 Hex,失败的一方转发后以 0 退出。这套语义实现在 src/linux_service.rs,其中 socket 协议版本为 2,帧上限 128 KiB,单次 I/O 超时 2 秒,最多 8 个客户端;版本 1 的老客户端会收到版本不匹配错误。

session.env 到底写什么

session.env 是理解“为什么服务能在图形会话里拿到 Wayland socket”的关键。源码把它分成两组键(src/linux_service.rs):

  • 总是写入(缺失即显式清空,避免用户管理器继承到过期的 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。

写入方式是先落到临时文件,再 rename 原子替换,权限 0600:内容里的换行、回车和 NUL 会被拒绝,避免把一个被污染的桌面对话串注入 systemd 环境文件。所有这一切不授予任何权限,单元也只是 PartOf=graphical-session.target。

托盘与退出

当桌面提供托盘宿主(Waybar、KDE、Omarchy 的 bar 等 StatusNotifierItem 宿主)时,Hex 显示托盘图标:点击打开窗口,菜单提供 Show Hex 与 Quit Hex。没有托盘时,用窗口侧栏底部的 Quit Hex、启动器的 Quit Hex 动作,或 hex quit。实现见 src/linux_tray.rs:托盘菜单的 quit 只是把 shutdown 原子标志置位,与窗口的 Quit 一样走“先排空已接受的工作”的路径。

窗口尺寸与浮动

Linux 上窗口固定为 980×760 逻辑像素(因此分数缩放仍清晰),不可调整大小。Wayland 没有“请平铺合成器浮动一个窗口”的接口,但 sway、Hyprland、niri 会对最小/最大尺寸相等的 toplevel 浮动;i3 等 X11 窗口管理器会对固定 size hints 的窗口浮动。因此窗口以浮动形式出现而不是占一个 tile。macOS 与 Windows 保持可调整大小。

原生 Wayland 听写:一条状态机,三个输入源

src/linux_input.rs 的模块注释把架构一句话说清了:所有输入源喂同一个状态机,分别是 X11 的按键抓取、Wayland 的快捷键 portal、以及用户在桌面里绑定运行的 hex 命令;听写侧只看到 HotkeyEvent。

pub(crate) enum HotkeyEvent {
    Start, Finish, Cancel, PasteLast,
    VoiceStart, VoiceFinish, Capture,
}

对应地,命令侧是一个幂等的枚举 ShortcutCommand:DictationStart、DictationStop、DictationToggle、DictationCancel、VoiceActionStart、VoiceActionStop、VoiceActionToggle、PasteLast。幂等性很重要——按键重复(key repeat)在快速连按时会重复投递命令,开始一个正在进行的录音或停止一个空闲状态必须是“什么都不做”。

路径一:X11 抓取

X11 上 Hex 直接抓取 Settings 记录的快捷键,并优先抓取带任意修饰键的 Escape;若被别的应用占用,则回退到纯 Escape 以及 Caps/Num Lock 变体。若纯 Escape 也冲突,听写仍可继续,但 Settings 与 hex status 会显示:

Escape cancel unavailable: another application holds Escape

每个冲突“回合”只记一次日志,下一次采集时重试,抓取成功后清除警告。常量 ESCAPE_CANCEL_WARNING 即定义在 src/linux_input.rs 中。

路径二:GlobalShortcuts portal

在带 portal 的 Wayland 桌面(例如 niri 配 xdg-desktop-portal-gnome、GNOME、KDE),Hex 向桌面申请 Settings 中记录的快捷键,由桌面决定:可以批准、改派别的键,或拒绝一个已被自己或其他绑定占用的组合。Settings 的 Desktop shortcuts 一栏列出桌面实际授予的触发键,被拒绝的会附错误说明。若桌面 portal 支持,Desktop shortcuts > Open 会打开桌面自己的对话框,Settings 随后跟随你的选择。

源码层面,src/linux_portal.rs 是 GlobalShortcuts 客户端,模块注释说明了两个会话的分工:一个会话绑定 Hex 的快捷键,第二个会话只在有录音时绑定纯 Escape,两者都报告按下与松开。portal 用 hex.desktop 这个 desktop entry 识别宿主应用(APP_ID = "hex"),因此:

  • 下载的裸可执行文件没有 desktop entry,Hex 会写一个最小的 ~/.local/share/applications/hex.desktop;受管安装会替换它;
  • 若 portal 仍找不到,重启 portal:systemctl --user restart xdg-desktop-portal;
  • 直接运行 hex service:曾经用于授予输入设备访问权的 setgid 包装(如 newgrp)会让 portal 拒绝 Hex。

快捷键 id 是稳定字符串,和命令名对应(src/linux_input.rs 的 portal_id):dictation、paste-last、voice-action、capture。Escape 会话使用 cancel 与 cancel-held 两个 id——后者正是文档所说“Escape 以及带有录音快捷键修饰键的 Escape”。

路径三:没有 portal 时绑定 hex 命令

Sway 这类没有 GlobalShortcuts portal 的桌面不会注册任何全局快捷键。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 中实现“按住说话”,以及任何只响应按键按下的桌面里的 Toggle:

bindsym F9 exec hex dictation start
bindsym --release F9 exec hex dictation stop
bindsym Ctrl+Alt+d exec hex dictation toggle

这些命令的语义边界值得背下来:

  • 它们只与运行中的 Hex 通信,绝不自己启动 Hex;没有实例,或 Hex 不在监听时,打印一行错误并以非零退出(控制 CLI 的退出码约定见 src/control/cli.rs:0 成功、1 被拒绝/失败、2 用法错误、3 Hex 未运行)。
  • 录音中 start、空闲时 stop、空闲时 cancel 都是空操作,因此按键重复无害。
  • start/stop 绕过 Hold、Toggle、双击模式:start 直接录音,stop 直接结束。快捷键的一次按下也可以结束由命令开始的录音。
  • 命令可以安全地绑在任何地方,包括 X11 上与抓取并存。

Hyprland:有 portal,但不给键

Hyprland 有 portal,却不带键接收所有快捷键,即使用户在 Settings 里录了键也不会生效;Settings 记录的键在这里不被使用,Hex 也无法判断你的配置是否绑定了它。需要自己在配置里绑定,例如新版 Lua 语法:

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。

文档建议优先选择不带修饰键的键(End、功能键),因为 Hyprland 会把仍按住的物理修饰键叠加到 Hex 的粘贴上,详见下一节。

录制快捷键的交互约束

  • 快捷键必须包含非修饰键;Linux 上不支持“仅修饰键”的快捷键(例如单独的 Super)。
  • 修改快捷键或修改监听器启动时读取的设置,会临时停止监听,编辑结束后恢复之前的运行状态。
  • 取消快捷键录制会保留旧绑定,除非新绑定已经保存;只有此前正在监听才会恢复监听。
  • 取消一次新采集时,Settings 中较早的待处理转录仍然可见——这正是 beta 说明里那条看起来“很小”但直接影响可用性的修复。

悬浮指示器:点击穿透的 layer-shell 覆盖层

录音/处理指示器在两种会话下都从不抢焦点、不拦截点击:Wayland 上是 layer-shell surface(overlay 层、无键盘交互、空输入区域),X11 上是 override-redirect 窗口加空输入形状。实现见 src/linux_rune_hud.rs,它复用共享的 Rune HUD,并且只做观察——监听器通过 LinuxIndicator 上报采集、音量表与待处理输出,从不等 HUD;HUD 尚未安装时上报会被丢弃。

因为它需要窗口的事件循环,所以在窗口无法启动时(无显示或无 GPU)以及 hex dictate 中不可用。Settings 的 Recording indicator 可以把指示器放在屏幕顶部、底部或关闭。若缺少 layer-shell,Settings 会报告 HUD 不可用,而不是用一个会抢焦点的普通窗口伪装成覆盖层。

在 Sway 上验证时,scripts/test-wayland-paste.sh 会专门检查“窗口打开后粘贴仍可重复”“关窗后同一进程仍应答”“再次打开窗口”,因为覆盖层与窗口共享同一个进程与事件循环。

粘贴链路:wtype 还是 RemoteDesktop portal

插入文本不是“直接打字”,而是剪贴板 + 粘贴快捷键。Hex 先复制转录(Wayland 用 wl-copy),再在首次粘贴时选择两条通用路径之一(src/linux_paste.rs):

  1. wtype:合成器提供虚拟键盘协议(zwp_virtual_keyboard_manager_v1,即 wlroots 系合成器与 niri)且 wtype 已安装。源码里的 offers_virtual_keyboard() 通过枚举 Wayland registry global 判断。
  2. 桌面 RemoteDesktop portal(org.freedesktop.portal.RemoteDesktop,KDE、GNOME):首次粘贴会请求你允许 Hex 控制键盘;Hex 保存 portal 的 restore token(数据目录下的 remote-desktop-token),因此只问一次。撤销请到桌面设置里操作。源码中 persist_mode = 2(persist until revoked),且仅在 portal 版本 ≥ 2 时启用持久化;restore token 是一次性的,每次启动会换发新的。
  3. 两者都不可用:听写以 “Copied to the clipboard; press Ctrl+V to paste” 失败,转录留在剪贴板。

没有任何静默的 XWayland、直接打字、uinput 或特权注入回退。转录文本经 stdin 传递,而不是命令行参数——这既避免暴露给进程列表,也规避参数长度与引号问题。

修饰键残留:250 ms 与 2 s

Wayland 上 Hex 看不到哪些键是按下的,而部分合成器会把仍按住的物理修饰键合并进它的粘贴:在 Hyprland 上,从 Alt+Z 起仍按住的 Alt 会把 wtype 的 Ctrl+V 变成 Ctrl+Alt+V;如果 paste-last 恰好绑在 Ctrl+Alt+V,Hyprland 会再次截获它,永远到不了应用。RemoteDesktop portal 共享桌面键盘,同理。

因此源码定义了有界等待(src/linux_input.rs):

const MODIFIER_GRACE: Duration = Duration::from_millis(250);
const HELD_LIMIT: Duration = Duration::from_secs(2);
  • 带修饰键的快捷键请求粘贴时,Hex 等待其松开(portal 的 Deactivated)后再加 250 ms;
  • 若按下后始终等不到松开,最多等 2 秒;
  • 由 hex 命令触发时,Hex 看不到键位,固定等待 250 ms。

源码注释把这段逻辑总结得很直白:ShortcutKeys 不是读键盘,而是“等快捷键自己的事件”。这也解释了文档里的建议——绑定不带修饰键的键,或在转录到达前松开修饰键。

另外两个细节:

  • RemoteDesktop 首次建立会话后会额外睡 250 ms(PORTAL_FOCUS_SETTLE),因为授权对话框会把焦点交还给目标应用;连续替换之间还有 100 ms 的 PASTE_SETTLE,它只是防抖,不是目标应用的确认。
  • Hex 在发出粘贴快捷键后就记为“已粘贴”,无法确认应用真的接受;beta 阶段转录留在剪贴板,不恢复此前的任意剪贴板格式。

插入绑定默认是 Ctrl-V;新安装可在 Settings 打开 Terminal paste shortcut 使用 Ctrl-Shift-V,既有 X11 设置会保留原来的 Ctrl-Shift-V 行为直到被修改。

Nix:flake、模块与更新归属

Nix 部分对应 beta 说明的最后一条:打包 + 匹配的开发 shell + 可选的 Home Manager 用户级自启动,且 Nix 安装把更新留给 Nix。

从 checkout 运行

nix build
nix run . -- model install
nix run . -- app

或在配置的 flake inputs 中加入 Hex,安装 hex.packages.x86_64-linux.default。包提供 hex 命令与桌面启动器、原生库,以及 curl、wl-copy、wtype 运行时依赖(nix/package.nix 的 runtimePackages 与 postFixup 的 wrapProgram)。系统仍需要可用的音频会话与 Vulkan 驱动,即使推理回退到 CPU。非 NixOS 宿主上的 Nix GUI 应用可能还需要宿主常规的 Nix 图形集成。

模型下载到用户数据目录,不进 Nix store;用普通桌面用户跑一次 hex model install,不要以 root 运行。

flake 输出结构(flake.nix):packages.x86_64-linux.{hex,default}、overlays.default、nixosModules.{hex,default}、homeManagerModules.{hex,default}、devShells.x86_64-linux.default、checks.x86_64-linux,formatter 为 nixfmt。

NixOS 模块

{
  imports = [ hex.nixosModules.hex ];
  programs.hex.enable = true;
}

它系统级安装 Hex,不会启动 root 服务,也不会为每个账户开启自启动;按用户自启动请用下面的 Home Manager 模块。两个模块都接受显式 programs.hex.package 覆盖,flake 也导出 hex.overlays.default 供 pkgs.hex 使用。

Home Manager 模块:逐个字段看

{
  imports = [ hex.homeManagerModules.hex ];
  programs.hex = {
    enable = true;
    autostart = true;
    # Use your compositor's session target when appropriate:
    # systemdTarget = "sway-session.target";
  };
}

模块总是安装 systemd 用户服务,autostart 默认 false;开启后单元默认被 graphical-session.target wanted。nix/hm-module.nix 中的关键字段:

字段 值 含义
Service.Type notify Hex 在 socket 应答后向 systemd 报就绪
Service.NotifyAccess main 只有主进程可发通知
Service.ExecStartPre hex-wait-for-session 等待 Wayland socket 或 X11 窗口管理器出现
Service.ExecStart ${hex}/bin/hex service 前台监听器,由 systemd 托管
Service.Environment HEX_APPLICATION_SUPPORT_DIR=${xdg.dataHome}/hex 固定数据目录,避免与未受管运行混用
Service.EnvironmentFile -${xdg.dataHome}/hex/session.env 前缀 - 表示文件缺失不报错
Service.TimeoutStartSec 35 覆盖就绪等待
Service.Restart / RestartSec on-failure / 5 崩溃重启但不形成紧凑重启循环
Service.TimeoutStopSec 30 停止时给排空工作留时间
Service.UMask 0077 进程创建的文件默认仅属主可访问
Unit.After / Unit.PartOf [ cfg.systemdTarget ] 跟随会话 target 的生命周期
Install.WantedBy 仅当 autostart 手动模式不自动启动

systemdTarget 默认 graphical-session.target,示例值为 sway-session.target;模块不创建图形会话,也不授予使用会话的权限。会话管理器必须在启动该 target 之前把当前的 DISPLAY、XAUTHORITY、WAYLAND_DISPLAY、XDG_RUNTIME_DIR 导入 systemd 用户环境,并在登出时停止 target。请用合成器自己的 systemd 集成(例如 Home Manager 的 Sway 集成),而不是从 shell 登录脚本里拉 target。没有 systemd 会话集成的裸 startx/i3 不会自动启动这个服务。

ExecStartPre 调用的 nix/wait-for-session.sh 逻辑很短但很实用:最多 30 次、每次间隔 1 秒,WAYLAND_DISPLAY 存在时检查它是绝对路径还是相对 XDG_RUNTIME_DIR 的 socket;否则在 DISPLAY 存在时用 xprop -root _NET_SUPPORTING_WM_CHECK 判断窗口管理器是否已就绪(注释说明 NixOS/i3 上 graphical-session.target 可能先于 WM 达成)。30 次都失败则打印提示并退出 1,由 systemd 按 Restart=on-failure 重试。

Home Manager 常规的服务切换策略同样适用:新启用的服务可能在会话 target 已激活时于 switch 期间启动,包变更也可能重启运行中的服务——不要在正在录音时 switch。排查用:

systemctl --user status hex.service
journalctl --user -u hex.service

非 Nix 安装的单元

直接安装与包管理器安装使用另一份单元 packaging/hex.service:PartOf/After=graphical-session.target、StartLimitIntervalSec=60 + StartLimitBurst=5、ExecStart=/usr/bin/hex service、EnvironmentFile=-%h/.local/share/hex/session.env、RestartSec=3、UMask=0077。与 Home Manager 版本的差别正好体现两种交付方式的取舍:包安装固定路径与数据目录,Home Manager 则参数化 target 与数据目录。

开发 shell

nix develop
cargo build --locked
cargo test --locked
cargo run --locked -- app

包与 shell 共享原生构建环境和运行时库/插件路径;OpenBLAS 的链接顺序由 build.rs 处理,而不是 Nix 专用的 RUSTFLAGS(nix/checks.nix 里断言了 hex 与 shell 都不应存在 RUSTFLAGS)。shell 也提供粘贴与下载辅助程序,因此不依赖已安装应用的 wrapper。

Nix 安装为什么不能自更新

Nix store 不是 Hex 的用户级受管安装布局,应用内更新不会替换 Nix 安装。更新方式是改 flake input 后重建/切换 Nix 或 Home Manager 配置。文档另外提醒:在启用第二种自启动机制前,删除旧的源码安装 XDG autostart 项;不要同时跑两个 Hex 监听器。

这一“所有权分离”原则在计划文档里是一条明确决策:应用管理的更新器只负责用户级直接安装;Nix 负责自己的包安装与可选用户服务;未来的 Arch 包也必须把更新留给包管理器。实践中,.deb/.rpm 与 AUR 的 hex-bin 安装同一批文件(/usr/bin/hex、desktop entry、hex.service 用户单元),Settings 会显示“Updated by your package manager”。

验证:脚本能证明什么

仓库把验证拆成三层,正好对应三类风险。

1. 真实 Wayland 粘贴与单进程行为 —— scripts/test-wayland-paste.sh <测试可执行文件> <hex>,在隔离的 headless Sway 下对 GTK 目标运行真实的粘贴辅助程序:

  • 首次粘贴时,另一个虚拟键盘正按住 Ctrl 与 Alt(脚本用 wtype -k v -M ctrl -M alt -p VoidSymbol -s 60000 制造这个状态),以复现修饰键残留场景;
  • 启动一个隔离的 Hex,通过第二个 hex app 打开窗口,并检查窗口属于同一进程;
  • 窗口打开期间重复粘贴,然后关窗,确认同一进程仍在应答;
  • 再次打开窗口(HEX_WAYLAND_REOPEN=0 可跳过),最后退出。

依赖 GTK 开发库、Sway、wl-clipboard、wtype、dbus-run-session 与 Vulkan 驱动(Mesa 软件驱动足够),且必须以非 root 用户运行;使用隔离的应用数据,不使用麦克风。

2. 完整 X11 听写路径 —— scripts/test-linux-dictation.sh <hex> <parakeet 模型> <jfk.wav>:私有 PulseAudio 虚拟麦克风 + Xvfb,通过第二个 hex app 打开窗口,回放 whisper.cpp 的公开 JFK 样本,按住并松开真实快捷键,在 GTK 编辑器中校验转录词,并检查有序退出与麦克风释放。

3. 无显示、无设备的单实例检查 —— scripts/test-linux-service.py:命令在无 Hex 时快速失败;hex start 自己变成 Hex;第二次启动(start、app --hidden、service、app)转发并以 0 退出;无显示时的窗口请求只让窗口失败;同用户 socket 权限;版本 1 客户端得到错误;非法、超大、停滞的帧;崩溃与陈旧 socket 恢复;两个并发启动产生一个 Hex;hex quit 排空并移除 socket;自定义数据目录从不调用 systemctl。

这些脚本能证明协议、权限、粘贴辅助与生命周期;它们不能证明“在真实 Arch/i3 主机上、真实麦克风、真实目标应用”的行为,也不能证明签名跨版本升级。计划文档把后者写成需在受支持主机上跑一次真实稳定版之间的升级并核对:manifest 签名与单调版本、精确大小与 SHA-256、原子激活与重启、保留版本回滚、拒绝覆盖开发版/root/包管理器安装、以及无需托盘宿主的 systemd 重启与窗口重开。

排错清单

现象 优先检查
HUD 不出现 是否缺 layer-shell;窗口是否根本无法启动(无显示/无 GPU);hex dictate 下不提供 HUD
portal 找不到 Hex 是否有 hex.desktop;是否用了 newgrp 之类 setgid 包装;尝试 systemctl --user restart xdg-desktop-portal
按了键没反应(Hyprland) Hyprland 有 portal 但不带键,必须自己 hl.bind(...);Settings 里的键不生效
Escape 无法取消 无 portal 时绑 hex dictation cancel;X11 上看 Escape cancel unavailable: another application holds Escape
粘贴变成 Ctrl+Alt+V 修饰键仍被按住;改绑无修饰键(End、F 键),或松开修饰键等转录
粘贴完全没发生 是否装了 wl-clipboard;wtype 或 RemoteDesktop portal 是否可用;转录应已在剪贴板
服务起不来(Nix/Home Manager) systemctl --user status hex.service、journalctl --user -u hex.service;会话 env 是否在 target 启动前导入
出现两个 Hex 旧源码安装的 XDG autostart 与 Nix/Home Manager 自启动并存;删掉多余机制

所有这些行为共同勾勒出这个 beta 的定位:用一条明确、可审计的能力契约换取原生 Wayland 体验——不读输入设备、不装特权助手、不伪装 XWayland,快捷键要么由桌面 portal 正式授予,要么由用户显式绑定同一组幂等命令。剩余的发布工作不是“再加功能”,而是在受支持宿主上把这条契约物理地验证一遍。若需要完整的安装与依赖矩阵,继续读 docs/linux.md;若要在 NixOS 或 Home Manager 中落地,继续读 docs/nix.md 与工程契约 docs/plans/linux.md。

登录后查看全文
hex