前言¶
在 DeepSeek Harness（DSH）里打开工作区文件时，内置文档预览已经覆盖文本、代码、Markdown、图片、PDF、HTML、Office 与表格等格式。音视频后缀虽被识别为「已知二进制容器」，却没有对应渲染器，预览区只会显示图标和「无法预览此格式」一类提示。若要在对话或文件树里快速确认一段素材，只能依赖系统播放器或把文件拖出工作区。
下面介绍社区插件 dsh-media-preview（维护者 439436269-ctrl），它在右侧 Sidebar 的文档预览中注册音视频后缀，用浏览器原生 <video> / <audio> 控件播放，字节通过带认证的 HTTP Range 流式读取，不把整文件载入内存或塞进会话上下文。插件归类为客户端，当前在 GitHub 上星标为 0；源码与说明以仓库 README 为准。
这是什么¶
dsh-media-preview 是面向 DeepSeek Harness 的客户端插件（npm 包名 dsh-media-preview，版本见仓库 package.json，许可证 MIT）。一句话定位：在右侧预览 pane 里播放常见视频（如 mp4、mov、mkv、webm）与音频（如 mp3、flac、wav），替代内置的空状态。
插件与 DeepSeek / 幻方无官方从属关系；可从社区目录 skillhub.cn 插件页 或 GitHub 仓库 获取信息。DSH 生态强调「一切皆插件」，目录站点独立于厂商应用商店。
核心功能¶
文档预览渲染器¶
插件注册两套 document-preview 实现：
dsh-media-preview/media：视频后缀dsh-media-preview/audio：音频后缀
优先级为 extension，loading: 'renderer'，并将后缀声明为二进制，避免回退到「纯文本」预览。播放器使用浏览器自带控件；视频在预览区内以 object-fit: contain 适配，竖屏或横屏片段可完整显示，不足处以黑边留白。视频下方提供倍速 / Speed（循环 1× → 1.25× → 1.5× → 1.75× → 2× → 0.5× → 0.75×）、循环 / Loop，以及全屏 / Full screen、画中画 / Picture in picture；音频同样有倍速与循环，选择会按浏览器记住。音频以卡片展示文件名、大小与播放器。页面会向 document preview 回报 loaded / failed，以便标签页加载状态结束。
默认认领的后缀（可在配置中改，见下节）包括：
- 视频：
mp4, m4v, mov, webm, ogv, ogg, mkv, avi, wmv, flv, 3gp, ts, m2ts, mts - 音频：
mp3, wav, flac, m4a, aac, oga, opus, weba, wma, aiff, aif
认证流式路由¶
Host 提供路由 GET|HEAD /api/media-preview?path=<绝对路径>（默认路径，可配置）：
- 正常响应
200，并带Accept-Ranges: bytes - 按区间请求返回
206与Content-Range - 无法满足的区间返回
416 HEAD仅返回头
读取通过 ctx.fs.readByteRange 分块（默认每块 chunkBytes 为 1 MiB），内存占用平稳。路由挂在 /api/ 下，由组合的 connection 服务做 Host/Origin 围栏与会话 cookie 校验，跨站页面无法借此读本地文件。超过 maxBytes（默认 2 GiB）的文件返回 413。
桌面端拖动进度条（loopback）¶
桌面应用从 dsh-app://app 提供页面并经 protocol.handle 代理请求。Chromium 对自定义协议响应的 video.seekable 会塌缩为 [0, 0]，因此仅走认证路由时可能能播但无法 seek。插件默认在 127.0.0.1 上启一个临时端口，通过 GET /api/media-preview?discover=1 向浏览器下发 capability token 的一半；桌面 shell 内播放器从该 loopback 源拉流，普通 HTTP Range 即可拖动时间轴。纯浏览器环境仍使用认证路由。loopback 仅绑定 127.0.0.1，请求路径须带每次启动的 token，否则返回裸 404。
安装与启用¶
在目标 profile 下执行官方安装命令（README 原文）：
dsh plugin --profile <profile> add dsh-media-preview
然后重启桌面应用（profile patch 在启动时读取）。默认无需额外配置即可覆盖常见后缀。
验证是否加载：在 Files 标签打开任意 .mp4，预览 pane 应出现播放器，而不是不支持格式的提示。
package.json 标明 Node >=22，与 DSH 0.2.0-rc.2 在插件元数据中标记为 compatible；安装前请对照你本机 DSH 版本与插件发布说明。
配置项（可选）¶
配置挂在 profile 的 media-preview 条目（Settings → Plugins，或 profile patch）。键均有代码侧默认值，部分填写即可。
| 键 | 默认值 | 含义 |
|---|---|---|
enabled |
true |
是否挂载路由；关闭时渲染器仍注册但传字节返回 503 |
routePath |
/api/media-preview |
路径须以 /api/ 开头，否则回退默认以保持认证围栏 |
loopback |
true |
是否启用 token 保护的 127.0.0.1 源（桌面 seek 依赖此项） |
debug |
false |
为 true 时把诊断写入 $DSH_HOME/media-preview-debug.log |
maxBytes |
2147483648 |
可服务的最大文件体积 |
chunkBytes |
1048576 |
每次 Range 读取的字节数 |
videoExtensions |
见 README 列表 | 视频播放器认领的后缀 |
audioExtensions |
见 README 列表 | 音频播放器认领的后缀 |
Host 会把路由路径注入页面为 __DSH_MEDIA_PREVIEW_CONFIG__，与播放器 URL 保持一致。修改后缀列表时，需与 lib/client.js 中的列表同步。
典型用法¶
日常使用无需命令行：安装并重启后，在工作区文件树或 Files 中点开已支持后缀的媒体文件，右侧预览即可播放、调节倍速与循环；视频可全屏或画中画。
若需本地开发或回归测试，仓库提供：
node --test test/*.test.js
对已安装插件的 Host 做端到端探测（需自行替换端口、token 与视频绝对路径）：
node scripts/e2e-browser.mjs --base http://127.0.0.1:<port> --token <token> --video "<absolute path to a video>"
桌面 seek 形状可用：
node scripts/e2e-seek.mjs --base http://127.0.0.1:<port> --token <token> --video "<absolute path to a video>" --simulate-desktop
播放能力与已知限制¶
解码能力取决于浏览器，不由插件转码。Chromium/Electron 通常可播 MP4（H.264/AAC）、WebM（VP8/VP9/Opus）、Ogg 及多数音频。Matroska（.mkv）与 AVI 在 Chromium 中往往无法解码，播放器会提示「浏览器不支持这个编码」；预览头栏的「在应用中打开」仍可将文件交给系统播放器，可靠做法是将文件 remux 为 MP4/WebM。
其他限制（README 摘录）：
- 每个请求只服务一个 byte window；多区间
Range返回416（浏览器媒体元素通常只请求单窗口） - 无自建播放列表、字幕轨或独立速度 UI（除插件提供的倍速按钮外，其余依赖原生控件）
- 若环境策略阻断 loopback，会自动回退认证路由：仍可播放，但桌面时间轴可能不可 seek
适用场景与注意¶
适合需要在 DSH 工作区内快速试听、试看素材的智能体开发者或日常使用者，尤其是对照脚本、标注或对话上下文核对音画内容时。
安装前请注意：
- 插件以当前 DSH 进程权限访问文件系统；流式读取仍走组合的
fs策略，与直接打开工作区文件同等敏感。 - 安装前应阅读 源码 与 MIT 许可证，确认组织策略允许从 npm / 社区目录拉取该包。
- 社区目录与 GitHub 星标数不代表安全审计结果；生产或受限网络环境请自行评估 loopback 端口与
/api/路由策略。
结尾¶
经过上面的步骤，dsh-media-preview 把 DSH 右侧预览从「音视频无法预览」补成可 seek 的流式播放（桌面端在默认 loopback 开启时），并控制单文件体积与分块读取，避免把大文件整包载入。进一步了解可访问 社区目录页 与 GitHub 仓库。
