前言¶

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