📌 本插件已收录于 dshfind 插件超市（GitHub 仓库打 dsh-better-sidebar / dsh-plugin topic 后自动收录），点击上方徽章直达主页。
dsh-video-preview
dsh-better-sidebar 的视频文件预览插件：
在侧边栏打开 .mp4 / .webm / .mov / .mkv / .avi 等视频文件时，内联渲染一个可播放、可拖拽进度条的 <video> 播放器。
背景
better-sidebar 内置的文件预览器只有 image / pdf / markdown / html / code / binary-download，
没有视频预览——视频文件目前会落到 code 视图（乱码）或下载按钮。
直接复用内置的 /sidebar/file 媒体路由也不行：
- 该路由不支持 HTTP Range（整个文件读进内存、返回
200），浏览器无法拖动进度条（seek）；
- 受
mediaLimit（默认 20MB）限制，更大的视频会被直接拒绝。
因此本插件自带一条 支持 Range（206 Partial Content）的 /video/* 宿主路由，
用 createReadStream 分片流式下发，seek / 拖进度条 / 倍速都能正常工作。
功能
- 通过
ctx.betterSidebar.registerFileViewer 注册 video 预览器（id video，与内置 viewer 同权）：
.mp4/.m4v/.webm/.mov/.qt/.mkv/.avi/.wmv/.flv/.ogv/.ogg/.mpeg/.mpg/.3gp/.3g2/.m2ts- 内联
<video controls>：播放/暂停、拖进度条（Range 206）、倍速、全屏、音量、preload=metadata
- 底部文件名 + 「下载」链接（浏览器无法解码的容器格式仍可下载原文件）
- 自带
/video/* 宿主路由：HTTP Range / If-Range / suffix-range（bytes=-N），视频大小不受 mediaLimit 限制
- viewer 描述符带
title/icon，Side card 设置页自动显示启用开关（含 16px 播放器图标）
- 客户端组件自包含：不依赖 better-sidebar 的 client 内部实现，
fetchStrategy: 'none'
依赖 better-sidebar 版本
需要 better-sidebar >= 0.4.0（ctx.betterSidebar.registerFileViewer 服务）。
安装（profile）
前置：DSH 已装好且 dsh web 能运行，已安装 dsh-better-sidebar。
# 从 npm 安装（推荐，发布后生效）：
dsh plugin --profile web add dsh-video-preview
# 本地开发（link: 热更新）：
dsh plugin --profile web add "link:<本目录>"
# 从 tarball 安装（离线 / 未发布）：
dsh plugin --profile web add file:<本目录>/dsh-video-preview-0.1.1.tgz
安装后重启 dsh web 进程并浏览器硬刷新（Cmd/Ctrl+Shift+R）。
说明：新增宿主半（/video 路由）需要重启一次；之后仅 client 改动硬刷新即可。
运行
- 打开侧边栏 → 在文件资源管理器中打开任意视频文件，
video 预览器自动命中；
- Side card 设置页 →「文件预览」清单中可见
Video 卡片（带播放器图标），可单独启用/禁用。
开发与检查
node test/route.test.mjs # 宿主路由回归测试（Range/206/416/403/HEAD/405，19 项）
| 检查项 | 命令 | 预期 |
|---|
| 宿主路由测试 | node test/route.test.mjs | 全部通过 |
| client bundle | node --check client.js | 语法 OK |
| bundle 形态 | 产物首行 | window.__ModuleLoader__.load({ id: 'dsh-video-preview', ... }) |
| 安装状态 | node_modules/dsh-video-preview/client.js 存在 | True |
结构
| 文件 | 作用 |
|---|
index.js | 宿主半：注册 /video/* 前缀路由（Host 头信任围栏 + 会话 cwd 越界检查 + Range/If-Range/suffix-range） |
client.js | 客户端 bundle：经 ctx.betterSidebar.registerFileViewer 注册 video 预览器（fetchStrategy: 'none'，含 16px 图标） |
cordis.patch.yml | dsh.bundle.patch：挂载行（entry name 与包名一致，供 client-modules 发现 client bundle） |
test/route.test.mjs | 宿主路由回归测试（自包含，无需 ffmpeg） |
安全
- 路由复用与
/api 网关相同的 Host 头信任围栏（loopback 或 trustedHosts，拒绝跨站）；
- 解析后的路径必须位于会话权威工作目录内（大小写/分隔符容忍），
.. 无法越界；
- 只读流式下发，不写文件、不设身份。
说明与限制
- 支持浏览器可解码的容器/编码（H.264 的 mp4/m4v、VP8/VP9 的 webm、mov、OGV 等）；
Chrome/Edge/Firefox 不内置解码的格式（如部分 HEVC、AV1 组合）会在播放器内报错，可用「下载」取回原文件；
- 视频大小不受 better-sidebar
mediaLimit 限制；
- 不新建 Tab 页，仅作为文件预览器注册（也可按需再加
registerTab）。
许可证
MIT
