Windows 测试版¶

Windows 移植版目前处于测试阶段，包含 Rune 桌面应用（一个托盘进程；参见应用）、WASAPI 采集、本地 transcribe.cpp 转录、全局快捷键，以及生成安全的自动粘贴。其日常使用面包括：实时麦克风、模型和快捷键设置，Hold、Tap 和双击快捷键模式，Paste Last Dictation（粘贴最后一段听写），录音提示音，可点击穿透的 HUD，保留的历史记录，文本替换，常驻系统托盘，以及按用户的登录时启动。全局和上下文模式可以通过与 macOS 相同的受截止时间约束的 OpenCode 处理策略改写已完成的听写，然后按顺序运行内置或用户自定义的 TypeScript 转换。

默认快捷键是 Ctrl+Space。在 Hold 模式下，说话时按住两个键，松开 Space 即可转录并粘贴。在 Toggle 模式下，按 Ctrl+Space 开始，再按一次结束，或按 取消 快捷键（默认为 Escape）丢弃录音；Hex 仅在录音运行时占用该键。Hold 模式没有取消功能（每次听写都会完成并粘贴），单独按住修饰键不会有任何作用。Hex 在匹配时消耗该组合键，因此应用程序和输入法不再看到 Ctrl+Space；如果你在其他地方依赖该组合键，请在设置中重新绑定。要让另一个应用使用相同的按键（例如 Discord 的按键说话键），请在“高级”下开启 与其他应用共享听写快捷键：Hex 仍然会响应它，但会将其按下和松开事件传递出去，这也可能触发其他应用中的该绑定。在 Hold 模式下，在 300 毫秒内点按快捷键两次可锁定录音，然后再次按下即可结束。Paste Last（粘贴最后一段）默认为 Ctrl+Alt+V。设置更改会实时生效，或通过自动重启监听器生效。

当快捷键在系统范围内、每个应用中都能工作时，设置卡片显示 已启用；当它不起作用时显示 已禁用。

安装¶

x86_64 PC 需要 2013 年或更新、支持 AVX2 的处理器（Intel Haswell / AMD Excavator 或更高版本）；在较旧的处理器上，Hex 会显示一条消息然后退出，而不是启动。

下载并运行适用于你 PC 的安装程序：

• x64: HexSetup.exe
• ARM64: HexSetup.exe

在 Hex 第一个稳定版发布之前，这些是最新的开发版构建，会不断从 Dev 渠道自我更新；之后则是稳定版。

anoma.ly/hex 会自动选择正确的版本。安装程序不需要管理员权限：它为当前用户安装，将 Hex 添加到开始菜单、添加到 设置 › 应用 以便卸载，并将 hex 添加到 PATH 供终端使用，然后打开 Hex，首次运行时会下载语音模型。一旦配置好 Anomaly 的 Azure Artifact Signing，之后构建的版本都会通过 Authenticode 签名（windows-signing.md）。在此之前，以及在新发布者建立 SmartScreen 信誉期间，SmartScreen 可能会提示它保护了你的 PC；请选择 更多信息，然后选择 仍要运行。

x64 通过 Vulkan 1.2 在 GPU 上解码，由最新的 NVIDIA、AMD 或 Intel 显卡驱动提供（vulkan-1.dll）。如果驱动缺失或过旧，Hex 仍然可以在 CPU 上启动和解码，设置 › 语音引擎会显示相应状态。ARM64 在 CPU 上解码。两者都是自包含的：不需要 Visual C++ 可再发行组件。Hex 随后通过签名更新源保持自身为最新版本。卸载会移除所有已安装的版本、快捷方式和登录时启动，并保留 %APPDATA%\hex 中的设置和历史记录，以及 %LOCALAPPDATA%\hex 中的日志和模型。

安装程序和下面的脚本会创建相同的托管布局，因此两者可以互相替换。如需脚本安装：

powershell -ExecutionPolicy Bypass -Command "iwr https://anoma.ly/hex/files/install-windows.ps1 -OutFile install-windows.ps1; ./install-windows.ps1"

使用 install-windows.ps1 -Uninstall 卸载脚本安装。

托管布局是 %APPDATA%\hex\versions\<version>\，其中包含 hex.exe（应用本身，一个 GUI 程序，因此启动 Hex 不会打开控制台窗口）和 hex.com（其控制台入口点，它会以相同的参数运行 hex.exe，等待其结束并返回其退出代码（hex 和 hex app 只会启动应用并立即返回））。快捷方式、登录时启动和开始菜单都会打开 hex.exe。%APPDATA%\hex\bin\hex.com 是运行 current-version 所指定版本的副本，位于用户的 PATH 中；终端会优先将 hex 解析为该副本，而不是任何 hex.exe，因为 PATHEXT 将 .COM 排在前面。安装前打开的终端需要重新打开才能看到 PATH。

