前言¶
DeepSeek Harness（DSH）是一個插件化框架，旨在擴展其核心功能。語音輸入通常需要切換窗口或複製粘貼文本。dsh-voice-input 插件在 DeepSeek Harness 的 composer 輸入框中集成了一個麥克風按鈕，並提供了一個 Web 設置頁面。它通過瀏覽器引擎或任何 OpenAI 兼容的 /audio/transcriptions 端點實現語音轉文字（ASR）。
核心功能¶
該插件具備以下能力：
- 輸入框內集成：在輸入框左側工具欄增加麥克風按鈕，支持開始/停止錄音快捷鍵（Alt+M）及取消快捷鍵（Esc）。
- 實時狀態反饋：錄音時輸入框上方出現狀態條，顯示電平、計時、實時文字、完成狀態及錯誤信息。
- 雙引擎支持：
- 瀏覽器引擎：零配置，調用瀏覽器原生語音識別（需 Chrome / Edge）。
- OpenAI 兼容 API 引擎：支持雲端服務或本地服務，通過
/audio/transcriptions接口進行轉錄。
- 本地 ASR 支持：支持本機 Whisper 服務器，提供一鍵準備腳本。
- 零依賴安裝：無構建步驟，無運行時依賴，宿主僅使用 Node 內置
fetch/FormData/Blob。 - 安全憑證管理：API Key 從憑證庫讀取（默認
VOICE_ASR_API_KEY），不在配置文件中明文存儲。 - 自動錯誤處理：針對 401（認證錯誤）、404（路徑錯誤）、413（文件過大）、超時等常見錯誤提供提示。
- 工具診斷：註冊了
voice_input_status工具，可直接詢問 DeepSeek 當前配置及狀態。
安裝與啓用¶
在安裝前，請確保環境滿足以下要求：
- DeepSeek Harness
0.1.5-rc.1或更新版本。 - Node.js 22+（宿主端使用
AbortSignal.any、FormData、Blob）。 - 一個現代瀏覽器（Chrome / Edge 支持
SpeechRecognition；Firefox 不支持）。
執行以下命令進行安裝：
# 執行安裝
./install.ps1
安裝完成後，刷新 Web UI，進入「設置 → 語音輸入」即可使用。
若需卸載，請執行：
./install.ps1 -Uninstall
注意：不要與 dsh plugin --profile web add github:owner/repo 命令同時使用。
使用方法¶
基礎操作¶
- 在輸入框左側工具欄點擊麥克風按鈕（或按
Alt+M）開始錄音。 - 錄音中按
Esc取消且不寫入輸入框。 - 說話結束後，轉寫結果會自動填入輸入框。
引擎選擇¶
- 瀏覽器引擎（無配置）：刷新頁面後直接點擊麥克風。若瀏覽器支持，將使用原生識別引擎。注意：瀏覽器引擎在中國大陸通常不可用。
- 雲端轉寫接口：在設置頁面配置接口地址（如 OpenAI、SiliconFlow、Groq 等）和模型。
- 本地轉寫：使用
local-asr/文件夾提供的離線 Whisper 服務，或通過設置頁面的「本機後端（一鍵準備）」腳本啓動。
Ollama 與本地模型¶
- Ollama：插件支持檢測 Ollama 模型，但目前無法使用，因爲 Ollama 0.34 版本的官方模型庫中沒有任何模型具備音頻投影（audio/mmproj）能力。
- 本地 Whisper：推薦使用支持 OpenAI 協議的本地服務（如 whisper.cpp 或 faster-whisper-server）。
配置與注意事項¶
API Key 管理¶
插件不會在配置文件中保存 API Key，而是從憑證庫按引用讀取（VOICE_ASR_API_KEY）。這使得輪換 Key 對下一次錄音立即生效，無需修改配置。
模型與瀏覽器限制¶
- Ollama：若要使用 Ollama 進行轉寫，模型必須具備音頻投影（mmproj）能力。目前 Ollama 官方庫中暫無此類模型。
- Firefox：由於不支持
SpeechRecognition，Firefox 無法使用瀏覽器原生引擎。
本機後端腳本¶
插件提供了 PowerShell 腳本用於管理本地 ASR 服務和 Ollama。安裝腳本會自動處理 cordis.patch.yml 的託管行，並在安裝完成後校驗文件完整性。
