video-reference

1. 定位

本技能把一部已完成的成片拆成下一次制作可参考的方法与数值，按需在本地运行。它只写自己的测量、标注与导出物，不调用 MiMo，也不对生产流程评分或拦截。

Agent 的角色是拆片编辑：先如实记录"这部片子怎么做的"（事实），再提炼"换一部素材还能怎么用"（方法）。 两者必须分开：事实只留在本地工作目录，导出物只含方法和测得的数值。

2. 输入

• 成片文件（.mp4 / .mov / .mkv / .webm）。
• 对这部成片跑出的视频理解产物目录 U（建议 ASR_SEGMENT_SECONDS=5，窗口越短，旁白语速越准）。 本技能读取其中可选的 asr_result.json、asr_timing_evidence.json、background_research.json、understanding_index.json （其 characters 的名字、别名与 ASR 提及都进入人名泄漏扫描）； 标注时 Agent 还应看故事板 / contact sheet 与 vlm_analysis.json。

没有理解产物也能跑，但旁白语速为空，泄漏扫描只剩 Agent 自己写的 entities，check 会给出警告； 看画面可用 frames --span 0,<时长> --step 2 生成的抽帧拼图。

下面的 scripts/... 均相对于本技能目录。

3. 流程

python3 scripts/reference.py measure <成片> --work-dir U        # 一次 ffmpeg：切点 + 响度，按文件身份缓存
python3 scripts/reference.py frames  <成片> --work-dir U --review          # 逐帧看被压下的疑似切点
python3 scripts/reference.py frames  <成片> --work-dir U --longest 5       # 看最长镜头里有没有漏切
python3 scripts/reference.py check   --work-dir U [--json]      # 校验并打印派生值
python3 scripts/reference.py export  --work-dir U --out <下次运行的 work_dir>/production_reference.json

1. measure 写 U/reference_measurements.json（只由脚本写）：镜头切点、镜长分布、每分钟切点数、10 秒切点曲线、 整体响度 / LRA / 真峰值、逐秒短期响度。它要解码整片：5 分钟 720p 约 15–70 秒，4K 约 7 分钟；成片不变时复用， 只改 --soft-score/--hard-score 不重新解码。切点规则：scdet 分数 ≥10 必算；≥4 且是前后 0.3 秒内其他帧（相邻帧除外） 两倍以上的孤立峰才算。运动镜头、急推拉、闪光会被压下，并列进 shots.review_windows；scdet 分数会减去前一帧的帧差， 从快速运动切进静止镜头的硬切可能只有 1 分，所以帧差本身的单侧峰（mafd_peaks）也进待复核窗口，但不会自动算切点。
2. 复核切点：固定阈值在真实成片上两头都错（暗场硬切只有 5–7 分；快速运动的单个镜头每 0.2 秒一个 7–8 分的峰）， 所以每次都要看图。frames --review 逐帧拼出每个待复核窗口，frames --longest 5 在最长的 5 个镜头里均匀取 12 帧； 页面在 U/reference_frames/，命令打印每格对应的秒数。看完写 labels.cut_fixes：add 漏掉的切点秒数， remove 误报的切点秒数（±0.1 秒内对上测得的切点）；看过无需改动就写 {}。重新 measure 后待复核窗口数变了，旧的 cut_fixes 不再算数，按新窗口重看一遍。之后所有镜头数值、段内切点密度和导出都用复核后的切点。
3. 标注：Agent 写 U/reference_breakdown.json 的 labels——音轨归属 audio_spans、叙事段落 sections、 字幕形态 subtitles、标注依据 basis。audio_spans 的边界放在声音实际起止处（听得到的人声起点与止点）， 不放在字幕或旁白块的开始处（按字幕出现帧定的旁白结束点实测晚 0.24–0.42 秒）。U/speech_boundary_anchors.json 存在时， 用它的 acoustic_pauses（start 是人声停下处，end 是下一句开口处）对齐边界；switch_on_cut_share 只容差 ±0.25 秒， 边界放错它就只反映标注习惯。原片自带的画外音、内心独白也是原片音轨，记 original_dialogue；要区分时写进 fact 和方法。 只有 labels 时就可以跑 check，它会打印 derived（各音轨占比、段内切点密度、 旁白语速、声音切换与画面切点的对齐比例、分数位置的结构、第一次原声出现位置）。
4. 事实与方法：在同一文件写 source_facts（带时间或测量锚点、显式 entities）和 methods （rule、applies_when、avoid_when、applies_to、evidence、targets）。targets 只写 {"from": "<测量路径>"}， 数值由 export 从当前测量填入，Agent 永远不手写数字。
5. check → export：零 error 才导出；导出后对产物再做一次泄漏扫描。

