前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，一旦任务涉及本地视频或音频，模型往往只能凭文件名或上下文去猜：时长多少、编码是什么、文件有多大。猜错就要重跑转码或压缩，浪费一轮对话和算力。本机若已安装 ffmpeg，更合理的做法是让 Agent 先「问清楚」再动手。
下面介绍社区插件 dsh-tool-media（维护者 yuehancn）。它把本机 ffmpeg / ffprobe 封装成六个结构化工具，供 DSH 在桌面版或 Web 版 profile 下调用，属于社区目录上的「模型推理」相关扩展；目录页与源码相互独立，并非 DeepSeek 官方应用商店条目。
这是什么¶
dsh-tool-media 是面向 DeepSeek Harness 的自建工具插件：不替代 ffmpeg，而是把探规格、转封装、抽帧、抽音轨、按目标体积压缩等常见操作，变成 Agent 可调用的固定接口。
插件在 README 中声明与 dsh 0.2.0-rc.2（preview）构建并测试；apply(ctx) 插件规范相对稳定，若你使用更新版本的 dsh，需自行对照验证。npm 包名为 @yuehancn/dsh-tool-media，当前资料中版本为 1.0.0，许可证 MIT。
核心功能：六个工具¶
长任务前可先调用 media_status，检查 ffmpeg / ffprobe 是否在 PATH 中可执行、版本信息，并列出可用的转换目标，避免等到超时才发现在本机找不到 ffmpeg。
media_probe(path) 返回结构化事实：时长、体积、码率、封装格式、视频流（编码、分辨率、帧率、像素格式）、音频流（编码、采样率、声道数）及流数量。
media_convert(path, target, ...) 按预设目标转码。资料中列出的 target 包括：
| target | 容器 | 视频编码 | 音频编码 |
|---|---|---|---|
mp4-h264 |
mp4 | libx264 | aac |
mp4-h265 |
mp4 | libx265 | aac |
webm |
webm | libvpx-vp9 | libopus |
gif |
gif | gif | — |
mp3 / wav / aac / flac |
各自容器 | — | 对应编码 |
可选参数包括：width（等比缩放并取偶数宽高）、start 与 duration（裁剪片段）、crf（0–51，数值越小画质越好）、removeAudio（去掉音轨）。
media_frames(path, count | timestamps, format) 从视频中抽帧。默认在整段时长上均匀取帧（而非只取开头若干秒）；也可传入显式时间戳，例如 "0,5,12.5"。
media_audio(path, target, sampleRate, channels) 导出音轨。默认输出 wav；若后续要做语音识别，可指定 sampleRate=16000、channels=1。
media_compress(path, targetSizeMb, audioKbps, width) 按字节预算压缩，而非简单的画质档位。实现上使用 ffmpeg 两遍编码，使输出尽量贴近目标体积而不轻易超出。若预算过小导致算出的视频码率低于 50 kbps，插件会直接报错，提示放宽预算或先裁短素材，而不是 silently 产出不可用的文件。README 中的示意关系如下：
media_probe → 时长 2:13 / 1920x1080 / h264 + aac / 48.2 MB
media_compress(targetSizeMb=10) → 两遍编码，落在 9.8 MB
安装与启用¶
官方一行安装命令如下（资料原文；desktop 可换为 web）：
dsh plugin --profile desktop add github:yuehancn/dsh-tool-media
支持的 profile 为 desktop（桌面版）与 web（Web 版）。安装完成后需重启 dsh 方可使用工具。
本机须能运行 ffmpeg 与 ffprobe。Windows 上 README 建议从 gyan.dev 下载 full build，解压后将 bin 目录写入配置或加入 PATH，执行 ffmpeg -version 能输出版本即可。
配置项¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中可为插件 tool-media 增加 config，例如：
# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: tool-media
config:
ffmpegPath: C:/AI/ffmpeg/ffmpeg-release-full/bin/ffmpeg.exe
ffprobePath: C:/AI/ffmpeg/ffmpeg-release-full/bin/ffprobe.exe
outputDir: C:/Users/you/Videos/media-output
maxFrames: 60
| 字段 | 默认 | 说明 |
|---|---|---|
ffmpegPath |
ffmpeg |
ffmpeg 可执行文件路径 |
ffprobePath |
ffprobe |
ffprobe 可执行文件路径 |
outputDir |
media-output |
输出产物目录 |
timeoutMs |
900000 |
单次调用超时（15 分钟） |
maxFrames |
60 |
单次最多抽取帧数 |
probe / convert / frames / audio / compress / status |
true |
可按需关闭单个工具 |
典型用法思路¶
- 用
media_status确认环境，再对目标文件调用media_probe，把时长、分辨率、编码写进后续决策。 - 需要发给他人或上传平台且有人为体积上限时，用
media_compress传入targetSizeMb，而不是反复试 crf。 - 要做封面或快速浏览内容时，用
media_frames均匀抽若干帧，或指定时间戳。 - 语音转写前用
media_audio导出 16 kHz 单声道 wav。 - 格式不兼容或需要 webm / gif 等时，用
media_convert选对应target，必要时配合裁剪与缩放。
以上步骤均在本机通过子进程调用 ffmpeg 完成；插件 README 说明仅使用 spawn(command, argsArray)，不拼接 shell 字符串；读写范围限于你指定的输入文件与 outputDir，不上传、不联网；-y 仅作用于输出目录内产物，不会覆盖源文件路径。
适用场景与注意¶
适合已经在 DSH 工作流里处理本地音视频、并希望 Agent 能结构化读取元数据与执行转码的开发者。插件以当前 dsh 进程的用户权限运行，安装前建议阅读 GitHub 仓库 源码与 MIT 许可证，确认路径与输出目录符合你的安全策略。
社区目录页：yuehancn/dsh-tool-media。DSH 生态强调「一切皆插件」；SkillHub 等目录站点与 DeepSeek / 幻方无官方从属关系，插件质量与维护节奏以仓库与维护者为准。资料中 GitHub 星标为 0，不代表功能不可用，仅反映当前关注度。
结尾¶
dsh-tool-media 把「猜媒体规格」换成可复用的六次工具调用：先 probe，再 convert、抽帧、抽音轨或按 MB 预算 compress。若你的 Agent 经常碰本地 ffmpeg 任务，可按上文命令安装、配好路径后重启 dsh 试用。
- 目录页：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-media
- 源码与完整说明：https://github.com/yuehancn/dsh-tool-media
