VoiceInk 自定义命令：把听写的文字交给脚本，而不是粘贴出来

作者 · 发布于

Custom Command（自定义命令）是 VoiceInk 的输出模式之一。VoiceInk 不再粘贴，而是把听写完成的文字交给你写的 shell 命令，由这条命令决定接下来做什么：追加到一份笔记、打开搜索、调用你自己的脚本，或者发送到你运行的某个服务。这是 VoiceInk 处理文字时最灵活的功能，在动手搭建之前，有几个硬性限制值得先了解。

我做了 YapToText，一款不同的 Mac 听写 App，所以请带着这一点来看我对 VoiceInk 的说法。这里关于 VoiceInk 的每一个事实，都来自它自己的文档，我在2026年10月10日读过。

在 Mac App Store 下载 YapToText免费下载。无需账号，没有锁定的功能。需要搭载 Apple 芯片的 Mac 和 macOS 14 或更高版本。 源代码在 GitHub 上。

用其他语言阅读： English, العربية, Čeština, Dansk, Deutsch, Ελληνικά, Español, Suomi, Français, עברית, हिन्दी, Magyar, Bahasa Indonesia, Italiano, 日本語, 한국어, Norsk, Nederlands, Polski, Português, Română, Русский, Slovenčina, Svenska, ไทย, Türkçe, Українська, Tiếng Việt, 繁體中文

命令会收到什么

VoiceInk 会用两种方式发送同一份最终文字：通过标准输入，以及放在变量 $VOICEINK_TRANSCRIPT 里。文字是 UTF-8 编码，文档要求给这个变量加上引号，这样空格、标点和换行才能保留下来。

  • AI Enhancement 关闭。经过 VoiceInk 的格式整理和词语替换之后的转写文字。
  • AI Enhancement 打开且运行正常。增强之后的文字。
  • AI Enhancement 被跳过或失败。没有加工的最终转写文字。

命令不会直接拿到音频、提示词，也拿不到选中的文字、剪贴板文字或屏幕文字。如果你想让上下文影响结果，文档的说法是使用提示词和 Context Awareness（上下文感知），这样它们已经包含在最终文字里了。

它是怎么运行的

出自 VoiceInk 的文档 Custom Commands，2026年10月10日查阅。

细节行为
Shell/bin/zsh -lc
超时10 秒，之后 VoiceInk 会终止这条命令
权限与 VoiceInk 相同的 macOS 用户权限
录音窗口在命令开始之前关闭
成功退出码为 0。其他情况都算失败
输出标准输出和错误信息会保留下来用于诊断，不会粘贴到 App 里
找不到命令VoiceInk 会尝试你的 shell PATH。如果失败，就用完整路径，例如 /opt/homebrew/bin/tool

容易踩到的限制

  • 不会替你粘贴。如果你还想让文字出现在 App 里，命令自己要负责复制或粘贴。
  • 只有十秒，不会提问。命令不能等待输入。要做更长时间的事，就自己启动一个后台进程，然后尽快退出。
  • 它不会改动保存的转写文字。命令打印出来的内容不会写回去。
  • 没有 Auto Send。Auto Send 只对 Paste output 有效，对 Custom Command 无效。
  • 只对实时听写有效。Transcribe file 队列里的文件会直接保存，不会运行输出命令。
  • 不能是空命令。命令为空的 Mode（模式）无法保存。

内置的模板

出自 VoiceInk 的文档 Custom Commands，2026年10月10日查阅。

模板它做什么
Paste and Press Tab复制文字，粘贴，然后按下 Tab 键
Lowercase and Paste把文字转成小写，复制，然后粘贴
Remove Trailing Period and Paste粘贴之前去掉最后的一个句号
Append to Journal把文字添加到 ~/Documents/VoiceInk/journal.md
Search Web用这段文字打开一次网页搜索

文档建议从一个模板开始，再去修改它。下面是他们最简单的两个例子：复制文字，以及把文字追加到一份笔记里：

