语音唤醒与按键说话

模式说明

• 唤醒词模式（默认）：持续运行的语音识别器等待触发词（swabbleTriggerWords）。匹配后启动捕获，显示带有 partial 文本的覆盖层，并在静默后自动发送。
• 按键说话（右 Option 长按）：按住右 Option 键立即开始捕获——无需触发词。覆盖层在按住期间显示；松开后短暂延迟以便修改文本，然后转发。

运行时行为（唤醒词）

• 语音识别器位于 VoiceWakeRuntime。
• 触发仅在唤醒词与下一个词之间有明显停顿时生效（约 0.55 秒间隔）。覆盖层/提示音可以在指令开始前的停顿时就启动。
• 静默窗口：语音流动时 2.0 秒，仅听到触发词时 5.0 秒。
• 硬性停止：120 秒，防止会话失控。
• 会话间防抖：350 毫秒。
• 覆盖层通过 VoiceWakeOverlayController 驱动，带有已提交/可变文本着色。
• 发送后，识别器干净地重启以监听下一个触发词。

生命周期不变量

• 若 Voice Wake 已启用且权限已授予，唤醒词识别器应持续监听（按键说话捕获期间除外）。
• 覆盖层可见性（包括点击 X 手动关闭）绝不能阻止识别器恢复。

覆盖层卡死问题（历史问题）

此前，如果覆盖层卡在可见状态并被手动关闭，Voice Wake 可能"死机"——因为运行时的重启尝试可能被覆盖层可见性阻塞，且之后不会再调度重启。

加固措施：

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

按键说话详情

• 热键检测使用全局 .flagsChanged 监视器监听右 Option（keyCode 61 + .option）。我们只观察事件（不拦截）。
• 捕获流水线位于 VoicePushToTalk：立即启动语音识别，将 partial 文本流式传到覆盖层，松开时调用 VoiceWakeForwarder。
• 按键说话启动时暂停唤醒词运行时，避免两者同时占用音频；松开后自动重启。
• 权限：需要麦克风 + 语音识别；接收按键事件需要辅助功能/输入监控授权。
• 外接键盘：部分键盘可能无法如预期暴露右 Option——若用户反映缺失，提供备用快捷键。

用户设置

• Voice Wake 开关：启用唤醒词运行时。
• Hold Cmd+Fn to talk：启用按键说话监视器。macOS < 26 上禁用。
• 语言和麦克风选择器、实时电平计、触发词列表、测试器（仅本地；不转发）。
• 麦克风选择器在设备断开时保留最后选择，显示断开提示，并临时回退到系统默认设备，直到设备恢复。
• 声音：触发检测和发送时播放提示音；默认使用 macOS"Glass"系统音。可为每个事件选择任意 NSSound 可加载的文件（如 MP3/WAV/AIFF），或选择无声音。

转发行为

• 启用 Voice Wake 时，转录文本会转发到活动的网关/Agent（与 Mac 应用其他部分使用的本地与远程模式相同）。
• 回复投递到最近使用的主要提供商（WhatsApp/Telegram/Discord/WebChat）。如果投递失败，错误会被记录，运行仍可通过 WebChat/会话日志查看。

转发载荷

• VoiceWakeForwarder.prefixedTranscript(_:) 在发送前添加机器提示前缀，唤醒词和按键说话路径共用此方法。

快速验证

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

小龙虾技巧：对着你的龙虾喊一声唤醒词，它就会竖起大耳朵准备接收指令——这个耳朵动效不是摆设，而是真实工作状态的反映。