已知问题¶

Discord 显示“正在玩 HEX: Shards of Fate”（#445）。在开启游戏活动检测的情况下，Discord Desktop 会将正在运行的 hex.exe 匹配到已认证的游戏 HEX: Shards of Fate。只要 Hex 在运行，它就会在你的个人资料上显示该游戏。报告者的本地测试表明 Discord 是根据可执行文件名称进行匹配的。Hex 保留 hex.exe 这个名称，因为安装程序、更新器、开始菜单快捷方式和登录时启动都使用托管的 %APPDATA%\hex\versions\<version>\hex.exe 路径。该问题已报告给 Discord。在 Discord 修复其游戏列表之前，请打开 Discord 的 设置 › 已注册游戏（或 活动隐私）并隐藏检测到的条目，或在那里关闭活动共享。无论哪种方式，Hex 的功能都不受影响。

流式听写¶

在 GPU 上使用 Parakeet Unified English 时，Hex 会在按住快捷键期间将音频流式输入到模型中，因此松开时只需解码最后的一到两秒。相同的引擎在 macOS（Metal）和 Linux（Vulkan）上支持流式传输。每次听写都会在 logs\process.log 中记录 source=stream 或 source=fallback；如果流式传输失败、超过截止时间停滞或未返回任何内容，则会回退到转录整个音频片段。CPU 设备（包括 ARM64）始终使用整段音频路径。设置 HEX_STREAMING=0 可强制使用整段音频路径。参见听写。

源码构建要求¶

• 64 位 Windows 10 或 11，x64 或 ARM64。
• PowerShell 7 或 Windows PowerShell 5.1。
• 来自 Microsoft App Installer 的 winget。
• Visual Studio C++ Build Tools、CMake 和稳定的 MSVC Rust 工具链。
• x64：Vulkan SDK（需设置 VULKAN_SDK），用于 GPU 后端。
• ARM64：Visual Studio 的 clang-cl 和 Ninja；ggml 的 ARM CPU 后端不接受 MSVC。请像 .github/workflows/check-windows.yml 那样，使用 CC=clang-cl、CXX=clang-cl、CMAKE_GENERATOR=Ninja 和 TRANSCRIBE_CMAKE_ARGS=-DGGML_NATIVE=OFF -DGGML_OPENMP=OFF 进行构建。

.cargo/config.toml 静态链接 C 和 C++ 运行时。分布式构建还会设置 TRANSCRIBE_CMAKE_ARGS=-DGGML_NATIVE=OFF；否则 ggml 会针对构建机器调整其 CPU 内核，生成的二进制在较旧的 CPU 上可能崩溃。

从仓库根目录运行仓库自带的设置脚本。它保留现有兼容的 Visual Studio 安装，只安装缺失的必备组件。

powershell -ExecutionPolicy Bypass -File .\scripts\setup-windows.ps1

该脚本还会安装 rustfmt、Clippy 和 rust-analyzer，获取 Cargo 依赖，并运行 cargo check --all-targets。

冒烟测试¶

列出 WASAPI 输入以及 transcribe.cpp 可见的计算后端：

cargo run -- devices
cargo run -- model devices

安装所选模型（在 Hex 停止时，model install 会在当前进程中下载），加载它，并转录一个 WAV 文件：

cargo run -- model install
cargo run -- model check
cargo run -- model transcribe .\sample.wav

对于波兰语，请指定多语言 Parakeet 模型：

cargo run -- model install parakeet_v3 --language pl
cargo run -- model check parakeet_v3 --language pl
cargo run -- record --model parakeet_v3 --language pl --copy

安装模型后，打开桌面应用程序：

cargo run -- app

当快捷键在系统中的所有应用中全局生效时，设置卡片显示 Enabled；当它毫无作用时显示 Disabled；卡片上的按钮和托盘的 Enable / Disable Hex 会在两者之间切换。Hex 默认在启动时自行启用（Enable on launch）。只有您在口述时，麦克风才会录音。更改转录模型、麦克风、口述快捷键、双击行为或 Paste Last 设置会自动重启监听器；您无需先停止它。文本替换和反馈音量在无需重新加载模型的情况下即可生效。模式规则、OpenCode 配置文件和有序转换由输出工作线程进行快照，并在无需重启采集的情况下应用于下一次完成的口述。命令行监听器使用应用保存的设置：

cargo run -- listen --model parakeet_v3 --language pl

record 会预热所选模型，并在提示之前打开麦克风。按一次 Enter 开始，再按一次停止。短于 300 毫秒的采集会被丢弃。--device 接受来自 devices 的不区分大小写的片段。

