VoiceFlow: 本機優先 macOS 語音 Agent
將口語意圖轉化為可驗證的 Mac 工作流，結合本機 Whisper、確認屏障機制與加密稽核軌跡。
01 · 問題定義與威脅模型
透過語音執行系統操作的桌面 Agent 面臨兩大核心危害。首先，將環境麥克風音訊持續串流至第三方雲端端點，會帶來重大的企業機密與個人隱私外洩風險。其次，自然語言本質上充滿歧義：單一語音辨識錯誤或不嚴謹的 Agent 計畫，可能導致重要檔案被誤刪、未審核的訊息被外發，或是觸發未授權的終端機腳本。
VoiceFlow 透過嚴格的本機優先架構與確定性確認狀態機解決此問題。所有音訊收音、轉錄與意圖路由 100% 於本機 CPU 硬體完成。此外，任何具有外部副作用的操作，皆會被攔截於不可繞過的人工確認屏障。
02 · 系統限制與非協商指標
收音、語音轉文字、意圖分類與工作流規劃完全於 macOS 本機執行，零雲端 API 依賴。
所有具外部副作用之操作（終端指令、瀏覽器表單提交、檔案刪除）必須獲得使用者實體確認。
所有語音指令、意圖解析與執行軌跡皆使用 Apple CryptoKit AES-GCM 加密儲存於本機 SQLite。
03 · 系統架構與外部副作用確認屏障
透過 Carbon 熱鍵擷取音訊，經由本機 faster-whisper 與繁體中文正規化進入意圖分派器。唯讀指令直接執行，狀態變更操作則停留於確認門檻。
本機語音意圖至可驗證 macOS 執行流程
01. 按鍵發話：透過 Carbon 熱鍵攔截收音，16kHz PCM 音訊直接送入本機記憶體，完全不經雲端。
02. 本機語音轉文字：使用 faster-whisper int8 CPU 推論，於中位數 2,003ms 內完成轉錄，零對外網路連線。
03. 繁體中文正規化：比對專業詞庫過濾模型幻覺，將口語慣用語標準化為精確的系統指令。
04. 意圖狀態機：將指令嚴格劃分為唯讀查詢與狀態變更操作（B7 基準測試成功率 1.0000）。
05. 外部副作用確認門檻：任何狀態變更操作必須經由實體視窗確認（160 次浸泡測試中 0 起自動提交）。
06. 沙盒執行與加密軌跡：沙盒轉接器執行已確認指令，背景守護程序 0.43s 恢復，稽核日誌經 AES-GCM 加密存於 SQLite。
04 · 三項關鍵技術決策
1. 外部副作用確認機制優於全自動執行
安全門檻背景與考量：在吵雜環境或與同事討論程式碼時，語音指令極易被環境雜音誤觸發。
架構決策：硬性規定執行器攔截所有不可逆操作（檔案修改、POST 請求、系統腳本），並要求實體確認。在社群發文示範中，自動化流程在發布按鈕前嚴格中止。
成效與取捨：在 8 小時涵蓋 160 項任務的長時間浸泡測試中，記錄到精確的 0 起高風險自動提交事件。
2. 具備 0.43 秒快速重啟的多程序守護架構
可靠度架構背景與考量：底層 CTranslate2 音訊程序或無頭瀏覽器轉接器在長時間運作下可能發生記憶體洩漏或崩潰。
架構決策：透過 UNIX domain socket 與心跳偵測，將 SwiftUI 選單列程序與背景 Worker 行程完全解耦。實作具備熔斷機制與行程池回收的自我修復守護程序。
成效與取捨：在穩定度測試中驗證：背景 Worker 崩潰後可在 0.43 秒內自動恢復，選單列 UI 不發生閃退，亦不遺失任務狀態。
3. 結合遮蔽過濾機制的加密稽核日誌
隱私保護背景與考量：除錯需要詳盡的軌跡日誌，但直接保存原始文字與螢幕截圖可能洩漏敏感憑證或個資。
架構決策：建立自動化正規化遮蔽過濾器，在寫入磁碟前遮蔽 API 金鑰、密碼與個人識別資訊。所有資料庫資料表透過 CryptoKit AES-GCM 加密，金鑰錨定於 macOS Keychain。
成效與取捨：在 160 項浸泡任務的稽核查驗中，未檢測出任何未遮蔽的機密資訊洩漏。
05 · 最具挑戰性的工程難題
消除熱鍵監聽器失效時路由選擇狀態機的懸掛問題
問題根本原因：在特定的 macOS 權限狀態下，Carbon 全域熱鍵監聽器在背景初始化時可能失敗，導致 UI 狀態機無限期停留在 waiting_confirmation，且無法接收使用者的鍵盤輸入。
工程解決方案：重構狀態機架構，將熱鍵監聽註冊與動作評估解耦。加入自動逾時降級機制：若鍵盤監聽器在 500ms 內未回報有效就緒狀態，系統自動降級為標準視窗對話框並導向預設安全路徑。
實測驗證：在測試框架中模擬連續 100 次鍵盤監聽器崩潰事件；100/100 均順暢降級至視窗備援，未出現任何孤立或無法復原的懸掛狀態。
06 · 負向實驗結果：語音微調模型之淘汰決策
工程紀律意味著拒絕出貨未達產品標準的模型，即便模型訓練與格式轉換在技術層面上順利完成。
07 · 長時間浸泡測試與實測數據
連續 8 小時自動化語音工作流程浸泡測試；主視窗零崩潰、零記憶體碎裂。
8 小時運作下呈現近乎水平的記憶體增長斜率，證實 CoreAudio 與 Swift 緩衝區零洩漏。
在故障注入測試中以 SIGKILL 強制終止 Worker 時，守護程序在亞秒級內完成重啟。
基準測試 B3：20/20 音訊樣本在純 CPU 硬體上於可接受之互動延遲內完成轉錄。
08 · 專案回顧與反思
工程經驗總結：工程經驗總結：在語音驅動的桌面 Agent 中，靜態音訊片段上的模型指標無法直接轉化為穩定的系統操作。在特定領域音訊上微調語音模型帶來的實際指令提升極為微小 (+0.0727)，反而是確定性規則過濾與狀態機確認屏障提供了 100% 的破壞性操作防護。
若重新開始我會做的調整：若重新開始我會做的調整：更早將瀏覽器自動化從直接的 DOM 操作解耦。改採 macOS 原生輔助功能 API（AXUIElement）進行系統級控制，能大幅降低因第三方網頁更新而造成的自動化脆弱性。