视频预览 chenyitao123/dsh-video-preview

dsh-video-preview

为 DeepSeek Harness（DSH） 右侧「文档预览」面板增加视频播放能力的本地增量插件：打开 .mp4 / .m4v / .webm / .mov / .ogv 时显示播放器，支持播放、暂停、拖动进度；不修改 DSH 自带文件，可随时整体卸载。

English: a local, additive DSH plugin that teaches the Sidebar document preview to play video files
(streaming over HTTP, in-memory playback on the Desktop shell so seeking works). No shipped DSH file is
modified; removing the bundle restores the original behavior. See English quick start.

1. 功能

- 在右侧文档预览 / 浮层面板中直接播放视频，替换原来的「该格式文件暂时无法预览」空状态。
- 拖动进度、音量、倍速等使用浏览器原生 控件。
- 已经打开着的「不可预览」视频标签会在插件加载后自动切换为播放器，无需刷新页面。
- 其他预览器（文本 / Markdown / 代码 / 图片 / PDF / HTML / Office / Excel）行为完全不变。
- 可随时删除：plugin_manager remove_bundle @local/dsh-video-preview。

2. 背景与根因

- 缺少渲染器：DSH 的 @deepseek-ai/dsh-client-ui-sidebar-documentpreview 只注册了文本 / Markdown / 代码 / 图片 / PDF / HTML / Office / Excel 渲染器；mp4、webm、mov 等被列入 UNVIEWABLE_BINARY_EXTENSIONS，没有匹配渲染器时固定显示「该格式文件暂时无法预览」。
插件通过公开的 ctx.documentPreviews.register(...) + keyed 槽 sidebar.right.tab.document 注册一个视频渲染器，即可复用整套文档预览外壳（标签、路径栏、刷新、自动刷新）。
- Desktop 拖动进度不可用：Desktop 页面来自自定义协议 dsh-app://app/，响应由 Electron 主进程合成后返回；Electron 已知缺陷使这类媒体响应不可 seek（video.seekable.end() === 0），即使返回正确的 206 / Content-Range。上游 issue： electron#38749、 electron#51442。
本项目不改 Electron 主进程，而是在渲染器里按页面来源选择播放方式。

3. 方案与实现

浏览器 Host（同一 DSH 进程） ┌─────────────────────────┐ ┌────────────────────────────────────┐ │ @local/dsh-video-preview│ │ @local/dsh-video-preview (index.js)│ │ client.js │ │ GET/HEAD /api/video-preview │ │ · documentPreviews │ │ · 校验 session + 路径 + 扩展名 │ │ .register(video) │ ───────► │ · workspaceFiles.stat 取 size/version│ │ · keyed body 注册 │ Range │ · 512 KiB 分块回传 200/206 │ │ · 中英文字典 │ ◄─────── │ · 416/404/415/499 语义完整 │ └─────────────────────────┘ │ 复用 connection 认证栅栏 │ └────────────────────────────────────┘

渲染器声明 loading: 'renderer'，由组件自己决定播放源：

| 页面来源 | 播放源 | 行为 |
| HTTP(S) 网页端 | | 原生 Range 流式读取，512 KiB/块，可 seek，内存平坦 |
| Desktop dsh-app://app/ | Session Remote 整文件读取 → Blob URL | ≤ 32 MiB 全量读入，可任意拖动；> 32 MiB 仍流式播放并提示不可拖动 |

- 路由复用 ctx.connection.fetch.register（与自带 /api/file 相同的认证栅栏）， ctx.workspaceFiles 取元数据、ctx.sessions + ctx.sandboxPolicy 解析会话工作区；只允许上述视频扩展名，不是通用文件服务器。
- 流式播放失败时只回退一次整文件读取；回退失败或超限时显示本地化提示，工具栏的「打开 / 显示文件位置」按钮始终可用。
- 全部资源用 ctx.effect(...) 注册，卸载即回收；不新增定时器、轮询或 DOM 监听。
- Blob URL 在换标签、刷新、卸载时 URL.revokeObjectURL，不长期占用内存。

4. 目录

| 路径 | 说明 |
| plugin/ | DSH bundle 包目录（安装 target） |
| plugin/package.json | bundle 清单：dsh.bundle.patch + dsh.client（platform: web，immediately） |
| plugin/cordis.patch.yml | 只 insert 一行 host 插件 video-preview，无配置、无覆盖 |
| plugin/index.js | Host 半：认证、Range 解析、分块流式读取 |
| plugin/client.js | 浏览器半：渲染器注册、keyed body、中英文案、双播放路径 |
| plugin/locale/{en,zh}.json | 插件列表显示的名称与描述 |
| plugin/icon.svg | 原创图标 |
| tests/test-client.mjs | 离线装配测试：模拟模块加载器，校验 inject / 渲染器元数据 / 槽注册 |
| tests/test-host.mjs | 离线集成测试：真实临时文件跑 HEAD/200/206/416/404/415 与分块读取 |
| tools/asar_*.py | 只读解析 Electron app.asar 的小工具，用于复核 DSH 内部契约 |
| samples/video-preview-test.mp4 | 4 秒 640×360 H.264+AAC 自测素材（含音轨） |

