前言¶

DSH 裏做多媒體處理，常見的兩條路都不順手：一是讓助手自己拼命令，路徑、參數、ffmpeg 版本一變就出錯；二是把文件扔到某個雲服務，隱私和網絡都受制。dsh-media-converter（維護者 a1121611810）走的是第三條路：插件把轉換、裁剪、提取音軌、字幕導出、圖片壓縮、元數據改寫、Base64 編解碼打包成圖形界面，底層統一調用本機的 ffmpeg，文件不出本機。下面介紹它的能力邊界、安裝方式和典型用法。

一、這是什麼¶

插件名是 dsh-media-converter，分類「工作流」，當前星標 0，已發佈到 npm，版本 1.3.1，許可證 MIT。

一句話定位：DeepSeek Harness 的本地多媒體工具箱插件，轉換 / 裁剪 / 提取音軌 / 字幕 / 元數據 / Base64，全部由本機 ffmpeg 完成。界面分兩層：隊列負責一次處理多個文件，點某一行進入文件詳情，那裏是單個文件的操作頁。

對智能體開發者來說，同一個引擎還註冊成工具 media_toolbox，助手可以直接調用，工具喫的是本機絕對路徑，不走上傳。

二、核心功能¶

支持的功能動作如下（來自 README 的功能表）：

• 轉成 X：視頻 12 種（mp4/mov/mkv/webm/avi/flv/wmv/ts/ogv/gif/mp3/m4a）、音頻 8 種（mp3/m4a/aac/wav/flac/ogg/opus/aiff）、圖片 7 種（png/jpg/webp/gif/bmp/tiff/avif）。
• 裁一段：從播放器取起點/終點，或手填 分:秒；裁剪與轉換一次完成。
• 提取音頻 / 提取畫面：直接拷貝軌道，不重編碼。
• 提取字幕：內嵌字幕軌導出 .srt，文件名帶語言碼（如 clip.chi.srt）。
• 圖片壓縮：選 JPG / WEBP 時按質量滑桿重編碼；右側實時預覽，支持並排/滑塊對比。
• 元數據：查看容器、章節、逐軌參數與全部標籤；改寫標題/作者/專輯/備註/日期/流派，另存爲新文件。
• Base64：當前文件轉成 data: URL；或粘貼 Base64 還原成文件/文本。
• 批量處理：按類型分組，視頻/音頻/圖片各自一個目標；文本單獨一段、不參與轉換；讀取中/未識別單獨一段；逐組全選、質量、逐行進度/結果/取消。

幾個實現細節值得留意：

• GPU / 直接拷貝：macOS VideoToolbox 的 H.264 可勾選 GPU 編碼（mp4/mov/mkv/flv/ts）；兼容編碼/容器直接 -c copy，不重編碼。
• 取消：批量中途取消會停掉當前 ffmpeg 且不再排隊；單文件任務可隨時取消；上傳中也能中斷傳輸。
• PTC 調度：批量轉換可選。在 DSH 已註冊模型裏選一個（默認跟隨主模型），模型只返回每文件 JSON 計劃，宿主校驗後交給 PTC 沙箱執行；低推理檔、分階段進度。默認關閉，耗 token。

README 裏給了一組實測數據（10 秒 1080p30 合成樣本，機器負載約 4.6，不是真實文件）：libx264 veryfast CRF 23 耗時 2.1–2.3 s、產物 6.35 MB、VMAF 95.02；h264_videotoolbox 5 Mbps 兩路並行 3.2 s、產物 6.45 MB、VMAF 95.15；直接拷貝 0.02 s、產物 11.48 MB、VMAF 無。結論是可拷貝時最快，GPU 畫質與 CPU 接近而 CPU 佔用更低。真實文件的分辨率和負載不同，以現場爲準。

三、安裝與啓用¶

已發佈到 npm（dsh-media-converter），一行裝完：

dsh plugin --profile web add dsh-media-converter

web 換成你自己的 profile 名即可。也可以在 Harness 裏用 plugin_manager 的 install_bundle 裝。

從 GitHub 裝（未發佈 npm 時的退路）：

dsh plugin add github:a1121611810/dsh-media-converter --profile <profile>

裝好後左側欄出現「媒體工具箱」。換包名後需要重啓應用：運行中的 Host 會緩存舊包名的客戶端條目，熱裝清不掉。

