Linux 计划¶

状态： 进行中的验证与能力计划。x86_64 X11 测试版、兼容 wlroots 的原生 Wayland 路径以及 Nix 打包均已实现。物理桌面/输入验证和真正的签名更新仍然是发布门槛；仅靠自动化检查无法确立这些行为。

所支持的契约范围有限¶

Linux 测试版保持其契约明确：

该测试版不声称支持语音命令、应用程序或浏览器上下文、会议或通用的 Wayland 支持。Wayland 需要 wl-copy、wtype 以及兼容的合成器协议；快捷键来自 GlobalShortcuts 门户，或来自用户合成器键绑定中运行的 hex 命令。不存在隐藏的 XWayland 或特权注入回退。参见 ../linux.md 和 ../nix.md。

已实现的内容¶

• 全局按住/松开听写、Esc 取消和双击锁定。
• 可配置且持久化的快捷键绑定。
• 本地模型安装与转录。
• 带有限稳定等待的自动剪贴板插入。转录文本保留在剪贴板上；不会恢复任意先前的格式。
• CLI 麦克风覆盖。
• 每个用户一个 Hex 进程（可选在 systemd 用户单元下运行），按需提供 Rune 窗口、CLI 控制、仅属主可用的 Unix IPC、桌面启动器和自启动条目。
• 一个快捷键状态机，由 X11 抓取、Wayland GlobalShortcuts 门户或幂等的 hex dictation、hex voice-action 和 hex paste-last 命令驱动（适用于没有门户的桌面）；并提供持久的可点击穿透录制/处理覆盖层。
• 可见的监听控件、事务性快捷键编辑和显式服务关闭；关闭“设置”后托管运行时仍继续运行。
• Nix 包及匹配的开发 shell、NixOS 安装、可选的 Home Manager 用户服务，以及经过评估的会话就绪检查。
• XDG 路径、诊断信息和独占的监听器所有权。
• 签名的用户本地更新，包括有界下载、精确大小与 SHA-256 验证、原子版本激活和重启移交。

更新路径已实现，但尚未在受支持的 Arch/i3 主机上通过一次完整的签名跨版本更新得到验证。

发布脚本将直接安装程序发布为 install-linux.sh。该安装程序与应用内更新器一样，验证相同的签名源和内容寻址构件，创建受管理的版本布局，并安装 XDG 桌面和自启动条目。AUR 包是未来 Arch 原生渠道的首选；pacman 必须拥有该布局的更新。

剩余工作按能力排序¶

1. 验证签名更新路径¶

在受支持的 Arch/i3 主机上，在已发布的两个稳定版本之间执行一次真实更新。验证：

• 清单签名与单调版本强制；
• 精确的构件大小与 SHA-256 验证；
• 原子激活与应用重启；
• 保留旧版本的回滚；
• 拒绝覆盖开发版、root 或包管理器安装；
• systemd 服务重启和窗口重新打开，且无需托盘宿主。

该验证不通过，就不能宣称直接安装更新渠道已被证明。

2. 添加 X11 命令与上下文¶

仅当命令功能对等成为产品优先级时，才着手这一部分工作。添加：

• Moonshine 命令识别与唤醒/睡眠行为；
• 通过 EWMH 获取 X11 前台应用与标题；
• 适合平台的命令快捷键与应用启动；
• 为 Hex 实际暂停过的播放器提供 MPRIS 暂停/恢复；
• logind 或 XDG 空闲休眠抑制；
• 可见的上下文年龄和失败状态。

在真正的浏览器适配器提供活动 URL 之前，保持浏览器宿主命令不可用。绝不要从窗口标题推断 URL。

3. 添加手动 PipeWire 会议¶

手动会议录制先于自动检测。采集两个明确的来源：

1. 选中或默认的麦克风源。
2. 选中或默认输出 sink 的监听（monitor）。

每个回调必须提供来源、呈现时间戳、单调到达时间戳、采样率和单声道浮点样本。复用现有的有界 WAV 写入器、实时草稿、间隙核算、清单、恢复和原子最终发布。

处理路由替换、蓝牙配置文件更改、时钟对齐、队列压力，以及出现在输出监听中的 Hex 反馈。路由丢失必须产生可见的间隙或失败，而不是静默损坏。

4. 添加仅元数据会议提议¶

手动采集可靠后，在不录制样本的情况下观察 PipeWire 注册表节点和活动链接。将进程和媒体元数据归一化到现有的会议候选项模型中。检测仍仅作为提议（offer-only），绝不会自动开始录制。

5. 仅在具备明确能力时扩展 Wayland¶

已实现的测试版从 GlobalShortcuts 门户或用户绑定在合成器中的 hex 命令获取快捷键，外加合成器提供的剪贴板和虚拟键盘协议。它不读取任何输入设备，也不授予任何权限。更广泛的支持需要单独的能力决策：

无特权的 Wayland 不保证任意的前台插入、全局活动观察、前台应用身份或裸修饰键快捷键。不要用 XWayland 掩盖这些限制。

不要添加特定于合成器的快捷键路径或原始输入设备读取器；portal 和 hex 命令是唯一通用契约。如果确实需要设备级对等性，请单独决定一个经批准的辅助程序，不要构建通用 root 守护进程。

6. 谨慎验证分发渠道¶

应用管理的更新程序只负责用户本地的直接安装布局。Nix 负责其打包安装和可选的用户服务；未来的 Arch 软件包也必须将更新留给包管理器。每次只添加一个经过验证的渠道，对应一种架构、发行版或包格式。

保留可移植核心¶

不要按平台分叉这些模块：

• 音频捕获、单声道转换、有界投递和丢弃统计；
• 听写预卷、可增长捕获、控制和重采样；
• 转录模型、推理、处理、排序和取消；
• 命令语法和纯解析；
• 事件模式和有界投影；
• 粘贴延续和剪贴板恢复状态转换；
• 会议清单、锁定、WAV 写入、转录稿发布和恢复。

平台适配器负责原生句柄、权限和清理。不要创建一个应用全局的 Platform trait。

仅在有真实实现时添加接缝¶

验证¶

自动化检查仍然包括：

cargo fmt --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
git diff --check
./scripts/test-install-linux-release.sh
nix flake check

针对真实适配器运行行为测试，而不是使用重复实现假设的模拟对象。

风险¶

记录的决定¶

• 目标平台：运行在 i3/X11 上的 x86_64 Arch Linux 滚动版。
• 通过已签名的用户本地直接安装渠道发布。
• 要求自动插入和包含按键的快捷键。
• 排除会议；将原生 Wayland 范围限定为兼容的 wlroots 协议，而不是宣称支持所有合成器。快捷键使用 GlobalShortcuts portal 或用户绑定的 hex 命令，绝不使用原始输入设备。
• 保持包管理器与应用管理的更新所有权分离。
• 不要为 X11 契约安装特权辅助程序。
• 在 #28 和 #29 中重建提案，并覆盖输入状态、叠加层所有权、辅助程序 I/O、设置重启和 Nix 环境的回归测试。