前言¶
在 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