字段、枚举和好/坏方法示例见 references/reference-schema.md。

4. 分离规则

check 的 error（退出码 1）：

规则	要求
R1	顶层、labels、fact、method、target、cut_fixes 都是封闭键集与封闭枚举；fact 不能带方法字段，method 不能带事实字段；id 为 f1… / m1… 且唯一；subtitles 值类型固定；skipped_dimensions 的值都是非空字符串
R2	audio_spans、sections 按时间排序、不重叠、间隙 ≤0.5s、覆盖整片；字幕证据时间在时长内；cut_fixes.remove 对得上测得的切点，add 不与测得的切点重复
R3	每条 fact 二选一锚定：t:[a,b] 在时长内，或 measure:[路径] 解析到 shots / loudness / derived 下的非字符串值；必须显式写 entities
R4	每条 method 至少一条证据：已有 fact id 或同样只认这三个根的 measure:<路径>
R5	target 只写 from：shots / loudness / derived 下的数值叶子，或白名单派生对象（见 schema）；不得带列表下标
R6	rule / applies_when / avoid_when 和 skipped_dimensions 的原因不得含：原片实体名（忽略空白）、与台词、背景资料或事实共有的连续 8 个汉字（标点隔开、跨相邻 ASR 窗口也算）或 5 个英文词、绝对时间码、"第 N 秒"或"N 分 M 秒"（含中文数字）、绝对路径
R7	五个维度各至少一条 method，或在 skipped_dimensions 写明原因
R8	导出物的每个键和字符串再扫一遍 R6，且不得出现 source_facts、labels、entities、evidence、statement、from、path 键

实体名来自 fact entities、understanding_index.json 的 characters / entities / research_glossary 名字与别名、background_research.json 的角色与 character_details 别名、≤5 字的 cultural_notes 条目，以及资料里《》「」引号中的短词。与事实共有 8 字时错误会注明来自 source_facts：通用剪辑措辞改写任一侧即可。

警告不阻断：method 缺 applies_when、rule 正文写了数字、ASR 不是 AVAILABLE_COARSE、有中文对白但理解产物与背景资料都没给出名字（此时只扫 fact entities）、basis 为空、 理解产物记录的成片身份与测量的成片不一致、有待复核窗口却没写 cut_fixes。

R6 只能拦住字面泄漏，拦不住改写过的剧情；写方法时要写"什么情况下怎么做"，不要复述"这部片里发生了什么"。 规则也不判断语义：方法的方向必须与 check 打印的派生值一致（例如先看各音轨的 cuts_per_min 再写"哪类段落切得密"）。

5. 交付与使用

production_reference.json 只含：时长与画布、cut_detection（切点规则的参数与 Agent 增删的切点数）、 profile（节奏数值，provenance 为 measured / reviewed（写了 cut_fixes，{} 也算）/ labeled）、 分数位置的 structure、字幕形态、methods、skipped_dimensions。

使用方式：把它复制进下一次制作的 work_dir。写稿阶段只在文件存在时阅读它， 并可在 recap_story_plan.json 的可选字段 reference_methods 记录每条方法的 adopt / adapt / skip。 采用时以新素材证据为准，不把参考数值当作配额。没有任何脚本读取它，也不会因为它的存在改变任何阶段的通过与否。

U/ 里的 breakdown 与 reference_frames/ 含原片事实和画面，只留在本地，不要复制或提交。

6. 能力边界

• 不调用 MiMo 或任何 LLM，不改动理解产物，不给成片打分，不做"新片与参考的差距"判定。
• 切点来自 ffmpeg scdet 分数：慢叠化测不到；相隔 0.3 秒内分数相近的两个真切点、刚好压在 soft 线上的切点（不同 ffmpeg 构建 4.00 与 3.989 分）、运动后的暗场硬切（0.9 分）都不算切点，只进待复核窗口。在一部 5 分钟剧集解说上测得 82 个切点， 11 个待复核窗口里 4 个含漏掉的 5 个真切点，其余是急推拉、翻页和运动镜头；补上后，三段逐帧真值（开场、暗场、中段共 27 个）全部对上、无误报。
• 旁白占比与语速是 labeled 精度：来自 Agent 的音轨标注与粗 ASR 窗口，不是逐词对齐。
• 泄漏扫描基于字面匹配，Agent 仍需自查方法是否在复述原片剧情。