SAOS-3624/dsh-video-storyboard · 上手攻略
- 仓库：SAOS-3624/dsh-video-storyboard
- 链接：https://github.com/SAOS-3624/dsh-video-storyboard
- 分类：multimodal（多模态 / agent 工具插件）
- 作者：spark
- 更新：2026-10-31
§0 三证 checklist 与自检
| 证据 | 状态 | 锚点 |
|---|---|---|
| GitHub URL（已 fetch） | ✅ | 本篇全部内容基于 raw.githubusercontent.com/.../main/ 的 README / INSTALL / USAGE / FAQ / CHANGELOG 与 package.json 实际抓取 |
| 版本锚点 | ✅ | 最新 release v0.5.4（tag v0.5.4，commit 4c85689ef90fa1b56d3e6bc924829d5b9c8e11bb，发布于 2026-10-30），package.json 版本号同为 0.5.4 |
| README 子模块 anchor | ✅ | package.json 的 exports 字段暴露 19 个公开子路径（./board ./locate ./subtitles ./ytdlp ./cache ./storage ./browser-time 等），bin 字段暴露 3 个 CLI |
| 顶会 venue / 年份 | ⚠️ 无 | 本仓库不是论文仓库，没有 venue / 会议 / 期刊。它是一个「实验性（experimental）」的 DSH 插件，star 数 268、周增 +500 |
| 第三方基准 | ⚠️ 无 | README 的实测数字均为作者自测，未见他方独立复现。凡本文引用均标注为「作者自测」 |
版本号浮动提醒（依据 W42 指引）：0.5.0 → 0.5.4 这四天内改了 8 个行为，其中 3 个会直接影响读者照抄的命令（quality 默认值、token 计价、size 语义）。本文以 v0.5.4 为准；若你装的是 0.4.x，--quality 不存在、minGap 会被静默丢弃（见 §六 坑 4）。
一个必须先说的口径冲突：README 与 USAGE 通篇写「一张图 = 384 token」，这是 0.5.4 之前的算法（640k 画布）。0.5.4 已改：默认预算从 640k 提到 1.2M，token 按实际出图尺寸动态计算，1.2M 约 700 token。README 尚未同步，FAQ 的「价位表」也还按 384 折算。下文凡涉及 token 成本，我会两个数字都给，并标明哪个是当前口径。
§1 它是什么
一个跑在 DeepSeek Harness（DSH） 上的插件，把一段视频压成 一张带编号的宫格图（9–16 格）+ 一份带时间码的文本清单（每格起止时间、该段台词、切了几刀、音频包络），让纯文本的 agent 也能"看"视频。
关键设计是两段式阅读：先用一张低分辨率宫格图看结构（这篇片子讲什么、大概在第几分之一），确定某段值得看时，再用 video_zoom 拉高清放大那一段。视频本身不交给模型，模型拿到的是「图 + 结构化文本」。
它暴露 5 个工具：
| 工具 | 干什么 | 何时用 |
|---|---|---|
video_probe |
只读容器头：时长、分辨率、帧率、有无音轨/字幕轨 | 第一次接触一部片子，0 token |
video_storyboard |
出宫格图 + 文本清单 | 主体功能 |
video_zoom |
只看某一段（更小时间窗、更密的格） | 清单看完觉得某段重要 |
video_locate |
纯文本：一句话 → 时间码 | 知道说了什么，不知道在第几分钟 |
video_subtitles |
把画面硬字幕裁成一张竖长图 + 每条秒数 | 无字幕轨、ASR 也转不出的素材（PV/唱歌/双语艺术字） |
配套还有 node bin/doctor.mjs 自检命令、~/.dsh/asr.json 转写配置、.evidence.json 复核文件。
成熟度定性：作者自己标为 experimental。0.5.0 是 breaking change（把陪看功能拆成独立包 dsh-watch-together），0.5.1–0.5.4 是密集的 bug 修复。能用，但要配环境。
§2 解决什么问题
多模态模型看视频，常见的两条路都有硬伤：
- 逐帧抽图喂模型 —— 10 分钟片子按 1 fps 抽就是 600 张图，token 直接爆。
- 只喂字幕 —— 画面里的构图、动作、场景变化全丢，模型只能"复述台词"。
本项目走第三条路：把画面压成一张宫格图（token 封顶），旁边配一份按时间对齐的文本清单。
作者给的成本对照（README 原表）：
| 插件 | 做法 | 90 秒片子成本 | 它更强的地方 |
|---|---|---|---|
dsh-video-see |
抽帧作为真图片交回模型 | 20 帧 ≈ 7,680 token | 每帧 ~1000px，小字表情都清楚 |
dsh-video-lens |
关键帧 → 外部 VLM → evidence JSON | 帧数×384 + VLM 调用费 | 有时间锚定问答，结论结构化 |
watch-skill |
帧+转写+OCR 索引成库 | 建库贵，追问几乎免费 | 答案带回执，可被第三方复核 |
| 本项目 | 一张宫格图 + 文本清单 | 约 1,900 token（0.5.4 口径下更高，见 §0） | 单位 token 覆盖的时间最长 |
作者自述：同一部 90 秒片子，其他"按镜头取关键帧"方案落在 3,900–8,500 token，本项目是它们的 1/2 到 1/4.5。README 里作者特别加了一句「不是 1/8 或 1/16 —— 那种数字是拿"每秒抽一帧"当对手，不诚实」。这种自我约束的口径，在同类项目里不常见，是加分项。
§3 快速安装
3.1 三句话版（Windows）
winget install Gyan.FFmpeg # 必须：ffmpeg + ffprobe
pip install --user -U yt-dlp # 只有贴 B 站/YouTube 链接才需要
node scripts/install-dev.mjs # 装插件，然后【重启 DSH】
3.2 依赖矩阵（作者原表）
| 依赖 | 必须吗 | 不装会怎样 |
|---|---|---|
| DSH 桌面版（宿主） | 必须 | 插件没地方跑 |
| Node.js ≥ 20 | 必须 | 插件本身跑不起来（engines: {"node": ">=20"}） |
| ffmpeg + ffprobe | 必须 | 第一步就报错 |
| yt-dlp | 可选 | 本地文件照常能用，贴链接不行 |
| ASR 服务 | 可选 | 能出图，但清单里没有台词 |
ffmpeg 跨平台安装：
# macOS
brew install ffmpeg
# Debian/Ubuntu
sudo apt install ffmpeg
# Fedora
sudo dnf install ffmpeg
装完必须关掉所有终端重开一个（PATH 要重新读），然后验证：
ffmpeg -version | head -1
ffprobe -version | head -1
两条都要有输出。只有 ffmpeg 没有 ffprobe 的精简包真实存在，插件会明确报出来。
3.3 装插件
git clone https://github.com/SAOS-3624/dsh-video-storyboard.git
cd dsh-video-storyboard
node scripts/install-dev.mjs
- 普通 profile 也可以：
dsh plugin --profile web add dsh-video-storyboard - 从 npm：
npm i -g dsh-video-storyboard - 查状态 / 卸载：
node scripts/install-dev.mjs --check/--remove - 装完必须重启 DSH（插件树只在进程启动时组装）
为什么不用软链：Node 解析裸模块名（
@deepseek-ai/dsh-tools）会顺着真实路径往上找，软链会让它从仓库目录往外爬，永远找不到宿主包。装的是快照，改完代码要重跑脚本 + 重启。
3.4 自检（强烈建议先跑）
node bin/doctor.mjs # 或 npm run doctor
它会一次查完 ffmpeg / ffprobe / yt-dlp / ASR / 缓存目录，每条后面直接跟"缺什么、怎么补"。作者原话：用户反馈里过半不是 bug，是没配 ASR 或装完 ffmpeg 没重启 DSH。
§4 核心用法
4.1 命令行直跑（不需要 DSH）
bin/*.mjs 全部独立可用：
# ① 先看容器信息，不出图
node bin/storyboard.mjs your-video.mp4 --plan 30
# ② 出一张图 + 清单
node bin/storyboard.mjs your-video.mp4 --cells 9 --out sheet.png --text
# ③ 只看某一段
node bin/storyboard.mjs your-video.mp4 --from 120 --to 180 --cells 6 --text
# 长片按 5 分钟切窗，产出 film-w01.png … + film-timeline.md
node bin/storyboard.mjs film.mp4 --batch 300 --out film.png
# 只测 ASR 链路
node bin/asr-check.mjs film.mp4 --from 100 --seconds 12
# 调阈值前先看分数分布
node bin/scan-stats.mjs film.mp4
成功的标志：
[probe] 1920x1080 24.00fps 299.41s audio
[scan] 7186 帧 → 141 个切点（阈值 16，自适应 28 个密集段）
[audio] mean -23.0 LUFS, peak -13.4 LUFS, 1 silence gaps (1.9s of 299s)
[transcript] asr (paraformer-zh)，136 段
[sheet] sheet.png 1009x623 3x3 cell≈331×184 strip=55px
4.2 作为 agent 工具调用
// 长片顺序读（叙事内容默认走这条，防剧透）
video_probe({ input }) // 先知道多长
video_storyboard({ input, from: 0, segment: 300 }) // 第 1 段
// → 结尾回显：segment 1/22 · 5% watched · 82 min left · next: from=300
video_storyboard({ input, from: 300, segment: 300 }) // 把 next 的 from 传回来
segment 是 0.5.4 新增的 SEQUENCE 自动推段：调用方不用自己记时间码。
// 短片看结构
video_storyboard({ input, cells: 9 })
video_zoom({ input, from: 12, to: 18 }) // 觉得某段有意思再放大
// 已知台词找时间点（纯文本，0 图 token）
video_locate({ input, query: "记忆" })
// 快闪蒙太奇
video_storyboard({ input, from: 42, to: 50, cells: 12 })
video_zoom({ input, from: 43, to: 46, cells: 6, minGap: 0.4 })
4.3 参数速查（0.5.4 口径）
| 参数 | 默认 | 说明 |
|---|---|---|
input |
— | 本地路径或 http(s) 链接 |
from / to |
全片 | 只看这一段 |
cells |
自动 | 1–16。不给就按「每格 ≤90 秒 + 镜头数」推 |
sheets |
自动 | 1–16（0.5.0 从 1–4 放开）。多张 = 多花图 token |
segment |
— | SEQUENCE 自动推段长度（秒） |
budget / size |
1.2M / size 是别名 |
一张图多少像素。small=640k / medium=1.2M / large=1.65M |
need |
scene |
要看多清：shot 160×90 / scene 320×180 / text 480×270 |
quality |
medium(720p) |
只影响贴链接时的下载清晰度：low=360p / medium=720p / high=1080p。本地文件永远读原片 |
scanGap |
0.35 | 粗扫时两刀最短间隔（秒），快闪素材调小 |
pick |
sharp |
sharp 3 候选选最锐 / mid 段中点 / thumb 段内最典型 |
burn |
index |
烧格号；none 关掉。时间码从不烧进画面 |
minGap |
1.2 | 格子合并的最小间隔，快闪段落可降到 0.4 |
transcript |
auto |
auto / off |
transcriptFile |
— | 直接喂 SRT/VTT/JSON，跳过 ASR |
detail |
med |
每格台词预算：low 60 / med 120 / high 400 字 |
cellRange |
— | 分页看文本清单，如 [14, 42] |
textOnly |
false |
只出文本不出图（翻页神器，约 0.8 秒/页） |
tileFirst |
false |
用格数换分辨率。是取舍不是优化，默认关 |
4.4 输出长什么样
<storyboard path="film.png" grid="3x3" size="1920x1080" fps="24.00" duration="90.09s"
footer="teal bars = loudness, grey blocks = silence, yellow ticks = cut points"
transcript="asr" cuts="44 (avg 2.0s)">
audio events (7): 00:00.50 +30dB, 00:12.80 -30dB, …
fast cuts: 00:42.80-01:04.80 (22 shots) — video_zoom({ from, to, cells: 6, minGap: 0.4 }) splits these
re-read at one-frame granularity: 00:47.10-01:03.70 18 shots (coarse saw 4)
cell 1 (r1c1) = 00:00.00-00:09.33 cuts 1
"所以你连他也要忘记吗"
cell 3 (r1c3) = 00:33.29-00:47.08 cuts 10 16 frames (4×4)
三条设计原则值得抄进笔记：
- 清单只给原材料，不下结论。 不说"这是高潮""这里是角色 A"，只给时间、刀数、台词 —— 判断是模型的事。
- 每加一行都要能说出它挡掉了什么误判。 说不出来就不加。
- 数字不可信时要说出来。 连续运镜被逐帧切碎时，清单写
cut count unreliable here，而不是让模型拿cuts=N当节奏依据。
4.5 算法要点
- 画面差异：缩到 64×36，逐帧比 HSV，色相按环形距离且按饱和度降权（灰色的色相没有意义），得到 0–255 变化分。
- 切点：分数超阈值即一刀，阈值按本片自己的分数分布和时长自适应推。
- 爆点重判：每个 2 秒窗口用一帧间隔重判一次 —— 粗扫看不见 0.35 秒以下的刀，而快闪全在那一档。
- 格位分配：按「密度积分」等分，每格承载的信息量相同，快的地方自动分到更短时段。
- 快闪摊开：某格平均镜头短于 1.4 秒且刀够硬时，摊成 k×k 子格（最多 4×4）。
二重细分（0.5.0 新增）会让一张图里混着不同尺寸：
这一格画面（meanMotion） |
摊成 | 每小块 |
|---|---|---|
| 很热闹（快剪、剧烈运动，≥8） | 3×3 = 9 张 | 110×61 |
| 在动（摇镜、正常剪辑，≥3） | 2×2 = 4 张 | 165×92 |
| 几乎不动（静态画面、字幕页） | 整帧 1 张 | 331×184 |
扫一眼就知道这段片子哪里快哪里慢。
§5 转写（ASR）配置 —— 价值差别最大的一步
没配转写 = 它只能看图说话。 能描述"画面里有个女孩在跑"，但说不出"她讲了什么"。作者原话：这是这个插件价值差别最大的一步。
5.1 优先级（第一个能用的赢）
- 视频自带字幕轨 → 直接读，不跑 ASR
transcriptFile→ 喂已有 SRT/JSON，完全不碰 ASR- ASR 服务 → 上面都没有时才用
video_storyboard({ input: "film.mp4", transcriptFile: "film.srt" })
支持 SRT / VTT / JSON（[{start, end, text}]）/ B 站字幕 JSON。作者实测：同一条 90 秒片子，带 ASR 16.9 秒、带字幕文件 5.1 秒，而且"平台自带的字幕比任何识别都可靠"。
5.2 后端选型（作者原表）
| 后端 | 模型 | 冷启动 | 体积 | 标点 | 热词 |
|---|---|---|---|---|---|
| sherpa（默认） | paraformer-zh-2024-03-09(int8) + ct-transformer + silero-vad |
约 5 秒 | 500 MB | 另加载 onnx | ❌ 无接口 |
| funasr（可选） | seaco_paraformer_large + fsmn-vad + ct-punc |
约 30 秒 | 2.1 GB | 内置 | ✅ |
| 云端 | SenseVoiceSmall / whisper-1 … | 0（联网） | — | 视服务而定 | 视服务而定 |
为什么默认 sherpa：2024 版 paraformer 更准（实测「像差」不加热词就对），冷启动 30 秒→5 秒、内存 6.8 GB→不到 1 GB。代价：sherpa 运行时没有热词接口，同音字只能靠 terms 表后处理。专有名词多时再切 funasr。
5.3 配置 A：本机服务（免费、不联网）
~/.dsh/asr.json：
{
"baseUrl": "http://127.0.0.1:8000/v1",
"model": "paraformer-zh-2024-03-09",
"language": "zh",
"hotwords": "像差 焦段 光圈",
"manage": {
"start": ["D:/asr-local/.venv/Scripts/python.exe", "D:/asr-local/server-sherpa.py"],
"idleMs": 5000,
"waitMs": 60000
}
}
- 本机地址不需要 key（
127.0.0.1/localhost/[::1]）。这是设计，不是漏了。 manage是生命周期托管：调用时端点不通就拉起；最后一次运行后idleMs内没有新运行就请它自己退出。idleMs按后端设，两者差 100 倍：sherpa → 5000（冷启动只 5 秒，随用随关）；funasr → 600000（冷启动 30 秒，关太早等于每次重付）。
服务端需满足三个约定：
GET /health → 200 即可（拿不到就读 /v1/models）
POST /shutdown → 返回后退出（不支持也行，插件会退回杀进程）
POST /v1/audio/transcriptions → OpenAI 兼容，返回 verbose_json
5.4 配置 B：云端服务（任何 OpenAI 兼容）
{ "baseUrl": "https://api.siliconflow.cn/v1", "key": "sk-...", "model": "FunAudioLLM/SenseVoiceSmall", "language": "zh" }
可换：OpenAI whisper-1 / 阿里云百炼 paraformer-v2 / Groq whisper-large-v3-turbo。云端不填 key 会直接跳过 ASR（不报错，清单写 transcript: none）。
5.5 热词比换模型更有效
video_storyboard({ input: "materials.mp4", hotwords: "位错 滑移 柏氏矢量 晶界 层错 固溶体" })
热词要按片子传，不要写死在全局 —— 全局那份是默认值，学科不对时它是负偏置（拿摄影词去识别材料学讲座，只会帮倒忙）。
作者实测（镜头评测视频）：
加之前：也就是所谓的相差。
加之后：也就是所谓的像差。
只加了一个词，别的一个没动。
5.6 硬字幕校正（detail: high 时自动开）
画面里烧进去的字幕是确定的文本，ASR 会听错。插件会：抽 2–3 张原分辨率帧找字幕带（≈3 秒，只做一次）→ 对若干条台词只裁那一条带子做 OCR（≈0.26 秒/条，不做检测）→ OCR 能覆盖 ASR 那句（≥60% 的字按顺序对得上）就替换。
on-screen subtitles used to correct 1 of 3 checked lines:
4.4s "他也忘记。" → "也要忘记吗"
⚠️ 这是抽检，不是全片校对 —— 默认只抽查 16 条，清单写的是 spot-checked N lines, corrected M，请按这个口径读。
§6 坑与注意（7 坑，每坑三段式）
坑 1 · token 计价口径过期（README 未同步 0.5.4）
- 现象：README、USAGE、FAQ 的「价位表」全部写「一张图 = 384 token ≈ 0.011 元」，但 0.5.4 已把默认预算从 640k 提到 1.2M，token 改为按实际出图尺寸动态计算，1.2M 约 700 token。FAQ 的钱数表也是按 384 折算的。
- 影响：照着 README 预估费用会低估约 1.8 倍。清单里现在会写
cost: 2 image(s) × ~737 = ~1474 vision tokens—— 以清单里的 cost 行为准。 - 修复：省钱就显式传
size: "small"或budget: 640000；或用textOnly: true只出文本。别信 README 的 384，去看清单的 cost 行。
坑 2 · cells:16 不是"更大的封面面积"
- 现象：0.5.4 之前的
cells:16在 640k 预算下每格只有 247×137（2.39:1 的片子是 286×118），模型看到的是色块，然后照着色块编剧情 —— 而清单对此一声不吭。 - 影响：模型会基于色块编造剧情，且不报错。这是本项目最危险的一个坑。
- 修复：0.5.4 起主动报警 —— 清单会写
!! cells are 286x118 — below what you asked for (text: 480x270…)并给三条改法（减格数 / 加预算 / 用 zoom）。看到这行就说明这次结果不可信。要覆盖更多就加sheets，不要用cells换分辨率。
坑 3 · 装完 ffmpeg 不重启 DSH = 一直卡在 ffprobe
- 现象：DSH 在启动时把"有没有 ffmpeg"记在进程里，装完不重启仍按"没有"走。表现是反复卡在 ffprobe。
- 影响：新手以为插件坏了，去翻源码找 bug。作者明确说"这不是 bug，是必须做的动作"。
- 修复：凡是装/改了 ffmpeg、yt-dlp 这类外部程序，完整退出 DSH 再打开。 改
asr.json不用重启（0.5.0 起按 mtime 热加载）。
坑 4 · 0.4.x 的 minGap 参数"写了没接线"
- 现象：0.4.3 的 zoom handler 逐字段手写参数列表，漏了
minGap——schema里声明了、也校验了，但到参数装配那一步就丢了。表现是video_zoom的minGap改了永远无效，按 1.2 秒走。 - 影响：快闪素材本该用
minGap: 0.4让短镜头各得一格，实际被合并成 1 格，看不清。 - 修复：0.5.0 起三个入口（storyboard / zoom / watch）参数统一由
board.js装配，只有一份定义，并有test/schema-audit.test.mjs扫args.X断言都在 schema 里。必须用 ≥0.5.0；用 0.4.x 的话minGap别指望。
坑 5 · 下载的视频没有音轨，但没人报错
- 现象：yt-dlp 合流音视频要调用 ffmpeg，而 DSH 桌面版把 ffmpeg 放在
~/.dsh/tools/ffmpeg/bin（不在 PATH 上）。找不到 ffmpeg 时 yt-dlp 不报错，静默只下视频轨，退出码还是 0 —— 你拿到一个没声音的 mp4。 - 影响：表现为"ASR 全是空的"，但根因在下载端，很容易查错方向。
- 修复：0.5.0 起会自动把解析到的 ffmpeg 路径通过
--ffmpeg-location传给 yt-dlp。验证办法：node bin/asr-check.mjs 视频.mp4第一行有没有NO AUDIO。doctor 第 1 段绿了就没事。
坑 6 · Chromium 127+ 解不开浏览器 cookie
- 现象：用
--cookies-from-browser会拿到v20密文解不开，报Failed to decrypt with DPAPI。 - 影响：B 站 1080P+ / HTTP 567（要登录）取不到高清，贴链接的图会糊。
- 修复：必须导出文件。用 Cookie-Editor 扩展 → Export → Netscape 格式 → 存
cookies.txt，然后配置：
// ~/.dsh/video.json
{ "cookies": "D:/cookies/cookies.txt" }
或调用时传 cookies: "D:/cookies/cookies.txt"，或设 DSH_VIDEO_COOKIES（桌面版读不到 setx 设的变量，优先用配置文件）。
🔐 安全：
cookies.txt里的SESSDATA等同于你的登录凭证。别提交到仓库、别发群里、别贴到 issue 里。用完退出登录让它失效。不想配 cookies 的替代方案：把视频自己下下来喂本地路径，插件对本地文件一视同仁，还更快。
坑 7 · asr.json 优先级被环境变量覆盖
- 现象：改了
~/.dsh/asr.json完全没反应，或本机服务明明不校验 key 却坚持要你填。 - 影响：反复折腾配置文件，浪费大量时间。
- 修复：优先级是「环境变量 >
$DSH_HOME/asr.json> 内置默认」。DSH_ASR_BASE_URL/DSH_ASR_MODEL/DSH_ASR_LANG/DSH_ASR_KEY/DSH_ASR_KEY_ENV都在配置文件之上。另外 baseUrl 必须带/v1（写成http://127.0.0.1:8000少了/v1会被当成未知端点）。node bin/doctor.mjs第 3 段会打印"实际在用的 baseUrl 和它的来源（env / file / default）"。
附加坑 · 已知限制（作者自列）
- 画面小于约 1% 的改动（PPT 上多一行字）在 64×36 上不可见，再聪明的阈值也救不回来。
- 连续运镜密集时
cuts=N会失真（清单会标cut count unreliable here）。 - 极暗素材的取帧锐度判断不稳。
- 分格摊开后子帧最小约 100×56，再小就只剩色块。
- 不做说话人分离 —— 实测 cam++ 在 1.9 秒短句上把单人素材切成 6 个人。
- 唱歌 / 纯音乐 / 多语言艺术字是语音模型的盲区（实测 92 秒 PV 只转出 4 段 35 字）。这类素材请用
video_subtitles。
§7 典型适用场景
适合：
1. 快速摸清一部片子讲什么 —— video_probe → video_storyboard → 按需 video_zoom，两轮 token 覆盖全片结构。
2. 长讲座/课程/访谈的顺序阅读 —— segment: 300 自动推段，还能防剧透（每段末尾回显 next: from=1500）。
3. 找一句话在哪一分钟 —— video_locate，纯文本 0 图 token。
4. 给 agent 一个"能引用视频"的能力 —— 清单里每格都有时间码，模型可以引用「第 5 格 = 00:33.29-00:47.08」。
5. PV / 唱歌 / 双语艺术字 —— video_subtitles 把硬字幕裁成竖长图（实测 92 秒 PV 从 4 段 ASR 变成"十几句全认出"）。
6. 成本敏感场景 —— textOnly: true（约 0.8 秒/页，0 图 token）做纯文本翻页。
不适合（作者原话）：
逐帧辨字、要复核结论、对同一部片子问二十个问题 —— 那三种情况请用 dsh-video-see / lens / watch-skill。
补充：需要第三方复核的场合，本项目配 .evidence.json（每格起止时间、取帧时刻、刀数、字数、原文），可以对着时间码回看原片 —— 但它不提供"答案带回执"那种可被另一个东西复核的机制。
§8 与同类对比
8.1 生态三条路线
| 插件 | 做法 | 90 秒成本 | 强在哪 | 本项目怎么补 |
|---|---|---|---|---|
dsh-video-see |
抽帧作为真图片交回模型 | ≈7,680 token | 每帧 ~1000px，小字、表情都清楚 | video_zoom 再取一次，但那是第二轮成本 |
dsh-video-lens |
关键帧 → 外部 VLM → evidence JSON | 帧数×384 + VLM 调用费 | 时间锚定问答、结论结构化 | video_locate 做时间定位，evidence.json 给结构 |
watch-skill |
帧+转写+OCR 索引成库 | 建库贵，追问几乎免费 | 答案带回执，可被第三方复核 | 清单里明说"图已在上下文"，追问不再重新出图 |
本项目最独特的位置：单位 token 覆盖的时间最长（1 张图 = 90 秒）。代价是单帧清晰度输（格 331×184 vs 别人 ~1000px）。
8.2 与"直接调视频模型"的对比
现在各家多模态 API 大多已支持直接上传视频。这本项目仍然有价值，原因是：
- 可控成本：一张图 ≈ 384–700 token，和片子长度无关（只和张数有关）。
- 可控输出形态：结构化清单（时间码 / 刀数 / 台词 / 音频包络）可被程序消费，不是黑盒。
- 可复核：.evidence.json 给出每格的原始素材坐标。
- 但要诚实说：如果你已经在用支持视频输入的闭源 API，且不在乎"结构化时间码"和"可复核"这两点，直接调视频模型可能更省事。
8.3 定位一句话
它是"让文本 agent 也能看视频"的成本优化层，不是"替代视频理解模型"。它的护城河不在理解能力，而在分镜算法 + 时间对齐 + token 预算控制这三件事的组合。
§9 一句话推荐结论
推荐，但请按 0.5.4+ 装、且先把 ASR 配好。 如果你的场景是"让 agent 读视频 / 读讲座 / 读访谈"，它把成本压到别人的 1/2~1/4.5 且输出结构化，这是真本事；但它是实验性项目、0.5.0 刚做过 breaking change、四天内连发 4 个版本，请锁版本、先跑 doctor.mjs、并且永远以清单里的 cost: 行和 !! cells are … 报警行为准，别信 README 的旧数字。
§10 附：速查卡
# 依赖
winget install Gyan.FFmpeg && pip install --user -U yt-dlp
# 安装
git clone https://github.com/SAOS-3624/dsh-video-storyboard.git
cd dsh-video-storyboard && node scripts/install-dev.mjs && node bin/doctor.mjs
# 重启 DSH
# 最小可用三步
node bin/storyboard.mjs film.mp4 --plan 30 # 探长度，不出图
node bin/storyboard.mjs film.mp4 --cells 9 --out sheet.png --text # 出图 + 清单
node bin/storyboard.mjs film.mp4 --from 120 --to 180 --cells 6 --text # 放大某段
缓存位置：%LOCALAPPDATA%\dsh-video-storyboard\cache（Windows）/ ~/.cache/...，上限 50MB，LRU 淘汰，换盘用 DSH_VIDEO_CACHE_DIR。
成本参考（2026-10-31）：一张 9 格图 = 384 token（640k 旧口径）→ ~700 token（1.2M 当前默认口径）；文本清单 9 格约 250 token、64 格约 3,800 token。记住：中文台词往往比图贵 —— detail 和 cellRange 才是真正的省钱开关。
本文档由 spark 于 2026-10-31 基于公开内容撰写（README / INSTALL.zh.md / USAGE.zh.md / FAQ.zh.md / CHANGELOG.md / package.json / GitHub API，均为实际抓取）。未 clone 仓库、未运行任何代码。所有实测数字均为作者自测，无第三方独立基准。版本锚点：v0.5.4 / commit 4c85689ef90fa1b56d3e6bc924829d5b9c8e11bb。