装完没反应:Handy 跨平台三个高频翻车点,说明文档不会明说

原创2026-11-02 10:45:501,916 阅读
文章标签:语音桌面应用本地部署人工智能跨平台

装完没反应:Handy 跨平台三个高频翻车点,说明文档不会明说

Handy 是 GitHub 上热度持续攀升的开源离线语音转文字桌面应用:Tauri + React 前端、Rust 后端,按住快捷键说话,松开后把识别出的文字自动打进当前焦点输入框,全程本地推理、不经过云端。社区里推荐它的文章很多,但翻 issue 区和排障文档会发现,绝大多数「装完没反应」的反馈并不出在语音识别本身——识别模型跑得飞快,真正卡住用户的是应用价值链上的三根「外部神经」:系统权限、合成按键注入、剪贴板时序。任何一环断了,表象都是同一个:按了快捷键,毫无反应。

这篇文章沿着仓库源码把这三个高频翻车点拆到底:macOS 的辅助功能授权顺序与 Secure Input 陷阱、桌面 Linux 的编译依赖与 Wayland 焦点抢占、以及无声音反馈与贴字失败的定位路径。每个结论都给出对应的源码位置或配置项,方便你自查时直接对照。

Handy 0.9.0 的流式录音覆盖层:说话时实时显示正在转写的文字

翻车点一:macOS 的辅助功能权限,授权顺序就是坑

引导流程为什么是「麦克风在前、辅助功能在后」

macOS 上 Handy 的引导流程(Onboarding)要求按顺序授予两个权限:先是 Microphone,再是 Accessibility。这不是随便排的——看前端逻辑 src/components/onboarding/screens/Permissions.tsx:

const rows = isMac
  ? (["microphone", "accessibility"] as const)
  : (["microphone"] as const);
const next = rows.find((r) => permissions[r] !== "granted");

rows 是一个有序数组,next 只取第一个未授权项,未轮到的那行按钮是 disabled 状态。也就是说界面会强制你先完成麦克风,再碰辅助功能。配套的 src/components/onboarding/usePermissions.ts 还处理了两个容易忽略的细节:

  • macOS 的麦克风授权只弹一次系统对话框,拒绝之后再点按钮,走的是 openMicrophonePrivacySettings(),直接打开系统设置页面,靠前端每秒轮询 checkMicrophonePermission() 检测你是否真的打开了开关;
  • 辅助功能授权成功的回调里,会立即调用 initializeEnigo() 和 initializeShortcuts() 完成输入注入与全局快捷键的初始化——顺序反了或者漏了,快捷键自然是「注册成功但永远不触发」。
const initializeAfterAccessibility = () =>
  Promise.all([
    commands.initializeEnigo(),
    commands.initializeShortcuts(),
  ]);

还有一个隐蔽的超时机制:如果授权后 15 秒内没检测到状态变化(WAITING_TIMEOUT_MS = 15_000),界面会重新把按钮交还给你。所以「卡在 Waiting 不动」多半是系统设置里那个开关你还没拨动,而不是应用坏了。

本地构建用户的特殊陷阱:TCC 里的「僵尸授权」

从源码构建的用户会踩一个发布版用户不会踩的坑,BUILD.md 里专门有一节:本地构建使用 ad-hoc 签名(signingIdentity: "-"),每次重新构建,Handy 的代码签名身份就变了。但系统设置里那条旧的 Accessibility 授权记录看起来依然是勾选状态——TCC 数据库按签名识别应用,旧记录对新构建的 bundle 已不生效,结果就是应用一直停在 Waiting...。修复命令在文档里写得很明白:

osascript -e 'tell application id "com.pais.handy" to quit' || true
tccutil reset Accessibility com.pais.handy
open /Applications/Handy.app

重置后重新授权即可。想确认是不是这个问题,可以对比新旧 bundle 的 designated requirements,ad-hoc 签名的 requirement 里含 cdhash,变了就说明旧授权必然覆盖不了新构建。

更阴的坑:Secure Input 让快捷键「静默死亡」

权限全部给齐之后,macOS 用户还会遇到一个更隐蔽的失效模式:某个进程开启了 Secure Input(密码输入框、Terminal 的 Secure Keyboard Entry、卡死的 loginwindow),此时 CGEventTap 收不到 KeyDown/KeyUp 事件,只收到 FlagsChanged。Handy 默认的 handy_keys 快捷键实现恰好是 tap-based,于是带具体按键的快捷键全部静默失效,纯修饰键的快捷键还能用——用户视角就是「快捷键突然没反应,重启应用也没用」。

