dsh-video-grab —— 让 Agent 真的"看"视频（免 ffmpeg）
给 DSH 用的 host 插件。核心不是"能抓帧"，而是用得起：一条 33 秒的视频，
逐帧读完约 61 万 token（爆），拼成一张联系表约 2200 token（一次读图看完整条）。
一、它解决的问题
Agent 看视频有个硬约束：读一张图的成本 ≈ 宽×高÷750 token。
| 做法 | 33 秒 / 720×720 / 883 帧 |
|---|
| 逐帧读原图 | 883 × 约 690 ≈ 61 万 token（任何上下文都装不下） |
| 一张联系表（20 格） | 1440×1152 ≈ 2200 token，一次读完 |
所以「看完一条视频」的正确姿势是联系表，不是抽一堆帧再一张张读。
第二个约束：这台机器上没有 ffmpeg，也没有 yt-dlp。解法是借本机已有的
Electron（electron.exe 自带 ffmpeg.dll，即 Chromium 的解码器）：
插件拉起一个隐藏窗口播 <video>，seek 到采样点，drawImage 到 canvas，导出 PNG。
二、四个工具
| 工具 | 作用 |
|---|
video_probe | 只读容器结构：轨道、编码、分辨率、样本数、时长（不解码，毫秒级） |
video_sheet | 主力：按时间点采样拼一张联系表，返回 PNG 绝对路径（用 read_image 读） |
video_frames | 均匀抽 N 帧存 PNG（只在需要逐帧细看时用，token 贵） |
video_fetch_bilibili | 匿名取 B 站公开视频直链并下载到本地（不需要账号/登录） |
典型流程：
video_fetch_bilibili { bvid: "BV1WLpA6uEB1" } → 本地 mp4 路径
video_sheet { path: "<上一步的路径>" } → PNG 路径
read_image { file_path: "<PNG 路径>" } → 真的看到内容
三、实测数据（2026-10-12，本机）
| 项 | 结果 |
|---|
video_probe 33 秒片 | 0.0s，720x720 avc1 32.7s 883 样本（音频轨 mp4a 1407 样本） |
video_sheet 12 格 | 23.9s，成图 1440x864，2.1 MB |
video_sheet 20 格 | 41s，成图 1440x1152，2.9 MB |
video_frames 4 帧 | 8.8s |
video_fetch_bilibili | 1.8s，下回 1571 KB |
耗时几乎全花在 seek 上：格数越多越慢（约 1.5-2s/格）。20 格 ≈ 40s 是常态。
四、⚠️ 六个实测过的坑（别"简化"掉）
ELECTRON_RUN_AS_NODE=1 会让 electron 变成纯 Node：它是 DSH 宿主注入给子进程的，
一旦存在，electron.exe 不建窗口、不跑应用代码、静默退出（exit=1，约 100ms）。
本插件显式构造子进程环境（只保留 Electron 需要的键），这个变量根本不在里面。
注意：Windows PowerShell 5.1 里 Remove-Item Env: 实测清不掉它。"type": "module" 会连累 Electron helper：本包 host 侧是 ESM，所以 package.json 有
"type": "module" —— 这个 type 会一并套到 helper 上。helper 必须叫 main.cjs，
否则 require('electron') 抛 ReferenceError: require is not defined in ES module scope，
表现为"启动即退、没有任何输出"。- 带值开关会吃掉入口脚本：
electron --disable-gpu main.cjs ... 里，
electron 把入口脚本当成了 --disable-gpu 的值（--disable-gpu=main.cjs），
argv 整体位移。所以参数按**"第一个 .cjs/.js 之后的"**来取，不按位置取。
app.exit() 可能抢在文件落盘前：回执一律写文件（_result.json），退出前留 300ms。- 不要捕获子进程 stdio：往被关闭的管道写日志会 EPIPE，Electron 把它升级成
用户桌面上的模态错误框。插件的
stdio 固定 'ignore'，进度写 <outDir>/_sheet.log。
- MP4 里 VisualSampleEntry 的宽高偏移：从 box 起点算 +32/+34（8 头 + 6 保留 + 2 dataRefIdx
- 16 预定义 + 4 宽高）。写成 +24/+26 会稳定读出 0x0，且不报错 —— 实测踩过。
排查顺序建议：先看 <outDir>/_sheet.log（每步都有时间戳），再看 _result.json，
最后才怀疑环境。"没有日志"本身就是结论：说明进程没进到应用代码。
五、依赖与边界
- 零 npm 依赖（只用 node: 内置模块 + 本机
electron.exe）。
- Electron 位置：
DSH_ELECTRON / VIDEO_GRAB_ELECTRON 环境变量优先，
否则找 %USERPROFILE%\.dsh\electron\electron.exe。
- 只支持 Chromium 能解的编码（H.264/H.265/VP9/AV1…）。本机是精简版 Electron，
专有编码可能缺失；遇到解不了的情况会如实报"没有可解码的画面"，不会假装成功。
- 音频听不到：只处理画面。台词要靠视频自带的字幕/画面文字，或另行转写。
- 只能看定格：联系表是N 张静态图，运动过程、节奏、音效都拿不到。
- B 站下载只处理公开视频，付费/仅登录可见会如实失败；文件名里的非法字符会被替换。
六、安装 / 卸载
$dsh = "C:\Users\Elysia\AppData\Local\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
& $dsh plugin --profile desktop add D:\workspace\workplace2\dsh-video-grab-0.1.0.tgz
& $dsh plugin --profile desktop remove dsh-video-grab
装完要重启 / 开新会话才会出现这四个工具（host 侧的 JS 是加载时进内存的）；
helper 的改动则立即生效（每次调用现读磁盘）。
七、许可与出处
- MIT。解码借用本机已安装的 Electron，不随包分发任何运行时。
- B 站接口按公开页面所见的调用方式使用，仅取公开视频、匿名访问；请自行遵守平台条款。
