前言¶

在 DSH（DeepSeek Harness）生态中，文件处理通常依赖插件分发。当需要处理本地媒体文件时，直接将大文件转换为 Base64 字符串会占用大量内存，而依赖外部链接又存在稳定性和隐私风险。dock-media 插件解决了这一痛点，它直接在浏览器端通过 HTTP Range 请求流式读取本地文件，实现音频和视频的即时播放。

它是什么¶

dock-media 是一个运行在 DSH Web 环境下的客户端插件，由维护者 AKS1st 开发。它为 dock-files 文件域注册了 media 文件查看器，能够识别音频和视频文件，并通过自有的 /dock-media/source 主机路由提供流式传输服务。

核心功能¶

1. 双模式播放
   插件根据文件类型自动切换视图：纯音频文件（如 MP3、WAV）进入音乐播放器模式，展示旋转唱片和均衡器动画；视频文件（如 MP4、WebM）则调用原生全屏播放器。

2. 流式传输
   不依赖整文件 Base64 编码，而是通过 HTTP Range 请求（状态码 206）分片返回文件字节。这支持大文件秒开、进度条拖拽定位，以及边下载边播放。

3. 音乐播放器控制
   音乐播放器提供完整的播放控制：播放/暂停、进度拖动、当前/总时长显示、音量调节、静音、播放速度调节（0.5x–2x）以及单曲循环功能。

4. 元数据与徽章
   通过 /dock-media/probe 接口（POST 请求）可获取文件大小与媒体种类。播放器头部会实时显示文件格式徽章与大小信息。

5. 优雅降级与安全

   • 降级：对于浏览器无法解码的封装或编码（如 AVI、FLV、WMV、MIDI、WMA），插件会给出明确提示，而非黑屏。
   • 安全：媒体解码完全交给原生 <audio> 和 <video> 标签，不使用 innerHTML 或危险 DOM 注入方式。

安装与启用¶

该插件依赖 dock 和 dock-files 插件。在安装前，请确保这两个插件已就绪。

dsh plugin --profile web add dock-base
dsh plugin --profile web add dock-files
dsh plugin --profile web add dock-media

典型用法¶

1. 在 dock-files 文件域中浏览文件列表。
2. 点击 MP3、WAV、FLAC 等音频文件，或 MP4、WebM、MOV 等视频文件。
3. 系统会自动识别文件类型并打开对应的播放器。
4. 通过 /dock-media/source 路由访问媒体流，支持 HTTP Range 请求。

安全与注意事项¶

• 路由安全：/dock-media 路由仅接受受信任来源的请求，包括回环地址（localhost）以及通过 trustedHosts 配置的域名，并进行同源检查。
• 文件访问：读取路径仅需为绝对路径，不限定在当前会话工作区内，也不限定读写权限（仅限只读）。
• 格式限制：.ts 文件由 dock-editor 处理，dock-media 不接管。
• 解码能力：浏览器能否解码头由解码器决定，插件无法绕过浏览器限制播放所有格式（如 AVI、FLV 在多数浏览器中无法解码）。

结尾¶

dock-media 提供了一种轻量级、内存友好的方式在 DSH 工作台内播放本地媒体。通过 HTTP Range 流式传输和原生标签渲染，它兼顾了性能与安全性，适合需要频繁处理本地音视频资源的场景。

• 文档与目录：dock-media Catalog
• 源码仓库：github.com/AKS1st/dock-media