# Video Insight

> 视频内容与画面的深度分析（拉片级），两档模式：L1 文案档做内容摘要、逻辑骨架、话术模板与文案层问题（口播视频凭转写，无口播视频凭画面文案提取）； L2 画面档叠加抽帧、帧差、定帧、音频与取色证据，回答画面承接、排版、节奏与标注时机，所有结论带帧证据与精度声明。 当用户要求「分析这条视频」「拆解文案/话术/结构」「拉片」「画面分析」「音画对齐」「节奏分析」「字幕排版检查」，或给出纯 BGM 无口播、文案烧在画面上的视频要求「提取画面文案/画面文字」时使用； 触发词包括「分析这条视频」「拉片」「无口播」「纯 BGM」「画面文案」「文案烧在画面上」等，即使未说「分析」二字，只要意图是理解或评估一条已有视频也应使用。 仅需转写字幕或浅摘要（不要结构化分析）时不要使用本 skill；生成视频素材、剪辑、下载非 B站 链接同样不属于本 skill。

- Skill: `gitzhiqing/video-insight` (Agent Skill, multi-file: 36 files)
- Install (CLI): `npx skillmds@latest add gitzhiqing/video-insight`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitzhiqing/video-insight/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: GitZhiQing (https://skillmd.com/u/gitzhiqing)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gitzhiqing/video-insight

---


# video-insight · 把一条视频变成可信、可回溯的结构化洞察

## 0. 开工确认门

先跑 doctor（只读）判环境，再单轮确认档位与形态；**确认前不跑任何分析命令**（fetch / 转写 / 抽帧均属分析命令）。分析深度决定成本一个数量级、交付形态决定整轮产出——**都属于用户的选择权，不能替他默选**（HIL 原则）。

**① 交互模式判定**（操作定义，不许凭感觉）：
- **交互模式**：请求来自人类用户的会话消息，且用户未明说「别问 / 直接跑 / 不用确认」→ 必须提问并等回应。**禁止以「用户无法实时回答」为由跳过提问**；判定不明时一律按交互模式处理——宁可多问一轮，不替用户做预算决策。
- **无人值守**：子代理任务、批处理脚本、用户明确免问 → 不提问，声明式执行（见⑤）。

**② doctor 前置**：环境事实并入确认门，让选项自带可行性——缺 `VOLC_BIGMODEL_API_KEY` 时 L1 选项标注「需先配 Key（可现场引导配置）/ 或走已有转写稿」；ffmpeg/ffprobe 为 missing 时诚实终止，不进确认门。

**③ 确认门（单轮合并呈现，以等待用户回应结束）**，一次回复包含：
1. 环境事实一句话（doctor 结论：就绪 / 缺什么、怎么补）；
2. 理解陈述一句话（这条视频是什么、用户要什么）；
3. 交付形态：措辞已含形态 → 复述确认；含糊 → 给选项（对话内摘要 / 落盘报告 / 问题清单+优化建议）；
4. 档位推荐 + 一句话理由 + 成本：

   > 推荐 <L1/L2>，因为 <理由>。两档对比：
   > - L1 文案档：约 6–10 分钟（40–130 万 token）——讲什么 / 结构 / 话术 / 文案问题
   > - L2 画面档：约 30–40 分钟（330–480 万 token，约 L1 的 3–8 倍）——追加 画面承接 / 排版 / 节奏 / 标注时机，结论全部带帧证据

合法回应只有三种：**确认**（按推荐执行）/ **调整**（改档位或形态后执行）/ **显式委托**（「你看着办」「直接开始」→ 按推荐档执行，报告头部注明「经委托采用推荐档」）。交互模式下**不存在「无回应默认执行」**。

**④ 提问格式与预算**：宿主有结构化选项工具时必须用（选项 ≤2 行，推荐项标「推荐」+ 一句话理由）；否则编号列表「A/B/C，回复编号或补充」。确认门必占且仅占 1 轮；小决策（如热词领域判断不了）并入同一轮（「顺带确认：内容偏 <金融/教育/科技>，热词按此注入，对吗？」），不单独占轮。

**⑤ 无人值守声明式执行**：取 L1，在报告头部与 manifest `declaration` 块写「档位未确认，按 L1 执行；如需画面层结论可升级 L2」。这是**声明**，不是默选。

## 1. 两档模式

| | L1 · 文案档 | L2 · 画面档 |
| --- | --- | --- |
| 输入 | 视频/音频/已有转写稿 | L1 全部 + 视频文件本身 |
| 手段 | 转写→校对→分段→结构分析 | L1 + 抽帧/帧差/定帧/放大/音频检测/取色 |
| 产出 | 01-转写校对、02-内容分析 | 追加 03-画面分析、04-音画对齐、05-问题与优化清单 |
| 成本（实测） | 40–130 万 token、6–10 分钟 | 330–480 万 token、27–37 分钟（约为 L1 的 3–8 倍） |

> 成本为 2026-09-14 实测（样本各 1–3 次，含全部图像读取，波动较大；视频越长越高）。档位未明确时必须按 §0 提问确认。

**无口播形态**（纯 BGM 无人声、文案烧录在画面上，或整条无音轨）：文案的唯一来源是画面，两档都必须先走画面文案提取（§2.1）。此时 L1 = 画面文案提取 + 内容分析，成本高于普通 L1（**预估** 60–150 万 token，待实测校准后回填）；L2 照常叠加画面/节奏/取色证据，音画对齐变为「BGM 结构 × 文案屏切换节奏」（audio_probe 照跑，BGM 是唯一音频线索）。

**升级到 L2 的触发**：用户提到 画面/拉片/排版/节奏/音画/承接/标注/字幕样式；或 L1 发现"文案本身没问题但效果不好"这类只有画面才能解释的现象。**触发只是建议**——带成本问用户，得到同意再跑（§0）。

## 2. 执行流程

设 `S` = 本技能 `scripts/` 目录，`OUT` = 输出目录（默认 `<cwd>/video-insight/<slug>/`，建议放到用户任务目录）。
**每个脚本跑完都会更新 `<OUT>/manifest.json`；继续下一步前检查对应 status 是否 ok，不 ok 先修复**——归档链中途断一次，空目录就会被当成"没问题"。唯一例外：transcribe 的 `no_speech` 不是故障，是无口播分支信号（§2.1）。

| 步骤 | 命令 | 产出 |
| --- | --- | --- |
| 0 自检 | **§0 确认门前先跑**：`python $S/doctor.py --workdir <目录>` | 环境事实并入确认门；缺项按 JSON 提示补齐 |
| 0.5 取链 | `python $S/fetch.py <B站URL> --output-dir $OUT` | $OUT/video.mp4（ffprobe 校验可播放） |
| 1 转写 | `python $S/transcribe.py <输入> --output-dir $OUT --domain finance` | transcript.srt/.txt/.json；无音轨或 ASR 空产出 → `no_speech`，转 §2.1 |
| 2 探测 | `python $S/probe.py <视频> --output-dir $OUT` | meta.json |
| 3 L1 分析 | （模型工作，读 transcript） | analysis/01、02 |
| 4 抽帧 | `python $S/extract_frames.py <视频> --output-dir $OUT [--strip-crop WxH+X+Y]` | evidence/overview、subtitle-strip + 时间戳 JSON |
| 5 帧差 | `python $S/detect_changes.py <视频> --output-dir $OUT` | data/changes.json |
| 6 定帧/放大 | `python $S/grab_frames.py <视频> --at "t1,t2" --output-dir $OUT [--crop WxH+X+Y --zoom 6]` | evidence/keyframes、crops |
| 7 音频 | `python $S/audio_probe.py <视频> --output-dir $OUT [--range 起:止]` | data/audio.json + 频谱图 |
| 8 取色 | `python $S/palette.py <视频> --at T --crop WxH+X+Y --output-dir $OUT` | data/palette.json |
| 9 L2 分析 | （模型工作，读全部 JSON + 帧图） | analysis/03、04、05 |

**输入识别**：B站链接（bilibili.com / b23.tv）用 fetch.py 直接下载（实测可用）；抖音 / 小红书 / 快手 / 视频号**不支持**（实测下载路径不可用或文档不可靠），fetch.py 会拒绝并给出原因，此时请用户手动下载后改用本地文件；音频直链交给 transcribe.py；已有转写稿（.srt/.txt）直接放入 `$OUT/transcript.*`，跳过步骤 1。
**领域热词**：从内容判断 finance / education / tech；金融术语漏了热词必错（"筹码峰""诱多"零错误的唯一原因就是热词）。判断不了就并入 §0 确认门同轮问一句，或 `--domain none`。
**缺 Key 引导配置**（交互模式）：doctor 报缺 `VOLC_BIGMODEL_API_KEY` 且用户选择口播 L1 → 给控制台链接（见 README「API Key 配置」），用户粘贴 Key 后写入本 skill 目录 `.env`（已 gitignore，不入库）→ 复跑 doctor 确认后继续；用户不配 → 改走已有转写稿 / 无口播分支等可行路径。`PADDLEOCR_ACCESS_TOKEN` 同款处理。

### 2.1 无口播分支 · 画面文案提取

**触发**（任一）：
- 步骤 1 输出 `no_speech: true`（无音轨，或 ASR 正常跑完但零文本——纯 BGM 无人声的客观信号）；
- 用户开局就说明是纯 BGM / 无口播视频、文案在画面上；
- 有口播但用户点名「提取画面文案 / 画面文字」——同走本分支，成稿与 transcript 对照（漏字/删改类问题恰来自这里）。

| 步骤 | 命令 | 产出 |
| --- | --- | --- |
| b0 确认门 | 告知判定证据与模式切换（见下） | — |
| b1 粗筛 | `python $S/extract_frames.py <视频> --output-dir $OUT [--fps 0.5]` | evidence/overview 拼版 → 确认文字卡形态、文案区域（居中/底部/多区）、估屏数 |
| b2 时间轴 | `python $S/detect_changes.py <视频> --output-dir $OUT` 然后 `python $S/screen_segments.py $OUT/data/changes.json --output-dir $OUT` | data/screen_segments.json：每屏起止 + 建议定帧时刻（帧差实测；文案卡切换=事件、停留=静止期） |
| b3 精读 | 自己能读图：`python $S/grab_frames.py <视频> --at "<各屏 grab_at>" --output-dir $OUT [--crop ... --zoom 6 --flags neighbor]`；不能读图：`python $S/screen_ocr.py <视频> --segments $OUT/data/screen_segments.json --output-dir $OUT` | evidence/keyframes 每屏一帧（读不清先放大）或 data/screen_ocr.json（逐屏文本+置信度） |
| b4 成稿 | （模型工作）逐屏读帧图或读 OCR JSON → 写 `transcript.screen.srt` + `transcript.screen.json` | 每屏 t_start/t_end/文案/证据帧路径/可读度（清晰·放大后可读·不可读） |
| b5 分析 | （模型工作）读 transcript.screen.* 按 §3 做 01（画面文案稿形态）/02 | analysis/01、02 |

**b0 告知门（告知即走，矛盾才停）**：客观证据（无音轨 / ASR 零文本）→ 告知「检测为无口播视频（证据：ASR 零文本产出 / 无音轨），文案在画面上，改用画面文案提取，成本预估 60–150 万 token」后**继续，不等许可**，manifest `declaration` 块记录该切换（无人值守同样声明）。**矛盾证据才是硬停点**：粗筛显示说话头/采访嫌疑、或 `suspect_no_speech: true` → 停下呈报矛盾证据，等用户定夺（检查音频质量 / 换转写配置 / 仍走画面分支）——客观判定无替代路径（文案只能来自画面），问许可是过度门禁；矛盾证据才有真选择。
**粗筛纠偏（b0 硬停点的执行层）**：b1 拼版若显示画面其实是说话头/采访（ASR 可能漏检），**不硬切**——停下呈报，等用户定夺。`suspect_no_speech: true`（ASR 只吐了零星幻听字）同样在粗筛时留意此情形。
**精度与合并**：屏起止来自帧差（实测）；b3 uniform 兜底模式（连续动画、无静止期）的时间一律写「约」；打字机/逐行浮现被拆成相邻屏且文案相同时，成稿合并并注明；读不清的字如实标「不可读」，禁止猜写。

## 3. L1 怎么做（读 transcript.*；无口播视频读 transcript.screen.*）

1. **术语校对**：对照热词表与领域常识逐句核对，产出 01-转写校对.md（改了哪些词、为什么）；无口播形态改为 01-画面文案稿.md（逐屏文案 + 可读度标注 + 合并记录，模板见 references/输出模板.md）。
2. **语义分段**：按话题/悬念/转折切段，标注每段时间码（无口播形态按文案屏分段）。
3. **口播数据**：字数、语速（字/秒）、停顿分布（有音频时用 data/audio.json）；无口播形态改为屏数、每屏字数、每屏停留时长（t_end−t_start，实测）。
4. **逻辑骨架**：钩子→展开→结论→CTA 各在第几秒、占比多少；话术模板是什么（对仗、设问、二选一……）。
5. **主张与准确性核查**：逐个主张标注 属实/存疑/违规（金融类必查合规：承诺收益、确定性结论、诱导开户）。
6. 按 `references/输出模板.md` 的 L1 骨架写 02-内容分析.md。

## 4. L2 怎么做（读 evidence/ + data/*.json）

1. **通览**：读 overview 拼版（时间戳在 data/frames_overview.json），先看信息增长节奏与模板复用痕迹。
2. **圈关键节点**：用 changes.json 的事件表定位每次画面变化，与文案分段对齐——"画面何时动、动了多大、和口播搭不搭"。
3. **拼版检查点（交互模式）**：定帧 / 放大 / 取色等重投入步骤前，把 overview 拼版图 + changes 事件表摘要 + 计划精读的节点清单呈报用户（一句话 + 证据），确认方向后再继续——L2 全程 30–40 分钟，方向跑偏要等交付才发现就太晚了。用户可显式跳过（「跑完直接给」，manifest 记录 `skipped_checkpoint`）；无人值守自动跳过并在 declaration 声明。
4. **下断言前必回查**：任何时间断言，落笔前用 grab_frames 定帧或 JSON 数据支撑一次；字幕逐字核对用 subtitle-strip + 局部放大。
5. **音频三层交叉**（单一手段不足以判断有无 BGM）：停顿 RMS vs 噪声底 vs 频谱图，三层一致才写。
6. **取色只信区域众数**：palette.py，禁止 1×1 采样——单像素取到白底就会给出误导色。
7. 按 `references/画面分析手册.md` 的清单过一遍画面元素，写 03/04/05。
8. 收尾：抽查 evidence/ 文件与 manifest 一致；临时目录已由脚本清理；把证据文件索引附在报告末尾。

## 5. 判断纪律（详见 references/证据纪律.md，此处只列要点）

- 表述分三档并强制标注：**实测**（有 JSON/定帧支撑）、**约**（1s 抽帧 ±0.5s 精度）、**推断**（显式标注，不得混入实测）。
- 画面文案（§2.1 产物）的表述映射：屏起止时间=帧差/定帧（实测档）；文案内容=模型读图（清晰/放大后可读/不可读三档标注）或 OCR 置信度；uniform 兜底模式的时间一律「约」；读不清的字如实标「不可读」，禁止猜写。
- 交付形态没对齐、分析深度没确认，都不动手（无人值守按 §0 声明式执行）；交互会话中**禁止以「用户无法实时回答」为由跳过档位提问**（§0 交互模式判定）。客观结论被用户质疑时，给一次带数据的说明，然后把表述改写成对两种可能都成立，继续推进——赢了检测输了进度。
- **交付后回路**（标准出口，一句话，不占轮）：报告末尾附「如需画面层结论可升级 L2（附成本）；存疑主张可点名核查；结论有质疑按证据纪律 R4 处理」。
- 追求"结论可信、可回溯、可重复"，不追求"分析得更多"。

## 6. 边界

- 转写是内部分步（内置火山 Seed ASR 托管 API 客户端），不对外提供独立的转写/字幕服务；不做视频下载（B站 除外，走 fetch.py）；不做剪辑与素材生成。
- OCR 只作为无读图能力时的画面文案回退（官方托管 API 或本地 paddleocr），不做通用"图片转文字"服务。
- 纯音频输入且转写为空 → 无画面可提取文案，如实说明并停止该分支，不硬造文案稿。
- 产出物命名与归档遵循用户工作区约定；本技能自己的产物集中在 `$OUT`。

## 7. 参考文档

- `references/输出模板.md` — 报告固定骨架（L1/L2），保证多次运行产物一致
- `references/证据纪律.md` — 三档表述 + 硬规则 + 交付前自检清单
- `references/画面分析手册.md` — 画面元素检查清单、layout.json 口径、BGM 三层判断法