前言¶

在 DeepSeek Harness（DSH）裏寫提示詞或長草稿時，鍵盤輸入往往跟不上思路。Harness 側存在若干實驗性語音相關包，依賴鏈和部署方式並不輕。若你已經在本機跑好了 Whisper（例如 faster-whisper 網關），更希望「瀏覽器點麥克風 → 本機轉寫 → 文字進編寫區」，且不走雲 API、不讓插件替你下載模型，pinion05/dsh-local-wispr（Local Wispr）就是按這條路徑設計的 DSH 插件。下面介紹它的定位、數據流、安裝與配置。

這是什麼¶

dsh-local-wispr（npm 包名 @local/dsh-local-wispr，當前資料版本 2.0.1）由維護者 pinion05 發佈，歸類爲模型推理相關能力。一句話：在 Harness Web GUI 的 composer 上增加獨立語音輸入按鈕，在瀏覽器裏錄音，經 DSH 宿主機同源路由轉發到本機 Whisper HTTP 網關做轉寫，再把文本插入當前草稿。不使用 Harness 自帶的實驗性語音棧（dsh-experimental-*speech*、ui-voice-input），也不依賴瀏覽器 Speech API，不由插件拉取模型。

許可證：MIT。兼容 DeepSeek Harness 0.2.x（engines.dsh: >=0.2.0-rc.1 <0.3.0-0），面向 web 配置文件。

核心功能與行爲¶

交互流程¶

1. 在 composer 工具行點擊麥克風 → 瀏覽器立即開始錄音（紅色脈衝與計時；最長 240 秒自動停止；按 Escape 可取消）。
2. 點擊停止（■） → 將錄音 blob 以 POST 提交到 DSH Web 服務器上的同源路徑 /local-wispr/transcribe。
3. 插件宿主機側在 trust-fence 校驗後，把音頻代理到本機 Whisper 網關（示例：POST /api/transcribe?lang=ko）。
4. 返回的轉寫文本通過 InputActions.insertText() 寫入草稿：優先插在開始錄音時記錄的插入點；若其間草稿已變則退回到當前插入點；若插入被拒絕則靜默放棄。不會自動發送消息。

架構要點¶

瀏覽器 (Harness Web UI)
│  MediaRecorder（webm/ogg/mp4）
▼
POST /local-wispr/transcribe     ← DSH 同源路由
▼
Whisper 網關（例：127.0.0.1:8813）
│  POST /api/transcribe?lang=
▼  faster-whisper large-v3-turbo（資料示例爲 int8、CPU）
{ text, seconds, elapsed }  →  編寫區

• 宿主機（index.js）：註冊 /local-wispr/transcribe、/local-wispr/health，向網關反向代理；瀏覽器不直連網關端口，避免 CORS，網關可只監聽 loopback。
• 客戶端（client.js）：在 conversation.input.right 插槽渲染麥克風；狀態機爲 idle → recording → transcribing → idle/error；處理權限拒絕、靜音、超時等。

README 中 STT 徽章指向 Whisper large-v3-turbo（faster-whisper）；實際推理由你自建的網關決定，插件只約定 HTTP 接口形狀。

環境與依賴¶

安裝與啓用¶

先將插件包放到本機目錄（從 GitHub 倉庫 獲取源碼或發佈物後解壓/拷貝均可，資料未規定單一獲取方式）。再在 Harness 中安裝 bundle：

• 圖形界面：Plugins → Install bundle，填入該目錄路徑。
• CLI（web profile）：

dsh plugin --profile web add <插件目錄路徑>

安裝成功後配置中會出現一行 local-wispr，composer 工具行出現麥克風按鈕。

注意：插件在當前 DSH 進程權限下運行；安裝前請自行閱讀倉庫源碼與 MIT 許可證，確認網關地址與網絡暴露範圍符合你的安全策略。

配置（可選）¶

在 profile patch 中修改 local-wispr 行的 config，例如：

- insert:
    - id: local-wispr
      name: '@local/dsh-local-wispr'
      config:
        endpoint: http://127.0.0.1:8813   # Whisper 網關基址
        lang: ko                            # 轉寫語言提示，可用 "auto"
        timeoutMs: 240000                   # 單次轉寫超時
        maxBodyBytes: 31457280              # 錄音 body 上限（30MB）

默認 endpoint 與 README 示例網關端口一致；若你改用 GPU 或其他 Whisper 服務，只需保證接口契約不變並改 endpoint / lang。

典型用法¶

1. 確認本機 Whisper 網關已啓動且 GET /health 正常（README 故障表示例：systemctl --user start pi-voice-board）。
2. 用 localhost 或 HTTPS 打開 Harness Web，進入帶 composer 的對話頁。
3. 光標停在要插入文字的位置，點麥克風說話，點停止等待轉寫。
4. 檢查草稿中是否出現轉寫文本；再按需編輯或發送（插件不會代你點發送）。

CPU 上 faster-whisper 的 RTF 在資料中約爲 1（30 秒錄音可能需約 30 秒以上轉寫）；換 GPU 網關可縮短等待。

故障排查（摘自 README）¶

適用場景與邊界¶

適合：已在同一臺機器（或 tailnet 內可信節點）部署 Whisper 網關、希望語音只走本地、又要與 Harness composer 草稿編輯流程綁定的開發者。

不適合：沒有 HTTP 網關、只想用瀏覽器內置聽寫、或需要插件內置模型下載的一站式方案——這些不在本插件設計範圍內。

插件目錄與說明亦見於社區目錄（與 DeepSeek / 幻方無官方從屬）：skillhub.cn 插件頁。源碼與文檔：github.com/pinion05/dsh-local-wispr。