前言¶
在 DeepSeek Harness（DSH）中，右側邊欄的文檔預覽目前支持文本、代碼、Markdown、圖片、PDF、HTML、Office 和表格等格式，但視頻和音頻被標記爲已知二進制容器，打開後會顯示一個圖標和一行提示，無法直接播放。對於需要查看本地視頻或音頻的開發者來說，這種體驗會打斷工作流。
dsh-preview-media 是一個客戶端插件，爲 DSH 添加了原生視頻和音頻預覽能力。它通過註冊新的文檔預覽實現，將瀏覽器原生 <video> 和 <audio> 元素嵌入右側預覽面板，並利用 HTTP Range 請求實現流式傳輸，使大文件無需全部載入內存，同時支持桌面端的進度條拖動和倍速控制。
是什麼¶
- 插件名稱：dsh-preview-media
- 維護者：439436269-ctrl
- 版本：0.1.5
- 許可證：MIT
- 分類：客戶端
這是一個爲 DeepSeek Harness 添加媒體預覽能力的插件，支持 .mp4、.mov、.mkv、.webm 等視頻後綴，以及 .mp3、.flac、.wav 等音頻後綴。插件通過註冊兩個文檔預覽實現：dsh-preview-media/video（視頻）和 dsh-preview-media/audio（音頻），優先級設置爲按後綴匹配，加載模式爲渲染器而非純文本回退。
核心功能¶
原生播放器集成¶
插件在右側預覽面板中嵌入瀏覽器原生的 <video> 和 <audio> 元素，使用 object-fit: contain 確保視頻和音頻在面板內完整顯示，豎屏或橫屏內容都能一次顯示，多餘部分以黑邊填充。視頻支持倍速切換（1× → 1.25× → 1.5× → 1.75× → 2× → 0.5× → 0.75×）、循環播放、全屏和畫中畫。音頻也支持倍速和循環，並顯示文件名和大小信息。
HTTP Range 流式傳輸¶
插件在 Host 上註冊路由 GET|HEAD /api/preview/media?path=<絕對路徑>，支持 HTTP Range 請求。服務器按 1 MiB 的塊大小通過 ctx.fs.readByteRange 讀取文件，返回 200、206（部分內容）或 416（無法滿足的窗口）狀態碼，並附帶 Accept-Ranges: bytes 和 Content-Range 頭。這意味着大文件（例如 2 GB）不會一次性載入內存或對話上下文，而是按需流式傳輸。
桌面端可拖動進度條¶
在桌面應用中，DSH 通過自定義協議 dsh-app://app 加載預覽頁面。Chromium 的媒體堆棧無法正確識別自定義協議響應的 seekable 屬性，導致進度條拖動後會自動回跳。插件通過在本地監聽一個臨時端口（127.0.0.1），並將瀏覽器重定向到該 loopback 源進行流式傳輸，使普通 HTTP Range 請求正常工作，從而支持桌面端進度條拖動。
認證與權限隔離¶
路由位於 /api/ 下，經過 DSH 的 Host/Origin 防護和瀏覽器會話 Cookie 檢查，確保跨站頁面無法通過該路由訪問本地文件。loopback 監聽器僅綁定 127.0.0.1，且每個請求必須在路徑中攜帶啓動時頒發的令牌，否則返回 404。文件讀取仍通過 DSH 的 fs 提供者，因此文件系統權限策略仍然生效。
安裝與啓用¶
使用官方安裝命令：
dsh plugin --profile <profile> add dsh-preview-media
安裝後重啓桌面應用（配置變更在啓動時讀取）。默認配置已覆蓋常見後綴，無需額外配置即可使用。
驗證插件是否加載：在 Files 標籤頁打開任意 .mp4 文件，右側預覽面板應顯示播放器，而不是“不支持此格式”的提示。
典型用法¶
打開任意支持的視頻或音頻文件，右側邊欄會自動切換到對應的預覽渲染器：
- 視頻文件（如
.mp4、.webm）：顯示播放器，支持倍速、循環、全屏、畫中畫。 - 音頻文件（如
.mp3、.flac）：顯示文件名、大小和播放器，支持倍速和循環。
播放器支持通過瀏覽器原生控件拖動進度條（桌面端）或使用倍速控制。
適用場景與注意¶
- 適合需要頻繁查看本地視頻或音頻的開發者，尤其是需要快速預覽而不切換到外部播放器的場景。
- 播放能力取決於瀏覽器支持的編解碼器。Chromium/Electron 可播放 MP4（H.264/AAC）、WebM（VP8/VP9/Opus）、Ogg 和大部分音頻格式；Matroska（
.mkv）和 AVI 在 Chromium 中通常無法解碼，會顯示錯誤提示，此時可使用系統播放器打開。 - 插件以當前 DSH 進程的權限運行，安裝前建議檢查源碼和許可證。
- 確保本地網絡配置未阻塞 loopback 源（如防火牆策略），否則桌面端進度條可能不可用，但文件仍可通過認證路由播放。
結尾¶
dsh-preview-media 通過原生播放器集成、HTTP Range 流式傳輸和桌面端 loopback 適配，讓 DeepSeek Harness 的文檔預覽支持視頻和音頻。適合需要在 DSH 中快速預覽本地媒體內容的開發者。
- 目錄頁：https://www.skillhub.cn/plugins/439436269-ctrl/dsh-preview-media
- GitHub：https://github.com/439436269-ctrl/dsh-preview-media
