Nix¶

该 flake 为 x86_64-linux 和 aarch64-linux 打包了 Hex。两者均从源码构建；aarch64-linux 可求值，但尚未在真实 ARM64 硬件上构建或运行。它支持 Linux X11 beta，以及在兼容的 wlroots 合成器上的原生 Wayland。Wayland 需要 layer-shell 用于录制叠加层、wl-copy 使用的剪贴板协议，以及 wtype 使用的虚拟键盘协议。全局快捷键来自桌面的 GlobalShortcuts portal，或者来自你自己的合成器键绑定运行 hex 命令。这并不表示支持所有 Wayland 桌面；GNOME 和 KDE 不在这一保证范围内。

运行或安装¶

在启用了 Nix flakes 的检出仓库中：

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

或者，将 hex.url = "github:anomalyco/hex" 添加到你的配置的 flake inputs，并安装 hex.packages.${system}.default（x86_64-linux 或 aarch64-linux）。该软件包提供 hex 命令和桌面启动器、原生库（包括用于 Annotate 的 PipeWire 和 libva），以及 curl、wl-copy、wtype 和 ffmpeg/ffprobe 运行时依赖。Annotate 的硬件编码器使用你的系统提供的任意 VA-API 驱动（NixOS 上通过 /run/opengl-driver 的 hardware.graphics）；如果没有，它回退到 ffmpeg 的 libx264。即使推理回退到 CPU，你的系统仍然需要正常的音频会话和用于 Settings 的 Vulkan 驱动。在非 NixOS 主机上，Nix GUI 应用程序可能需要主机通常的 Nix 图形集成。

在 NixOS 上，由自带的固定 nixpkgs 构建的 Hex 可能使用比你系统图形驱动所需更旧的 glibc。这样 Hex 就找不到合适的 Vulkan 适配器，其窗口无法打开。让 Hex 的 nixpkgs 跟随你的系统 nixpkgs，这样两者使用相同的 glibc：

