macOS 伴侣应用
Voice Wake
模式
- 唤醒词模式（默认）：常驻的语音识别器等待触发词（
swabbleTriggerWords）。匹配后开始捕获，显示带有部分文本的悬浮窗，并在静默后自动发送。 - 按键通话（按住右 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中：立即启动语音识别，将部分结果流式传输到悬浮窗，并在松开时调用VoiceWakeForwarder。 - 当按键通话开始时，我们会暂停唤醒词运行时以避免音频采集冲突；松开后它会自动重启。
- 权限：需要麦克风 + 语音识别；接收事件需要辅助功能/输入监控批准。
- 外接键盘：某些键盘可能无法按预期暴露右 Option 键——如果用户报告未检测到，请提供备用快捷键。
面向用户的设置
- Voice Wake 开关：启用唤醒词运行时。
- 按住 Cmd+Fn 说话：启用按键通话监视器。在 macOS < 26 上禁用。
- 语言和麦克风选择器、实时电平表、触发词表、测试器（仅本地；不转发）。
- 麦克风选择器在设备断开连接时保留上次选择，显示断开连接提示，并在设备恢复前暂时回退到系统默认设备。
- 声音：检测到触发词和发送时的提示音；默认为 macOS "Glass" 系统声音。你可以为每个事件选择任何
NSSound可加载文件（例如 MP3/WAV/AIFF）或选择无声音。
转发行为
- 当 Voice Wake 启用时，转录文本会转发到活动的网关/智能体（agent）（与 mac 应用其余部分使用的本地与远程模式相同）。
- 回复会发送到最后使用的主要提供商（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，会记录错误，并且运行仍可通过 WebChat/会话日志查看。
转发负载
VoiceWakeForwarder.prefixedTranscript(_:)在发送前添加机器提示。唤醒词和按键通话路径共享此功能。
快速验证
- 打开按键通话开关，按住 Cmd+Fn，说话，松开：悬浮窗应显示部分文本然后发送。
- 按住期间，菜单栏耳朵图标应保持放大（使用
triggerVoiceEars(ttl:nil)）；松开后恢复。