前言¶
DeepSeek Harness 的文檔預覽目前支持文本、Markdown、代碼、圖片、PDF、HTML 以及 Office 文檔和表格，但不支持音頻和視頻。打開 mp4、mp3、wav 等文件時，預覽區會提示 “Preview is not available for this file type yet”，只能通過頂部的 Open 按鈕在宿主機上用原生應用打開。在宿主機上沒問題，但在遠程瀏覽器（例如手機、另一臺電腦或 Tailscale 對等節點）上打開，就會在用戶看不到的屏幕上彈出窗口。
dsh-media-web-preview 爲 DSH 右側邊欄添加了原生播放器，支持音頻和視頻的即時預覽與跳轉。
插件介紹¶
dsh-media-web-preview 是一個 DSH 插件，由維護者 wilsonchengassistant 開發，分類屬於「聯網工具」。它註冊了 video 和 audio 兩種文檔渲染器，在右側邊欄的文檔預覽區嵌入瀏覽器原生播放器。插件通過一個帶認證的 HTTP Range 路由 /api/media 流式傳輸文件，使得遠程瀏覽器可以播放和跳轉大文件，而無需在宿主機上打開本地應用。
核心功能¶
- 原生播放器控制：支持播放/暫停、跳轉、音量、全屏（視頻），以及瀏覽器的畫中畫功能。
- 按需流式讀取：利用 HTTP
Range請求（206 Partial Content和Content-Range），播放器按需請求字節片段，大視頻無需將整個文件讀入內存或對話上下文。 - 遠程瀏覽器可用：URL 爲文檔相對路徑，支持
http://127.0.0.1:3080、局域網地址、Tailscale MagicDNS 名稱或tailscale serve端口 80，無需額外配置。 - 下載與新標籤打開：播放器下方提供下載和在新標籤頁打開的操作。
- 本地化界面：提供英文和簡體中文字典。
- 零運行時依賴：僅包含一個宿主機模塊和一個瀏覽器打包文件。
支持的格式：
| 類型 | 後綴 |
|---|---|
| 視頻 | mp4, m4v, webm, ogv, mov, mkv, avi, mpg, mpeg, 3gp, 3g2, ts, m2ts |
| 音頻 | mp3, m4a, m4b, aac, wav, flac, ogg, oga, opus, weba, aiff, aif, wma, mid, midi |
安裝與啓用¶
從 npm 安裝：
dsh plugin --profile web add dsh-media-web-preview
從本地目錄安裝：
dsh plugin --profile web add file:/absolute/path/to/dsh-media-web-preview
dsh plugin add 會記錄依賴並將包追加到 dsh.profile.bundles。插件自帶 dsh.bundle.patch，無需在 cordis.patch.yml 中手動添加 insert: 行。
宿主機端會熱掛載插件到正在運行的 dsh web，刷新頁面一次讓瀏覽器包進入模塊圖；如果構建只在啓動時組合插件，則重啓 dsh web。
在右側邊欄的 Files 標籤頁打開任意支持格式的文件，播放器即可出現。頂部的原生 Open 菜單仍然可用。
爲什麼需要一個獨立的媒體路由¶
DSH 已有 GET /api/file 路由，用於圖片和 Markdown 預覽。該路由總是返回完整 200 響應，忽略 Range 請求，且默認限制響應體大小約 20 MB。這對圖片和文本預覽是合適的，但對視頻毫無用處：無法跳轉，大文件會直接返回 413 Payload Too Large。爲了避免改動共享路由，本插件新增了一個支持 Range 的兄弟路由 /api/media：
| 特性 | /api/file |
/api/media |
|---|---|---|
| 完整響應 | 200 |
200 |
Range 請求 |
忽略，返回完整 200 |
206 + Content-Range |
| 跳轉 | 必須下載整個文件 | 即時 |
| 響應體大小限制 | ~20 MB | 受文件系統限制 |
| 讀取方式 | 整個文件緩衝 | 通過 ctx.fs.readByteRange 每次讀取 1 MiB 塊 |
兩個路由都位於 /api 下，因此共享同樣的 Host/Origin 檢查和瀏覽器 Cookie 認證。
技術實現¶
宿主機端：
- 通過
ctx.connection.fetch.register({ path: '/api/media', methods: ['GET', 'HEAD'] })註冊路由。 - 請求通過
ctx.fs解析，解析Range頭部爲閉區間。 416錯誤攜帶bytes */<size>，HEAD請求僅返回頭部，download=1參數添加Content-Disposition: attachment。- 響應攜帶
Cache-Control: private, no-store和X-Content-Type-Options: nosniff。
瀏覽器端：
- 通過
ctx.documentPreviews註冊渲染器，設置loading: 'renderer'，將文件後綴聲明爲二進制，避免回退到文本預覽。 - 播放器從資源地址讀取絕對路徑，構建文檔相對路徑的
api/media?path=…URL，調用content.loaded(version)結束加載狀態。
安全說明¶
- 路由位於
/api下，繼承 DSH API 的認證和 Host/Origin 檢查，未認證請求返回401，不受信 Host 返回403。 - 僅接受絕對路徑，不提供目錄列表，不會繞過文件系統提供者的解析和訪問策略。
- 響應頭包含
Cache-Control: private, no-store和X-Content-Type-Options: nosniff。 - 無遙測、無出站網絡請求、無運行時依賴。
兼容性與使用範圍¶
- DSH
0.2.0-rc.2及之後版本，需提供ctx.documentPreviews、sidebar.right.tab.document、ctx.connection.fetch和ctx.fs.readByteRange。 - Node.js 22+。
- 也可在 DSH 桌面應用中使用，此時媒體路由爲文檔相對路徑。
本插件聚焦於默認右側邊欄和遠程瀏覽器播放，不提供播放列表、字幕軌道、播放速度控制和對話中的內聯媒體卡片，這些由其他社區插件覆蓋。
結尾¶
dsh-media-web-preview 解決了 DSH 在遠程場景下無法預覽和跳轉音視頻的問題，通過 HTTP Range 路由實現流式讀取，適合需要在遠程瀏覽器中處理媒體文件的智能體開發者。
- 插件目錄頁：https://www.skillhub.cn/plugins/wilsonchengassistant/dsh-media-web-preview
- GitHub：https://github.com/wilsonchengassistant/dsh-media-web-preview
