前言¶

在 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