cjpais/Handy · 上手攻略

  • 仓库：cjpais/Handy
  • 链接：https://github.com/cjpais/Handy · 官网 https://handy.computer · 讨论 https://discord.com/invite/WVBeWsNXK4
  • 分类：ai（桌面语音转写 / 无障碍工具）
  • 作者：spark
  • 更新：2026-08-17

⚠️ 本稿涉及系统权限、键盘钩子、Wayland/X11 输入路径，命令与坑均以仓库 README 与 BUILD.md 抓取为准；Whisper 模型在 Windows / Linux 部分系统会 crash 的已知问题官方未给出受影响硬件清单，先按"自己机器先试小模型"建议执行。

1. 是什么

Handy 是一款完全离线、跨 Windows / macOS / Linux 的桌面语音转写应用——按一个全局快捷键开始录音，松开后把语音转成文字直接"粘贴"到你正在用的输入框里。它不联网、不发音频、不收费。

技术栈是 Tauri 桌面壳 + Rust 推理后端 + 前端 React/TypeScript；推理引擎可选：

  • Whisper（small / medium / turbo / large），有 GPU 加速时优先 GPU；
  • Parakeet V3，CPU 优化、自动语种检测、零额外配置；
  • 用到的底座是 transcribe-cpp（whisper.cpp 的 Rust 绑定，GGML/GGUF）与 transcribe-rs（Parakeet ONNX 路径）。

VAD（静音切除）用的是 Silero；输入工具链在 X11 上用 xdotool、Wayland 上用 wtype / dotool、macOS 上走系统原生 API。

2. 解决什么问题

无障碍与日常生产力：

  • 写代码、写邮件、写笔记时不想打字，按键说话直接落到文本框；
  • 在不联网 / 受限网络 / 隐私敏感环境做转写（医院、律所、内网）；
  • 当作"开源 fork-friendly"基座，做二次开发（README 直白说："it isn't trying to be the best speech-to-text app—it's trying to be the most forkable one"）。

它不是 Whisper 训练框架，也不是云端转写 API；它的目标只是"按一个键，粘贴文字到你光标所在位置"。

3. 快速安装

3.1 用户安装（推荐）

平台 命令
通用 从 https://github.com/cjpais/Handy/releases 拉最新的 .dmg / .msi / .deb / .rpm / .AppImage
macOS brew install --cask handy（⚠️ cask 不归 Handy 团队维护）
Windows winget install cjpais.Handy（⚠️ winget 包同样不归团队）
Linux .deb / .AppImage 双击；详见 README "Linux Notes"

3.2 启动流程

  1. 安装 → 启动 Handy；
  2. 第一次启动会请求：麦克风、辅助功能（macOS 隐私/可访问性、Linux 桌面键盘钩）；
  3. 在 Settings 里配好快捷键（默认通常是按住某个修饰键）；
  4. 把光标放在任意输入框 → 按键开始录 → 松开 → 文字粘贴进光标处。

3.3 命令行控制

已经运行的实例可以被命令行 flag 控制（"single-instance" 远程控制）：

handy --toggle-transcription     # 开始/停止录音
handy --toggle-post-process      # 带后处理
handy --cancel                   # 取消当前

handy --start-hidden             # 启动时不弹窗
handy --no-tray                  # 不要托盘图标
handy --debug                    # 调试日志
handy --help                     # 全部 flag

macOS 上二进制在 app bundle 深处：

/Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription

3.4 Raycast 集成

社区有 Raycast 扩展（README 提到 by @mattiacolombomc），可在 Raycast 里 toggle 录音、翻历史、换模型 / 语种、加字典。

4. 核心用法

4.1 最小可跑流程

# 1) 下载并装好 Handy（见 §3.1）
# 2) 首启授予麦克风 + Accessibility
# 3) Settings → 选择推理模型：Whisper small（最低门槛）或 Parakeet V3（CPU 友好）
# 4) 设置快捷键，比如按住 Right Ctrl
# 5) 任意文本框 → 按住快捷键 → 说话 → 松开 → 文字落进文本框

不联网、不注册账号、不上传音频——这就是 README 强调的 "four freedoms"：Free / Open Source / Private / Simple。

4.2 模型选择策略

场景 推荐模型 理由
无 GPU 的笔记本 Parakeet V3 CPU 优化、自动语种检测、不需要编译
有 NVIDIA/Metal GPU Whisper large-v3-turbo 或 large-v3 GPU 加速后识别精度与速度都更好
多语种混合（含普通话/粤语/小语种） Whisper large 覆盖最广，CPU 跑 small 也行但精度掉
严苛隐私 Parakeet V3（ONNX 路线，完全离线） 二进制体积小、依赖少

Whisper 模型量化格式是 GGML/GGUF，可换 ggml-tiny.bin / ggml-base.bin / ggml-large-v3-turbo.bin 等，对应磁盘、显存、速度取舍。

4.3 二次开发（开发者）

