前言¶
在 DSH 裏做會議記錄、播客整理或從視頻抽字幕時，若走雲端 ASR，既要上傳音頻，又受配額與隱私策略約束。自備 whisper.cpp 可以本地推理，但命令行拼路徑、合併多段文件、對齊時間軸仍要手工處理。dsh-local-transcribe 由維護者 bizbin 發佈，歸類爲模型推理，把 whisper.cpp 接到 DSH：提供側邊欄可視化面板，並在智能體會話中暴露 transcribe_audio 工具，轉寫與音頻處理均在本機完成。
這是什麼¶
dsh-local-transcribe 是 DeepSeek Harness（DSH）插件，用 whisper.cpp 做完全本地語音轉文本，音頻不上傳外網。宿主倉庫：bizbin/dsh-local-transcribe；社區目錄頁：SkillHub 插件頁。許可證 MIT；package.json 標明版本 1.0.0，要求 DSH >=0.2.2-rc.1 且使用 web profile。
核心功能¶
可視化面板¶
打開側邊欄波形圖標後，可拖拽或瀏覽本地文件；多文件可按順序合併再識別。上傳文件落在 ~/.dsh/storages/local-transcribe-uploads/，單文件上限 500 MB。轉寫過程中顯示階段與進度；結束後可預覽全文、分段時間軸，播放合併音頻，並就地編輯文本後保存（會重寫原始 txt 並重新生成 markdown）。
智能體工具 transcribe_audio¶
任意 agent 會話可調用：單文件用 path，多文件按序合併用 paths；可選 language、prompt、output_dir、output_name、markdown、keep_wav 等。返回完整文本、分段時間軸與輸出文件路徑。
格式與安全¶
支持的輸入包括 m4a、mp3、wav、flac、aac、ogg、opus、wma、m4b、amr、aiff、aif、caf，以及 mp4、mov、mkv、avi、webm、m4v、ts、3gp、mpg、mpeg 等視頻容器。面板 HTTP 路由（/local-transcribe/rpc、/local-transcribe/upload、/local-transcribe/play/*）僅接受環回地址（127.0.0.1 / localhost），插件卸載時路由會移除；轉寫依賴本機二進制，音頻不離開本機。
環境與依賴¶
使用前需滿足：
- 已運行 DSH（≥ 0.2.2-rc.1），且 profile 爲 web。
- 系統 PATH 上有
ffmpeg/ffprobe（macOS 可用brew install ffmpeg）。 - 已編譯 whisper.cpp，能得到
whisper-cli可執行文件，並下載 ggml 模型文件。
whisper.cpp 與模型示例如下（摘自官方 README）：
git clone https://github.com/ggml-org/whisper.cpp
cd whisper.cpp && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
curl -L -o ggml-medium.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin
安裝與啓用¶
在 DSH 中可通過 Plugin Manager，或由智能體執行 install_bundle，指向本插件解壓後的絕對路徑。README 給出的直接安裝說明爲：
# 在 DSH 中向智能體說明，或在 Plugin Manager UI 中執行：
# install_bundle <dsh-local-transcribe 目錄的絕對路徑>
也可從 Plugin Manager 安裝 bundle（需先取得倉庫內容到本地目錄）。插件以當前 DSH 進程權限運行，安裝前請自行查看源碼與 MIT 許可證。
配置¶
在 profile 的 cordis.patch.yml 中，爲 local-transcribe 條目填寫 config：
- id: local-transcribe
config:
whisperCli: /path/to/whisper.cpp/build/bin/whisper-cli
model: /path/to/ggml-medium.bin
# ffmpeg: ffmpeg
# ffprobe: ffprobe
# language: zh
# prompt: '以下是普通話的句子。'
# threads: 10
| 配置項 | 默認值 | 含義 |
|---|---|---|
whisperCli |
PATH 上的 whisper-cli |
whisper-cli 可執行文件路徑 |
model |
（必填） | ggml 模型文件的絕對路徑 |
ffmpeg / ffprobe |
ffmpeg / ffprobe |
PATH 或絕對路徑 |
language |
zh |
默認語言；auto 爲自動檢測 |
prompt |
以下是普通話的句子。 |
whisper 初始 prompt |
threads |
10 |
whisper-cli 線程數 |
whisperCli 與 model 是日常使用裏最常需要改的兩項。
典型用法¶
面板工作流¶
- 打開側邊欄波形圖標。
- 拖拽或選擇音頻（或視頻），調整多文件順序，指定輸出目錄、語言與 prompt。
- 點擊 Transcribe，等待進度完成。
- 預覽時間軸、試聽合併音頻，按需編輯後點 Save edits。
默認輸出目錄爲首個輸入文件旁，或由面板指定的 output_dir，生成：
<name>_原始轉寫.txt— 純文本<name>_帶時間軸.json— 毫秒級分段<name>_轉寫稿.md— 按分鐘分節的 markdown
在會話中調用 transcribe_audio¶
在已加載該插件的 DSH 會話中，讓智能體對本地文件調用 transcribe_audio：單文件傳 path，多段合併傳有序 paths，並按需設置 language、output_dir 等；工具返回全文、時間軸與寫出路徑，便於後續摘要或入庫。
適用場景與注意¶
適合需要在本地處理會議錄音、採訪、課程視頻字幕，且希望與 DSH 智能體共用同一套轉寫能力的開發者。中文默認可將 language 設爲 zh，並用 README 中的 prompt 示例減少誤識別。
注意：轉寫速度與質量取決於所選 ggml 模型與 threads；面板單文件 500 MB 限制需自行拆分超大素材。DSH 生態強調「一切皆插件」；SkillHub 等目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
鏈接¶
- 目錄頁：https://www.skillhub.cn/plugins/bizbin/dsh-local-transcribe
- GitHub：https://github.com/bizbin/dsh-local-transcribe
