macOS 配套应用
语音唤醒（macOS）
语音唤醒与按键通话
模式
- 唤醒词模式（默认）：始终开启的 Speech 识别器会等待触发词（
swabbleTriggerWords）。匹配后开始采集，显示带有部分文本的浮层，并在静音后自动发送。 - 按键通话（按住右 Option 键）：按住右 Option 键即可立即采集，无需触发词。按住时会显示浮层；松开后会完成采集，并在短暂延迟后转发，方便你微调文本。
运行时行为（唤醒词）
- Speech 识别器位于
VoiceWakeRuntime。 - 只有在唤醒词和下一个词之间存在有意义的停顿（约 0.55 秒间隔）时才会触发。即使命令尚未开始，浮层/提示音也可以在停顿时启动。
- 静音窗口：语音连续输入时为 2.0 秒；如果只听到触发词，则为 5.0 秒。
- 硬停止：120 秒，用于防止失控会话。
- 会话之间的防抖：350 毫秒。
- 浮层通过
VoiceWakeOverlayController驱动，并使用已提交/易变着色。 - 发送后，识别器会干净地重启，以监听下一个触发词。
生命周期不变量
- 如果语音唤醒已启用且权限已授予，唤醒词识别器应处于监听状态（显式按键通话采集期间除外）。
- 浮层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。
粘滞浮层故障模式（以前）
以前，如果浮层卡住并保持可见，而你手动关闭了它，语音唤醒可能会看起来“失效”，因为运行时的重启尝试可能会被浮层可见性阻塞，并且不会安排后续重启。
加固：
- 唤醒运行时重启不再被浮层可见性阻塞。
- 浮层关闭完成后会通过
VoiceSessionCoordinator触发VoiceWakeRuntime.refresh(...)，因此手动点击 X 关闭始终会恢复监听。
按键通话细节
- 热键检测使用全局
.flagsChanged监视器监听右 Option（keyCode 61+.option）。我们只观察事件（不吞掉事件）。 - 采集管线位于
VoicePushToTalk：立即启动 Speech，将部分结果流式传输到浮层，并在松开时调用VoiceWakeForwarder。 - 按键通话开始时，我们会暂停唤醒词运行时，以避免音频 tap 相互竞争；松开后它会自动重启。
- 权限：需要麦克风 + Speech；看到事件需要辅助功能/输入监控批准。
- 外接键盘：某些键盘可能不会按预期暴露右 Option，如果用户报告漏检，请提供备用快捷键。
面向用户的设置
- 语音唤醒开关：启用唤醒词运行时。
- 按住 Cmd+Fn 说话：启用按键通话监视器。在 macOS < 26 上禁用。
- 语言和麦克风选择器、实时电平表、触发词表、测试器（仅本地；不会转发）。
- 麦克风选择器会在设备断开连接时保留上次选择，显示断开连接提示，并临时回退到系统默认设备，直到该设备恢复。
- 声音：在检测到触发词和发送时播放提示音；默认使用 macOS “Glass” 系统声音。你可以为每个事件选择任何可由
NSSound加载的文件（例如 MP3/WAV/AIFF），也可以选择无声音。
转发行为
- 启用语音唤醒后，转录文本会转发到活动的 Gateway 网关/智能体（使用与 Mac 应用其余部分相同的本地与远程模式）。
- 回复会投递到上次使用的主提供商（WhatsApp/Telegram/Discord/WebChat）。如果投递失败，错误会被记录，并且运行仍可通过 WebChat/会话日志查看。
转发载荷
VoiceWakeForwarder.prefixedTranscript(_:)会在发送前添加机器提示。唤醒词路径和按键通话路径共享该逻辑。
快速验证
- 打开按键通话，按住 Cmd+Fn，说话，然后松开：浮层应显示部分结果，然后发送。
- 按住期间，菜单栏耳朵图标应保持放大（使用
triggerVoiceEars(ttl:nil)）；松开后它们会恢复。