前言¶

在 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