---
read_when:
    - 处理语音唤醒或按住说话路径
summary: mac 应用中的语音唤醒与按住说话模式，以及路由细节
title: 语音唤醒（macOS）
x-i18n:
    generated_at: "2026-04-23T20:56:07Z"
    model: gpt-5.4
    provider: openai
    source_hash: b49077200b34102e4d75d214249115450cbc690d13fc12c2979d87d6fae36f45
    source_path: platforms/mac/voicewake.md
    workflow: 15
---

# 语音唤醒与按住说话

## 模式

- **唤醒词模式**（默认）：始终开启的语音识别器会等待触发词（`swabbleTriggerWords`）。匹配后，它会开始采集，显示带有部分转录文本的悬浮层，并在静音后自动发送。
- **按住说话（按住右侧 Option 键）**：按住右侧 Option 键即可立即开始采集——无需触发词。按住期间会显示悬浮层；松开后会完成并转发，且会有一个短暂延迟，以便你微调文本。

## 运行时行为（唤醒词）

- 语音识别器位于 `VoiceWakeRuntime` 中。
- 只有当唤醒词与下一个词之间存在**明显停顿**时，触发才会生效（大约 0.55 秒间隔）。悬浮层/提示音可以在这个停顿点开始，即使命令本身还未开始。
- 静音窗口：当语音持续流动时为 2.0 秒；如果只听到了触发词，则为 5.0 秒。
- 硬停止：120 秒，用于防止会话失控。
- 会话之间的防抖：350 毫秒。
- 悬浮层由 `VoiceWakeOverlayController` 驱动，并使用已提交/易失着色。
- 发送后，识别器会干净地重启，以监听下一个触发词。

## 生命周期不变量

- 如果启用了语音唤醒且已授予权限，则唤醒词识别器应处于监听状态（除显式的按住说话采集期间外）。
- 悬浮层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复运行。

## 粘滞悬浮层故障模式（之前）

此前，如果悬浮层卡住并保持可见，而你手动将其关闭，语音唤醒可能会表现得像“失效”了一样，因为运行时的重启尝试可能被悬浮层可见性阻止，而且之后也不会再安排新的重启。

加固措施：

- 唤醒运行时的重启不再受悬浮层可见性阻塞。
- 悬浮层关闭完成后，会通过 `VoiceSessionCoordinator` 触发 `VoiceWakeRuntime.refresh(...)`，因此手动点击 X 关闭后总会恢复监听。

## 按住说话细节

- 热键检测使用针对**右侧 Option** 的全局 `.flagsChanged` 监视器（`keyCode 61` + `.option`）。我们只观察事件（不吞掉事件）。
- 采集管线位于 `VoicePushToTalk`：立即启动语音识别，将部分结果流式传输到悬浮层，并在松开时调用 `VoiceWakeForwarder`。
- 当按住说话开始时，我们会暂停唤醒词运行时，以避免音频 tap 相互冲突；松开后会自动重启。
- 权限：需要麦克风 + 语音识别；要看到事件，还需要授予辅助功能/Input Monitoring 权限。
- 外接键盘：某些键盘可能不会按预期暴露右侧 Option——如果用户反馈漏检，请提供备用快捷键。

## 面向用户的设置

- **语音唤醒** 开关：启用唤醒词运行时。
- **按住 Cmd+Fn 说话**：启用按住说话监视器。在 macOS < 26 上禁用。
- 语言和麦克风选择器、实时电平表、触发词表、测试器（仅本地；不会转发）。
- 麦克风选择器会在设备断开后保留上次选择，显示断开提示，并在设备恢复前临时回退到系统默认设备。
- **声音**：在检测到触发词和发送时播放提示音；默认使用 macOS “Glass” 系统声音。你可以为每个事件选择任意可由 `NSSound` 加载的文件（例如 MP3/WAV/AIFF），或选择 **No Sound**。

## 转发行为

- 启用语音唤醒后，转录文本会被转发到当前活动的 gateway/智能体（与 mac 应用其余部分使用的本地/远程模式相同）。
- 回复会投递到**最近使用的主 provider**（WhatsApp/Telegram/Discord/WebChat）。如果投递失败，会记录错误日志，但该次运行仍可通过 WebChat/会话日志查看。

## 转发负载

- `VoiceWakeForwarder.prefixedTranscript(_:)` 会在发送前添加机器提示前缀。该逻辑由唤醒词和按住说话路径共享。

## 快速验证

- 打开按住说话，按住 Cmd+Fn，开始说话，然后松开：悬浮层应显示部分转录文本，然后发送。
- 在按住期间，菜单栏耳朵应保持放大状态（使用 `triggerVoiceEars(ttl:nil)`）；松开后恢复。
