前言¶
在 DeepSeek Harness（DSH）里做智能体，常见做法是上传附件或让模型「看一张图」。音频波形、频谱、Whisper 转写，以及需要保留时间轴的视频理解，往往要另起脚本、本地服务或旧版 Local AI 应用。工具链分散时，权限边界和 GPU 占用也不好在一次会话里统一管。
下面介绍社区插件 dsh-media-tools（维护者 averyjohnkucan-arch）。它在 DSH/Cordis 侧注册独立可切换的音视频插件，同时提供 Agent Skills、CLI 与 stdio MCP 服务；按需接入 Omni 听音与原生时序视频后端，README 写明旧版 Local AI v2 应用不必常驻运行。
这是什么¶
dsh-media-tools（npm 包名 dsh-media-tools，当前版本 0.2.2，MIT 许可证）是一套面向 DSH 的客户端类媒体工具集：两个彼此独立的 DSH/Cordis 插件、对应 Agent Skills、命令行与 MCP 服务，并内置按需的 Omni 听音与原生时序视频后端。
目标环境为 DSH 0.2.1-rc.2 与 Cordis ~4.0.5（见 package.json 的 peer 依赖）。插件在 SkillHub 目录 归类为客户端；该目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
两个可独立启用的插件¶
| 插件 | 可选工具 |
|---|---|
| Audio | analyze_audio、edit_audio、convert_audio、transcribe_audio、listen_audio |
| Video | probe_video、convert_video、analyze_video |
音频：分析可返回内联波形/FFT/频谱图/瀑布图、数字电平与数值频谱；编辑会生成新 WAV；转换支持抽轨及 WAV/FLAC/MP3/M4A/OGG，以及 MP4/WebM/GIF；CPU Whisper 提供带时间戳的语音转写；Omni 提供可能出错的听音描述。
视频：原生视频路径保留时序帧、对齐音频与引擎证据；analyze_video 面向具备原生时序视频能力与兼容 engine/projector 的模型（README 列举 Flash 3.8、Flash Next、Qwen 3.6 35B-A3B、Qwen 27B 等部署标签，并说明并非完整兼容性矩阵）。
DSH 集成行为¶
通过 npm pack 与 dsh plugin add 安装后，包会插入 dsh-media-audio 与 dsh-media-video，可分别开关；使用 DSH 工具注册、附件、prompt 段与 Cordis 生命周期清理，无需改宿主源码。关闭任一插件会取消其自有任务并移除注册，不会删除已生成文件或模型。也可参考仓库内的 audio.patch.yml、video.patch.yml 单独插入。
在已安装 DSH 的环境里，modelScheduler 服务可协调 GPU 准入；工作进程持有包内锁，避免与无关 GPU 占用方冲突。同一 DSH profile 下不要既装直连插件又在 MCP 里重复注册同名工具。
CLI 与 MCP¶
- CLI：
dsh-media（src/cli.mjs）、自检doctor。 - MCP：
dsh-media-mcp（src/mcp.mjs），官方 MCP SDK，暴露上述八个工具，可返回绘图块、保存文件与报告 JSON。
输出落在唯一的 .dsh-media 目录，原文件不改。CLI/MCP 路径相对于显式授权的 workspace；DSH 内可使用最近一次单文件上传或附件 ID。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前请自行审阅 GitHub 源码 与许可证（THIRD_PARTY_NOTICES.md、provenance.json）。
主机前提（README）：Python 3.12（venv/pip）、NVIDIA 驱动；完整后端安装会装 CUDA 用户态库。原生可执行包当前面向 Linux x64 / CUDA 13；Windows/macOS GPU 未声明可用。CPU 工具在可用处使用平台 FFmpeg 依赖。Node >= 22.19.0。FFmpeg/FFprobe 通过固定 npm 依赖自动安装。
1、安装 Skills 与运行时¶
在取得仓库副本后进入目录，执行官方安装脚本（会写入 ~/.agents/skills、 ~/.local/share/dsh-media-tools 并配置 ~/.config/dsh-media/config.json）：
cd dsh-media-tools
npm ci
node src/install.mjs --setup-python \
--include-backends --local-ai '/path/to/Local AI version 2'
说明：安装过程仅一次把 V2 当作导入源，复制原生可执行文件到自有缓存并复用模型存储；V2 应用与推理伴侣可保持停止。Linux 在未指定 --python 时，还会导入可用的独立 Python 发行版到包内存储。移动插件检出目录不会破坏已装 Skills。
新机且模型单独管理时，可将 --local-ai 换为 --backend-config /path/to/backend-models.json。仅 CPU 工具可省略 --include-backends 与 --local-ai，并用 --whisper-model /path/to/faster-whisper-model 配置语音。卸载：node src/install.mjs --uninstall（仅移除自有且未改动的 Skills，保留模型、配置与工作区输出）。
模型体积需单独规划：Omni 加 projector 约 21 GB；原生视频可能更大。详见仓库 docs/standalone-backends.md。
2、作为 DSH 插件安装¶
在选定的 DSH profile 中打包并添加（路径改为本机绝对路径）：
npm pack
dsh plugin --profile web add /absolute/path/dsh-media-tools-0.2.2.tgz
安装器不会修改正在运行的 DSH profile，也不会自动重载 DSH。
3、（可选）配置 MCP 客户端¶
安装脚本会打印运行时路径。在 MCP 客户端中加入（args 中的路径按安装结果填写）：
{
"mcpServers": {
"dsh-media": {
"command": "node",
"args": ["/installed/runtime/src/mcp.mjs", "--workspace", "/authorized/workspace"]
}
}
}
GPU 任务需允许较长工具超时。Codex 的配置语法见 官方 MCP 文档。
典型用法¶
先做环境检查：
node src/cli.mjs doctor
音频分析（30 秒片段、8192 FFT）：
node src/cli.mjs analyze_audio --workspace /path/to/workspace \
--args '{"source_path":"recording.mp3","duration_seconds":30,"fft_size":8192}'
Omni 听音：
node src/cli.mjs listen_audio --workspace /path/to/workspace \
--args '{"source_path":"recording.mp3"}'
时序视频问答：
node src/cli.mjs analyze_video --workspace /path/to/workspace \
--args '{"source_path":"clip.mp4","question":"Describe the events in timestamp order."}'
转换示例见仓库 docs/conversion.md。开发侧可 npm ci && npm test；可选 DSH_MEDIA_PYTHON 指定解释器。
适用场景与限制¶
适合：已在用 DSH/Cordis，希望在同一 harness 里做可测量的音频分析、格式转换、Whisper 转写、Omni 听音描述，以及在支持原生时序视频的模型上做带时间轴的视频理解；或希望通过 MCP/CLI 在授权 workspace 内复用同一套工具。
限制与注意（均来自 README）：
- 数值音频片段最多 120 秒、2500 万 channel-samples；输入最大 2 GiB。
- CPU 转写与转换/编辑上限 2 小时；转换默认只处理前 30 秒。
- 电平单位为 dBFS，非校准 SPL；Whisper 似然度不是正确率百分比；Omni 描述可能幻觉，应对照测量结果。
- 捆绑原生路径：约 6 FPS、15 秒窗口、3 秒重叠，含 SVE2 记录与 M-RoPE 轨迹；不以独立静帧替代时序视频。
- 便携 CPU runner 做路径检查而非 OS 沙箱；Linux GPU 后端在自有进程与有界输入下运行。MCP 客户端无法控制其他应用的私有 scheduler：独立 GPU 推理前需卸载无关常驻模型。
结尾¶
dsh-media-tools 把音视频分析、转换、转写、听音描述与时序视频推理收成 DSH 可开关插件，并可选 Skills、CLI 与 MCP，减少为媒体任务单独维护本地应用的开销。查阅目录说明与 issue 可访问 SkillHub 插件页 与 GitHub 仓库。
