装完按了没反应:权限、热键与模型下载的五个高频坑

原创2026-11-02 15:49:191,935 阅读
文章标签:语音桌面应用本地部署人工智能音频

装完按了没反应:权限、热键与模型下载的五个高频坑

Hex 的安装过程很短:拖进 Applications,授权,下载模型。真正让人卡住的往往发生在之后的第一次按下 Option。菜单栏里那个六边形还在,进程也活着,hex status 能返回 JSON,但按住快捷键说话,什么都没发生。

这类“装完按了没反应”的故障,绝大多数不是语音模型坏了,而是链路上三个环节之一的静默失败:macOS 没有把权限交给当前这个进程、快捷键在到达 Hex 之前就被别的软件消费掉了、或者磁盘上的模型文件只是一个“看起来存在”的残缺品。下面五个坑,全部可以在仓库源码里找到对应的状态机、常量和错误文案。

Hex 首次运行设置界面:麦克风与辅助功能两行权限,右侧为 Allow

坑一:授权了,但授权没有落到正在运行的这个进程上

macOS 的隐私授权从来不是“开关一变,旧进程立刻获得能力”。Hex 把权限建模成四个状态,而不是一个布尔值,src/onboarding.rs 里的定义很直白:

pub enum PermissionState {
    Ready,
    NeedsRequest,
    NeedsSettings,
    /// Switched on in System Settings, but macOS applies it to Hex only
    /// after Hex restarts.
    NeedsRestart,
}

关键在第四个状态。它存在的原因不是 macOS 要求用户重启电脑,而是 TCC 判定作用在进程上:你在系统设置里勾选了 Hex,但当前正在跑的那个 PID 可能仍旧是旧判定。所以 Hex 在重启类操作上做了三件事:

一是把状态查清楚再决定要不要重启。辅助功能的判定同时看两个 API(src/onboarding.rs):

accessibility: accessibility_state(CGPreflightPostEventAccess(), AXIsProcessTrusted()),

注释解释得很清楚:AXIsProcessTrusted 会跟随开关实时变化,而 CGPreflightPostEventAccess 保留的是启动时的答案。所以只要 trusted 为真就算 Ready——这意味着多数情况下辅助功能授权不需要重启 Hex,只有事件 tap 真正建不起来时才需要。这一点很重要:网上大量“授权后必须重启”的说法,在这个项目里被收窄成了一个更精确的条件。

二是只在确认需要时重启一次。设置页的重启按钮由 restart_needed() 控制:必须存在 NeedsRestart,且麦克风与辅助功能都已经是 Ready 或 NeedsRestart,否则不打扰用户。重启本身也不是简单地 open 一次,src/onboarding.rs 里的 relaunch_arguments 拼的是一段 shell:

pid=$1; shift; while kill -0 "$pid" 2>/dev/null; do sleep 0.1; done; \
exec /usr/bin/open "$@"

先等旧进程退出再 open,是为了不和新进程抢实例锁;open 不带 -n,保证只有一个 Hex。同时它会把所有 HEX_* 环境变量通过 open --env 转发过去——因为 LaunchServices 启动的 App 拿不到调用方的环境,HEX_RETAIN_DICTATION_AUDIO、HEX_ENABLE_LLM 这类诊断开关如果在重启后丢失,会让你误以为“功能又坏了”。

三是不允许多次自动重启。守卫常量是 120 秒:

pub const RELAUNCH_GUARD_MS: u64 = 120_000;

一次引导流程里最多自动重启一次;如果授权始终没有生效,界面会退化成一条静态提示“请退出并重新打开 Hex 以完成设置”,而不是陷入无限重启循环。守卫过期后的重启标记也不会再被当作“继续引导”的依据(take_resume_at 只在 120 秒内生效)。

还有一个真实存在的分支:事件 tap 创建失败时,src/suppression.rs 返回的错误是 could not create keyboard event tap; grant Accessibility permission;src/macos_rune.rs 检测到错误信息里包含 event tap,就会调用 note_listener_failure(),随后触发同一条重启路径。这是 macOS 不为辅助功能提供“Quit & Reopen”按钮之后,应用层自己补的一次性补救。

排障要点:别猜。hex status 的 permissions 字段直接给出内部状态,取值域是 ready | needs-request | needs-settings | needs-restart(见 docs/cli.md)。看到 needs-settings 就是系统设置里没勾上,看到 needs-restart 才是“勾了但没生效”。

