1. 定位與流程
本技能是自包含的影片解說與剪輯生產技能，將影片理解、故事立意、畫面剪輯、旁白撰稿、配音合成與音畫混音收斂在同一條連貫工作流中，各階段共享同一工作目錄 work_dir 下的 JSON 與 MP4 產物：
understand.py（影片理解）─▶ Agent 制定故事/聲畫方案並寫 clip_plan.json 或 narration.json ─▶ [cut.py（剪輯與重出簡報）] ─▶ validate.py（本地底線校驗）─▶ voiceover.py（TTS 配音）─▶ assemble.py（混音與字幕渲染）
日常使用可直接呼叫總入口 scripts/recap.py 自動串聯全流程並在創作節點暫停，也可按需單獨呼叫本技能 scripts/ 下的單階段入口（understand.py、cut.py、validate.py、voiceover.py、assemble.py）。
把現有成片拆解為製作參考（production_reference.json）不在預設生產鏈上。當使用者要求拆片學習時：先對樣片跑 understand.py（建議設 ASR_SEGMENT_SECONDS=5），再用獨立的拆片技能依序執行測量（measure）、標註、校驗（check）與匯出（export），將匯出的 production_reference.json 複製進下一輪執行的 work_dir，或登記為資源庫裡的 production_reference 模板並經 --project 綁定。主流程不會自動跑拆片，也不拿新成片去跟參考片做機械比對。
全流程支援斷點續跑：Agent 寫完 clip_plan.json 或 narration.json 後，重跑同一條 recap.py 指令即可往下走。續跑時腳本會核對 recap_run_manifest.json 中記錄的來源影片路徑、檔案大小、修改時間及執行參數，一旦發現工作目錄來自其他影片或不同參數組合會直接拒絕複用；影片理解快取也只在來源片與配置完全一致時命中。每次暫停時終端列印的續跑指令保留了原始呼叫寫法，並自動把影片與路徑參數轉為絕對路徑、補齊 --work-dir，複製貼上到任意目錄都能直接跑。
畫面流程 --edit-mode full|cut 與聲音策略 --audio-mode narration|source-mix 相互獨立：narration 走標準解說配音鏈，source-mix 不產生配音而直接混入原聲與可選配樂。系統僅支援下表列出的五條合法路線，其餘組合在啟動時直接報錯攔截：
| 輸入 | --edit-mode | --audio-mode | Agent 暫停點 | 流程 | 詳見 |
|---|---|---|---|---|---|
| 單影片 | full | narration | 1 次：寫 narration.json | 理解 → 寫稿 → 校驗 → 配音 → 合成 | §4 |
| 單影片 | cut | narration | 2 次：先寫 clip_plan.json，剪完再對成片寫 narration.json | 理解 → 剪輯 → 重出輸出時間簡報 → 寫稿 → 校驗 → 配音 → 合成 | §4 |
| 多影片 | cut | narration | 2 次：同上，且每條片段必須帶 source_id | 逐源理解 → 剪輯 → 寫稿 → 校驗 → 配音 → 合成 | §4.5 |
| 單影片 | full | source-mix | 無暫停 | 直接合成當前整段影片（不跑理解或 TTS） | §4.7 |
| 單 / 多影片 | cut | source-mix | 1 次：寫 clip_plan.json | 理解 → 剪輯 → 合成（不寫旁白） | §4.7 |
2. 創作職責
創作拍板權完全歸 Agent。動筆前先判斷本輪的創作控制模式（CREATE 開放創作 / DIRECTED 定向創作 / REVISION 定稿返修，與 --edit-mode 獨立），並在進入配音和渲染前作為同一個創作大腦一氣呵成完成五項判斷：
- 導演判斷：明確觀眾點進來看什麼、全程跟誰的視角（POV）走、核心懸念是什麼、情緒從哪兒起到哪兒落，以及哪張底牌留到最後掀開。
- 故事編輯：每一拍（beat）都必須交代「局勢發生了什麼實質轉折」，絕不寫流水帳式的場景摘要。
- 畫面剪輯：挑出最扎人的動作、變臉反應與最佳入出點，砍掉拖泥帶水的過場。
- 聲音/旁白：先定每一拍由畫面、原聲對白、動作聲、沉默還是旁白當家，再按「墊半句、讓半句、接半句」動筆寫詞。
- 觀眾複核：站在第一次點進來的觀眾視角，分別做關旁白看畫面、閉眼純聽聲音和首尾兌現自檢。
三種控制模式的分工、REVISION 下的鎖定不回退規則、具體剪輯與寫作技法，以及 recap_story_plan.json、visual_audio_board.json、style_card.json 的格式規範詳見 references/creative-editing-playbook.md。這些 JSON 用來沉澱可複查的創作決定，確保選鏡、原聲留白與解說詞從頭到尾咬住同一個故事意圖。
3. 環境與遠端呼叫說明
# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***
同一個 MIMO_API_KEY 即可驅動預設全鏈路。為保證資料流向透明，本技能涉及遠端網路呼叫的環節說明如下：
- 影片理解（
understand.py）：將切分後的音訊視窗發往 MiMo ASR（mimo-v2.5-asr），將抽幀 JPEG 連同background_research.json摘要發往 MiMo VLM（mimo-v2.5）。若工作目錄已有完整分析產物，傳--brief-only或--edited-storyboard-only則純本機執行、不發起任何網路請求。 - 旁白配音（
voiceover.py）：按--tts-provider（預設auto優先選已設定的 MiMo，其次 Fish Audio，絕不自動選index-tts）將解說文字發往對應 TTS 服務：mimo-tts：發往 MiMo TTS（mimo-v2.5-tts）；若顯式傳了--voice-ref <audio>，還會將該參考音訊切片發往mimo-v2.5-tts-voiceclone（使用前請確認已獲聲音授權）。fish-audio：需設定FISH_API_KEY，將每段解說文字與FISH_TTS_REFERENCE_ID發往FISH_TTS_API_URL（預設https://api.fish.audio/v1/tts）。index-tts：僅在顯式指定--tts-provider index-tts時啟用，將文字與INDEX_TTS_VOICE發往使用者自建的INDEX_TTS_ENDPOINT（詳見references/index-tts.md）。
- 解說校驗（
validate.py）、影片剪輯（cut.py、shot_review.py）與音畫合成（assemble.py）：純本機確定性邏輯與ffmpeg/ffprobe呼叫，不發起任何網路請求。
以 tp- 開頭的 Token Plan 金鑰預設發往中國區叢集，可透過 MIMO_TOKEN_PLAN_CLUSTER 切換叢集。全量設定項見 references/config-playbook.md，所有中間產物格式見 references/data-schema.md。下文中的 scripts/... 均相對於本技能目錄。
4. 一氣呵成的創作與剪輯流程
4.1 背景調研與影片理解
只要能從檔案名或使用者指令裡認出片名、劇集名或科普主題，開跑前先按 references/research-guide.md 查清人物關係與前情，寫入 work_dir/background_research.json。這樣後續跑畫面分析時就能直接叫準角色姓名、看懂潛臺詞，不會滿屏只寫出「黑衣男子」「年輕女子」。多影片連剪時同樣寫在專案根 work_dir 下，腳本會自動同步到各源子目錄 sources/<source_id>/。
隨後啟動理解與編排入口：
python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
腳本完成音訊提取、靜音與句末停頓錨點偵測（speech_boundary_anchors.json）、場景切分、VLM 幀分析與 ASR 轉寫後，生成故事板拼圖 storyboard/storyboard_*.jpg 與創作簡報 agent_narration_brief.md 並自動暫停。
4.2 導演意圖與選鏡計畫（cut 第一階段）
通讀 agent_narration_brief.md 並直接檢視故事板抽幀圖片後，先寫 recap_story_plan.json（至少列出 2 個候選方案並選定主視角 POV、開場鉤子、情緒弧線與留白底牌）與 visual_audio_board.json（逐拍明確選哪個瞬間、為何進出、聲音誰當家）。
在 cut 模式第一階段，接著編寫基於**原片時間軸（SOURCE）**的 work_dir/clip_plan.json（此時還不寫 narration.json）：
{
"target_duration": "3m",
"clips": [
{
"start": 12.0,
"end": 38.0,
"reason": "b01 | hook | knowledge: unknown→threat | POV=沈曼 | 撞見未婚夫摟著千金談聯姻 | 入點=推門看清兩人動作 | 出點=轉身攥緊戶口本"
}
],
"required_evidence": {
"nodes": [
{"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推門撞見兩人擁抱"}
],
"before": []
}
}
選鏡與切點必須嚴守以下底線：
reason七段式結構：依序寫明beat_id | 敘事功能 | 局勢狀態變化（A→B） | POV=人物 | 本段實質看點 | 入點=具體動作/原聲錨點 | 出點=具體反應/落點，倒逼每段畫面都服務於故事推進。- 必保畫面與原聲證據（
required_evidence）：拍板決定必須留住的高光動作、變臉瞬間或關鍵原聲問答，寫入頂層required_evidence（nodes登記id/source絕對路徑/start/end/track/content，before登記不可顛倒的先後對）；邊界吸附一旦裁掉任何必保區間或打亂先後順序，腳本會直接報錯阻斷。 - 開場晚進場與鏡頭取捨：預設按時間順序「晚進場」（直接從衝突爆發、荒誕反差或關鍵動作切入，砍掉推門進屋、寒暄起勢等慢熱鋪墊）；僅當正序衝突出現過晚時才允許摘
<= 2.5s的冷開場懸念鏡，且必須做到不鋪墊也能看懂、不與正片重複同一機位畫面、只留懸念絕不提前劇透反轉結果。旁白壓低原聲時，優先選聽者變臉反應、動作細節或穩態鏡頭，避免把角色正臉滔滔不絕張嘴卻被消音的畫面墊在旁白底下；同款點頭或呆看反應鏡不重複超過兩次。 - 句末安全切點與呼吸尾墊：切點必須落在原片首尾、句末停頓錨點或靜音視窗內，或者屬於同源相鄰片段無縫順接；吸附句末時會自動在停頓視窗內預留最多
0.30s反應/呼吸氣口且絕不跨越硬切點，片段最短時長不低於0.8s。片尾最後一拍必須在結局動作或臺詞落定後留出1.5–2.5s表情餘韻，並在跨入下一場前乾淨收尾。踩進原聲臺詞中間會觸發unsafe_clip_sentence_boundary阻斷並給出nearest_safe；若回退硬切吸附會同時暴露<= 0.20s閃幀與截斷臺詞，則直接報shot_speech_conflict阻斷。 - 高頻快切與碎鏡頭排查：
cut.py渲染edited_source.mp4後會自動呼叫shot_review.py產生shot_review.json，並對時長<= 0.20s（約 1–5 幀）的極短殘鏡閃幀（flash_slivers）直接硬阻斷。面對動作戲或密集反打時，也可手動執行ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null -或唯讀工具scripts/shot_review.py（用法見references/shot-review.md）定位高分切點，但必須區分原片自帶的切點與由本次拼接製造的切點——若屬於原片自帶的無關短鏡頭整段刪除或把切點挪到快切簇外側；若屬於由本次拼接製造的切點（如硬切邊緣殘留幾幀隔壁鏡頭、碎反打），則外擴入出點或合併同源相鄰片段，嚴禁靠塞轉場遮醜。
寫好 clip_plan.json 後重跑 recap.py，腳本會呼叫 cut.py 完成三步邊界吸附（鏡頭硬切吸附 → 句末靜音吸附與尾墊 → 幀網格對齊）、渲染恆定幀率 edited_source.mp4 並完成閃幀體檢，再把 ASR、VLM 與句末錨點重新對應到成片輸出時間軸（speech_boundary_anchors_output.json、storyboard/edited_storyboard.*），隨後再次暫停等待寫解說詞。
4.3 解說詞與原聲留白創作（full / cut 第二階段）
進入寫稿階段後（full 模式在第一次暫停、cut 模式在剪完 edited_source.mp4 後的第二次暫停），先檢視剪後故事板、補齊 visual_audio_board.json 的成片輸出時間，並按需編寫 style_card.json，再撰寫 work_dir/narration.json：
[
{
"start": 0.2,
"end": 5.0,
"narration": "相戀五年揣著戶口本去求婚，沈曼推開門，卻撞見未婚夫正摟著千金談聯姻。",
"pause_after_ms": 250,
"overlaps_speech": true
}
]
注意：編排 cut 模式下，narration.json 必須直接填寫剪後成片的 OUTPUT 時間戳（0 .. 成片總時長）（單獨呼叫校驗器時傳 validate.py --mode cut_output）。動筆時遵循九條核心寫作鐵律（詳規與正反例見 references/creative-editing-playbook.md）：
- 前 2.5 秒內亮出鉤子或原聲高光，直接拋具體反差動作或核心懸念，不寫人物簡歷、日期播報或寒暄開場；超過
2.5s既無旁白也無原聲對白的冷開場會觸發weak_cold_open_silence阻斷。 - 講清背景、人物關係與因果，控制點名密度，拒絕「看圖說話」：已提供
background_research.json角色名時嚴禁用「黑衣男子」「年輕女子」等籠統外貌詞指代（違者報generic_character_label阻斷）；60 秒以內短片最多點名 1–2 個核心人物（首句最多點 1 人並順帶點明身份），其餘次要角色統一用關係/身份稱呼（如「前女友」「她上司」「太醫」），句句圍繞「處境 → 動作 → 當場後果」推進。 - 聲畫對位「墊半句、讓半句、接半句」且強視覺必同頻：高光原聲臺詞、耳光聲、沉默變臉前果斷閉嘴讓位，原聲落定後再接半句點破潛臺詞；畫面出現接吻、扇耳光、下跪、暈倒、亮信物等強視覺動作時，必須由保留原聲或緊鄰旁白正面交代因果，禁止各說各話；全片嚴禁出現連續超過
5.0s既無旁白也無原聲對白的死氣空窗（違者報excessive_dead_air阻斷）。 - 死守原聲切入與回升雙紅線：壓低原聲切入旁白（
overlaps_speech: true）時，start必須貼緊句末錨點或靜音區（違者報interrupts_source_sentence阻斷）；旁白結束放回原聲時同樣不得在角色半句話中間突然恢復音量（違者在校驗與合成階段分別報unsafe_source_release/unsafe_source_handoff阻斷）。 - 嚴控時間窗字數預算、保持自然語速與完整句收尾：每段必須以完整句末標點收口（殘句報
incomplete_sentence硬阻斷），靠精煉字數適配時間窗而非指望高倍速硬塞；full模式超預算 1.25 倍直接報over_budget阻斷，校驗器絕不擅自替 Agent 刪字。 - 清零議論昇華腔與電報腔，結局交給畫面演完：寫自然連貫的口語長短句，不寫一詞一頓的碎句；嚴禁寫「這意味著……」「這是一場關於……的較量」「讓權力與驕傲退場」「命運的齒輪」等閱讀理解式點評與昇華套話（觸發
editorial_commentary_tone告警）。故事結局必須由畫面與原聲當場演出來，嚴禁在結局兌現後再畫蛇添足補一句總結昇華旁白，也不要在收束旁白後再拖一句重複同一結果的原聲尾巴。 - 錨定具體畫面證據與純器樂配樂紀律：用看得到的眼神、道具、動作細節說話，不替角色編造畫面外的心理活動；若選用外部配樂（
BGM_PATH），必須使用純器樂（零人聲歌詞），且當原片已帶無法避開的高音量人聲插曲時不再疊外部配樂，防止多軌人聲互搶。 - 核准原聲留白字幕：當開啟原片字幕遮罩且留有原聲高光段落時，同步在
work_dir/original_subtitles.json中按成片時間寫出校對後的原聲臺詞，修正 ASR 同音錯字。 - 寫完先做三遍自檢：先通讀全文看故事線通不通、事實與原片對不對得上，再對照時間窗查有沒有搶話或超字數，最後跑
validate.py（或直接重跑recap.py）。如需撰寫外層宣發標題、封面幀與花字方案（packaging_plan.json），必須在正片故事鎖死後按references/promotional-copy.md執行。
4.4 配音合成與音畫混音渲染
寫好 narration.json 後重跑同一條 recap.py 指令：
- 本機確定性校驗（
validate.py）：產生narration_lint.json，對時間重疊、越界、字數超預算、殘句、開場冷場、超過 5 秒的死氣空窗、搶斷原話、半句放回原聲、籠統角色代稱與佔位符洩漏做硬門禁檢查，存在 error 立即停機。 - TTS 配音（
voiceover.py）：逐段合成語音並寫入tts_segments/與tts_meta.json。快取按文字、音色、模型與參考音訊指紋精確命中；若某段音訊時長低於正常語速下限（TTS_MIN_SPEECH_RATE）疑似模型幻讀，會自動重試並留存*.rejected.wav拒止入庫。 - 音畫合成（
assemble.py）：將畫面、逐段旁白、壓低與句末回升後的原聲（詳見references/data-schema.md中source_handoff_status說明）、可選 BGM（BGM_PATH）、可選點綴轉場音效與精裝視覺包裝（work_dir/packaging_plan.json：支援9:16豎版舞臺/劇集雙金線畫幅、16:9影院印章與米白紙感字幕條、@2x超取樣人物銘牌/資料卡/書法花字，以及雙層柔光重點詞點亮字幕；或packaging_layers.json靜態貼圖）、片尾平滑淡出（預設350ms）一併混音渲染為最終 MP4，並輸出後端無關的timeline.json（傳--export-jianying可同步匯出剪映草稿）。
任何一段旁白若在允許的微加速上限內仍塞不進可用時間窗，合成器直接報 no_safe_fit 阻斷，絕不削斷旁白尾音。更多聲音模式、音訊路由與外層視覺包裝規範分別見 references/audio-modes.md、references/audio-routing.md 與 references/packaging.md。
4.5 多影片連剪與資源庫
多影片輸入僅支援 cut 模式。專案級簡報會列出每個影片固定的 source_id，編寫 clip_plan.json 時每條片段都必須指明所屬的 source_id：
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
如需把單集理解結果存進本機目錄供跨集複用，可開啟輕量檔案素材庫（--material-library-dir .video-materials --save-materials 與 --use-materials），直接用 grep 檢索 JSON/MD 檔案。同一個庫根目錄下還可登記可複用的製作資源（BGM、音效、音色、字型、貼圖）、帶採納記錄的模板（subtitle_style、packaging、production_reference）及樣片，通過 scripts/library.py check|list|show 查詢，並用 --project recap_project.json 一鍵綁定到當次執行；每次合成結束後會在 work_dir/resource_lock.json 中記錄實際使用的資源及授權狀態。詳見 references/resource-library.md。
如需測量原片硬字幕的縱向畫素區間以啟用精確遮罩，可在完整原始碼倉庫下執行 tools/measure_subtitle.py <video>，或直接檢視抽幀圖片量出上下邊界，再傳入 --subtitle-y-top 與 --subtitle-y-bot。
4.6 最終觀看與交付複核
任何腳本指標、接點打分、抽幀拼圖和自動 QC 報告都替代不了肉眼看片與親耳聽音。每次準備交付前，必須直接開啟本輪最終要交付給使用者的成片檔案，完成五步複核：
- 原速通看一遍：從頭到尾不倍速、不跳看，邊看邊記下所有扎眼或卡頓的地方。
- 逐個盯拼接點：把每個切點前後 0.5–1 秒拉出來看，排查閃幀、半截疊化、動作跳接和被掐斷的半句原聲。
- 閉上眼純聽一遍：不看畫面只聽聲音，檢查旁白有沒有碎成一蹦一跳的電報腔、轉場處聲音過得順不順、關鍵原聲臺詞清不清楚。
- 單拎三處戲眼：把前 5 秒開場鉤子、中段情緒爆發點和片尾最後一幕單獨重看一遍，確認切入時機、情緒停留和收尾餘味全都立得住。
- 返修對帳與規格兜底：REVISION 模式先逐條確認「點名要改的真改到位了、沒點名的鎖定項分毫未動」，最後再核對
final_qc.json的解碼完整性、總時長、殘幀掃描與音畫編碼規格（--require-final-qc預設開啟，阻斷項直接決定退出碼；僅除錯時可傳--no-require-final-qc）。
交付成片時務必查看 final_qc.json 裡的 metadata.warnings：只要非空（例如開啟部分容錯後出現 partial_tts 缺段，或本機 ffmpeg 缺少 libass 觸發 subtitle_burn_degraded 降級為外掛 .srt）就必須如實告知使用者，不能只報一句「渲染成功」。
4.7 不需要解說的原聲成片
# 對當前整段輸入直接混音合成；不隱式跑理解、ASR 或 TTS
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# 按 cut 流程產生剪輯計畫，剪完直接合成原聲成片，不再暫停等待 narration.json
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix
source-mix 會走完整的混音、片尾平滑淡出與音訊重新編碼。切換音訊模式時必須使用全新的工作目錄。詳見 references/audio-routing.md。
5. 自檢與唯讀看板
python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <目錄> [--port 0] [--open]
doctor.py 檢查本機 ffmpeg / ffprobe、字幕濾鏡與各家遠端服務金鑰連通性；dashboard_server.py 在本機 127.0.0.1 啟動嚴格唯讀的極簡審片臺（僅回應 GET 與 HEAD），自動掃描 --root 下的成片工作目錄與 library.json，直觀展示成片播放、解說詞與鏡頭同步對照及素材庫預覽。
6. 輸出與參數
核心交付物：
recap_<video>.mp4：最終解說或原聲成片。subtitles.srt/subtitles.ass：產生的字幕檔案。work_dir/：全套中間分析、計畫與校驗產物，欄位契約見references/data-schema.md。work_dir/recap_story_plan.json與visual_audio_board.json：Agent 落盤的導演意圖與分鏡聲畫決定。
全量命令列參數以 python3 scripts/recap.py --help 及各階段腳本 --help 輸出為準。其中 --style 是原封不動透傳給寫稿 Agent 的自由文字要求，並非固定預設或列舉開關。
7. 能力邊界
- 本機確定性底線校驗（殘鏡/碎鏡、臺詞截斷、旁白壓臺詞、時間窗字數硬上限、超長削尾、必保畫面丟失、佔位符洩漏、解碼與封裝規格）始終作為硬門禁執行；腳本只負責機械執行與工程地板兜底。
- 故事弧線、開場鉤子、聲畫呼吸感與事實一致性等語義與敘事品質不設模型打分門禁，由 Agent 對照畫面證據、原聲時間軸及
references/creative-editing-playbook.md自主把控並完成交付前視聽複核。