后端在 src-tauri/src/secure_input.rs 里做了一整套防御:

  • 监控线程每秒轮询 IsSecureEventInputEnabled(),持续超过 3 秒(SUSTAIN_THRESHOLD)才判定为「卡住」,避免密码框临时获得焦点造成的误报;
  • 判定后把受影响的按键绑定通过 Carbon 通道影子注册(reconcile_fallback),Carbon 全局快捷键不受 Secure Input 影响;
  • 通过 ioreg 的 kCGSSessionSecureInputPID 尽力定位「凶手」进程并显示在 UI 上——src/components/SecureInputWarning.tsx 的黄色横幅会告诉你具体是哪个应用(比如 Terminal)在持有 Secure Input、影响了几个绑定;
  • 调试面板提供 run_keyboard_diagnostic():开一个 3–30 秒的短生命周期键盘监听,只统计 key_down/key_up/flags_changed 事件数量。如果你看到 flags_changed 正常、key_down 为零,基本就可以确诊是 Secure Input,而不是权限没给。

注意一个反直觉的事实:如果 Carbon 回退把所有绑定都无感覆盖了,横幅反而不会出现——项目团队的选择是「用户无感就保持沉默,只写日志」。所以「没看到警告但快捷键失灵」时,主动去调试面板跑一次键盘诊断是最快的路。

翻车点二:桌面 Linux 的编译依赖坑,以及 Wayland 的焦点暗箭

源码构建:依赖清单比你想的长

先看 BUILD.md 给 Ubuntu/Debian 的完整命令,感受一下这个项目的链接面有多宽:

sudo apt install build-essential clang libclang-dev libevdev-dev libasound2-dev \
  pkg-config libssl-dev libvulkan-dev vulkan-tools glslc spirv-headers \
  glslang-tools libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev \
  librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmake

Rust、Bun 之外还有 ALSA、Vulkan 工具链、GTK、WebKitGTK、AppIndicator、gtk-layer-shell。其中最容易漏的是 libgtk-layer-shell0:Handy 用 gtk-layer-shell 做录音覆盖层并在运行期链接它,缺失时表现为启动即崩或窗口永远不出现,而不是给出任何有意义的报错,README 专门把它列成 Linux 启动排障的第一步。

还有一个文档很少明说的约束:裸编译出的 src-tauri/target/release/handy 不能独立运行——它依赖 Tauri 资源文件(托盘图标、提示音、VAD 模型)按预期路径摆放。BUILD.md 给出的跨发行版安装法是解包 deb:

cd /tmp
ar x /path/to/Handy/src-tauri/target/release/bundle/deb/Handy_*_amd64.deb data.tar.gz
tar xzf data.tar.gz
sudo cp usr/bin/handy /usr/bin/
sudo cp -a usr/lib/. /usr/lib/

运行期库被放进应用私有的 /usr/lib/Handy/(写死在二进制的 rpath 里),所以不需要 ldconfig。

AppImage 在滚动发行版上的必摔之坑

在 Arch、CachyOS 这类滚动更新发行版上,bun run tauri build 走到打包阶段会报一个吞掉了真实错误信息的笼统报错:

Bundling Handy_*_amd64.AppImage
failed to bundle project `failed to run linuxdeploy`

根因是 linuxdeploy 自带的 strip 太旧,处理不了新工具链编译的系统库;而 Tauri 把 linuxdeploy 的真实输出吞了。BUILD.md 给了两个动作:手动运行 linuxdeploy 看真实错误,以及绕开它——

bun run tauri build -- --bundles deb

binary、deb、rpm 都能正常产出,只有 AppImage 这一步会失败,装 deb 解包即可。

默认 Ubuntu 26.04 + GNOME Wayland:三重修正

这才是 Linux 侧真正的「装完没反应」重灾区。仓库里有一份针对 Ubuntu 26.04.1 LTS + GNOME Wayland + Handy 0.9.8 实测的排障文档 docs/troubleshooting/ubuntu-26-04-gnome-wayland/README.md,结论是:wtype 在 GNOME 下根本不可用(Mutter 刻意不实现 zwp_virtual_keyboard_manager_v1),必须切到 ydotool(打字)+ handy_keys(快捷键),并且:

  1. 用户必须在 input 组,/dev/uinput 需要 root:input 0660,否则 ydotool 起不来:
echo "$XDG_SESSION_TYPE"      # 确认是 wayland
ls -l /dev/uinput
sudo usermod -aG input "$USER"   # 改完必须重新登录
  1. 启动 ydotool 用户服务并验证:
