前言¶
DSH Web UI 的內置文檔預覽註冊了 text、PDF、Excel 和圖片，但視頻不在其中。在文件樹裏點開一個 .mp4、.webm 或 .mov，看到的往往是一句 “preview is not available for this file type yet”，要麼就是被平臺 size 上限卡住、只能整段讀完再播放。
下面介紹的 lvxianchao/dsh-video-preview 補齊了這個渲染器：點擊視頻文件就地播放，走一條帶鑑權的 byte-range 路由，支持 seek 和大文件，無構建步驟、零運行時依賴。
這是什麼¶
@lvxianchao/dsh-video-preview，維護者 lvxianchao，MIT 許可證，當前版本 1.1.1，要求 Node.js >= 22.19。分類是客戶端插件。
一句話定位：給 DeepSeek Harness（DSH）Web UI 側邊欄加一個視頻預覽渲染器，覆蓋原來沒有的視頻文件類型。它在社區插件目錄 SkillHub 上單獨列頁，目錄站是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係。
核心功能¶
- 後綴匹配渲染：
mp4/m4v/webm/ogv/ogg/mov，從文件樹、@引用或工作區變更列表點開都可以播放。 - 真流式播放：
<video>直接請求 byte-range 路由（返回206 Partial Content），seek 即時生效；沒有整文件讀取上限，看一個 5 GB 視頻只消耗實際播放的那些字節。 - 靜音自動播放：瀏覽器不允許帶聲音自動播放，因此預覽默認靜音開始，用原生控件點一下即可解除靜音。
- 元信息展示：文件名、容器格式、大小（來自 stat 路由）。
- 失敗可讀：編解碼或容器不支持時明確提示，而不是留一個白屏播放器。
- 零運行時依賴：React 來自宿主，其餘用標準 Node/瀏覽器 API；瀏覽器端是手工寫的
__ModuleLoader__模塊，不需要構建步驟。 - 不與宿主耦合：瀏覽器端走公開的
documentPreviews/slots/locale服務註冊，宿主端走connection.fetch路由，和其它/api路由處於同一瀏覽器鑑權圍欄內。
安裝與啓用¶
官方安裝命令，三種來源任選：
# npm
dsh plugin --profile web add @lvxianchao/dsh-video-preview
# from GitHub
dsh plugin --profile web add "github:lvxianchao/dsh-video-preview"
# from a local checkout
dsh plugin --profile web add /path/to/dsh-video-preview
main 分支只承載已發佈代碼，前兩種遠程形式安裝的都是最新穩定版。安裝後重啓 dsh，Web UI 會在啓動時重新加載前端模塊：
sudo systemctl restart dsh-web # 按你的部署方式調整
包裏聲明瞭 dsh.bundle，所以安裝過程會把包追加到 profile 的 bundle 列表並自動掛載這一行，不需要手工改 cordis.patch.yml。
想先不動現有 profile，可以用 overlay 方式試：
dsh --profile web --patch ./dev.yml --host 127.0.0.1 --port 3099 --no-open
# dev.yml
- insert:
- id: video-preview
name: '/absolute/path/to/dsh-video-preview/lib/index.js'
典型用法¶
- 在輸入框裏輸入
@，選中一個視頻文件（也可以從工作區變更列表裏打開）。 - 點擊文件引用，右側邊欄打開播放器並開始靜音播放。
- 用原生控件拖動進度、解除靜音、全屏。拖動時只會請求新位置附近的字節。
配置¶
只有一個配置項 rangeBytes：
| Key | Default | Meaning |
|---|---|---|
rangeBytes |
2097152 (2 MiB) |
每次流請求返回的字節窗口。瀏覽器在播放過程中連續發起多個range，所以這是延遲/吞吐旋鈕，不是大小上限。 |
# ~/.dsh/profiles/web/cordis.patch.yml
- id: video-preview
config:
rangeBytes: 4194304 # 4 MiB windows
工作原理¶
插件拆成宿主端和瀏覽器端兩部分：
| Half | File | Role |
|---|---|---|
| Host | lib/index.js |
註冊 GET/HEAD /api/video-preview.stream（通過 workspaceFiles.readBytes(range) 提供 byte range，返回 206 + Content-Range），以及 GET /api/video-preview.stat（大小/版本/類型），掛載在 connection.fetch 上 |
| Browser | lib/client.js |
註冊渲染器元信息（loading: "renderer"）和帶 key 的文檔主體；渲染 <video src=…> 指向流路由，並上報加載的版本 |
渲染器用 loading: "renderer"，因此預覽框架永遠不會對視頻文件做整字節讀取——這正是把平臺 32 MB 整文件上限從視頻路徑上移除的原因。
瀏覽器端不需要構建步驟，它本身就是宿主 loader 直接認識的模塊格式：
window.__ModuleLoader__.load({ id: "@lvxianchao/dsh-video-preview", factory: (require) => { /* … */ } });
限制與適用場景¶
適合：已經在用 DSH Web UI、希望在側邊欄直接看視頻，或需要處理大視頻文件的用戶。安裝前應檢查源碼與許可證（MIT），並注意插件以當前 dsh 進程權限運行。
已知限制，README 已列明：
| Limit | Cause | Workaround |
|---|---|---|
不支持 mkv |
Chrome 無法解碼 Matroska | 重封裝爲 mp4/webm |
| 依賴編解碼器 | 瀏覽器只能播放平臺能解碼的內容，HEVC/AV1 表現不一 | H.264/AAC 的 mp4 最穩 |
| Session 必須可解析 | 流路由按文件地址中的 session 解析文件 | 來自活躍 session 的預覽總能解析；session 消失則 404 |
| 僅已鑑權瀏覽器可用 | 路由在其餘 /api 的同一鑑權圍欄內 |
這是設計意圖，不做未鑑權文件分發 |
如果要在公網暴露 Web UI，README 建議同一作者的 dsh-web-guard 加在前面。本插件只改文件如何預覽，不改誰能打開：如果 UI 的可達範圍超出 loopback，需要在前面放 dsh-web-guard。
結尾¶
這個插件的價值在於補齊 DSH 側邊欄的視頻渲染缺口，並把原始 Blob 方案裏 32 MB 整文件上限的問題改成 byte-range 流式讀取。零運行時依賴、無構建步驟，接入成本低；限制也清楚寫在README裏。
目錄頁：https://www.skillhub.cn/plugins/lvxianchao/dsh-video-preview
GitHub：https://github.com/lvxianchao/dsh-video-preview