{
  inputs.hex = {
    url = "github:anomalyco/hex";
    # Use the name of your own nixpkgs input here.
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

模型会下载到你的用户数据目录，而不是 Nix store。运行一次 hex model install，然后以你正常的桌面用户启动 Hex。不要以 root 身份运行 Hex。

Nix store 不是 Hex 的本地用户托管安装布局。应用内更新不会替换 Nix 安装。请更新 flake input，然后重新构建或切换你的 Nix/Home Manager 配置。在启用第二个自启动机制之前，移除任何旧的源码安装 XDG autostart 条目；不要运行两个 Hex 监听器。

NixOS¶

导入 hex.nixosModules.hex 并启用该软件包：

{
  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 user 服务。自启动默认值为 false；启用后，该 unit 默认被 graphical-session.target 需要。它在启动 hex service 之前会等待 Wayland socket 或 X11 窗口管理器；一旦其 socket 响应，就会向 systemd 报告就绪（Type=notify）。Hex 是一个进程：hex 打开其窗口，在 unit 未运行时启动它，而 hex start 则在不打开窗口的情况下启动它。关闭窗口永远不会停止 Hex；当桌面有托盘宿主时，托盘图标会显示。该 unit 随配置的 target 停止，并在失败启动时重试而不会紧密重启循环；崩溃重启不会打开窗口。hex quit（或窗口中的 Quit Hex）会使其保持停止状态，直到下一个会话或下一次启动。

你的会话管理器必须在启动 target 之前，将当前的 DISPLAY、XAUTHORITY、WAYLAND_DISPLAY 和 XDG_RUNTIME_DIR 值（如适用）导入 systemd 用户环境，并在注销时停止该 target。请使用你的合成器的 systemd 集成（例如 Home Manager 的 Sway 集成），而不要从 shell 登录启动 target。该模块不会创建图形会话，也不会授予使用图形会话的权限。没有 systemd 会话集成的裸 startx/i3 会话不会自动启动此服务。

hex start 将当前显示/会话环境记录在一个仅所有者可读的文件中，该文件由 unit 读取；在 X11 和 Wayland 之间切换时，它会清除过期的变量。每个用户有一个 Hex。从不同的桌面启动它会为该会话显式重启 unit。该 unit 指定了 Hex 的默认数据文件夹，因此 Hex 仍然将其视为自己监管的服务：早期登录留下的过期 XAUTHORITY（GNOME 的 XWayland cookie）会被替换为用户管理器当前的 XAUTHORITY，从而在重新登录后保持 HUD 正常工作（#1140）。

Home Manager 的正常服务切换策略适用：如果会话 target 已经激活，新启用的服务可以在切换期间启动，而软件包更改可以重启正在运行的服务。不要在录制进行中切换。使用以下命令检查失败：

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

声明式设置¶

{
  programs.hex = {
    enable = true;
    shortcut = "control+option+space"; # dictation_hotkey
    model = "parakeet_v3";
    language = "de";
    installModel = true;
    settings = {
      shortcut_mode = "toggle";
      sound_effect_volume = 0.4;
      paste_with_shift = true;
      "meetings.enabled" = true;
    };
  };
}

settings 接受 hex settings list 显示的点分键，其值为 JSON：布尔值、数字、文本（如快捷键和选项）、null 用于清除可选设置，以及属性集或列表用于其 json 设置。shortcut、model 和 language 选项分别是 dictation_hotkey、transcription.model 和 transcription.language 的简写。

每次激活都会在 systemd 单元重新加载后，通过 hex settings apply 将它们合并到 Hex 中。已声明的键会覆盖 Hex 的值；你在窗口中更改但未声明的任何内容，其值会一直保留，直到你声明它。正在运行的 Hex 会立即保存并采用这些设置，因此它绝不会从内存中写回旧值；当 Hex 停止时，这些设置会直接写入 settings.json。settings.json 始终是一个普通的可写文件。未知键或无效值不会应用任何内容，并会打印一条警告，而不会导致切换失败。

声明模型只是选择它；激活时绝不会下载。设置 installModel = true 后，hex-model 用户服务会在登录时、系统达到 network-online.target 后（或两分钟后），为所选模型运行 hex model install，并重试失败的下载。切换不会等待该过程完成。

Wayland 快捷键¶

Hex 不读取任何输入设备，因此两个模块都不会将用户添加到 input 组、安装 udev 规则或授予 capabilities。借助 GlobalShortcuts 门户，桌面会授予 Settings 记录中的快捷键；门户通过软件包的 anomaly.hex.desktop 条目来识别 Hex，因此请将软件包的 share/applications 保留在 XDG_DATA_DIRS 中（NixOS 和 Home Manager profile 就是这样做的）。如果没有门户，请在合成器中绑定这些命令，例如在 Sway 中：

bindsym F9 exec hex dictation start
bindsym --release F9 exec hex dictation stop

hex dictation toggle 和 hex paste-last 也可用；请参阅 Linux 指南。粘贴辅助工具是 wtype；不会安装特权输入注入回退方案。

开发¶

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

软件包和 shell 共享原生构建环境以及运行时库/插件路径。OpenBLAS 链接顺序由 build.rs 处理，而不是由仅限 Nix 的 RUSTFLAGS 处理。shell 还提供粘贴和下载辅助工具，因此它不依赖已安装应用的外层包装。桌面命令仍然需要真实的图形/音频会话以及上述权限。

nix flake check 会评估模块和 shell 环境的回归情况，并使用常规的无显示器 Rust 测试构建软件包。那些因需要桌面或已安装模型而被明确标记为忽略的测试仍保持忽略；Nix 构建不会下载模型，也不会进行实时输入测试。

最初的打包设计基于 PR #29。声明式设置遵循 @SymphonySimper 在 #588 中的请求。