dsh-voice：DeepSeek Harness 的本地語音輸入插件

前言¶

DeepSeek Harness (DSH) 是用於調試和開發智能體的工具。在智能體開發中，語音輸入是一個常見需求，但通常需要依賴外部 API 或複雜的本地服務部署。dsh-voice 是一個插件，它爲 DSH 引入了本地、私密的語音轉文本能力，無需外部二進制文件即可運行。

插件介紹¶

dsh-voice 是一個單面插件，旨在爲 DeepSeek Harness 提供 Web UI 和 TUI 的語音輸入功能。

維護者：wencharmwang
許可證：MIT
核心價值：Host 端提供基於 ONNX 的本地 Whisper 服務，瀏覽器端集成麥克風按鈕。

安裝與啓用¶

該插件以 Bundle 形式添加到 DSH Profile 中。

從 NPM 安裝：

    dsh plugin --profile web add dsh-voice

或直接從 GitHub 安裝：

    dsh plugin --profile web add github:wencharmwang/dsh-voice

注意：在使用 pnpm >= 10 從 Git 安裝時，如果 prepare 腳本報錯，需要在 Profile 的 pnpm-workspace.yaml 中配置 allowBuilds。

安裝完成後，插件會自動激活 voice Row。也可以手動在 ~/.dsh/profiles/web/cordis.patch.yml 中聲明 Row。

配置¶

所有配置均爲可選，可通過 Patch 文件修改。配置項包括模型、語言、數據類型和緩存目錄。

- id: voice
  config:
    model: onnx-community/whisper-medium  # Hugging Face Whisper ONNX ID 或本地目錄
    language: auto                       # 'auto' | 'zh' | 'en' | ...
    dtype: q8                            # 'q8' | 'fp32' | 'q4'
    dir: ''                              # 模型緩存及錄音目錄，留空則使用默認路徑

模型層級的優先級爲：配置文件優先於 Schema 默認值。

功能與使用¶

Host 端服務 (ctx.stt)¶

插件在 Host 端暴露了 ctx.stt 服務，提供以下接口：

status()：檢查就緒狀態及當前模型，不加載/下載模型。
ensureModel(onProgress)：確保模型已下載並加載。
transcribe(input, options)：將音頻輸入轉換爲文本。支持 Float32Array (16kHz mono)、Buffer (PCM/WAV) 或文件路徑。
startRecording() (TUI)：開始錄音，返回 WAV 文件路徑及停止/取消方法。

Web UI 交互¶

在 Web 界面的 Composer 中集成了麥克風按鈕。錄音在瀏覽器本地完成，解碼爲 16kHz 單聲道 PCM 後，通過 HTTP 請求發送到 Host 端。

HTTP 路由¶

Web 模式下暴露了以下路由：

POST /voice/transcribe：接收音頻數據，返回轉錄文本。支持查詢參數 ?lang=<iso> 指定語言。
GET /voice/status：檢查模型加載狀態。

模型支持¶

插件支持從 Hugging Face Hub 下載的多種 Whisper ONNX 模型，模型緩存於 ~/.dsh/voice/models。

onnx-community/whisper-medium (約 0.8 GB，默認)
onnx-community/whisper-small (約 250 MB)
onnx-community/whisper-large-v3 (約 1.6 GB)

注意事項¶

TUI 錄音依賴：TUI 模式下的麥克風錄音功能需要系統級的錄製工具（如 ffmpeg、sox 或 arecord）。
模型緩存：首次使用會自動下載模型，後續緩存於指定目錄。
生態定位：本插件由社區開發者維護，與 DeepSeek 官方無直接隸屬關係。使用前請檢查源碼與許可證。