1. 定位
本技能用於按需拆解一部已經做好的優秀解說成片，把它的剪輯節奏、聲音分工與敘事手法提煉成下一次製作可直接參考的方法卡片與量化指標。全程在本機執行，只輸出測量資料、拆片標註與去敏參考檔案，不呼叫 MiMo，也不對日常生產線做評分或阻斷。
Agent 在此扮演拆片編輯：先把「這條成片具體是怎麼剪、怎麼配的」（原片事實）如實記下來，再從中提煉出「換一部新素材還能怎麼借鑑」（可遷移方法）。事實與方法必須徹底分家：包含原片人名、劇情和具體台詞的事實只留在本機拆片目錄裡，最終匯出的 production_reference.json 只保留通用方法與實測節奏數值。
2. 輸入
- 待拆解的成片影片檔案（支援
.mp4 / .mov / .mkv / .webm）。 - 針對這部成片跑出的影片理解產物目錄
U（建議在理解階段設ASR_SEGMENT_SECONDS=5，分窗越細，測算出的旁白語速越準）。本技能會從中讀取可選的asr_result.json、asr_timing_evidence.json與background_research.json（其中登記的角色名、別名及 ASR 台詞都會納入防劇透洩漏掃描）；Agent 做人工標註時還應結合故事板拼圖（storyboard）與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 # 抽出最長的 5 個鏡頭，排查裡面有無漏檢切點
python3 scripts/reference.py check --work-dir U [--json] # 校驗拆片稿並列印派生指標
python3 scripts/reference.py export --work-dir U --out <下次執行的 work_dir>/production_reference.json
- 實測鏡頭與響度（
measure）：由腳本產生U/reference_measurements.json（人工切勿手改），記錄全片鏡頭切點、鏡頭時長分佈、每分鐘切點數、10 秒滑動視窗切點密度曲線、整體響度（Integrated LUFS）、響度動態範圍（LRA）、真峰值以及逐秒短期響度。該步驟需完整解碼整部成片（5 分鐘 720p 影片約耗時 15–70 秒，4K 影片約 7 分鐘）；只要成片檔案未變就會直接複用快取，單獨調整--soft-score或--hard-score閾值無需重新解碼。- 切點初篩邏輯：
scdet場景切換得分≥10的幀直接判為切點；得分在4到10之間時，只有當該幀得分達到前後0.3秒視窗內其餘非相鄰幀最高分的兩倍以上（即鶴立雞群的局部峰值），才判為切點。這樣能過濾掉大部分跟拍晃動、急推拉和閃光燈，把這些拿不準的幀歸入待複核視窗shots.review_windows。此外，由於scdet得分會扣減上一幀的畫面變化量，從劇烈運動鏡頭突然硬切到靜止畫面時，scdet得分可能被壓到只有 1 分左右；因此工具會把幀間畫面差（mafd）自身突起的峰值也一併收進shots.review_windows供人工看圖確認，但不會直接算作自動切點。
- 切點初篩邏輯：
- 看圖複核切點（
frames）：任何固定閾值在真實成片面前都會顧此失彼（昏暗夜戲的硬切可能只有 5–7 分，而激烈打鬥的一個長鏡頭裡每隔 0.2 秒就能蹦出 7–8 分的峰值），因此必須看圖複核。執行frames --review會把每個待複核視窗逐幀拼成圖片，執行frames --longest 5會在全片最長的 5 個鏡頭裡各均勻抽取 12 幀拼圖；圖片輸出在U/reference_frames/下，終端會列印每一格對應的時間秒數。看完圖後在labels.cut_fixes中登記修正：add填入演算法漏掉的真切點秒數，remove填入演算法誤報的假切點秒數（與測得切點誤差在±0.1秒內即可匹配）；若確認全部正確、無需增刪，顯式寫"cut_fixes": {}表示已複核。注意：一旦重跑measure導致待複核視窗發生變化，舊的cut_fixes不再算數，Agent 必須對照新視窗重新核對更新。複核完成後，後續所有鏡頭統計指標、段落切點密度和最終匯出物都會按修正後的切點重新計算。 - 標註音軌與段落（
labels）：由 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，如需在打法上區分，寫進後面的source_facts與methods即可。 - 填完
labels後即可先跑一次check，查看終端列印出的派生統計值derived（各音軌時長佔比、各段落切點密度、旁白字速、聲音換手落在畫面硬切上的比例、全片各敘事功能段落在時間軸上的起止佔比structure，以及第一次原聲亮相的相對位置first_original_at）。
- 音軌邊界必須卡在真實聲音起止點：
- 提煉事實與可遷移方法（
source_facts與methods）：對照剛剛算出的客觀派生資料，在同一份reference_breakdown.json中繼續填寫原片事實source_facts（必須錨定具體時間區間或測量路徑，並顯式列出涉及的專有名稱entities）與可遷移方法methods（包含做法規則rule、適用場景applies_when、避坑條件avoid_when、作用的下游檔案applies_to、支撐證據evidence與量化參考指標targets）。注意：targets裡只允許寫引用路徑{"from": "<測量路徑>"}，嚴禁在規則正文裡手寫具體數字；匯出時腳本會自動把實測數值填進去。 - 校驗並匯出（
check→export）：執行check確認零 error 後，執行export匯出production_reference.json；匯出器在寫盤前會對產物再做一遍全欄位防劇透洩漏掃描。
完整欄位定義、列舉詞表以及好/壞方法寫法對比見 references/reference-schema.md。
4. 校驗與防洩漏規則
reference.py check 遇到以下任一錯誤（error）都會以退出碼 1 阻斷：
| 規則編號 | 校驗要求 |
|---|---|
| R1 | 頂層、labels、fact、method、target、cut_fixes 均採用嚴格封閉鍵集與封閉列舉；fact 不得混入方法欄位，method 不得混入事實欄位；編號須形如 f1… / m1… 且全域唯一；subtitles 欄位類型固定；skipped_dimensions 的原因說明必須為非空字串 |
| R2 | audio_spans 與 sections 必須按時間升序排列、互不重疊、相鄰間隙 ≤0.5 秒且完整覆蓋全片時長；字幕取證時間點必須落在全片時長內；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 的原因說明中，嚴禁出現：原片專有名稱（忽略空格比對）、與 ASR 台詞/背景資料/source_facts 完全重合的連續 8 個漢字（跨標點、跨相鄰 ASR 視窗同樣攔截）或連續 5 個英文單詞、絕對時間碼、「第 N 秒」或「N 分 M 秒」（含漢字數字）、本機絕對路徑 |
| R7 | 五大製作維度（narrative_structure、pacing、shots_editing、narration_subtitles、audio_visual）每個維度至少提煉一條 method，若某維度確實無法提煉則必須在 skipped_dimensions 中寫明原因 |
| R8 | 匯出 production_reference.json 時，對所有鍵名和字串值再跑一遍 R6 防洩漏掃描，且匯出物任意層級嚴禁出現 source_facts、labels、entities、evidence、statement、from、path 鍵 |
防洩漏詞表會自動彙總 source_facts[].entities、background_research.json 中的角色與 character_details 別名、不超過 5 個字的 cultural_notes 詞條，以及資料中帶《》「」引號的短詞。若報出與 source_facts 連續 8 字重合，只需把其中一側的通用剪輯表述換個說法即可。
以下情況僅報警告（warning），不阻斷匯出：method 未填 applies_when、rule 正文裡直接寫了阿拉伯數字、ASR 精度不是 AVAILABLE_COARSE、成片含中文對白但理解產物與資料庫均未提供人名（此時僅靠手寫的 entities 把關）、basis 為空、理解產物記錄的影片檔案身份與當前測量的成片不一致、存在待複核切點視窗但未填寫 cut_fixes。
注意：R6 只能攔住字面重合，攔不住換了詞卻仍在複述原片劇情的寫法；編寫 method 時必須總結「遇到什麼素材特徵時怎麼處理」，絕不能寫成「主角進門後怎麼剪」。此外，校驗器不檢查自然語言語義是否與資料吻合——動筆寫「哪類段落切鏡更密」前，必須先核對 check 列印出的 cuts_per_min 實測值，切忌憑印象寫出與實測資料相反的結論。
5. 交付物與後續使用
最終匯出的 production_reference.json 只包含：成片總時長與畫布尺寸、cut_detection（切點檢測參數及人工增刪的切點數）、profile（核心節奏與響度指標，附帶資料來源標記 provenance：measured 表示純演算法實測、reviewed 表示經過 cut_fixes 人工複核、labeled 表示依賴人工音軌/段落標註）、全片各敘事段落在時間軸上的相對位置分佈 structure、字幕版式特徵 subtitles、可遷移方法列表 methods 以及跳過的維度說明 skipped_dimensions。
使用方法：將匯出的 production_reference.json 放進下一次製作任務的 work_dir（或透過資源庫的 production_reference 範本綁定）。下游寫稿階段發現該檔案存在時會主動讀取，並在 recap_story_plan.json 的可選欄位 reference_methods 中逐條記錄對每條方法的採納決定（adopt / adapt / skip）。借鑑參考方法時永遠以新素材的真實畫面和台詞證據為準，絕不把參考片裡的切點密度或留白佔比當成硬性配額生搬硬套。沒有任何生產腳本會機械校驗該檔案，它的存在與否也不會改變任何門禁的放行結果。
U/ 目錄下的 reference_breakdown.json 與 reference_frames/ 抽幀拼圖包含原片劇情事實與畫面，僅供本機拆片使用，切勿複製進新專案或提交到公共倉庫。
6. 能力邊界
- 全程純本機運算，不呼叫 MiMo 或任何大模型，不修改上游影片理解產物，也不給成片好壞打分或計算「新片與參考片的差距」。
- 鏡頭切點基於 ffmpeg
scdet分數加人工看圖複核：慢速疊化轉場無法被演算法自動檢出；間隔不足0.3秒的連續兩個快切、恰好卡在soft_score臨界線上的切點（不同 ffmpeg 版本可能算出4.00與3.989的微小差異）、以及劇烈運動後突入暗場的硬切（得分可能低至0.9）都不會被直接算作自動切點，而是統一收進待複核視窗靠人工看圖兜底。在一部 5 分鐘的劇集解說實測中，演算法初篩抓出 82 個切點，並在 11 個待複核視窗中框住了全部 5 個漏檢真切點（其餘 7 個視窗為急推拉、翻頁與運動鏡頭）；人工看圖補齊這 5 個切點後，與片頭、暗場、中段三處逐幀人工真值（共 27 個切點）100% 吻合、零誤報。 - 旁白佔比與語速屬於
labeled級別精度：由人工標註的音軌區間結合粗粒度 ASR 分窗估算得出，而非逐字時間戳對齊。 - 防劇透洩漏掃描基於字面字串比對，Agent 落筆時仍需主動自查，確保
methods寫的是通用創作手法而非原片故事梗概。