​

语音唤醒与按键通话

​

模式

• 唤醒词模式（默认）：常驻语音识别器等待触发词（swabbleTriggerWords）。匹配后开始采集，显示叠加层并展示部分文本，静默后自动发送。
• 按键通话（长按右 Option 键）：长按右 Option 键立即开始采集——无需触发词。长按期间显示叠加层；松开后完成采集并在短暂延迟后转发，以便你调整文本。

​

运行时行为（唤醒词）

• 语音识别器位于 VoiceWakeRuntime 中。
• 仅当唤醒词和下一个词之间存在有意义的停顿（约 0.55 秒间隔）时才会触发。叠加层/提示音可以在停顿时启动，甚至在命令开始之前。
• 静默窗口：语音持续时为 2.0 秒，仅听到触发词时为 5.0 秒。
• 硬停止：120 秒，防止会话失控。
• 会话间去抖：350 毫秒。
• 叠加层通过 VoiceWakeOverlayController 驱动，具有已确认/临时着色。
• 发送后，识别器干净重启以监听下一个触发词。

​

生命周期不变量

• 如果语音唤醒已启用且权限已授予，唤醒词识别器应保持监听状态（显式按键通话采集期间除外）。
• 叠加层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。

​

叠加层卡住故障模式（历史问题）

• 唤醒运行时重启不再被叠加层可见性阻塞。
• 叠加层关闭完成后通过 VoiceSessionCoordinator 触发 VoiceWakeRuntime.refresh(...)，因此手动点击 X 关闭始终会恢复监听。

​

按键通话详情

• 热键检测使用全局 .flagsChanged 监视器检测右 Option 键（keyCode 61 + .option）。我们仅观察事件（不拦截）。
• 采集管道位于 VoicePushToTalk 中：立即启动语音识别，将部分结果流式传输到叠加层，松开时调用 VoiceWakeForwarder。
• 按键通话开始时，我们暂停唤醒词运行时以避免音频输入冲突；松开后自动重启。
• 权限：需要麦克风 + 语音识别权限；查看事件需要辅助功能/输入监控授权。
• 外接键盘：某些键盘可能无法按预期暴露右 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)）；松开后恢复。