> ## Documentation Index
> Fetch the complete documentation index at: https://claw-tw.jackle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Wake (macOS)（語音喚醒與按鍵通話）

# 語音喚醒與按鍵通話

## 模式

* **喚醒詞模式** (預設): Always-on 的語音辨識器等待觸發 Token (`swabbleTriggerWords`)。匹配時開始擷取，顯示帶有部分文字的覆蓋介面，並在靜默後自動發送。
* **按鍵通話 (按住右 Option)**: 按住右 Option 鍵以立即擷取——無需觸發詞。按住時覆蓋介面顯示；釋放時在短暫延遲後完成並轉發，讓您可以微調文字。

## 執行時行為 (喚醒詞)

* 語音辨識器位於 `VoiceWakeRuntime`。
* 只有當喚醒詞與下一個詞之間有 **有意義的停頓** (\~0.55s 間隔) 時才會觸發。覆蓋/鈴聲甚至可以在指令開始前的停頓時啟動。
* 靜默視窗：語音流動時為 2.0s，若僅聽到觸發詞則為 5.0s。
* 硬性停止：120s 以防止工作階段失控。
* 工作階段間的去除彈跳 (Debounce)：350ms。
* 覆蓋介面透過 `VoiceWakeOverlayController` 驅動，具有已提交/變動中的顏色區分。
* 發送後，辨識器乾淨地重啟以聆聽下一個觸發。

## 生命週期不變量

* 若語音喚醒已啟用且權限已授權，喚醒詞辨識器應處於聆聽狀態（除非正在進行明確的按鍵通話擷取）。
* 覆蓋介面的可見性（包含透過 X 按鈕手動關閉）絕不能阻止辨識器恢復。

## 黏滯覆蓋失敗模式 (先前)

先前，若覆蓋介面卡在可見狀態而您手動關閉它，語音喚醒可能會看似「死掉」，因為 Runtime 的重啟嘗試可能被覆蓋介面的可見性阻擋，且後續未排程重啟。

強化措施 (Hardening):

* 喚醒 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）或選擇 **No Sound**。

## 轉發行為

* 當語音喚醒啟用時，轉錄內容會轉發至活動的 Gateway/Agent（使用 mac 應用程式其餘部分相同的 Local vs Remote 模式）。
* 回覆會傳遞至 **最後使用的主要供應商** (WhatsApp/Telegram/Discord/WebChat)。若傳遞失敗，錯誤會被記錄，且執行仍可透過 WebChat/工作階段日誌查看。

## 轉發負載

* `VoiceWakeForwarder.prefixedTranscript(_:)` 在發送前將機器提示 (machine hint) 加在轉錄內容之前。喚醒詞與按鍵通話路徑共用此邏輯。

## 快速驗證

* 開啟按鍵通話，按住 Cmd+Fn，說話，釋放：覆蓋介面應顯示部分內容然後發送。
* 按住時，選單列耳朵圖示應保持放大（使用 `triggerVoiceEars(ttl:nil)`）；釋放後縮回。