前置：Rust（rustup）、Bun、Tauri prerequisites（仓库 BUILD.md 列得很清楚）。

git clone https://github.com/cjpais/Handy.git
cd Handy
bun install
bun tauri dev            # 开发态
bun run tauri build      # 打 release bundle

平台特殊点：

  • Intel Mac：没有官方 ONNX Runtime 预编译包，要 Homebrew 装 onnxruntime 并用动态链接： bash brew install onnxruntime ORT_LIB_LOCATION=$(brew --prefix onnxruntime)/lib \ ORT_PREFER_DYNAMIC_LINK=1 bun run tauri build
  • Windows：需要 Visual Studio 2019/2022 C++ 工具链 + CMake + Vulkan SDK（编译 vulkan-shaders-gen 要 glslc 头文件）。
  • Linux： bash # Ubuntu / Debian sudo apt update 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

构建产物带平台原生 bundle（.deb / .rpm / .AppImage / .dmg / .msi）。

5. 典型适用场景

  • 开发者语音写代码注释 / commit message / PR 描述：在 IDE 里按热键说话直接落字，Whisper large-v3-turbo 配 RTX 卡延迟可控。
  • 记者 / 律师 / 医生做访谈/问诊内录：本地模型落到本地磁盘，不上过云服务，合规友好。
  • 视障 / 运动障碍用户：与系统 Accessibility 配合，作为"免提输入法"。
  • AI 应用基座：把 Handy 当成"任意时刻拉起 + 把文字塞回当前 focus" 的本地 hook，自己写 plugin。

6. 坑与注意

  • Whisper 在某些 Windows/Linux 配置会 crash：README 显式列出，且"问题与系统配置强相关"——遇到先去 Discord 拉 debug 日志再发 issue。规避：先试 Parakeet V3 或 Whisper small。
  • Wayland 输入 = 必须装 wtype / dotool：单纯 xdotool 在 Wayland 上没用。Ubuntu 26.04 默认 Wayland 时尤其注意——README 指向 PR #557 的方案（装 ydotool + systemd 配置）。
  • WebKit / GTK layer shell 运行时缺失：Linux 启动报 libgtk-layer-shell.so.0 就是缺包：apt install libgtk-layer-shell0（Fedora gtk-layer-shell，Arch 同名）。
  • Wayland 模式下全局快捷键受限：Wayland 不允许任意应用注册系统级快捷键，必须在你的 DE（GNOME/KDE/Sway）里配；README 末尾有专门段落。
  • 录制浮层在 Linux 默认关掉：因为部分 compositor 会把它当 active window 抢焦点，导致粘贴丢目标窗口。如果你必须开，会出现"粘贴到错窗口"。
  • macOS 重签后 Accessibility 缓存残值：本地 dev build 用 ad-hoc sign，重装后 Settings 里"Handy 已授权"会卡住；README 给出 osascript ... quit + tccutil reset 流程清掉。
  • HOME 截断 + 260 字符路径：Windows 老问题，自 transcribe-cpp 0.1.3 起已自动绕过，但偶尔还遇到，看 Troubleshooting。
  • CLI flag 与 bundle 入口分离：/Applications/Handy.app/Contents/MacOS/Handy 不在 $PATH，脚本化要写绝对路径。

7. 与同类对比

维度 Handy Wispr Flow MacWhisper whisper.cpp（纯 CLI）
跨平台 ✅ Win/Mac/Linux macOS 主打 macOS ✅ 命令行
完全离线 ✅ ❌ 付费版混合云 ✅ ✅
开源可 fork ✅（MIT） ❌ ❌ ✅
焦点粘贴 ✅ ✅ ✅ ❌（要自己写）
多引擎（Whisper + Parakeet） ✅ ❌ ❌ ❌
内置 VAD（Silero） ✅ n/a n/a 插件
MCP / 二次扩展点 Tauri + Rust，前后端都可 fork ❌ ❌ 库

如果想要"现成的商业免提输入体验 + 云端精度"选 Wispr Flow；想要"开源 + 跨平台 + 自己 fork"选 Handy；只想跑批转写脚本选 whisper.cpp。

8. 一句话推荐

Handy 是当前开源跨平台语音转写到当前输入框里最"装上就能用"的项目，技术栈 Tauri/Rust/Whisper/Parakeet 上手顺；但 Windows/Linux 的 Wayland + 模型崩溃 + 音频后端坑一定要先扫一遍再上生产。

来源

  • README：https://github.com/cjpais/Handy（web_fetch, 2026-08-17）
  • BUILD.md：https://github.com/cjpais/Handy/blob/main/BUILD.md（web_fetch, 2026-08-17）
  • 模型与 Raycast 集成说明均来自 README 段落

⚠️ Wayland 输入路径以 README "Linux Notes" 段落为准；Ubuntu 26.04 的 ydotool 流程引自 PR #557 评论；Whisper 崩溃影响范围未在 README 中给出明确清单，按"自己机器先试小模型"兜底。