前言¶

在 DeepSeek Harness（DSH）的 web GUI 中，dsh-better-sidebar 提供了侧边栏文件树。浏览到音视频文件时，如果只能在外部播放器里打开，操作链路会比较长。tsonglew/dsh-media-preview 解决的是这个问题：它在侧边栏文件树中注册一个文件查看器，让支持的音频和视频文件直接内联播放。

下面介绍这个插件的定位、核心能力、安装方式、可选配置，以及使用时的注意事项。

这是什么¶

dsh-media-preview 是一个面向 DSH web GUI 的插件，包名为 dsh-media-preview，当前仓库版本为 0.1.0，许可证为 MIT，维护者是 tsonglew。

它的作用很集中：

• 在 dsh-better-sidebar 中注册为 FileViewer
• 让音频和视频文件在侧边栏中直接播放
• 使用浏览器原生控件播放
• 通过独立流式路由 /media-preview/file 提供媒体内容

GitHub 地址：

https://github.com/tsonglew/dsh-media-preview

核心能力¶

在侧边栏中内联播放¶

安装启用后，打开侧边栏文件树中的音频或视频文件时，插件会把文件作为可播放媒体处理。播放使用原生控件，不需要额外安装本地播放组件。

独立流式路由¶

插件提供独立路由：

/media-preview/file

这个路由用于提供媒体流。根据已核实的资料，它具备以下能力：

• 支持 HTTP Range（206）seeking，适合长视频拖动进度
• 使用 fs.createReadStream 流式返回响应，不做整文件缓冲

支持的文件识别¶

插件支持两类文件识别方式：

1. 按扩展名识别
2. 对无扩展名媒体做 magic-byte sniffing

已核实支持的 magic-byte 标识包括：

ftyp
EBML
OggS
fLaC
RIFF/WAVE
RIFF/AVI
ID3
MP3 frames

信任边界¶

插件在提供媒体时会使用 loopback Host 和 same-origin marker trust fence。

如果需要扩展可访问的主机范围，可以通过可选配置项 trustedHosts 添加额外的非 loopback authorities。

支持格式¶

已核实支持的视频扩展名：

mp4 webm mov m4v mkv avi ogv ts 3gp flv

已核实支持的音频扩展名：

mp3 wav ogg oga m4a aac flac opus weba wma

安装与启用¶

先确认运行环境满足以下要求：

Node.js >= 22
dsh-better-sidebar >= 0.4.0
@deepseek-ai/cordis >= 4.0.1
@deepseek-ai/schemastery >= 3.18.1

其中 dsh-better-sidebar >= 0.4.0 会暴露 ctx.betterSidebar.registerFileViewer，这是本插件注册文件查看器所需的能力。

安装命令：

dsh plugin --profile web add github:tsonglew/dsh-media-preview

这条命令会把插件安装到 web profile 中。

可选配置¶

以下字段都是可选配置，位于 profile patch layer：

- id: media-preview
  config:
    maxMediaBytes: 2147483648  # 单个服务文件的硬上限，默认 2 GiB
    trustedHosts: []           # 额外的非 loopback authorities

配置项说明：

• maxMediaBytes：单个被服务文件的大小硬上限。默认值为 2147483648，即 2 GiB。
• trustedHosts：用于添加额外的非 loopback authorities。默认可以保持空数组。

典型用法¶

经过上面的安装步骤后，使用方式比较简单：

1. 在 DSH web GUI 中打开 dsh-better-sidebar 的文件树
2. 选择一个受支持的媒体文件，例如 .mp4、.webm、.mkv、.mov
3. 或者选择一个受支持的音频文件，例如 .mp3、.flac、.wav
4. 文件会在侧边栏中内联播放，并使用原生播放控件

这个流程不需要额外打开外部播放器。

适用场景与注意¶

适合的使用场景是：在 DSH web GUI 的侧边栏文件树中快速预览本地音频或视频文件，尤其是需要拖动长视频进度的场景。

需要注意：

• 插件会按照当前 dsh 进程所具备的权限访问和提供媒体文件。
• 安装前应先检查插件源码和 MIT 许可证。
• trustedHosts 会扩展可信任的非 loopback authorities，只在明确需要时配置。
• maxMediaBytes 会限制单个服务文件的大小上限，默认 2 GiB。

结尾¶

tsonglew/dsh-media-preview 是一个小而具体的 DSH web 端插件：它为 dsh-better-sidebar 增加音视频内联预览，通过独立流式路由提供 Range seeking 和流式响应，适合在侧边栏中直接查看媒体文件。

GitHub 地址：

https://github.com/tsonglew/dsh-media-preview