sudo apt install ydotool
systemctl --user start ydotool
ydotool type "HELLO FROM YDOTOOL"
  1. 修改设置文件。Handy 的设置存放在 ~/.local/share/com.pais.handy/settings_store.json(由 src-tauri/src/settings.rs 的 SETTINGS_STORE_PATH 决定),文档给出的是直接 sed 两个字段:
sed -i 's/"typing_tool": "auto"/"typing_tool": "ydotool"/' ~/.local/share/com.pais.handy/settings_store.json
sed -i 's/"keyboard_implementation": "tauri"/"keyboard_implementation": "handy_keys"/' ~/.local/share/com.pais.handy/settings_store.json

重启后日志里应出现 handy-keys manager thread started 与 handy-keys shortcuts initialized。typing_tool 与 keyboard_implementation 这两个字段在 src-tauri/src/settings.rs 里分别对应 TypingTool 枚举和 KeyboardImplementation 枚举,注意后者的编译期默认值:Linux 默认 Tauri,其他平台默认 HandyKeys——文档里那条 sed 正是把 Linux 的默认值扳过去。

  1. 把 Overlay 设为 None。这是最反直觉的一条:GNOME 下 overlay 是个普通窗口,会抢焦点,焦点一走,粘贴就落空。所以文档直接要求关掉它——这也解释了代码里的默认值:
fn default_overlay_style() -> OverlayStyle {
    // Linux hides the overlay by default; other platforms show the live overlay.
    #[cfg(target_os = "linux")]
    return OverlayStyle::None;
    #[cfg(not(target_os = "linux"))]
    return OverlayStyle::Live;
}
  1. 装 wl-clipboard。src-tauri/src/clipboard.rs 中,Wayland 下的剪贴板写入会优先探测 wl-copy(is_wl_copy_available()),装了才走它,否则回退到 Tauri clipboard 插件——在 Wayland 下后者往往写不进去,表现为「识别成功、历史里有文字、但输入框里什么都没有」。

  2. 非 QWERTY 布局要换 External Script。文档特别点名 bépo、Dvorak 布局:ydotool 发的是物理键码,内置粘贴法按 QWERTY 假设去按「V 键」,在你的布局上按到的可能是完全不同的字符;而 Shift+Insert 会在修饰键还被按住时发出去,直接乱码。解法是写个外部脚本,用你布局上真正能打出 v 的键码(bépo 是 KEY_U 22,Dvorak 是 KEY_DOT 52):

#!/bin/sh
printf '%s' "$1" | wl-copy
sleep 0.1
ydotool key 29:1 22:1 22:0 29:0

把 Paste Method 切成 External Script 并指向它。后端对应 PasteMethod::ExternalScript,走 src-tauri/src/clipboard.rs 的 paste_via_external_script(),文本作为单一参数传给脚本,且不捕获脚本的 stdio——注释里解释了原因:wl-copy 会 fork 一个继承管道 fd 的后台 selection 守护进程,捕获 stdio 会把调用挂死。

Handy 设置中的 Shortcut Behavior 选项:Auto(按住录音或点按切换)/ Hold / Toggle

翻车点三:无声音与贴字失败的定位路径

「没有声音」的第一嫌疑:声音反馈默认就是关的

很多用户的排障路径是「按住快捷键没声音 → 以为没在录音 → 以为应用没响应」。先说结论:Handy 的录音启停提示音(audio feedback)默认关闭,源码在 src-tauri/src/settings.rs:

fn default_audio_feedback() -> bool {
    false
}

设置面板对应 src/components/settings/AudioFeedback.tsx,开关绑定 audio_feedback 字段。开启后,提示音走 src-tauri/src/audio_feedback.rs:播放前读取 selected_output_device,指定设备找不到时 warn!("Device '{}' not found, using default device") 并回退系统默认设备——所以「换了声卡/拔了蓝牙耳机后没声音」时,先检查 Sound 区域里选定的输出设备是否还在,再调 audio_feedback_volume,或换 Marimba/Pop 主题、放自定义 wav。另外 README.md 的已知问题里提醒:macOS 上插蓝牙耳机录音时,蓝牙会切到双向音频,播放质量或音量可能瞬时下降,建议保持耳机为输出、在 Handy 里另选内置或外置麦克风作输入。

顺带一提,录音状态本来还有第二层确认:覆盖层。但如前文所述,Linux 默认把它关了,所以声音反馈在 Linux 上几乎是唯一的实时状态提示——这就解释了为什么 CSDN 的安装指南把「无声音」和「贴字失败」并列为两大高频问题:前者多半是开关没开,后者往下看。

