前言¶
在 DeepSeek Harness（DSH）中，右侧边栏的文档预览目前支持文本、代码、Markdown、图片、PDF、HTML、Office 和表格等格式，但视频和音频被标记为已知二进制容器，打开后会显示一个图标和一行提示，无法直接播放。对于需要查看本地视频或音频的开发者来说，这种体验会打断工作流。
dsh-preview-media 是一个客户端插件，为 DSH 添加了原生视频和音频预览能力。它通过注册新的文档预览实现，将浏览器原生 <video> 和 <audio> 元素嵌入右侧预览面板，并利用 HTTP Range 请求实现流式传输，使大文件无需全部载入内存，同时支持桌面端的进度条拖动和倍速控制。
是什么¶
- 插件名称：dsh-preview-media
- 维护者：439436269-ctrl
- 版本：0.1.5
- 许可证：MIT
- 分类：客户端
这是一个为 DeepSeek Harness 添加媒体预览能力的插件，支持 .mp4、.mov、.mkv、.webm 等视频后缀，以及 .mp3、.flac、.wav 等音频后缀。插件通过注册两个文档预览实现：dsh-preview-media/video（视频）和 dsh-preview-media/audio（音频），优先级设置为按后缀匹配，加载模式为渲染器而非纯文本回退。
核心功能¶
原生播放器集成¶
插件在右侧预览面板中嵌入浏览器原生的 <video> 和 <audio> 元素，使用 object-fit: contain 确保视频和音频在面板内完整显示，竖屏或横屏内容都能一次显示，多余部分以黑边填充。视频支持倍速切换（1× → 1.25× → 1.5× → 1.75× → 2× → 0.5× → 0.75×）、循环播放、全屏和画中画。音频也支持倍速和循环，并显示文件名和大小信息。
HTTP Range 流式传输¶
插件在 Host 上注册路由 GET|HEAD /api/preview/media?path=<绝对路径>，支持 HTTP Range 请求。服务器按 1 MiB 的块大小通过 ctx.fs.readByteRange 读取文件，返回 200、206（部分内容）或 416（无法满足的窗口）状态码，并附带 Accept-Ranges: bytes 和 Content-Range 头。这意味着大文件（例如 2 GB）不会一次性载入内存或对话上下文，而是按需流式传输。
桌面端可拖动进度条¶
在桌面应用中，DSH 通过自定义协议 dsh-app://app 加载预览页面。Chromium 的媒体堆栈无法正确识别自定义协议响应的 seekable 属性，导致进度条拖动后会自动回跳。插件通过在本地监听一个临时端口（127.0.0.1），并将浏览器重定向到该 loopback 源进行流式传输，使普通 HTTP Range 请求正常工作，从而支持桌面端进度条拖动。
认证与权限隔离¶
路由位于 /api/ 下，经过 DSH 的 Host/Origin 防护和浏览器会话 Cookie 检查，确保跨站页面无法通过该路由访问本地文件。loopback 监听器仅绑定 127.0.0.1，且每个请求必须在路径中携带启动时颁发的令牌，否则返回 404。文件读取仍通过 DSH 的 fs 提供者，因此文件系统权限策略仍然生效。
安装与启用¶
使用官方安装命令：
dsh plugin --profile <profile> add dsh-preview-media
安装后重启桌面应用（配置变更在启动时读取）。默认配置已覆盖常见后缀，无需额外配置即可使用。
验证插件是否加载：在 Files 标签页打开任意 .mp4 文件，右侧预览面板应显示播放器，而不是“不支持此格式”的提示。
典型用法¶
打开任意支持的视频或音频文件，右侧边栏会自动切换到对应的预览渲染器：
- 视频文件（如
.mp4、.webm）：显示播放器，支持倍速、循环、全屏、画中画。 - 音频文件（如
.mp3、.flac）：显示文件名、大小和播放器，支持倍速和循环。
播放器支持通过浏览器原生控件拖动进度条（桌面端）或使用倍速控制。
适用场景与注意¶
- 适合需要频繁查看本地视频或音频的开发者，尤其是需要快速预览而不切换到外部播放器的场景。
- 播放能力取决于浏览器支持的编解码器。Chromium/Electron 可播放 MP4（H.264/AAC）、WebM（VP8/VP9/Opus）、Ogg 和大部分音频格式；Matroska（
.mkv）和 AVI 在 Chromium 中通常无法解码，会显示错误提示，此时可使用系统播放器打开。 - 插件以当前 DSH 进程的权限运行，安装前建议检查源码和许可证。
- 确保本地网络配置未阻塞 loopback 源（如防火墙策略），否则桌面端进度条可能不可用，但文件仍可通过认证路由播放。
结尾¶
dsh-preview-media 通过原生播放器集成、HTTP Range 流式传输和桌面端 loopback 适配，让 DeepSeek Harness 的文档预览支持视频和音频。适合需要在 DSH 中快速预览本地媒体内容的开发者。
- 目录页：https://www.skillhub.cn/plugins/439436269-ctrl/dsh-preview-media
- GitHub：https://github.com/439436269-ctrl/dsh-preview-media