运行时数据存储在 %APPDATA%\hex 下，但日志和语音模型除外，它们属于这台计算机，位于 %LOCALAPPDATA%\hex：在受管网络上，Windows 会在每次登录时将 Roaming 文件夹复制到服务器，而数百 MB 的模型会拖慢这一过程。旧版 Hex 的 logs 和 models 会一次性移动到该位置（app_paths::machine_local）；只要运行中的 Hex 仍占用着它们，Roaming 副本就会一直处于使用状态。观测数据位于 logs\live.ndjson，原生/运行时诊断信息位于 logs\process.log，包括每次 panic 的线程和回溯。意外停止的工作线程会在那里留下原因。hex.exe 是一个 GUI 程序，因此从资源管理器、开始菜单或登录时启动不会打开控制台窗口。如果从终端运行，它会在终端中打印启动错误，然后应用脱离终端，不再有 stdout 或 stderr。成功粘贴的口述内容会保留在 history.json 中，具体取决于所选保留时间窗口和硬性大小限制。默认情况下，采集的音频绝不会被保留。

控制命令¶

hex 控制命令（docs/cli.md）像在 macOS 上一样驱动正在运行的托盘应用：status、start、quit、restart、dictation start|stop|cancel|toggle（带 stop --print）、paste-last、settings、model、window、vocabulary、history clear、check-for-updates、launch-at-login（Run 注册表项）、onboarding reset、logs、commands init|check、annotate、meetings record|stop|copy-last、history 和 mcp。它们通过其本地 API（%APPDATA%\hex 中的 local-api.json 和基于 bearer 认证的 POST /control）访问应用。口述命令会同快捷键按下一样进入监听器自身的循环，而 annotate 的 start、stop、cancel 和 status 会等待其采集宿主。history、meetings 和 mcp 的工作方式与 macOS 上相同。hex restart 会退出，等待排空，然后重新启动 hex app --hidden。

自定义转换¶

Modes 中的 Transformations 卡片始终提供内置转换。在那里选择 Set up 可创建 ~/.config/hex/hex.config.ts，并加载该配置注册的任何转换。Hex 在其内置 JavaScript 引擎（QuickJS）中运行该配置，因此无需安装其他任何组件。

转换会在模式修正和可选的 OpenCode 重写之后，按显示顺序运行。对它们进行重新排序、添加或删除会持久化到全局或上下文模式，并应用于下一个输出任务。每次转换调用限制为一秒，引擎限制为 64 MiB；失败的步骤会保留之前流水线的输出。保存配置会重新加载它；若配置加载失败，则保留之前的配置，并在卡片中显示错误。

应用¶

hex app（用于登录启动的 --hidden）在 Rune 上运行托盘应用。无需启动任何内容即可生成快照夹具：hex app -- --snap out.png --scene modes。

hex app
├── named event already held -> signal it (the running app shows its window) -> exit
└── becomes the app                                   // windows::rune::open
    ├── the local API's POST /control -> control::host::answer
    ├── runtime thread: WindowsDesktopHost (listener, model preparation, OpenCode, transformations, updater), publishes every 250 ms
    ├── main thread: rune::App's winit loop and the window; rune::Tray runs on its own thread
    ├── --hidden -> windowless start; close -> hide (keep_running)
    ├── tray Show or a relaunch -> AppHandle::open (shows and focuses)
    └── tray Quit / Ctrl-C / restart into an update -> AppHandle::quit -> runtime stops the listener

• 在窗口或托盘中退出 Hex 会停止监听器并结束应用； 仅关闭窗口只是隐藏它。
• 窗口使用共享的 Rune 窗格（General、Modes、 History、转录选择器、首次运行设置），并带有 Windows 行： 开机启动（当前用户的 Run 键），没有终端粘贴行。 侧边栏底部包含 Check for updates，以及用于非托管安装的 Download update。快捷键通过轮询键盘并挂起监听器的钩子来记录， 因为仅修饰键组合永远不会作为按键事件到达窗口。
• 模型在进程内通过 transcription/preparation 准备；运行时在准备就绪时 保存选择并重启监听器。
• 启动时启用会等到首次运行设置记录完成。
• 听写 HUD 是一个 Rune 覆盖层（rune_hud.rs，与 Linux 共享）： HUD 线程推进共享指示器模型和 Dot 作用域，并且 覆盖层的合成器使用 rune_hud.wgsl 在 GPU 上绘制每一帧；Rune 在顶层工具窗口中显示它， 使用 WS_EX_NOACTIVATE|WS_EX_TRANSPARENT|WS_EX_LAYERED，并通过 SW_SHOWNOACTIVATE 显示，距顶部 12 pt 或距任务栏 24 pt。相同的 模型、着色器和覆盖层在 Linux 上运行；在 Windows 上仅进行类型检查。
• 窗口通过 Rune 的 App::on_window 钩子获取可执行文件的图标 （通过 WindowHandle::with_raw_handle 获取其 HWND），用于任务栏、 Alt-Tab 和标题栏。原生标题栏保留其图标和标题， 并融合到窗口中：DWM 将标题栏绘制为主题色 bg_deep （DWMWA_CAPTION_COLOR，Windows 11；Windows 10 保留自己的标题栏 颜色）。视图在系统主题切换时重新绘制它。
• 没有托盘（创建失败）时，关闭窗口将退出 Hex。 参见单进程计划。

