前言¶
在 DSH（DeepSeek Harness）的插件化用法裏，agent 常需要調用外部工具完成具體任務。視頻處理如果靠臨時 shell 腳本，往往要反覆處理命令拼裝、參數邊界、進程超時和輸出覆蓋。dsh-ffmpeg 是一個 DSH 視頻處理工具插件：它用本機 ffmpeg/ffprobe 提供探測、剪輯、拼接、轉碼、字幕、提取與 GIF 七類工具。
這是什麼¶
dsh-ffmpeg 是一個 MIT 許可證的 DSH 視頻處理工具插件，倉庫地址爲：
https://github.com/STARDUSTLC666/dsh-ffmpeg
資料稱其在 @deepseek-ai/dsh@0.1.1-rc.2 上驗證（2026-08-26）。package.json 要求 node >=22。插件零運行時依賴，但需要本機可運行 ffmpeg。
核心功能¶
下面介紹已列出的七類工具。
ffmpeg_probe¶
探測媒體信息，包括格式、時長、分辨率、幀率、碼率、音軌、字幕軌。多視頻流時返回完整 videos 列表。
ffmpeg_cut¶
剪輯片段。默認流拷貝，速度快；也可按需求精確重編碼。
ffmpeg_concat¶
拼接 2-20 個片段。同編碼場景可流拷貝，混合編碼場景可重編碼。
ffmpeg_encode¶
轉碼。支持 bilibili-1080p、4K、豎屏 1080p、web-720p 等預設，也可覆蓋 crf、fps、scale。
ffmpeg_subtitle¶
燒錄 SRT/ASS 硬字幕。
ffmpeg_extract¶
提取 m4a 音軌、抽幀序列、單幀或字幕流。
ffmpeg_gif¶
從視頻生成 GIF，使用兩遍調色板方式提高質量。
運行約束¶
- 所有參數以獨立 argv 數組傳遞，不經過 shell。
- 進程走 DSH 官方 subprocess 服務。
- 超時由 AbortSignal 觸發樹級終止：
SIGTERM後強殺；Windows 使用taskkill /T。 - 默認不覆蓋同名輸出，自動加序號；輸出與輸入相同時直接拒絕。
- 單次操作超時範圍鉗制在 10 秒 - 2 小時；探測額外限制 60 秒。
安裝與啓用¶
先確認本機 ffmpeg 可用：
ffmpeg -version
然後在目標 profile 中安裝插件：
dsh plugin --profile web add dsh-ffmpeg
如果 ffmpeg 不在 PATH 上，可在 profile 的 cordis.patch.yml 中覆蓋本插件行：
- id: ffmpeg
name: 'dsh-ffmpeg'
config:
ffmpegPath: C:\tools\ffmpeg\bin\ffmpeg.exe
ffprobePath: C:\tools\ffmpeg\bin\ffprobe.exe
timeoutMs: 300000
也可使用環境變量：
DSH_FFMPEG_PATH
DSH_FFPROBE_PATH
卸載命令爲：
dsh plugin --profile web remove dsh-ffmpeg
卸載後重啓 Web 服務。如需徹底清理，再手動刪除自己 profile 的 cordis.patch.yml 中覆蓋的插件行。
典型用法¶
下面是資料中給出的示例：
ffmpeg_probe { input: E:\videos\raw.mp4 }
ffmpeg_cut { input: E:\videos\raw.mp4, start: 10, end: 30 }
ffmpeg_encode { input: E:\videos\raw.mp4, preset: bilibili-1080p }
ffmpeg_subtitle { input: E:\videos\raw.mp4, subtitle: E:\videos\subs.srt }
ffmpeg_gif { input: E:\videos\raw.mp4, duration: 3, width: 480 }
這些示例覆蓋探測、剪輯、轉碼、字幕燒錄和 GIF 生成。使用時可先探測輸入文件，再根據返回的時長、流信息和分辨率選擇剪輯或轉碼參數。
適用場景與注意¶
適合在 DSH agent 流程中自動化處理本地視頻素材，例如先探測再剪輯、轉碼、加字幕或導出 GIF。
需要注意：
- 插件會啓動
ffmpeg/ffprobe子進程，因此會運行在當前 DSH 進程可訪問的環境與權限範圍內。 - 安裝前應檢查源碼、配置項和 MIT 許可證。
- 本機必須已安裝可用
ffmpeg。 - 默認防覆寫同名輸出；輸出與輸入相同時直接拒絕。
- 單次操作有 10 秒 - 2 小時超時範圍，探測額外限制 60 秒。
結尾¶
dsh-ffmpeg 的價值在於把常見 ffmpeg 視頻操作封裝成 DSH 工具，減少 shell 拼裝、進程管理和輸出覆蓋等重複工作。資料未提供目錄頁 URL；GitHub 地址爲：
https://github.com/STARDUSTLC666/dsh-ffmpeg
