Handy 语音转文字 安装与上手教程

教程一：Windows 安装 Handy 并装好识别模型

这篇教程面向第一次使用 Handy 的 Windows 用户。有一个前提要先说清楚：Handy 装完之后并不能立刻用。它本身不含识别模型，模型是单独分发的文件，需要放到指定目录里软件才认得。这一步在国内往往是最大的坎——官方模型源在境外，速度常年在几百 KB/s，几百 MB 的模型要下十几二十分钟，中途断流还得重来。下面会把这一步拆开讲清楚，照着做可以绕开这个坑。

第 1 步：准备好安装包和模型文件

回到首页下载区，点击「下载 Windows 版」，会直接跳转到夸克网盘分享页，登录后把整个文件夹转存到自己的网盘，再取回本地即可。网盘包里有两样东西：一是官方安装器，二是常用的识别模型文件——建议整包转存，省得后面回去补下模型。

第 2 步：运行安装器

双击安装器，Windows 可能弹出蓝色的 SmartScreen 窗口，提示「Windows 已保护你的电脑」。这是因为 Handy 没有购买商业代码签名证书，并不代表文件有问题——未签名的开源工具普遍如此。点击「更多信息」，再点击「仍要运行」即可继续。安装过程自动完成，默认装到当前用户目录，不需要手动选路径，完成后开始菜单和桌面会出现 Handy 图标。

第 3 步：把模型放进 models 目录（关键一步）

先别急着打开软件，模型要先归位。Handy 认的是应用数据目录下的 models 文件夹，Windows 上的默认位置是：

%APPDATA%\com.pais.handy\models

不用手敲路径：按 Win + R 打开运行框，粘贴 %APPDATA%\com.pais.handy 回车，就能直接进到那个目录；如果里面还没有 models 文件夹，自己新建一个（名字必须完全一致，全小写）。也可以先启动一次 Handy，在「关于」页找到「应用数据目录」，点旁边的「打开」跳过去。然后把模型文件放进 models：

• Whisper 系列的 .bin 文件和 Parakeet 的 .gguf 文件都是单文件，直接丢进 models 即可；
• 如果是压缩包形式的 Parakeet 模型，解压后把整个文件夹放进去，文件夹名必须保持原样；
• 所有模型文件名都不能改。Handy 是靠文件名识别模型的，改了名字它就认不出来。

第 4 步：选一个模型，放出第一句话

打开 Handy，首次启动会直接停在模型选择页，选中你要用的模型即可。之后想换模型，去左侧「模型」页随时切换。接着打开任意一个能打字的窗口（记事本就够），按住 Ctrl + Space 说一句话，松手后文字应该会出现在光标处。

第 5 步：把中文相关的设置调顺

几个值得花的设置，都在左侧导航里：

• 通用：转写快捷键默认是 Ctrl + Space，取消键是 Escape，都可以改。快捷键行为有「自动 / 按住 / 点按」三档——说一大段建议用点按，碎片化输入用按住更顺手。
• 高级：把「简繁转换」设成简体；打开「移除语气词」，「嗯、啊、那个」会被自动删掉；「自定义词汇」里加上常被识别错的专有名词，比如公司名和行业术语。
• 语言：默认是自动检测，中英混说时会按当前语言判断；如果结果跑偏，在通用页把语言固定成中文会更稳。

教程二：macOS 安装 Handy 与 Gatekeeper 放行

macOS 上多两道关：一是 Gatekeeper 拦截未公证应用，二是系统权限必须手动给。先确认两件事——系统版本为 macOS 11 及以上；芯片类型点左上角苹果菜单 →「关于本机」查看，看到 Apple M 系列芯片就选 Apple Silicon 版，看到 Intel 处理器就选 Intel 版。下错架构会直接打不开。

第 1 步：下载对应架构的安装包

在首页下载区点「下载 macOS 版」，跳转夸克分享页后下载 dmg。Apple Silicon 与 Intel 各有一个安装包，确认文件名里的架构与你的机器一致再继续。同时把网盘包里的模型文件一起取回本地。

第 2 步：拖入「应用程序」

双击 dmg，把 Handy 图标拖进旁边的 Applications 文件夹，等待拷贝完成。这是 macOS 应用的标准安装动作，不需要安装器。

第 3 步：绕过 Gatekeeper 拦截

首次双击打开时，大概率遇到两种提示之一：「无法打开，因为无法验证开发者」或「已损坏，无法打开」。前者可以先右键点击应用、选择「打开」再确认一次；如果提示「已损坏」，说明系统给文件打上了隔离标记，打开「终端」执行：

xattr -cr /Applications/Handy.app

执行后再双击即可正常启动。这一步只清除系统给文件打的隔离标记，不会改动应用本身——Handy 未做 Apple 公证，开源工具在 macOS 上普遍要走这一步。

第 4 步：给足两项系统权限

这一步容易被忽略，但缺一不可：

• 麦克风权限：不给就录不了音。「系统设置 → 隐私与安全性 → 麦克风」里勾上 Handy。
• 辅助功能权限：Handy 靠它把识别结果「敲」进其它应用。不授权的话，文字能被识别出来，但不会自动粘到你的文档里。「隐私与安全性 → 辅助功能」里添加 Handy 即可。

第 5 步：放模型并上手

macOS 的应用数据目录是：

~/Library/Application Support/com.pais.handy/models

同样在 Handy 的「关于」页可以看到完整路径并一键打开。把模型文件放进去（压缩包版的 Parakeet 解压后原样放入），重启 Handy，然后选中模型、按住 Ctrl + Space 开始说话。习惯了之后，写作、回消息、记会议纪要基本可以脱离键盘。

附：Linux 简要说明

Linux 用户按发行版选择包格式：通用性最强的是 AppImage（chmod +x 后直接运行）；Debian / Ubuntu 系可以安装 deb 包，随系统更新升级；其余发行版可用 rpm 或解压 tar.xz 运行。有一点要注意：Handy 的录音浮层依赖 gtk-layer-shell，多数发行版需要单独安装这个运行库，装完再启动，否则可能出现浮标空白或者启动即退出的情况。Wayland 环境下如果浮层显示异常，可以试着用 XWayland 兼容方式启动。

← 返回下载页 ｜ 查看常见问题