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

0. 开工确认门

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

① 交互模式判定（操作定义，不许凭感觉）：

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

② doctor 前置：环境事实并入确认门，让选项自带可行性——缺 VOLC_BIGMODEL_API_KEY 时 L1 选项标注「需先配 Key（可现场引导配置）/ 或走已有转写稿」；ffmpeg/ffprobe 为 missing 时诚实终止，不进确认门。doctor 之后顺手检索经验层：按输入平台/形态关键词 grep -i 本技能 memory/INDEX.md 与 memory/lessons/*.json，命中条目并入环境事实句（「历史教训 N 条：<finding> → <action>」），未命中一行带过——不占额外轮次。

③ 确认门（单轮合并呈现，以等待用户回应结束），一次回复包含：

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. 两档模式

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

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

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

2. 执行流程

设 S = 本技能 scripts/ 目录，OUT = 输出目录（默认 <cwd>/video-insight/<slug>/，建议放到用户任务目录）。

机械采集一条命令：确认门通过后，采集段——取链 → 转写 → 探测 → 按 no_speech 自动切无口播分支（含 b1~b3 与 ocr 路径成稿）→ L2 基础证据（抽帧/帧差/音频）——全部由 pipeline.py 一次完成，不要逐步调用单脚本当编排器：

• 输入：视频/音频文件、B站链接、或已有转写稿（.srt/.txt，自动拷入 $OUT/transcript.* 并跳过转写）。
• --screen-mode：无口播分支的精读方式——frames（默认，抓每屏一帧由你读图成稿，多模态主路线）/ ocr（无读图能力时，OCR 后自动组装 transcript.screen.srt/.json，整条分支零模型介入）。无口播分支细节见 references/no-speech-batch.md §1。
• 幂等：失败修复后重跑同一条命令，已完成步骤（manifest 记 ok / transcribe 记 no_speech）自动跳过；manifest.json 仍是权威状态账本。
• 收尾报告（stdout 一份 JSON）：branch（voiced / no_speech / transcript_only）、steps、ready（就绪文件清单）、stats（时长/字数/语速，或屏数/每屏停留——已算好直接引用）、ai_next（按本文件节号指路）、notes（b0 告知门与 b1 目检纠偏提醒）。任一步失败时报告 failed_step 与原因，修好重跑即可。

条件分支：无口播（branch: no_speech、纯 BGM、点名提取画面文案）→ references/no-speech-batch.md §1；多条视频或对比 → 同文件 §2。

分工边界：pipeline 只做机械采集；确认门（§0）、读图成稿、内容分析（§3/§4）与视觉决策由模型做。确认门前禁止调用 pipeline（doctor 是唯一例外）。

单步命令（仅排查与补采）：修复失败步骤、或模型决策类的定点采集才单步调用——grab_frames.py --at "t1,t2" / --range "T1:T2" --step 0.5（定帧/放大/等步扫窗补采）、palette.py --at T --crop WxH+X+Y（取色）、audio_probe.py [--range 起:止]（补音频段）、extract_frames.py [--strip-crop ...]（非默认字幕带布局）、screen_ocr.py --segments ...（重跑 OCR）、screen_srt.py transcript.screen.json（成稿 SRT 机械渲染）、doctor.py --workdir <目录>（复检环境）。单步产物照常记入 manifest。

失败先检索再诊断（硬顺序）：任一步骤报错，先拿报错签名 grep -i 本技能 memory/lessons/（trigger 字段），命中即按条目 action 行动，未命中才从头诊断。数据形态异常同理：统计反直觉、机械结论与目检矛盾时，先按形态关键词查 memory 再动手。

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

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

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

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

L2 基础证据（overview 拼版、字幕带、帧差、音频）已由 pipeline.py --tier L2 采集完毕；以下是你的分析工作。

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

5. 判断纪律（详见 references/evidence-discipline.md，此处只列要点）

• 表述分三档并强制标注：实测（有 JSON/定帧支撑）、约（1s 抽帧 ±0.5s 精度）、推断（显式标注，不得混入实测）。
• 画面文案（references/no-speech-batch.md §1 产物）的表述映射：屏起止时间=帧差/定帧（实测档）；文案内容=模型读图（清晰/放大后可读/不可读三档标注）或 OCR 组装稿的置信度三档（清晰/低置信/不可读，阈值见 references/no-speech-batch.md §1）；uniform 兜底模式的时间一律「约」；读不清的字如实标「不可读」，禁止猜写。
• 交付形态没对齐、分析深度没确认，都不动手（无人值守按 §0 声明式执行）；交互会话中禁止以「用户无法实时回答」为由跳过档位提问（§0 交互模式判定）。客观结论被用户质疑时，给一次带数据的说明，然后把表述改写成对两种可能都成立，继续推进——赢了检测输了进度。
• 交付后回路（一句话，不占轮）：报告末尾附「可升级 L2（附成本）；存疑主张可点名核查；质疑按证据纪律 R4 处理」。
• 收尾写回（经验闭环）：交付前自检三问——环境坑？数据形态新知？流程摩擦？有则按 schema 写 memory/lessons/NNN-slug.json 并在 INDEX.md 加一行；条目实际改变动作时 used +1。单视频结论、未验证猜测、用户隐私不写回。used ≥ 3 或反复验证稳定 → 毕业进代码 / 证据纪律 / SKILL.md，条目标 graduated 并指向去处。
• 追求"结论可信、可回溯、可重复"，不追求"分析得更多"。

6. 边界

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

7. 按需读取与参考文档