語音喚醒與按住說話

模式

• 喚醒詞模式（預設）：常駐的語音辨識器等待觸發詞（swabbleTriggerWords）。比對成功後開始擷取，顯示帶有局部文字的覆蓋層，並在靜默後自動送出。
• 按住說話（按住右 Option 鍵）：按住右 Option 鍵立即開始擷取——不需要觸發詞。覆蓋層在按住期間顯示；放開後最終確定並短暫延遲後轉發，讓你有機會調整文字。

執行環境行為（喚醒詞）

• 語音辨識器位於 VoiceWakeRuntime 中。
• 觸發只在喚醒詞與下一個字之間有有意義的停頓（約 0.55 秒間隔）時才觸發。覆蓋層／提示音可在停頓期間、命令開始前就啟動。
• 靜默窗口：語音持續時為 2.0 秒，只聽到觸發詞時為 5.0 秒。
• 硬性停止：120 秒，防止失控的工作階段。
• 工作階段間的防抖：350 毫秒。
• 覆蓋層透過 VoiceWakeOverlayController 驅動，使用已確認／暫時的色彩標記。
• 送出後，辨識器會乾淨地重新啟動以監聽下一個觸發。

生命週期不變量

• 若語音喚醒已啟用且權限已授予，喚醒詞辨識器應該處於監聽狀態（按住說話擷取期間除外）。
• 覆蓋層可見性（包括透過 X 按鈕手動關閉）不得阻止辨識器恢復。

覆蓋層卡住的故障模式（先前）

先前若覆蓋層卡在顯示狀態且你手動關閉它，語音喚醒可能看起來「失效」，因為 runtime 的重啟嘗試可能被覆蓋層可見性阻擋，且後續不再排程重啟。

強化措施：

• 喚醒 runtime 重啟不再被覆蓋層可見性阻擋。
• 覆蓋層關閉完成後會透過 VoiceSessionCoordinator 觸發 VoiceWakeRuntime.refresh(...)，確保手動按 X 關閉後一定會恢復監聽。

按住說話細節

• 快捷鍵偵測使用全域 .flagsChanged 監控右 Option（keyCode 61 + .option）。我們只觀察事件（不攔截）。
• 擷取管線位於 VoicePushToTalk 中：立即啟動語音辨識，將局部結果串流至覆蓋層，放開時呼叫 VoiceWakeForwarder。
• 按住說話開始時會暫停喚醒詞 runtime 以避免音訊輸入衝突；放開後自動重新啟動。
• 權限：需要麥克風 + 語音辨識；觀察事件需要輔助使用/輸入監控核准。
• 外接鍵盤：部分鍵盤可能不會如預期公開右 Option——若使用者回報漏失，提供備用快捷鍵。

使用者端設定

• Voice Wake 切換：啟用喚醒詞 runtime。
• Hold Cmd+Fn to talk：啟用按住說話監控。macOS < 26 時停用。
• 語言與麥克風選擇器、即時音量計、觸發詞表、測試器（僅本機；不轉發）。
• 麥克風選擇器在裝置斷開時保留上次選擇，顯示已斷線提示，並暫時退回系統預設直到裝置恢復。
• 音效：觸發偵測和送出時的提示音；預設為 macOS「Glass」系統音效。你可以為每個事件選擇任何 NSSound 可載入的檔案（如 MP3/WAV/AIFF）或選擇無音效。

轉發行為

• 語音喚醒啟用時，轉錄結果會轉發至活動中的 Gateway/代理程式（與 Mac 應用程式其他部分使用相同的本機或遠端模式）。
• 回覆會遞送至最近使用的主要供應商（WhatsApp/Telegram/Discord/WebChat）。遞送失敗時會記錄錯誤，但執行結果仍可透過 WebChat/工作階段日誌查看。

轉發內容

• VoiceWakeForwarder.prefixedTranscript(_:) 在送出前加上機器提示。喚醒詞和按住說話路徑共用。

快速驗證

• 開啟按住說話，按住 Cmd+Fn，說話，放開：覆蓋層應顯示局部結果然後送出。
• 按住期間，選單列耳朵應保持放大（使用 triggerVoiceEars(ttl:nil)）；放開後恢復。