前言¶
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