printf "%s" "$VOICEINK_TRANSCRIPT" | pbcopy
mkdir -p "$HOME/Documents/VoiceInk"
printf -- "- %s\n" "$VOICEINK_TRANSCRIPT" >> "$HOME/Documents/VoiceInk/notes.md"

怎么确认它运行成功了

Custom Command 运行之后，VoiceInk 不会显示成功或失败的提示。文档给了一条 Terminal 命令，可以显示最近 10 分钟的投递日志，包括命令是成功了、失败了，还是运行超过了 10 秒：

/usr/bin/log show --last 10m --style compact \
  --predicate 'subsystem == "com.prakashjoshipax.voiceink" AND category == "TranscriptionDelivery"'

文档提醒，这些日志里可能包含你听写的文字。另外，如果你的命令把文字发送给某个网络服务，那个服务就会收到它：VoiceInk 只负责运行你配置好的内容。

YapToText 的情况

VoiceInk 的内容出自它的文档，2026年10月10日查阅。YapToText 的内容出自它自己的设置。

VoiceInkYapToText
带着文字运行 shell 命令可以，用 Custom Command 输出不可以
在光标处粘贴Paste outputPaste，默认选项
改成逐字输入这一页没有说明Type character by character
只放进剪贴板用 pbcopy 这样的命令Copy to clipboard only
之后按一个键Paste and Press Tab 模板每个 App 可选 Return 或 Command Return
插入之前先检查这一页没有说明Review before inserting，默认关闭

如果你想让听写驱动你自己的脚本，VoiceInk 的 Custom Command 能做 YapToText 做不到的事。如果你想让文字出现在光标处，并且配合周围的文字，YapToText 默认就是这样，不需要任何脚本。VoiceInk 模式页面讲了输出模式在哪里设置，VoiceInk 对比 superwhisper则拿它和另一款围绕模式设计的 App 做了比较。

在 Mac App Store 下载 YapToText免费下载。无需账号，没有锁定的功能。需要搭载 Apple 芯片的 Mac 和 macOS 14 或更高版本。 源代码在 GitHub 上。

小结

  • 它是什么。一种输出模式，用最终文字运行你的 shell 命令。
  • 文字。通过标准输入，以及在 $VOICEINK_TRANSCRIPT 里。
  • 限制。10 秒，没有输入，不会自动粘贴，只对实时听写有效。
  • 调试。App 里没有提示。用上面的 Terminal 命令读日志。
  • 从哪里开始。修改五个模板中的一个。

如果 VoiceInk 改了 Custom Commands 的工作方式，请在 GitHub 上提交 issue，我会更新这个页面。每一条我都会看。

在 Mac App Store 下载 YapToText免费下载。无需账号，没有锁定的功能。需要搭载 Apple 芯片的 Mac 和 macOS 14 或更高版本。 源代码在 GitHub 上。

关于作者。 Ryleigh Newman 从事软件开发，用手打字有困难，每天都用本站介绍的 YapToText 听写。本页译自英文。App 的界面和网站的其他页面是英文的。 进一步了解这个项目（英文）。

指南

更多指南（英文）

资料来源

常见问题

VoiceInk 的 Custom Command 是什么？

它是一种输出模式。VoiceInk 不再粘贴，而是运行你写的 shell 命令，并把听写的最终文字交给它。

VoiceInk 的 Custom Command 怎么拿到文字？

通过标准输入，以及变量 $VOICEINK_TRANSCRIPT，编码为 UTF-8。给变量加上引号，才能保留空格和换行。

为什么我的 VoiceInk Custom Command 什么都没粘贴？

Custom Command 输出不会自己粘贴。你的命令要自己复制或粘贴文字，就像 Paste and Press Tab 模板那样。

VoiceInk 的 Custom Command 最长能运行多久？

10 秒。超过之后 VoiceInk 会终止它。要做更长时间的事，就启动一个后台进程。

YapToText 有像 VoiceInk 那样的自定义命令吗？

听写之后它不会运行 shell 命令。它在光标处粘贴或逐字输入，也可以只复制到剪贴板，还可以在文字出现之后按下 Return。