语音口述输入
给 Agent 下指令写的是自然语言，而自然语言说比打快——在手机上尤其如此。在任何已附着的 Agent 会话里，开口说，转写结果就像你亲手敲进终端一样落进去。
把语音变成文字有两条路，按服务记录逐条选择：
- 在本机完成，用 Apple 的语音识别。不用账号、不用 API key，音频从头到尾不出设备——连 Apple 也拿不到。
- 交给你自带的服务，用你自己的 API key。音频从你的设备直达该服务，绝不经过我们。SigilTTY 不运营自己的语音服务。
麦克风在哪里
Section titled “麦克风在哪里”- iPhone 与 iPad——键盘附件条上的麦克风键，在回形针（上传）键左边。它只在已附着的 Agent 会话里出现，跟着键盘走，就在你打字的地方。（1.6.2 之前它是终端右下角的悬浮按钮。）
- Mac——终端右下角的悬浮麦克风按钮。
这个键只负责开始；结束录音由随后浮出的录音条负责（见口述）。录音条在场期间点麦克风不会有任何反应——这样就不可能在上一段还在转写时又开出第二段。会话已结束、或正在进行 ZMODEM 传输时，麦克风同样不响应。
若此时还没有配置任何服务，浮条会直接把问题摆出来——「尚未配置转写服务。要设置 Apple 本机模型或第三方服务吗？」——带一枚 Set Up…（去设置…）按钮，一点直达。
进入 Settings › Voice Input，点 Add Service，选 Apple Speech (On-Device)——列表第一项，也是唯一一个没有东西要填的。没有 API key，没有 Base URL，唯一要紧的设置是 Language。
Apple 的识别器一次只认一种语言，没有 Auto。编辑器默认取你设备的语言，你也可以从列表里另选（中文、英文、日文、韩文、粤语、繁体中文），或在 Custom… 里填任意 BCP-47 语言码，例如 de-DE。
语言下面有一行状态，告诉你这台设备到底跑不跑得动它：
| 状态 | 含义 |
|---|---|
| 正在检查本机可用性… | 探测进行中，稍候即出结果。 |
| 已可在本机转写 | 无需再做任何事。 |
| 下载语言模型 | 该语言受支持，但模型还不在设备上。点一下下载，带进度条，只需一次。 |
| 模型正在下载中… | 已有下载在进行——包括系统别处发起的那一次。 |
| 一句橙色提示 | 这台设备上两条路都跑不了该语言，见排障。 |
**SigilTTY 绝不会在口述途中下载模型。**模型动辄数百 MB，而你可能正在用蜂窝网络，所以下载被放在这里、放在服务的设置里，由你决定什么时候发生。
具体跑哪个引擎取决于设备：iOS 26 与 macOS 26 用 Apple 较新的语音模型，也就是上面那次显式下载；更早的系统——以及少数用不了新模型的设备——走系统听写识别器，而 SigilTTY 把它钉死在端侧识别上：某个语言无法在本地完成时，口述会明确报错，而不是悄悄把你的音频发去 Apple 的服务器。因此识别质量随设备与系统版本而异。
配置第三方服务
Section titled “配置第三方服务”同一个 Add Service 菜单里，预置模板覆盖 OpenAI、Groq、SiliconFlow、Volcengine (Doubao) 与 iFlytek (讯飞听写)，还有 Custom… 对接任意其他端点。服务记录的类型创建后即固定，其余字段随时可改。
远端服务分三类：
- OpenAI 兼容——一个 HTTPS 转写端点。填 API key、选模型（也可自行输入），非 OpenAI 的服务（如 Groq、SiliconFlow）再配上 Base URL。录音结束后整段发送。
- Volcengine (Doubao)——边说边经 WSS 流式上传，停下后几乎立刻返回转写。选择 Resource（豆包 2.0 或 1.0，按时长或按并发计费），并可调节 Number Formatting、Punctuation 与 Remove Filler Words 三个开关。去除语气词会改写你说的话，因此默认关闭。
- iFlytek (讯飞听写)——同为流式，用讯飞控制台的 App ID、API Key 和 API Secret 配置。单次录音到 55 秒为止，因为讯飞单个会话不得超过 60 秒。
每条记录都有自己的 Language 设置。OpenAI 兼容与火山引擎提供 Auto 以及中文、英文、日文、韩文和粤语（另有自定义入口）；讯飞提供中文和英文，没有 Auto。
你可以同时保留多条记录——比如 iPhone 上用 Apple 端侧模型应付没网的场合、Mac 上用 OpenAI。记录（连同 key）会随凭据同步经 iCloud 钥匙串流转，但选中哪条是每台设备自己的事——各设备按自己的网络环境和用途各选各的。
点击麦克风，终端底部浮出录音条，带实时波形：「停顿时自动转写」。正常说话即可。只要你已经开了口（约三分之一秒以上的语音），停顿 1.8 秒录音就自动收尾并送去转写——开口前的思考停顿永远不会触发它。也可以随时按 Done 主动结束，或按 Cancel 丢弃。单次录音上限 120 秒（讯飞为 55 秒）。
转写文本如同你亲手键入一般插入终端——仅此而已：
- 换行会折成空格、首尾空白会去掉，转写里混进的换行符不可能把半句话提前发出去。
- **它永远不会替你按回车。**你先读一遍、改掉听错的地方，再自己发送。语音管线不应该在你的眼睛没看到文本之前就能指挥 Agent。
- 空转写什么也不插入，只给一条简短提示。会话在转写途中结束、或有文件传输启动时同样如此。
Settings › Voice Input 里有一个 Test 区：录一小段试音，交给当前选中的服务转写，展示转写文本和往返耗时。测试不留任何痕迹。
这也是把「配置问题」和「会话问题」分开的最快办法——在 Test 里失败的服务，在终端里同样会失败；在 Test 里正常，问题就收缩到了那个会话上。
失败会显示在同一条底部浮条上，消息旁边带 Retry。录音会一直留在内存里直到你关掉浮条，所以重试转写的是你刚才已经说过的那段话，不需要重说一遍。全程不落盘。
下面引用的都是中文界面里的原话。设置路径本文按界面英文原名写作 Settings › Voice Input，在中文界面里它显示为「设置 › 语音输入」。
口述要用到两个彼此独立的权限，其中第二个只有端侧转写这条路才需要。
| 提示 | 怎么办 |
|---|---|
| SigilTTY 的麦克风权限已关闭 | 点浮条上的 打开设置。在 iPhone 与 iPad 上会直接打开 SigilTTY 在系统设置里的那一页；Mac 上打开「系统设置 › 隐私与安全性 › 麦克风」。 |
| SigilTTY 的语音识别权限已关闭 — 请在系统设置中开启 | 同样是 打开设置（Mac 为「隐私与安全性 › 语音识别」）。这个权限是在录完之后、转写时才被拒的，音频还押着——授权回来点 Retry，转写的就是刚才那段话。 |
端侧转写的报错
Section titled “端侧转写的报错”| 提示 | 原因与处置 |
|---|---|
| 该语言的本机模型尚未下载 — 请在「设置 › 语音输入」的服务设置中下载 | 新模型支持该语言，但模型没装在设备上。进 Settings › Voice Input，打开那条记录，点 下载语言模型。这一步有意不自动进行，理由见上文。 |
| 该语言的本机识别尚未就绪 — 请在系统键盘设置中将其添加为听写语言 | 当前走的是旧路径，而系统里没有该语言的本地听写模型。iPhone 与 iPad：设置 › 通用 › 键盘 › 听写，打开听写并添加该语言；Mac：系统设置 › 键盘 › 听写，在语言里添加。回到那条记录，状态行应变成已可在本机转写。 |
| 此设备不支持该语言的本机语音识别 | 这台设备根本不认识该语言码。若你填的是 Custom… 自定义码，先检查格式——它是 BCP-47，应写 zh-CN，而不是 zh_cn 或 zh-cn-hans。否则请从列表里选一个语言，或该语言改用第三方服务。 |
| 端侧记录上出现 Transcription failed (code …) | 系统识别器抛出的意外错误，代码原样透传。先重试；反复出现就回头检查语言那一行，以及模型是否真的下载完成。 |
关于模拟器：新模型在模拟器上不可用，它一定会回退到旧识别器。识别质量请以真机为准。
什么都没转写出来
Section titled “什么都没转写出来”浮条提示转写为空，说明这段录音里没有可识别的语音。检查一下是不是走了预期之外的麦克风（连着的耳机，或 Mac 上的外接麦克风）、人是不是离得太远，以及记录里的语言和你实际说的话对不对得上——一条中文记录拿英文句子是转不出什么的。
第三方服务的报错
Section titled “第三方服务的报错”| 提示 | 原因与处置 |
|---|---|
| 没有转写服务 — 请在「设置 › 语音输入」中添加 | 选中的那条记录在转写途中消失了（通常是你说话时被另一台设备删掉了）。进 Settings › Voice Input 重新选一条或新建一条。 |
| 转写服务拒绝了该 API Key | HTTP 401/403。核对 key 本身，以及它是否属于 Base URL 指向的那个服务商。讯飞的 403 多数并不是 key 填错，而是设备时钟偏差超过 5 分钟，或者控制台上开了 IP 白名单；服务商自己的说明会接在破折号后面，务必读一读。 |
| Transcription failed (HTTP 404) | 端点或模型名不对。非 OpenAI 的服务商往往要求 Base URL 保留路径前缀——Groq 的是 https://api.groq.com/openai。 |
| Transcription failed (HTTP 429) 或 5xx | 服务商侧限流或故障。直接点 Retry——录音还在内存里。 |
| Transcription failed (code …) | 流式服务在 WebSocket 内部回报的服务商代码，不是 HTTP 状态码。这个数字属于服务商，请查它们自己的文档：火山引擎 45000001 是参数错误、55000031 是服务繁忙；讯飞 10165 通常是会话状态非法、10114 是会话超时。 |
| 转写服务返回了无法解析的响应 | 端点返回的东西根本不是转写结果——最常见的是 Base URL 指到了错误的路径，或者真实服务前面挡着一层网关/代理页面。 |
| 一条网络错误（超时、找不到主机……） | 来自系统的原文。检查网络连通性；另外记住火山引擎与讯飞走的是 WSS 而不是 HTTPS，只处理 HTTP 的代理在这里会失败。 |
转写停在半句话
Section titled “转写停在半句话”几乎总是流式服务商提前关闭了会话。讯飞单个会话不得超过 60 秒，SigilTTY 因此在 55 秒停止录音，长段口述会在那里被截断。改成分几段短一点说，或者换用 OpenAI 兼容记录或端侧记录——这两者都没有这个限制。
转写完成了，但终端里什么都没出现
Section titled “转写完成了，但终端里什么都没出现”有三种情况会让一段已完成的转写不被插入，每一种都会给出简短提示：转写为空；转写途中会话结束了；转写途中启动了文件传输。后两种情况下文本会被丢弃，而不是敲进一个不该去的地方。
失败会记入日志中心的 App 类别，并附上错误消息——偶发性故障靠它才查得清，也正是支持请求里该附上的东西。转写文本、音频和 API key 根本无法写入日志。
若某条记录显示为 Needs a newer version of SigilTTY，说明它是另一台设备上更新版本的 app 创建的。它会显示出来，但既不能选中也不能编辑；请升级这台设备上的 app，或者在这里另建一条。
- **端侧记录不向任何地方发送任何东西。**音频与转写文本都留在设备上，而且 SigilTTY 把识别器钉死在本地处理上——跑不了就明确报错，绝不回退到 Apple 的服务器。
- 音频只存在于内存中，从不写入磁盘——任何平台上都没有需要清理的录音文件。
- 第三方记录的音频只发给你自己配置的服务，用你的 key 认证。SigilTTY 没有自己的语音服务器。
- 流式服务（火山引擎、讯飞）边说边上传；OpenAI 兼容服务在你停止后收到完整录音。
- 取消——或录音途中切换标签页、把 app 切到后台——音频即被丢弃。