前言¶
在 DSH 里用 dsh-better-sidebar 浏览工作区文件时，图片往往可以直接在侧栏卡片里打开，而 .mp4、.mp3 等常见媒体却容易落到代码兜底或「不支持预览 · 下载查看」。侧栏自带的 /sidebar/file 对非图片常回 application/octet-stream，也不支持 Range，浏览器既选不到合适的 demuxer，也拖不动进度条。下面介绍社区插件 dsh-media-viewer：它不修改侧栏源码，只注册一个文件查看器，用 Blob 在侧栏里播放音视频，侧栏升级时不会被覆盖。
这是什么¶
dsh-media-viewer 由维护者 feigo313 发布，归类为 DSH 客户端插件。仓库自述为 dsh-better-sidebar 的「插件中的插件」：宿主侧几乎为空壳，客户端通过 betterSidebar.registerFileViewer 补上侧栏缺的媒体预览能力。项目为自用取向，不上插件市场、不发 npm；想用需把仓库放到本地，在 profile 的 package.json 里用 file: 引用。
核心功能¶
侧栏内直接播放¶
在侧栏中点开支持的音视频扩展名，会出现 <video> 或 <audio> 播放器，可播放、可拖动时间轴，无需先下载文件，也无需另起本地 HTTP 服务。
实现要点¶
- 宿主半（
index.js）：只导出name、inject: []与空的apply()，不起路由、不读会话、不依赖随宿主变化的webRuntime等服务。 - 客户端半：在 effect 里调用公开 API 注册查看器，
fetchStrategy为mediaUrl，由侧栏解析路径并给出/sidebar/fileURL；支持约 26 种音视频容器扩展名，priority为 50。 - 播放路径：
fetch(mediaUrl)→ 构造带正确 MIME 的Blob→ 交给媒体元素。字节在内存中，拖动进度不依赖服务端Range。单文件大于 256 MB 时自动退化为直链播放；解码失败时给出明确提示并提供「下载原文件」，而不是黑屏。
支持的容器¶
- 视频：
mp4、m4v、webm、mov、qt、ogv、mkv、avi、wmv、flv、mpeg、mpg、3gp、3g2、m2ts - 音频：
mp3、m4a、aac、wav、flac、oga、ogg、opus、weba、aiff、aif
能否出画面取决于宿主 Electron 自带的 ffmpeg 能力。H.264、VP9、AAC 等常见编码一般可用；QuickTime Animation RLE（qtrle，常见于带通道的特效素材）、ProRes 等可能无法在侧栏内解码——外部播放器能播不代表 Chromium 能播，这类素材需先转码。README 示例：
# 保留透明通道，Chromium 可解
ffmpeg -i in.mov -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 out.webm
# 或丢掉通道，最通用
ffmpeg -i in.mov -c:v libx264 -pix_fmt yuv420p -movflags +faststart out.mp4
边界¶
只做预览：不转码、不做缩略图、不做播放列表、不记忆播放进度。/sidebar/file 缺少媒体 MIME 与 Range 属于上游侧栏议题（README 指向 DSH-better-sidebar#1027），本插件用 Blob 绕开。若侧栏日后变更 registerFileViewer 签名，伴生插件需同步适配。
安装与启用¶
依赖 dsh-better-sidebar（提供 betterSidebar 服务）。未安装侧栏时本插件不会激活，也不会报错。Node 引擎要求 >=20（见 package.json）。
官方 README 安装方式：复制仓库到任意目录，在 profile 中声明本地路径并加入 bundle，再在 profile 目录执行 pnpm install：
# 复制到任意目录，然后把路径写进 profile
# ~/.dsh/profiles/desktop/package.json
# "dependencies": { "dsh-media-viewer": "file:G:/dsh-media-viewer" }
# "dsh": { "profile": { "bundles": [ ... , "dsh-media-viewer" ] } }
cd $env:USERPROFILE\.dsh\profiles\desktop
pnpm install
Linux/macOS 用户将路径改为本机 clone 目录，例如 file:/home/you/dsh-media-viewer，profile 路径对应为 ~/.dsh/profiles/desktop。
宿主半安装后需重启一次 DSH App；之后侧栏客户端会按内容哈希自动加载插件客户端包。
典型用法¶
- 确保 profile 已启用
dsh-better-sidebar与dsh-media-viewer，并完成上述pnpm install与 App 重启。 - 在侧栏文件树中打开工作区内的
.mp4或.mp3等已注册扩展名文件。 - 在卡片内使用播放器控件；若提示无法解码，按 README 用 ffmpeg 转码后重试，或使用侧栏提供的下载原文件。
适用场景与注意¶
适合已在 DSH 桌面 profile 中使用 dsh-better-sidebar、需要在侧栏快速试听/试看媒体、又不想改侧栏源码的开发者。插件以当前 DSH 进程权限运行，安装前请阅读 GitHub 仓库 源码与 MIT 许可证。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。仓库当前 GitHub 星标为 1，版本 1.0.0。
结尾¶
dsh-media-viewer 用独立包补上侧栏音视频预览，升级侧栏不会被覆盖。需要本地 file: 安装与侧栏依赖，能力边界清晰。更多信息见目录页与仓库：