另外,macOS 27 把系统设置里的辅助功能列表改了名字,Hex 的权限引导面板会读取系统真实名称(src/permission_guide.rs 的 list_name),所以你在截图教程里找不到“Accessibility”那一行时,先确认自己系统的叫法,而不是去找一个不存在的列表。

Hex 设置页权限区域与快捷键、模型、麦克风选项

坑二:快捷键没丢,只是在到达 Hex 之前被消费了

这是最容易误判成 bug 的一类。Hex 的 macOS 实现同时挂了三类事件 tap(src/suppression.rs):带过滤的键盘 tap、被动观察修饰键的 tap,以及一个 HID 层的只读 tap。第三个是为了解决一类特定问题:

Listens for key presses at the HID level, where shortcuts that other apps register globally are still visible. Without it those chords are invisible to the session taps; dictation still works.

也就是说,当某个软件用 Carbon RegisterHotKey 注册了 Option+1 这类全局快捷键,这个组合会在 session tap 之前就被吃掉,Hex 只能看到 Option 的按下与释放。docs/features/dictation.md 记录了这个真实案例:按住 Option 超过 300 ms 再按数字切工作区,麦克风录下的是环境声并会粘贴出去;快速切两次还可能被当成双击锁定。修复方式不是抢那个键,而是让 HID 层提供“这个按键确实发生了”的证据,从而把这次 Option 按下判定为 chord 丢弃。

问题在于:你现在看到的“按了没反应”,可能正是这个保护机制在正常工作。证据链是可查的:

  • process.log 里会出现 dictation press discarded as a chord(或 HID 证据反超时的 dictation press dropped),附带键码、按下后经过的毫秒数;
  • live.ndjson 的 discarded 事件带 reason,取值 key、hid-key、mouse、extra-modifier。

所以判定方法不是反复按快捷键,而是先看日志里到底有没有 press,再看 press 有没有被丢弃。

第二个截获来源是“tap detector”类工具。裸修饰键(只用 Option、不用字母键)不会被消费,别的应用会把它当成一次 Option 单击。Raycast 绑在 Option 单击上时,每次口述都会触发它,这就是仓库里记录的“口述触发 Slack、退出全屏 Space 再粘贴”的事故。为此 Hex 增加了一个 chord breaker:在拥有一次修饰键按下之后,向系统补发一次键码 0x44 的按下,只发一次,且仅在恰好是快捷键要求的那几个修饰键仍物理按着时发出。结果是别的工具的“单击”判据看到的是一个组合键,tap 被取消。

第三个截获来源其实是 Hex 自己。多个快捷键共享同一套冲突判定(src/app_settings.rs 的 hotkey_in_use / HotkeySlot),设置页会直接拒绝重复绑定,提示 Already in use;控制协议返回的错误码是 shortcut-in-use。还有一条容易忽略的自愈逻辑 repair_hotkey_conflict:如果你后来把口述快捷键改成了和已启用的 Voice Action 相同的键,它会在加载设置时把 Voice Action 换到 Option+Command、Option+Command+E、Control+Command 中第一个不冲突的绑定,并写一条 replaced a conflicting Voice Action shortcut 警告。也就是说,Voice Action 的键会“自己变了”,这不是错乱。

跨平台还有各自的分叉:

  • Linux / X11:GrabKey 遇到别人已占用的组合会返回 BadAccess,src/linux_input.rs 用 is_grab_conflict 精确区分这种情况与其他致命错误;Escape 被占用时还会退化为不抓 Escape,保证取消键不拖垮整个监听。
  • Linux / Wayland:快捷键由桌面的 GlobalShortcuts portal 决定,桌面可以授予、改键或拒绝。设置页会列出“桌面已授予”的实际组合,被拒绝时给出“桌面保留了此快捷键”的提示,并提示 niri 用户去 config.kdl 里删掉自己的 bind。Hyprland 有 portal 但不吃这一套,必须自己 hl.bind 到 hex:dictation。
  • Windows:默认 Ctrl+Space,与中文输入法的全半角切换直接冲突;docs/windows.md 明确写了“其他应用和输入法不再看到 Ctrl+Space,请在设置里改绑”。

一次决定性的分叉测试:直接用命令绕过热键层。

hex dictation start
hex dictation stop

如果这条链路能正常录音并粘贴,说明权限和模型都没问题,问题 100% 在热键层(被截获、被拒绝、或绑定冲突);如果命令也失败,才回去查坑一和坑四。Linux 上还能用 hex status 的 listener.status 区分 Enabled、Waiting for setup、No microphone、Stopped。