贴字失败的时序学:固定延迟 vs 剪贴板回执

标准剪贴板粘贴的完整时序在 src-tauri/src/clipboard.rs 的 paste_via_clipboard() 里,四个动作:保存当前剪贴板 → 写入转写文本 → 睡 paste_delay_ms(默认 60ms)→ 发 Ctrl+V → 睡 paste_delay_after_ms(默认 60ms)→ 恢复原剪贴板。问题出在最后两步:粘贴按键只是被排队,目标应用什么时候真正读剪贴板取决于它自己的事件循环,系统一忙,恢复就可能发生在读取之前——用户拿到的是自己旧剪贴板里的内容,转写文本反而留在 Handy 历史里。

paste_tx/mod.rs 的文件头注释把这件事说得很透:

The paste keystroke is only enqueued at that point — the target application reads the clipboard whenever its event loop gets to it, so any fixed delay can lose the race and the user gets their old clipboard pasted back.

新版给的对策是「回执排序粘贴」(Reliable Paste,仍标 Beta,仅 macOS/Windows):不再按计时器恢复剪贴板,而是把转写文本发布成一个惰性承诺(Windows 用 delayed rendering 的 WM_RENDERFORMAT,macOS 用 declareTypes:owner: 的 owner 对象),等操作系统通知「确实有消费者读走了」再恢复。两个让回执可信的规则:只有粘贴按键注入之后的观察到的读取才算数——之前的读取是剪贴板管理器、杀软这类「闻风而动」的第三方;恢复还要求剪贴板所有权未变(序号/changeCount 一致),你中途复制了新东西,你的操作优先。参数上,最后一次读取后有 200ms 静默期(QUIET_PERIOD,覆盖 Chromium 那种「先探测再读」的双读行为),整体超时 8 秒(RESTORE_TIMEOUT),按键注入彻底失败则 500ms 快速收场(FAILED_INJECTION_TIMEOUT)。失败模式被刻意设计成「转写文本在剪贴板上多留一会儿」,绝不会是「旧内容被粘出去」。

开关藏在调试面板里(macOS Cmd+Shift+D / Windows/Linux Ctrl+Shift+D),前端 src/components/settings/debug/ReliablePaste.tsx 里也能看到平台门禁:非 macOS/Windows 直接不渲染这个开关。

一张定位决策表

现象 第一嫌疑 验证位置
快捷键完全无反应(macOS) 辅助功能未授权 / TCC 僵尸记录 / Secure Input 引导页轮询状态;tccutil reset Accessibility com.pais.handy;调试面板跑 run_keyboard_diagnostic,flags_changed 有数而 key_down 为零即 Secure Input
识别成功但输入框无字(Wayland) 打字工具缺失、overlay 抢焦点、无 wl-copy 日志中 Using ydotool for...;Overlay 设 None;sudo apt install wl-clipboard
非 QWERTY 布局贴字乱码 ydotool 按物理键码发 Ctrl+V 换 Paste Method = External Script(见 bépo/Dvorak 示例)
粘出来的是自己旧剪贴板 固定延迟丢失竞态 调试面板开 Reliable Paste (Beta)(macOS/Windows);否则调大 Paste Delay (After)
按住录音没声音 audio_feedback 默认 false / 输出设备失效 Sound 区域开关与输出设备选择;default_audio_feedback() -> false
Linux 启动即崩 libgtk-layer-shell0 缺失 README 排障首条;必要时 HANDY_NO_GTK_LAYER_SHELL=1 handy 兜底

小结:把「没反应」翻译成可验证的断点

这三个翻车点表面上都是「按了没反应」,实际上断点各不同:macOS 断在权限链(授权顺序、签名身份、Secure Input),Linux 断在依赖链与桌面环境契约(编译依赖、input 组、焦点模型、物理键码),跨平台共断在时序(剪贴板恢复竞态)和反馈通道(声音默认关闭)。

值得说的是,Handy 的仓库本身就是在持续把这些「文档不会明说」的东西显性化:secure_input.rs 的凶手进程定位、paste_tx 的回执机制、docs/troubleshooting/ 下按发行版+桌面环境命名的实测排障文档、src/components/settings/debug/ 一整套诊断面板(键盘诊断、日志目录、LiveLogViewer)。遇到疑难时,最省时间的动作永远是:Ctrl+Shift+D 打开调试菜单,找到日志目录,翻一眼带 [reliable-paste]、Using ydotool、SecureInput 前缀的行——那里记录的正是上面每一个断点的第一现场。

登录后查看全文
Handy