该应用从未在 Windows 上运行过。 早期版本发布了一个 GPUI 应用， 有人运行过；那个应用已消失，Rune 应用在下一个版本中取而代之，因此 必须有人在发布之前在 Windows（x64 和 ARM64）上运行它。通过使用 cargo-xwin 在 Linux 上交叉编译进行类型检查：

rustup target add x86_64-pc-windows-msvc && cargo install cargo-xwin
# clang-cl、lld-link 和 llvm-lib 必须在 PATH 上（llvm-lib 可以是
# rustup 的 llvm-tools llvm-ar 的符号链接）。
mkdir -p /tmp/no-transcribe/lib
echo '{"libraries":[],"shared":false}' > /tmp/no-transcribe/lib/transcribe-link.json
# TRANSCRIBE_DIR 跳过 transcribe.cpp/Vulkan CMake 构建；检查中不链接任何内容。
TRANSCRIBE_DIR=/tmp/no-transcribe cargo xwin clippy --target x86_64-pc-windows-msvc \
  --all-targets -- -D warnings

对于 ARM64，添加 aarch64-pc-windows-msvc 目标并设置 XWIN_CROSS_COMPILER=clang：ring 的 aarch64 构建强制使用 GNU 风格的 clang 驱动程序，它拒绝 cargo-xwin 默认传递的 clang-cl /imsvc 标志。 另外设置 CARGO_FEATURE_NO_NEON=1：blake3（通过 Rune）构建 NEON C， 而 xwin sysroot 的 arm64_neon.h 宏在该驱动程序下会破坏它。

这会检查所有 Rust 路径，包括 Rune、wgpu 的 DX12 和 Vulkan 后端，以及 Windows 模块；它会为目标编译 C 构建脚本（ring）， 但从不链接、构建 transcribe.cpp 或运行任何内容。

本地转录服务¶

此构建中在 Windows 上不可用。windows-shell 分支曾将 经过身份验证的本地 API（service 和 service --embedded）推广到 所有平台，但 dev 此后已针对 macOS 重新调整了它；将其移植到 该版本上是后续工作。

macOS 对等性¶

目标是产品和对等视觉上与 macOS 一致，在操作系统 API 不同的地方 使用原生 Windows 适配器。直接复制 AppKit、CoreAudio 事件点击、 Metal、SMAppService、辅助功能或 ScreenCaptureKit 代码在 Windows 上 无法运行；Windows 实现必须通过 Win32、WASAPI、Rune（wgpu）、 当前用户启动注册表、UI Automation 和 Windows 捕获 API 保留相同的 用户契约。

设置保存在 %APPDATA%\hex\settings.json 中，与 macOS 和 Linux 使用同一文件。

Windows 窗口使用共享设计系统（design-system.md）：在原生标题栏下使用与 macOS 和 Linux 相同的 Rune 面板。模式处理、OpenCode 重写和转换通过与 macOS 相同的 dictation/processor 和 personal_commands 模块运行，并且 Windows 以相同方式访问正在运行的 OpenCode 服务：通过其注册文件和回环 HTTP，绝不使用 CLI。与 macOS 一样，未设置 OpenCode 模型时会先尝试排名靠前的推荐模型，然后才使用 OpenCode 默认模型。其余面板只有在具备完整 Windows 行为时才应添加；空有其表的相似屏幕不算作对等。

当前移植边界¶

Windows 监听器保留物理按下/释放时间戳，使音频采集不占用转写和粘贴工作线程，并且仅当没有更新的剪贴板更改取代它时才恢复之前的剪贴板。check-windows 在 Release 的 check 和 stable 通道中构建并测试针对 x64 和 ARM64 优化过的 MSVC 发布版；拉取请求仅编译 x64。在物理矩阵变绿之后，剩余的代码对等部分仅是开发者专用的 Meetings 界面。共享的首次运行引导、完整的 OpenCode 模式重写控件以及有边界的 TypeScript 转换主进程已经发布。Windows 发布版由 release.yml 配合 scripts/build-windows.sh 为 x64 和 ARM64 构建，经过 Authenticode 签名，并与其他平台一同发布到 Anomaly 发布服务（docs/releasing.md）；.github/release/install-windows.ps1 从其稳定清单进行安装。用户通过 Install 下的命令安装。