语音唤醒与按键说话

模式

• 唤醒词模式（默认）：始终在线的语音识别器等待触发词（swabbleTriggerWords）。匹配后开始捕获，在浮窗中显示部分文本，静默后自动发送。
• 按键说话（按住右 Option 键）：按住右 Option 键立即开始捕获——无需触发词。按住期间浮窗显示；松开后经过短暂延迟完成转录并转发，给你时间调整文本。

运行时行为（唤醒词）

• 语音识别器在 VoiceWakeRuntime 中。
• 只有在唤醒词和下一个词之间有明显停顿（约 0.55 秒间隔）时才触发。浮窗/音效可以在停顿时就开始，甚至在命令开口前。
• 静默窗口：语音持续时为 2.0 秒，仅听到触发词时为 5.0 秒。
• 硬性上限：120 秒，防止会话失控。
• 会话间防抖：350 毫秒。
• 浮窗通过 VoiceWakeOverlayController 驱动，区分 committed/volatile 文本的着色。
• 发送后识别器干净重启，继续监听下一个触发词。

生命周期不变量

• 如果语音唤醒已启用且权限已授予，唤醒词识别器应始终在监听（按键说话捕获期间除外）。
• 浮窗的可见性（包括通过 X 按钮手动关闭）决不能阻止识别器恢复。

浮窗卡住的问题（历史）

此前如果浮窗卡在可见状态、你手动关闭了它，语音唤醒可能会看起来”死了”——因为运行时的重启尝试会被浮窗可见性阻塞，且不会安排后续重启。

加固措施：

• 唤醒运行时重启不再被浮窗可见性阻塞。
• 浮窗关闭完成时通过 VoiceSessionCoordinator 触发 VoiceWakeRuntime.refresh(...)，因此手动点 X 关闭总是会恢复监听。

按键说话细节

• 快捷键检测使用全局 .flagsChanged 监视器，检测右 Option（keyCode 61 + .option）。只观察事件（不拦截）。
• 捕获管线在 VoicePushToTalk 中：立即启动语音识别，将部分文本流式显示到浮窗，松开时调用 VoiceWakeForwarder。
• 按键说话开始时暂停唤醒词运行时以避免音频冲突；松开后自动恢复。
• 权限要求：麦克风 + 语音识别；事件监听需要辅助功能/输入监控权限。
• 外接键盘：有些可能不会按预期暴露右 Option——如果用户反馈未检测到，提供备用快捷键。

用户设置

• Voice Wake 开关：启用唤醒词运行时。
• Hold Cmd+Fn to talk：启用按键说话监视器。macOS < 26 上禁用。
• 语言和麦克风选择器、实时电平表、触发词列表、测试器（仅本地；不转发）。
• 麦克风选择器记住上次选择；设备断开时显示断开提示，临时回退到系统默认，设备恢复后自动切回。
• 声音：触发检测和发送时的音效；默认为 macOS 的 “Glass” 系统声音。你可以为每个事件选择任何 NSSound 可加载的文件（如 MP3/WAV/AIFF）或选择 No Sound。

转发行为

• 语音唤醒启用时，转录文本会转发到活跃的 Gateway/agent（与 macOS 应用其余功能使用相同的 local/remote 模式）。
• 回复投递到最近使用的主频道（WhatsApp/Telegram/Discord/WebChat）。投递失败时记录错误，运行结果仍可通过 WebChat/会话日志查看。

转发载荷

• VoiceWakeForwarder.prefixedTranscript(_:) 在发送前预置机器提示。唤醒词和按键说话路径共用。

快速验证

• 打开按键说话，按住 Cmd+Fn，说话，松开：浮窗应显示部分文本然后发送。
• 按住期间菜单栏耳朵应保持放大（使用 triggerVoiceEars(ttl:nil)）；松开后恢复。