前言¶
在 DeepSeek Harness（DSH）里让模型理解视频，常见做法是先下载整片再抽帧或转写。整片往往几百 MB，耗时长、占磁盘，而且绝大部分字节从未被模型用到。浏览器拖进度条时并不会拉完整文件，而是发 Range: bytes=... 只取目标区间。dsh-readvideo（仓库名 dsh-read-video，维护者 RaganaBloodedge）走同一条路：给一条视频直链，用 HTTP Range 只取目标时间附近的一小段字节，取某一秒的帧或某一段音频送去转写，整片大部分字节不碰，磁盘上也不落完整视频文件。
插件归类为联网工具，当前处于骨架阶段：只有 video_probe（URL 可跳读性探测）已落地为 DSH 工具；取帧、取音频窗口、转写在 spike/ 里验证通过，代码尚未搬进插件。下文按「定位 → 能力 → 安装 → 用法与规划 → 注意」说明。
这是什么¶
dsh-readvideo 是 TypeScript 编写的 DSH 插件，npm 包名 dsh-readvideo，版本 0.1.0，MIT 许可证。它面向「视频直链 + 按需字节」场景：依赖容器索引（如 MP4 的 moov sample table，或 HLS 的 m3u8 分片清单）和 ffmpeg 远程 seek，在服务器支持 Accept-Ranges: bytes 时做跳读；不支持时只能顺序读，需事先用 video_probe 探测。
与「下载后分析」的对比在 README 里写得很直接：慢、占盘、易碰版权边界，且多数字节用不到。本插件的设计目标是按「成本台阶」尽量停在便宜手段上（元数据、字幕轨、单帧、短音频窗口等），再考虑更贵的全量流式转写。
核心功能（已核实）¶
已落地的工具：video_probe¶
服务器不返回 Accept-Ranges: bytes 时，Range 跳读失效。video_probe 用一次 HEAD（等效探测）提前判断 URL 是否可跳读——这是后续「只取一帧 / 只取一段音频」能否成立的前置条件。
spike 已验证、尚未进插件的能力¶
在 spike/remote_seek_spike.py 中，对目标 media.w3.org/2010/05/bunny/movie.mp4（Content-Length 约 237.7 MB，时长约 9 分 56 秒）做了流式代理计量（ffmpeg 经本地代理转发，记录真实出站字节数）。摘录如下：
| 操作 | 从服务器实拉 | 占整片 | 请求数 | 耗时 |
|---|---|---|---|---|
| 取第 30 秒一帧 | 2.0 MB | 0.839% | 4 | 10.5 s |
| 取第 8 分钟一帧 | 1.7 MB | 0.707% | 4 | 10.5 s |
| 第 8 分钟起 20 秒音频 | 6.6 MB | 2.784% | 4 | 13.1 s |
第 8 分钟对应文件里约 185 MB 偏移，前面约 176 MB 未读取。README 还归纳了四条实现约束：同会话应复用探测与索引（非 faststart 的 MP4 每次新开约有约 1.3 MB 固定开销）；目标区使用开放式 Range（bytes=X-），中间件须流式转发；muxed MP4 取音频窗口比单帧贵一个量级；无 Range 时只能顺序读。
规划中的成本台阶（设计文档）¶
README 用「台阶」描述阅读策略优先级，便于 agent 选手段：
| 台阶 | 手段 |
|---|---|
| 0 | 页面元数据（标题、时长、简介、章节、封面等） |
| 1 | 字幕轨（.vtt / .srt，几 KB） |
| 2 | 单帧取证（给定时间 t） |
| 3 | 音频窗口转写（给定 [t1,t2]） |
| 4 | 粗采样雪碧图 |
| 5 | 全量流式转写 |
台阶 1 常被忽略：不少视频自带字幕轨，不必先走 ASR。
尚未实现¶
- MCP server：
cordis.example.yml里mcp-readvideo为占位，README 标明尚未实现。 - 取帧、取音频窗口、转写：仅在 spike 中验证，未作为插件工具暴露。
安装与启用¶
推荐从 npm 安装（桌面应用插件页填包名即可，勿凭仓库名自行拼接 CLI 安装命令）。
- 打开 DSH 桌面应用 → 插件页 → 添加插件。
- 填写包名：
dsh-readvideo。 - 重启应用。
管理器会执行 pnpm add dsh-readvideo，把包写入 profile 的 dsh.profile.bundles，包内 cordis.patch.yml 在 bundle 层自动生效，一般无需手写 profile 的 cordis.patch.yml。装进 node_modules 后入口为 dist/index.js（Node 不对 node_modules 下的 .ts 做类型剥离）。
自检（CLI 开发场景，非 desktop profile）可用：
dsh --profile web --patch "<cordis.local.yml 的绝对路径>" --dump-config
输出中出现 - id: read-video 表示组合成功。desktop profile 由 Electron 独占管理，dsh --profile desktop --dump-config 会被拒绝。
安装来源注意（README 实测）： 插件页对「包名」和「本地绝对路径」可用；默认环境下用 GitHub 仓库地址安装常因 pnpm 解析为 git+ssh 且无 SSH key 而失败，应使用 npm 包名 dsh-readvideo。本地目录挂载前需在插件目录执行 npm install 以解析 @deepseek-ai/* peer。
运行环境：package.json 要求 node >= 22.6，peer 含 @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools。
典型用法与当前边界¶
当前用户侧可依赖的 DSH 工具是 video_probe：在让模型对某直链做 Range 抽帧或音频截取之前，先确认该 URL 是否支持字节跳读。取帧与音频窗口的调用方式在插件内尚未提供；行为与数据以 spike/remote_seek_spike.py 及 README「实测数据」「成本台阶」为准，便于后续工具落地时对齐预期。
本地改代码时，README 建议用 --patch 挂载 src/index.ts（在 node_modules 外可剥类型）；发布形态以 dist/ 为准，files 含 dist、cordis.patch.yml、README.md。
适用场景与注意¶
适合谁： 需要在 DSH 智能体流程里处理「可直链访问」的视频、且希望尽量少拉字节、不落整片的开发者；愿意接受当前仅 video_probe 可用、其余能力仍在骨架阶段的现状。
权限与安全： 插件以当前 DSH 进程权限运行，会向用户提供的 URL 发起 HTTP 请求；安装前应阅读源码与 MIT 许可证，确认直链来源与合规要求。
技术前提： 远端需支持 Range；MP4 非 faststart 时索引在文件尾，重复冷启动探测有固定开销；取音频在交织容器上比单帧更费流量；中间件必须流式转发，避免把「取一帧」放大成缓冲整段 range。
生态说明： DSH 社区插件目录在独立站点展示，与 DeepSeek / 幻方无官方从属关系；本文事实来自仓库 README 与 package.json。
结尾¶
dsh-readvideo 把「浏览器式 Range 跳读 + ffmpeg 远程 seek」接到 DSH 插件形态上：目标是让模型按时间戳取帧或取音频而不下载整片，spike 已表明单帧可仅占整片约 0.7% 量级流量，而工具面目前以 video_probe 为主。后续取帧与转写工具进包后，可按 README 的成本台阶在 agent 里分层选用。
- 目录页：https://www.skillhub.cn/plugins/RaganaBloodedge/dsh-read-video
- GitHub：https://github.com/RaganaBloodedge/dsh-read-video
- npm 包名：
dsh-readvideo
