GitZhiQing video-insight · 把一条视频变成可信、可回溯的结构化洞察
0. 开工确认门
先跑 doctor（只读）判环境，再单轮确认档位与形态；确认前不跑任何分析命令（fetch / 转写 / 抽帧均属分析命令）。分析深度决定成本一个数量级、交付形态决定整轮产出——都属于用户的选择权，不能替他默选（HIL 原则）。
① 交互模式判定（操作定义，不许凭感觉）：
- 交互模式：请求来自人类用户的会话消息，且用户未明说「别问 / 直接跑 / 不用确认」→ 必须提问并等回应。禁止以「用户无法实时回答」为由跳过提问；判定不明时一律按交互模式处理——宁可多问一轮，不替用户做预算决策。
- 无人值守：子代理任务、批处理脚本、用户明确免问 → 不提问，声明式执行（见⑤）。
② doctor 前置：环境事实并入确认门，让选项自带可行性——缺 VOLC_BIGMODEL_API_KEY 时 L1 选项标注「需先配 Key（可现场引导配置）/ 或走已有转写稿」；ffmpeg/ffprobe 为 missing 时诚实终止，不进确认门。
③ 确认门（单轮合并呈现，以等待用户回应结束），一次回复包含：
环境事实一句话（doctor 结论：就绪 / 缺什么、怎么补）；
理解陈述一句话（这条视频是什么、用户要什么）；
交付形态：措辞已含形态 → 复述确认；含糊 → 给选项（对话内摘要 / 落盘报告 / 问题清单+优化建议）；
档位推荐 + 一句话理由 + 成本：
推荐 <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.）
- 术语校对：对照热词表与领域常识逐句核对，产出 01-转写校对.md（改了哪些词、为什么）；无口播形态改为 01-画面文案稿.md（逐屏文案 + 可读度标注 + 合并记录，模板见 references/输出模板.md）。
- 语义分段：按话题/悬念/转折切段，标注每段时间码（无口播形态按文案屏分段）。
- 口播数据：字数、语速（字/秒）、停顿分布（有音频时用 data/audio.json）；无口播形态改为屏数、每屏字数、每屏停留时长（t_end−t_start，实测）。
- 逻辑骨架：钩子→展开→结论→CTA 各在第几秒、占比多少；话术模板是什么（对仗、设问、二选一……）。
- 主张与准确性核查：逐个主张标注 属实/存疑/违规（金融类必查合规：承诺收益、确定性结论、诱导开户）。
- 按
references/输出模板.md的 L1 骨架写 02-内容分析.md。
4. L2 怎么做（读 evidence/ + data/*.json）
- 通览：读 overview 拼版（时间戳在 data/frames_overview.json），先看信息增长节奏与模板复用痕迹。
- 圈关键节点：用 changes.json 的事件表定位每次画面变化，与文案分段对齐——"画面何时动、动了多大、和口播搭不搭"。
- 拼版检查点（交互模式）：定帧 / 放大 / 取色等重投入步骤前，把 overview 拼版图 + changes 事件表摘要 + 计划精读的节点清单呈报用户（一句话 + 证据），确认方向后再继续——L2 全程 30–40 分钟，方向跑偏要等交付才发现就太晚了。用户可显式跳过（「跑完直接给」，manifest 记录
skipped_checkpoint）；无人值守自动跳过并在 declaration 声明。 - 下断言前必回查：任何时间断言，落笔前用 grab_frames 定帧或 JSON 数据支撑一次；字幕逐字核对用 subtitle-strip + 局部放大。
- 音频三层交叉（单一手段不足以判断有无 BGM）：停顿 RMS vs 噪声底 vs 频谱图，三层一致才写。
- 取色只信区域众数：palette.py，禁止 1×1 采样——单像素取到白底就会给出误导色。
- 按
references/画面分析手册.md的清单过一遍画面元素，写 03/04/05。 - 收尾：抽查 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 三层判断法