前言¶

在 DSH 里看视频，通常有两条路：从右侧栏的文件系统、聊天文件引用或别的插件的文件树里点开一个 .mp4，落到浏览器默认播放器；或者把文件复制出去，交给专门的播放器。这两种做法在处理筛查 Agent 生成的录屏、逐帧看动画时都不太顺手：浏览器默认播放器里拖动进度条会回弹到上一个关键帧，框住画面时缩放基本没用，逐帧也做不了。

下面介绍的 dsh-quicktime-player 就是把这两件事收进右侧栏：注册一个自定义 tab 类型，视频无论从哪里被打开都落到同一个播放器里，支持 Range 流式拖动、滚轮缩放、拖动平移、逐帧步进，以及截帧和按标记导出片段。

这是什么¶

dsh-quicktime-player 是社区维护的 DSH 插件，维护者 rUrU516，分类为客户端。它声明在当前仓库的 package.json 里，版本 0.4.0，许可证 MIT。

一句话定位：DSH 右侧栏里的视频播放器，解决的是“视频在 DSH 里怎么好好看”的问题——能拖进度、能缩放平移、能逐帧、能截取，而不是简单地把 <video> 塞进一个 tab。

核心功能¶

视频来自哪里都能播¶

插件注册了自己的右侧栏 tab 类型，通过 ctx.sidebarRightTabs.register 认领视频地址。视频可以来自 DSH 文件 tab、聊天文件引用、其他插件的文件树，或者 sidebar_open；无论哪种来源都会落到这个播放器里，不需要额外安装或改造别的插件。

进度可以拖，字节不进内存¶

Host 侧用一条路由以 HTTP Range 头返回 206，所以进度条是真正的拖动，而不是跳回最近的关键帧。大文件也不会被整个读进内存：字节留在磁盘上，按 Range 一段段取。

桌面端也支持拖动¶

Electron 壳里页面从 dsh-app:// 提供，Chromium 在跨 scheme 时无法对 <video> 做 seek。插件因此改为从带 token 的 127.0.0.1 端口拉流；当该端口不可用时，退化回同源路由。

缩放与平移¶

滚轮在指针位置缩放，范围 1×–8×；缩放状态下拖动可以平移。平移会停在画面边缘，不会出现把视频拖出画框外的情况。双击切换全屏。

自带的控制条¶

播放/暂停、时间与帧号切换、速度滑块（0.2×–5×，0.2 为步长）、循环、垂直音量弹窗、静音、画中画、全屏，都由播放器自己提供。鼠标静止时控制条会淡出。

逐帧步进¶

← / → 每次走一帧，帧率由实际送出的帧测量得到，不是写死的常量。

记住上次播放位置¶

按文件的绝对路径记录位置、速度、循环、音量和静音，最多保留最后 50 个文件，30 天后失效。切换会话再回来，会回到同一个位置。如果文件被重新渲染、时长变了，旧记录会被丢弃，而不是跳到一个无关的位置。

截帧、剪片段、检查更新¶

? 旁边的相机按钮把当前播放头的画面以 PNG 写入剪贴板，失败时退化为下载，完成时弹出提示。

剪刀按钮在播放头处打一个标记；同时最多保留两个标记，中间用虚线连接，悬停剪刀按钮会出现保存/清除。保存会调用 Host 的 ffmpeg 做流复制（stream copy），因此片段与源字节一致，不重新编码，切在最近的关键帧上。如果 Host 没有 ffmpeg，按钮会直接说明，而不是静默失败。

? 旁边的云按钮向 Host 查询当前安装版本和 registry 上的最新版本，在对话框里报告结果。只支持手动检查，没有轮询、角标和自动安装。

跟随 DSH 主题¶

控制条（标题栏、引导卡、对话框、通知）使用 DSH 的 --dsw-alias-* 变量绘制，所以在浅色主题下播放器是浅色的；视频画面区域保持深色。如果变量不存在，会退化回一直使用的深色配色。

内置引导¶

角落里的 ? 会盖一层可点击的引导卡，每个功能一行，图标与工具栏一致。它是纯文本，不需要额外维护箭头对齐。

键盘不被抢占¶

只要焦点在播放器内部，即使焦点落在滑块上，Space 和方向键都留给播放器本身。

安装与启用¶

先确认宿主 DSH 使用 profile bundles（插件声明了 dsh.bundle.patch），然后执行：

dsh plugin --profile <profile> add dsh-quicktime-player

安装后需要重开一次窗口，让客户端 bundle 被重新加载。

前置要求¶

• DSH 支持 profile bundles。
• 只有在导出片段时才需要 Host 上有 ffmpeg。查找顺序为 /opt/homebrew/bin/ffmpeg、/usr/local/bin/ffmpeg，最后是 PATH 上的 ffmpeg。没有它的前提下，播放、截帧等其他功能正常，保存按钮会提示 Host 上没有 ffmpeg。

插件不需要任何配置项：路由前缀、4 GiB 上限、回环媒体服务端口以及工作目录限制都是写死的。

典型用法¶

用快捷键操作¶

键盘操作一览：

导出一段片段¶

1、把播放头移到片段起点，点击剪刀按钮，打第一个标记。
2、把播放头移到终点，再点一次剪刀按钮，打第二个标记；两点之间会出现虚线。
3、悬停剪刀按钮，选择保存。Host 会执行类似下面的逻辑：用 ffmpeg 以 -ss、-t、-c copy 处理，音频和视频流直接复制，不重新编码；临时文件在发送完成后删除。

没有 ffmpeg 时，保存按钮会提示“宿主上没有 ffmpeg”，这时可以从 ~/.dsh/quicktime-player.log 里确认解码和导出过程中的报错。该日志文件按播放器事件逐行写入 JSON，包含 source 解析、元数据和解码错误。

确认客户端 bundle 是否已加载¶

如果改完窗口发现还是旧界面，可以发一个请求看客户端 bundle 是否进入了模块图：

GET /quicktime/_graph

这是一个开发期探针，返回模块图的检查结果。

适用场景与注意¶

适合需要在 DSH 里审查视频的开发者，尤其是 Agent 生成录屏后想直接逐帧看、想截取某一帧或剪一小段的情况。由于它把视频播放和导出能力挂到 DSH 进程上，安装前应先打开源码和 LICENSE 看过：插件以当前 DSH 进程的权限运行，路由路径被限制在会话工作目录内，4 GiB 以上的文件走的是固定的 Range 上限。

环境与依赖¶

• 播放、缩放、逐帧、截帧都不依赖 ffmpeg，只有导出片段会调用。
• .mkv、.avi、.wmv、.flv 会被接受，但 Chromium 无法解码，播放器会如实报告，而不是假装在播放。
• 更新检查依赖 Host 能访问 registry.npmjs.org；离线、代理或 DNS 问题时，对话框会显示“检查失败”。
• 社区目录页显示该插件 0 星，但功能自足，不依赖其他插件，核心就是“一个 tab 类型加一条路由”。

结尾¶

dsh-quicktime-player 的定位很简单：把视频播放收进 DSH 右侧栏，并保证拖动、缩放、逐帧和导出的几个关键动作都可用。如果你的痛点是浏览器默认播放器拖不动进度、无法对着帧看，它是目前结构上比较对路的方案。

• 目录页：https://www.skillhub.cn/plugins/rUrU516/dsh-quicktime-player
• 仓库：https://github.com/rUrU516/dsh-quicktime-player