前言¶

在 DeepSeek Harness（DSH）里查看工作区文件时，内置的 Document Preview 覆盖了 Office、Markdown、代码、图片、PDF 等类型，但没有媒体渲染器，音视频往往会落到「不支持预览」。社区里的 dsh-knit 能预览部分视频格式，且路径限定在工作区根目录内，也不覆盖音频。若用 workspaceFiles Remote 把大文件读进前端，还有体积上限，不适合几百 MB 级别的视频。

dsh-media-sidebar 是面向 web / desktop 配置的客户端插件：在右侧栏增加媒体播放器 tab，通过宿主侧只读 HTTP 接口提供字节流，原生格式走 HTTP Range（206），浏览器解不了的容器则用 ffmpeg 实时转码。下面介绍它的定位、能力与安装用法。

这是什么¶

• 名称：dsh-media-sidebar（仓库与安装线索为 guwenwu112233-dot/dsh-media-sideba）
• 维护者：guwenwu112233-dot
• 分类：客户端（Cordis patch + 右侧栏 UI）
• 许可：MIT（见仓库 package.json）
• 兼容：dsh >=0.2.0-rc.2 <0.3.0，node >=20.18（engines 要求 >=22.19），profiles: web、desktop

一句话：在 DSH 右侧栏就地播放本机音频与视频，并补全内置预览与 dsh-knit 未覆盖的能力——音频，以及工作区外的绝对路径文件。

核心功能¶

两个右侧栏 tab¶

客户端由 window.__ModuleLoader__ 直接装载，无需单独构建步骤；与 dsh-knit 类似，使用 React.createElement 而非 JSX。对媒体扩展名的 canOpen 优先级高于内置 fallback 预览，因此只有音视频会落到本插件，其它类型仍走内置预览。

宿主 API¶

宿主在 src/host/index.js 注册：

1. GET /dsh-media/api/token?path=<...>[&sessionId=<...>] — 校验路径后签发 HMAC 令牌，返回 { ok, path, contentType, token }（及转码时的 mode）。
2. GET /dsh-media/api/raw?path=<...>&sessionId=<...>&token=<...> — 只读回环访问，按白名单扩展名输出媒体字节。

路径规则：

• 绝对路径：直接使用。
• 相对路径：必须带 sessionId，相对该会话工作区根（session.header.cwd）解析；无会话返回 400 session-required-for-relative，不会落到宿主进程 CWD。
• .. 逃逸会话根返回 403 outside-session-root。

格式与支持方式¶

原生（浏览器可解码，原文件 + Range）：

• 音频：mp3 wav m4a aac flac oga opus weba
• 视频：mp4 m4v webm mov ogv

转码（ffmpeg 实时输出 H.264/AAC 分片 MP4 流）：

• 视频：mkv avi flv wmv
• 音频：wma

转码发现顺序：DSH_MEDIA_SIDEBAR_FFMPEG_PATH 优先，否则 PATH 上的 ffmpeg。启动时用 ffmpeg -encoders 探测 libx264；不可用则返回 415 transcode-unavailable，原生格式不受影响。转码流通常无法拖动进度（accept-ranges: none），客户端会提示；并发转码上限为 2，超出 429 transcode-busy。

安全边界（摘要）¶

插件以当前 DSH 进程权限读文件。宿主侧约束包括：仅回环来源、来源围栏（跨站 / 跨源 / 转发头拒绝）、扩展名白名单、/raw 必须带与 realpath 绑定的 HMAC 令牌、只读 GET/HEAD。密钥默认在 $DSH_HOME/cache/dsh-media-sidebar.secret（可用 DSH_MEDIA_SIDEBAR_SECRET_FILE 覆盖）。绝对路径按设计可访问本机任意白名单扩展名下的媒体文件——这是「工作区外也要能播」的取舍；安装前宜自行审阅源码与许可证。

安装与启用¶

从 GitHub 安装（仓库 README 推荐，无构建步骤）：

dsh plugin --profile web add github:guwenwu112233-dot/dsh-media-sideba

或从本地目录：

dsh plugin --profile web add /path/to/dsh-media-sidebar

装完后重启 DSH Desktop（宿主只在进程启动时装载；只刷新页面可能出现新客户端请求旧宿主路由的错配）。

可选转码：安装带 libx264 的 ffmpeg 并保证在 PATH，或设置 DSH_MEDIA_SIDEBAR_FFMPEG_PATH。无 ffmpeg 时原生格式仍可播放。

典型用法¶

1. 右侧栏开始页 → 媒体播放器 → 输入文件绝对路径 → 播放；「最近打开」记在 localStorage。
2. 聊天里点击 媒体文件引用（dsh-resource://file/...）或右侧栏文件树中的音视频，自动打开播放器并 autoPlay。
3. 播放流程：客户端先请求 /dsh-media/api/token，再用返回的 path 与 token 访问 /dsh-media/api/raw（长视频依赖不过期令牌与 Range 分段）。

普通 http(s) 链接仍由官方 Browser tab 处理，不会进入本播放器。插件不做播放列表。

适用场景与注意¶

适合：在 DSH 会话里快速试听本地音频、预览工作区内或外的视频；需要 mkv/avi 等格式且本机有 ffmpeg 时点开即播（不落盘缓存）。

注意：

• 插件与 DSH 同源信任模型：安装前请阅读 GitHub 仓库 源码与 MIT 许可证。
• 解码依赖浏览器，转码依赖 ffmpeg；部分原生格式在个别环境可能无法解码。
• 修改 src/host/ 后必须重启 Desktop；修改客户端侧可刷新页面，但改完 src/ 建议统一重启以免宿主/客户端版本不一致。
• 社区目录 SkillHub 插件页 为独立生态索引，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-media-sidebar 用右侧栏 tab + 宿主 Range/转码流，补上 DSH 里本地音视频的 inline 播放能力。需要安装命令、环境变量与安全细节时，以仓库 README 为准。

• 目录页：https://www.skillhub.cn/plugins/guwenwu112233-dot/dsh-media-sideba
• GitHub：https://github.com/guwenwu112233-dot/dsh-media-sideba