坑三:按得“太短”,是设计而不是故障

这一条听起来像 UX 问题,但它在计数上经常就是“高频坑”的第一名。

Hold 模式下,短于 300 ms 的按下会被判为 tap 并丢弃(dictate.short-tap),因为大量用户是在用组合键做别的事时顺手碰到了 Option。这个 300 ms 不是定时器猜的,而是按音频时钟判定的;仓库里有一批专门盯这个边界的测试,例如 callback_press_reaches_intentional_hold_on_the_audio_clock。

更微妙的是“按住修饰键 + 任意键”的规则:当快捷键是裸修饰键时,只要在按住期间按了任何非修饰键,这次采集会被丢弃,按键原样送给前台应用(dictate.held-chord)。所以“我明明按住了 Option 也说话了,却没反应”有一种解释是:你在说话过程中碰了别的键。

双击锁定也有对应的时序:双按 Option 进入持续录音,再按一次结束;Toggle 模式下每次按下都等价于双击的第二下。如果在双击之间插入了一个别的键,两次按下就不再构成锁定。

排障要点:先确认模式。设置页的 Shortcut mode 只有 Hold 和 Toggle 两个选项,持久化键是 shortcut_mode,旧配置文件缺这个字段时按 Hold 处理。如果你预期“按一下开始、再按一下结束”,却停在 Hold 模式,那么第一次短按本来就会被丢弃——这不是失灵,是模式不匹配。其次,hex dictation start 是“锁定式”的(等价于双击后开始),它没有按下时长可供判断,因此立刻被视为有意采集。这也是为什么分叉测试能干净地区分热键层与语义层。

坑四:模型下载中断后,磁盘上留下的是“看起来装好了”的文件

模型下载是这个项目里最工程化的一段代码,值得单独讲,因为它解释了绝大多数“设置里显示已安装,但转录起不来”的现象。

默认英文模型 Parakeet Unified English 的大小是明确的:

bytes: 731_357_568,
sha256: "4b50b6dd862bf6e346929aaf4f5eaacec003bfa3f56462d6c874b41ef2f38795",

约 698 MB。下载走的是系统 curl,参数在 src/transcription_models.rs 里写死:

.args([
    "--fail", "--location",
    "--retry", "3",
    "--connect-timeout", "15",
    "--speed-limit", "1024",
    "--speed-time", "60",
    "--continue-at", "-",
    "--silent", "--show-error",
    "--output",
])

两个细节决定了断网后的行为:--continue-at - 是续传;--speed-limit 1024 --speed-time 60 意味着速率低于 1 KB/s 持续 60 秒就判定这次传输失败,而不是永远挂着。下载写入的是 .gguf.partial,不是目标文件名——这是全部设计的前提。

失败之后,重试时会发生这样一串判断:

  1. 目标文件存在,且“回执”匹配(大小、sha256、mtime 都对得上)→ 直接返回,离线也能激活。
  2. 目标文件存在但回执不匹配 → 进入 Verifying,重新算 sha256;校验通过就补写回执,不通过则保留原文件,等新副本下载完再替换(注释写得明确:will replace invalid transcription model after verifying its replacement)。
  3. .partial 比目标大小还大 → 直接删掉重下(说明是坏数据)。
  4. .partial 大小正好等于目标 → 先校验,通过就“提升”为目标文件。
  5. 否则继续续传。

“提升”这一步是原子性的(verify_and_promote_partial):校验 → fsync → rename → fsync 目录 → 写 .gguf.verified.json 回执。回执里存 bytes、sha256、modified_ns,下次启动只做一次廉价的比对,不用每次重算几百 MB 的哈希。

而 is_installed() 只看文件大小:

ModelRuntime::Gguf(artifact) => model_path(model)
    .and_then(|path| Ok(fs::metadata(path)?.len() == artifact.bytes))
    .unwrap_or(false),

这就是“显示已安装”和“真的能用”之间的缝。大小对得上、内容坏掉的模型会通过 is_installed,但真正加载时会失败。修复动作必须走会重新校验的那条路径:

hex model install <model-id>

不要用 hex model use——docs/cli.md 明确写了它只在已下载的模型间切换并检查磁盘,从不下载或修复。

