语音覆盖层生命周期（macOS）

适用范围

在以下情况使用此页面：

• 调整语音覆盖层行为

面向对象：macOS 应用贡献者。目标：在唤醒词和按键通话重叠时保持语音覆盖层可预测。

当前意图

• 如果覆盖层已从唤醒词可见并且用户按下热键，热键会话将采用现有文本而不是重置它。按住热键时覆盖层保持向上。当用户释放时：如果有修剪的文本则发送，否则关闭。
• 仅唤醒词仍然在静音时自动发送；按键通话在释放时立即发送。

已实现（2025 年 12 月 9 日）

• 覆盖层会话现在为每次捕获（唤醒词或按键通话）携带一个令牌。当令牌不匹配时，部分/最终/发送/关闭/电平更新会被丢弃，以避免过时的回调。
• 按键通话采用任何可见的覆盖层文本作为前缀（因此在唤醒覆盖层向上时按下热键会保留文本并附加新语音）。它等待最多 1.5s 以获得最终转录，然后回退到当前文本。
• 提示音/覆盖层日志在类别 voicewake.overlay、voicewake.ptt 和 voicewake.chime 中以 info 发出（会话开始、部分、最终、发送、关闭、提示音原因）。

后续步骤

1. VoiceSessionCoordinator（actor）
   • 一次仅拥有一个 VoiceSession。
   • API（基于令牌）：beginWakeCapture、beginPushToTalk、updatePartial、endCapture、cancel、applyCooldown。
   • 丢弃携带过时令牌的回调（防止旧的识别器重新打开覆盖层）。
2. VoiceSession（model）
   • 字段：token、source（wakeWord|pushToTalk）、提交/易变性文本、提示音标志、计时器（自动发送、空闲）、overlayMode（display|editing|sending）、冷却截止时间。
3. 覆盖层绑定
   • VoiceSessionPublisher（ObservableObject）将活动会话镜像到 SwiftUI。
   • VoiceWakeOverlayView 仅通过发布者渲染；它从不直接突变全局单例。
   • 覆盖层用户操作（sendNow、dismiss、edit）使用会话令牌回调到协调器。
4. 统一发送路径
   • 在 endCapture 时：如果修剪的文本为空 → 关闭；否则 performSend(session:)（播放发送提示音一次、转发、关闭）。
   • 按键通话：无延迟；唤醒词：自动发送的可选延迟。
   • 在按键通话完成后对唤醒运行时应用短暂的冷却，以便唤醒词不会立即重新触发。
5. 日志记录
   • 协调器在子系统 com.clawdbot 中发出 .info 日志，类别 voicewake.overlay 和 voicewake.chime。
   • 关键事件：session_started、adopted_by_push_to_talk、partial、finalized、send、dismiss、cancel、cooldown。

调试检查清单

• 在重现粘性覆盖层时流式传输日志：

  sudo log stream --predicate 'subsystem == "com.clawdbot" AND category CONTAINS "voicewake"' --level info --style compact

• 验证只有一个活动会话令牌；过时的回调应该被协调器丢弃。

• 确保按键通话释放始终使用活动令牌调用 endCapture；如果文本为空，期望 dismiss 而无提示音或发送。

迁移步骤（建议）

1. 添加 VoiceSessionCoordinator、VoiceSession 和 VoiceSessionPublisher。
2. 重构 VoiceWakeRuntime 以创建/更新/结束会话，而不是直接接触 VoiceWakeOverlayController。
3. 重构 VoicePushToTalk 以采用现有会话并在释放时调用 endCapture；应用运行时冷却。
4. 将 VoiceWakeOverlayController 连接到发布者；从运行时/PTT 中删除直接调用。
5. 为会话采用、冷却和空文本关闭添加集成测试。