语音唤醒和按键通话

适用范围

在以下情况使用此页面：

• 处理语音唤醒或 PTT 途径

模式

• 唤醒词模式（默认）：始终开启的语音识别器等待触发令牌（swabbleTriggerWords）。匹配时开始捕获，显示带有部分文本的覆盖层，并在静音后自动发送。
• 按键通话（按住右 Option）：按住右 Option 键立即捕获——无需触发。按住时显示覆盖层；释放后经过短暂延迟完成并转发，以便你可以调整文本。

运行时行为（唤醒词）

• 语音识别器位于 VoiceWakeRuntime 中。
• 仅当唤醒词和下一个词之间有有意义的停顿时触发（~0.55s 间隙）。覆盖层/提示音可以在命令开始之前的停顿时启动。
• 静音窗口：语音流动时为 2.0s，如果只听到触发词则为 5.0s。
• 硬停止：120s 以防止失控会话。
• 会话之间的防抖：350ms。
• 覆盖层通过 VoiceWakeOverlayController 驱动，具有提交/易变性着色。
• 发送后，识别器干净地重新启动以监听下一个触发。

生命周期不变量

• 如果启用语音唤醒并授予权限，唤醒词识别器应该正在监听（显式按键通话捕获期间除外）。
• 覆盖层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。

粘性覆盖层故障模式（之前）

以前，如果覆盖层卡住可见并且你手动关闭它，语音唤醒可能看起来"死机"，因为运行时的重新启动尝试可能被覆盖层可见性阻止，并且没有安排后续重新启动。

硬化：

• 唤醒运行时重新启动不再被覆盖层可见性阻止。
• 覆盖层关闭完成通过 VoiceSessionCoordinator 触发 VoiceWakeRuntime.refresh(...)，因此手动 X 关闭始终恢复监听。

按键通话详细信息

• 热键检测对右 Option使用全局 .flagsChanged 监视器（keyCode 61 + .option）。我们仅观察事件（不吞没）。
• 捕获管道位于 VoicePushToTalk 中：立即启动语音，将部分流式传输到覆盖层，并在释放时调用 VoiceWakeForwarder。
• 当按键通话启动时，我们暂停唤醒词运行时以避免决斗音频点击；它在释放后自动重新启动。
• 权限：需要麦克风 + 语音；查看事件需要辅助功能/输入监控批准。
• 外部键盘：有些可能不会按预期公开右 Option——如果用户报告未命中，提供回退快捷键。

面向用户的设置

• 语音唤醒切换：启用唤醒词运行时。
• 按住 Cmd+Fn 通话：启用按键通话监视器。在 macOS < 26 上禁用。
• 语言和麦克风选择器、实时电平表、触发词表、测试器（仅本地；不转发）。
• 如果设备断开连接，麦克风选择器会保留最后的选择，显示断开连接提示，并暂时回退到系统默认值，直到它返回。
• 声音：触发检测和发送时的提示音；默认为 macOS “Glass"系统声音。你可以为每个事件选择任何 NSSound 可加载文件（例如 MP3/WAV/AIFF）或选择无声音。

转发行为

• 启用语音唤醒时，转录将转发到活动网关/智能体（与 mac 应用的其余部分使用的相同的本地与远程模式）。
• 回复将传递给最后使用的主提供商（WhatsApp/Telegram/Discord/WebChat）。如果传递失败，错误将被记录并且运行仍然可以通过 WebChat/会话日志看到。

转发负载

• VoiceWakeForwarder.prefixedTranscript(_:) 在发送前添加机器提示。在唤醒词和按键通话路径之间共享。

快速验证

• 打开按键通话，按住 Cmd+Fn，说话，释放：覆盖层应显示部分内容然后发送。
• 按住时，菜单栏耳朵应保持放大（使用 triggerVoiceEars(ttl:nil)）；释放后它们会下降。