语音唤醒和按键说话

模式

• 唤醒词模式（默认）：始终开启的语音识别器等待触发词（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。
• 当按键说话开始时，我们暂停唤醒词运行时以避免重复音频 taps；它在松开后自动重新启动。
• 权限：需要麦克风 + 语音；查看事件需要辅助功能/输入监控批准。
• 外部键盘：某些可能无法正确暴露右 Option — 如果用户报告遗漏，请提供后备快捷键。

用户面向的设置

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

转发行为

• 启用语音唤醒时，转录被转发到活动的 gateway/代理（与 mac 应用其余部分使用的相同本地 vs 远程模式）。
• 回复被发送到最后使用的主要提供商（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，错误被记录，并且运行仍可通过 WebChat/会话日志可见。

转发负载

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

快速验证

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