前言¶
在 DeepSeek Harness（DSH）里看项目文件时，右侧栏往往有两条互不相同的预览路径：自带 Files 页签走 ctx.documentPreviews，装了 dsh-media-web-preview 时音视频通常能正常播；而 dsh-better-sidebar 的文件树则维护自己的 ctx.betterSidebar 注册表，且不会查询 documentPreviews。结果就是，同目录下的 MP4 在 Files 里能预览，从 better-sidebar 树里点开却落到 binary-download——提示无预览、只能下载。
cg-media-viewer 由 DonGeeo87 维护，npm 包名同为 cg-media-viewer，属于客户端插件。它在 better-sidebar 的注册表里挂上视频与音频 viewer，用浏览器原生 <video> / <audio> 播放，并在服务端支持 Range 时提供可拖动的真实 seek。
这是什么¶
一句话：cg-media-viewer 在 DSH 右侧栏（含 dsh-better-sidebar 文件树）内播放音视频，并在条件允许时通过字节范围请求实现拖动定位，而不是把整个文件先下完。
| 项 | 说明 |
|---|---|
| 维护者 | DonGeeo87（Giorgio Interdonato） |
| 分类 | 客户端 |
| npm | cg-media-viewer（当前资料中版本为 1.0.0） |
| 许可证 | MIT |
| GitHub | https://github.com/DonGeeo87/cg-media-viewer |
它解决什么问题¶
README 用表格概括了两条预览链路的差异：Files 页签由 harness 的 documentPreviews 渲染；better-sidebar 树只认自己的 registry。开启或关闭 dsh-media-web-preview 不会改变树里的行为，缺的是在 better-sidebar 注册表 里登记的 viewer。本插件注册 cg-media:video 与 cg-media:audio，填补这一缺口。
核心功能¶
支持的扩展名¶
在 ctx.betterSidebar 中注册两个 viewer：
| Viewer | 扩展名 |
|---|---|
cg-media:video |
mp4 m4v webm ogv mov mkv avi mpg mpeg 3gp 3g2 m2ts |
cg-media:audio |
mp3 m4a m4b aac wav flac ogg oga opus weba |
mkv、avi 被列入声明列表以便仍尝试播放器，但 Chromium 往往无法解码，此时会显示格式提示并保留下载入口——这是浏览器能力边界，而非插件逻辑错误。
有意不声明的扩展名包括：ts（在编码工作区里多为 TypeScript）、以及 Chromium 普遍不支持的 aiff aif wma mid midi，避免用无效播放器替换本可工作的下载面板。
播放与 seek¶
- 使用原生控件：播放、seek、音量、全屏。
- 支持 Range 时：优先通过
GET /api/media?path=<绝对路径>取流（与dsh-media-web-preview的 Host 半部同源路由），响应206 Partial Content与Content-Range，拖动进度条不必下载整文件。 - 无 Range 时：若仅有 better-sidebar 主机计算的
mediaUrl（/sidebar/file，整文件、无范围），页脚会明确提示 No seek: the server does not support byte ranges…；元素使用preload="none"，Download 为主操作，不假装两种模式等价。
错误与页脚¶
MediaError.code2（网络）、3（解码）：网络提示 + Retry；code 4（格式不支持）：格式提示；code 1（中止）不按失败处理。- 页脚显示标签标题、主机上报时的文件大小、Download 与 Open in new tab。
- harness 若暴露
locale服务，界面跟随当前语言（含英语、西班牙语词典）；否则保持英语。
依赖与版本¶
DeepSeek Harness: >=0.2.1-rc.2 <0.3.0-0
dsh-better-sidebar: >=0.28.0（peer，optional）
Node（开发/测试）: >=18
未安装 dsh-better-sidebar 时，bundle 仍可加载但无处注册，保持空闲，不会拖垮 harness。
可拖动 seek 需要能响应 Range 的 /api/media 路由，通常由 npm 包 dsh-media-web-preview 提供 Host 半部。未安装时仍可通过 mediaUrl 播放，但无 seek。
安装与启用¶
下列命令来自插件 README，按顺序执行即可。
先在项目或环境中安装 npm 包：
npm install cg-media-viewer
在 DSH 内安装 bundle：
plugin_manager action=install_bundle target=cg-media-viewer
安装后刷新页面一次，使客户端 bundle 进入模块图。卸载：
plugin_manager action=remove_bundle target=cg-media-viewer
插件以当前 DSH 进程权限在浏览器侧运行。安装前建议浏览 GitHub 源码与 MIT 许可证，确认符合你的安全与合规要求。DSH 社区插件目录（如 skillhub.cn）为独立站点，与 DeepSeek / 幻方无官方从属关系，本文安装步骤以 README 为准。
如何确认已生效¶
- 打开 Settings > Side：viewer 清单中应出现带播放三角图标的 Video 与 Audio 及对应开关。
- 从侧栏树打开一个 MP4：面板应显示带控件的
<video>，而非仅下载按钮。 - 播放器根节点应带有
data-cg-media="video"或data-cg-media="audio"。
典型用法¶
本插件无单独配置文件：安装 bundle 并刷新后，在 dsh-better-sidebar 文件树中点击已声明扩展名的音视频文件即可。
若已安装 dsh-media-web-preview，拖动进度条时应走 /api/media 的分段请求；若未安装，仍可播放，但页脚会说明不支持字节范围，并引导以下载为主。
维护者在仓库中提供的校验命令（开发侧）：
node --check lib/client.js
node --check lib/index.js
node --test
已知限制¶
- 本插件的 Host 半部不注册路由，复用已有
/api/media；移除dsh-media-web-preview后仍可通过 fallback 播放，只是没有 seek。 - 使用
fetchStrategy: 'mediaUrl'时，主机通常不上报文件大小，页脚往往只有标题（不为每次打开额外发 HEAD）。 - 无字幕轨、播放列表、倍速等：能力限于浏览器内置播放器。
- 文件缺失且主机路由也失败时，Chromium 可能报
MEDIA_ERR_SRC_NOT_SUPPORTED（code 4），界面按格式提示处理；短暂故障仍可使用 Retry。
结尾¶
cg-media-viewer 针对 better-sidebar 与内置 Files 预览分叉的问题，在侧栏注册表里补上音视频 viewer，并在服务端支持 Range 时提供 honest 的 seek 与无 Range 时的明确降级。适合日常在 DSH 侧栏树里听讲解、看演示片段的开发者。
- 目录页：https://www.skillhub.cn/plugins/DonGeeo87/cg-media-viewer
- 源码与文档：https://github.com/DonGeeo87/cg-media-viewer