四、典型用法¶

1、網頁界面裏裁一段視頻¶

1. 在隊列拖入文件。
2. 點這一行的「詳情」進入文件詳情頁。
3. 在動作網格里選「裁一段」，起點/終點可以手填 分:秒，例如裁 0:10 到 1:00。
4. 目標格式選 mp4，參數就地展開，轉換完成後結果就地顯示。

2、批量轉換¶

1. 在隊列勾選多個視頻文件。
2. 頂部「批量處理」卡選「轉換」，目標格式在視頻組標題裏設置。
3. 需要的話勾選「GPU 編碼（VideoToolbox）」。
4. 提交後逐行看進度與結果，中途可以取消。

3、讓 Agent 直接調用¶

工具 media_toolbox 的動作包括 probe（讀時長、分辨率、編碼、音軌、字幕軌、標籤）、convert（轉格式，可帶 trim 裁剪、quality 圖片質量）、extract-audio / extract-video（抽音軌/抽畫面，不重編碼）、subtitle（導出內嵌字幕爲 .srt）、rewrite-tags（改寫標題/作者/專輯/備註/日期/流派）。

輸入框工具排（「+」按鈕那一排）有一個「媒體工具箱」按鈕：點一下把示例指令 把 xx.mov 裁 0:10 到 1:00 轉成 mp4 插進輸入框，改成你自己的文件和區間後發送即可。

五、配置與依賴¶

依賴：ffmpeg¶

插件按順序查找 ffmpeg：config.ffmpegPath → FFMPEG_PATH → PATH → 常見安裝目錄 → imageio-ffmpeg 自帶的靜態包。找不到時頁面頂部會提示安裝方式。沒有 ffprobe 也能用，元數據從 ffmpeg -i 的輸出解析。

配置項¶

設置彈窗側邊欄的「媒體工具箱」頁可直接編輯配置：保存經宿主的 settings 服務校驗並寫入 profile（cordis.patch.yml 裏會出現對應的 config 塊），同時立即應用到運行中的插件，無需重啓。同一個配置也驅動「內置插件」頁裏本插件行的官方配置表單，來自插件導出的 Schemastery schema：

- id: media-converter
  name: 'dsh-media-converter'
  config:
    outputDir: ~/Movies/converted
    ffmpegPath: /opt/homebrew/bin/ffmpeg
    maxUploadMb: 2048

• outputDir：~ 會展開成主目錄，路徑解析成絕對路徑。默認 ~/Downloads/media-toolbox。
• ffmpegPath：找不到 ffmpeg 時手動指定。
• maxUploadMb：單次上傳上限，默認 2048 MB，超了直接拒絕，不寫盤。
• composerButton：是否在輸入框工具排顯示「媒體工具箱」按鈕，默認開。
• groups：文件詳情頁動作模塊的順序與顯隱（convert,edit,view，寫進字符串的才顯示）。

六、適用場景與注意¶

適合需要在 DSH 裏做頻繁、批量、又不希望文件外發的多媒體處理的場景：轉碼、裁預告片、抽音軌、導出內嵌字幕、壓圖改圖、改元數據、Base64 往返。大文件方面，上傳邊收邊落盤、預覽走 HTTP Range、轉碼期間 DSH 界面照常響應，臨時文件放在 $TMPDIR/dsh-media-converter，超過 2 小時自動刪除，插件卸載時也清空。

三點注意：

• 插件以當前 DSH 進程的權限運行，安裝前應先檢查源碼與許可證（本插件爲 MIT）。
• 上傳上限、CPU 調度容量、GPU 編碼開關都取決於本機 ffmpeg 與系統環境，探測不到時相應開關會隱藏。
• PTC 批量轉換默認關閉且消耗 token，只在需要讓模型決定每份文件的目標格式時打開。

七、結尾¶

一句話回顧：dsh-media-converter 把 ffmpeg 的常用操作收進 DSH 的圖形界面和 media_toolbox 工具裏，轉換與裁剪一次完成，兼容時直接 -c copy，本機處理不外發。

目錄頁：https://www.skillhub.cn/plugins/a1121611810/dsh-media-converter
倉庫：https://github.com/a1121611810/dsh-media-converter