5. 安装

前提：DSH 是 Web 或 Desktop 组合（必须存在 ui-sidebar-documentpreview；headless / SDK / ACP 等无浏览器 UI 的组合装了也不会显示），版本兼容性见第 8 节。

git clone https://github.com/chenyitao123/dsh-video-preview.git

然后任选一种：

1. 让 DSH Agent 安装：plugin_manager install_bundle，target 指向克隆目录下的 dsh-video-preview/plugin 绝对路径。
2. 设置界面：设置 → 插件 → 从本地目录安装，选择同一个 plugin/ 目录。
3. 也可以用压缩包：把 plugin/ 打成 zip（或使用仓库 Release 附件），解压后同样指向 plugin/。

安装结果应为 application: applied，设置 → 插件出现「视频预览 / Video Preview」。
安装只写当前 profile（package.json 的 bundle 列表 + node_modules 里的链接），不改 DSH 全局安装目录，也不影响同机其他 profile。

注意：如果安装时选择本地目录链接（junction），不要移动或删除 plugin/；需要迁移时先 remove_bundle，拷贝到新位置后重新安装。

6. 验证

node tests/test-client.mjs
node tests/test-host.mjs

两者应输出 all assertions passed。

运行中验证：

1. 设置 → 插件，能看到「视频预览 / Video Preview」条目和图标。
2. 打开任意视频文件：应出现播放器；播放、暂停、拖动进度正常。
3. 用 samples/video-preview-test.mp4 验证音量（该文件带 AAC 音轨；无音轨视频的音量控件会被 Chromium 禁用，这是浏览器行为）。
4. 关闭标签后 Host 的流请求中止；换标签/刷新后 Blob URL 被回收。

7. 卸载

plugin_manager action: remove_bundle target: @local/dsh-video-preview

手动删除等价步骤：

1. 从当前 profile 的 package.json 删除 dsh.profile.bundles 里的 @local/dsh-video-preview 以及 dependencies 里的同名项。
2. 删除该 profile node_modules/@local/dsh-video-preview（链接或目录）。
3. 重启 DSH。然后本仓库可整体删除。

插件不写持久化数据、不改任何自带配置，删除后无残留。

8. 兼容性基线

- 实测 DSH 0.2.1-rc.2（Desktop build commit 332895e0f7c9d4dbfb29729f5eb367fa263ff986）。
- 依赖的上游公开契约（已核对内置包源码）：
- ctx.documentPreviews.register({ id, extensions, binaryExtensions, title, loading, wrap })
- sidebar.right.tab.document keyed 槽（locale 选项；body props：content、resourceAddress、 useTabInfo、t）
- ctx.connection.fetch.register({ path, methods, requestBody, fetch })
- ctx.workspaceFiles.stat/readBytes、ctx.sessions.get、ctx.sandboxPolicy.resolve
- DSH 升级后若这些契约或 UNVIEWABLE_BINARY_EXTENSIONS 实现变化：先跑 tests/，再按第 7 节卸载。若上游开始内置视频渲染器，直接删除本插件即可，原有行为不受影响。
- 其他 DSH 版本/平台请先按第 6 节验证；上游契约不兼容时插件最多是不激活，不会破坏 DSH 原有功能（设置 → 插件里可重试或卸载）。

9. 已知限制

- 播放能力取决于 Electron/Chromium 自带解码器：H.264/AAC 的 mp4、webm 等常见格式可播； H.265/HEVC 以及 AVI / WMV / FLV / MKV 等未注册扩展名（保持原「不可预览」提示，可在工具栏用系统应用打开）。
- Desktop 端超过 32 MiB 的视频可播放但无法拖动进度（Electron 自定义协议媒体不可 seek，见第 2 节）；页面会显示提示条，可用工具栏在系统应用中打开以获得完整控制。
HTTP(S) 网页端没有此限制。若上游 DSH 桌面壳改用可 seek 的媒体服务，或 Electron 修复该缺陷，此限制自然消失。
- 音量控件是否可用取决于视频是否有音轨；无音轨文件由 Chromium 禁用，属预期行为。
- 视频预览为只读；不做转码、截图、字幕等额外功能。

英文快速上手

一个本地、增量式的 DSH 插件，为右侧 Sidebar 文档预览添加视频播放能力（mp4/m4v/webm/mov/ogv）。它通过公开的 ctx.documentPreviews API 注册渲染器，并挂载一个带 key 的 sidebar.right.tab.document 主体；不修改任何随 DSH 发布的文件。在 HTTP(S) 页面上，播放器通过带鉴权的 range 路由流式播放；在桌面端 dsh-app://app/ 壳中，它从 Blob URL 播放完整字节（≤32 MiB），因为 Electron 自定义协议的媒体无法 seek（electron#38749）。

git clone https://github.com/chenyitao123/dsh-video-preview.git
then from a DSH session:
plugin_manager install_bundle target=<repo>/plugin

已在 DSH 0.2.1-rc.2（Web/Desktop 组合）上测试。用 plugin_manager remove_bundle @local/dsh-video-preview 卸载。

许可证

MIT — 见 LICENSE。