并发与删除也有约束。模型目录里有一个 .download.lock,下载期间是独占锁;此时删除模型会被拒绝并返回 “A model download is in progress. Try again when it finishes.”。Windows 上更绕一层:加载模型时文件被 mmap,无法删除也无法替换,于是实现先把文件 rename 成带时间戳的 .set-aside,等下次启动再清扫(delete_set_aside)。如果你在 Windows 上看到 xxx.gguf.<timestamp>.set-aside,说明有一次删除被延后了,这属于正常回收机制。

网络层面必须区分三个不同的主机,它们的失败互不代表:

用途 主机 说明
App 下载与更新 anoma.ly 与模型下载完全独立
口述模型 huggingface.co 及其 CDN 默认英文模型实测会跳到 us.aws.cdn.hf.co
语音命令模型 download.moonshine.ai 可选功能,不装不影响口述

仓库甚至在 docs/downloads.md 里写下了这句提醒:“App download success does not establish model-host reachability.” 公司网络放行了 anoma.ly、却拦了 huggingface.co 的情况下,安装包能下、模型永远装不上,错误文案会点名 Hugging Face 并告诉你进度已保留可重试。这不是含糊的“网络错误”,是可直接转给 IT 的信息。

Hex 模型选择器在下载中的界面状态

坑五:你在授权的,可能不是你以为的那个 Hex

最后一个坑最隐蔽,因为它让前四个坑的排障全部失效:权限、日志、模型都正常,但你看的是另一份 Hex。

三种分身方式:

旧 Swift 版共存。 README 的迁移说明写得很直接:新 App 需要手动安装并重新完成设置,设置与历史不会迁移;“Quit the old app before dictating in the new one so their shortcuts do not compete.” 两个 App 抢同一个裸修饰键,表现就是其中一个永远没反应。

两套数据目录。 src/app_paths.rs 里,测试构建用 hex-test,正式版用 hex;HEX_APPLICATION_SUPPORT_DIR 又能整体覆盖。数据目录里放的是设置、模型、日志,以及 local-api.json——CLI 就是靠这个文件的 pid 和 token 找到正在运行的实例。如果 CLI 连的是另一份数据目录,hex status 的一切正常都毫无意义。

CLI 与 App 版本不一致。 控制协议带版本号,不匹配时的报错是“use the hex inside the running app or restart Hex”。用 Homebrew 装的最新 CLI 去驱动一个旧 App,命令会一直被拒。

对应的检查顺序很短:

which hex                       # CLI 到底是哪一个
ps aux | grep -i hex            # 有几个进程
hex status                      # 返回的 app_version / pid 是不是你正要用的那个

hex status 返回的 pid 与 app_version 是最省事的对齐手段。如果版本和你菜单栏里看到的不一致,直接换用 App 包内的二进制:/Applications/Hex.app/Contents/MacOS/hex。

一张排障顺序表

把上面五个坑压成一张表,按从上到下的顺序排除,比反复重装高效得多。

现象 先看什么 说明
按住快捷键完全无反应,但命令能用 热键层 被全局快捷键消费、被桌面拒绝、或与 Hex 其他绑定冲突
命令也不录音 hex status 的 permissions needs-settings 去系统设置,needs-restart 才重启
有录音动画但不粘贴 辅助功能 粘贴依赖同一份辅助功能授权
短按无反应、长按正常 shortcut_mode Hold 模式下 300 ms 内属 tap,本就会丢弃
说话中途碰了别的键就没反应 live.ndjson 的 discarded.reason key / hid-key / extra-modifier 都指向 chord 丢弃
显示已安装但转录不启动 hex model install is_installed 只比大小,损坏文件需要重新校验替换
一切正常但版本对不上 hex status 的 pid / app_version 两份 App、两套数据目录、或 CLI 版本过旧

日志位置也值得记一下(README.md):macOS 在 ~/Library/Application Support/hex/logs/,Windows 在 %APPDATA%\hex\logs\,Linux 在 ~/.local/share/hex/logs/(或 XDG_DATA_HOME 下)。hex logs 可以只读 live.ndjson 或 process.log,且不需要 Hex 正在运行——在“进程已经挂了”的场景里,这是唯一还能用的入口。

最后一句实话:这五个坑里,只有第四个是真意义上的“故障”,前三个更像是本地优先应用必须付出的代价——macOS 的权限按进程生效、全局快捷键是一个各方博弈的公共资源、裸修饰键在别的软件眼里就是一次普通单击。理解这些边界之后,“按了没反应”就不再是玄学,而是一条可以用 hex status、一条 hex dictation start、以及一份 discarded 日志逐段定位的链路。

登录后查看全文
hex