语音覆盖层（Voice Overlay）管理唤醒词和按键通话（PTT）的交互生命周期，确保两者重叠时行为可预测。
核心设计意图
- 覆盖层已因唤醒词显示时，用户按下热键：PTT 会话继承现有文本而非重置
- 唤醒词在静默后自动发送；PTT 在释放时立即发送
- 每次捕获携带唯一 token，过期回调被丢弃，避免旧识别器重新打开覆盖层
会话 Token 机制
- 覆盖层会话携带每次捕获的 token（唤醒词或 PTT）
- 不匹配 token 的 partial/final/send/dismiss/level 更新被丢弃
- PTT 继承可见覆盖层文本作为前缀，等待最多 1.5s 获取最终转录
日志调试
# 流式查看语音覆盖层日志
sudo log stream \
--predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' \
--level info --style compact关键事件：session_started、adopted_by_push_to_talk、partial、finalized、send、dismiss、cancel、cooldown
架构组件（规划中）
| 组件 | 职责 |
|---|---|
VoiceSessionCoordinator（actor） | 同一时间只持有一个 VoiceSession |
VoiceSession（model） | token、source、文本、计时器、overlayMode |
VoiceSessionPublisher | 将活跃会话镜像到 SwiftUI |
VoiceWakeOverlayView | 仅通过 publisher 渲染，不直接修改全局单例 |
相关链接
- platform-mac-voicewake — 语音唤醒详情
- platform-macos — macOS 平台总览