影片指南製作技能
將任何原始螢幕錄影轉換為精美、附帶旁白與動態註解的使用者指南影片（.mp4 + .srt）。
核心規則（務必遵循）
- 零JSON / 使用者無需手動準備： 使用者僅需提供錄影路徑（例如
C:\recordings\demo.mp4或一個幀資料夾）以及可選的指南/流程備註。你負責提取幀、分析整個影片、撰寫recipe JSON、驗證時間並渲染。 - 在編輯前分析所有3-FPS幀： 例如，一段210秒的錄影可產生約630個幀 @ 3 fps。透過FFmpeg提取每個3-fps的幀，掃描所有630個幀，檢查每個產生的Storyboard Contact Sheet（
storyboard_*.png），並檢查全解析度的0NNN_frame.png幀（或使用inspect_frame_slice），然後再撰寫任何recipe步驟。 - 語音、語調與編輯前計畫閘門： 在最終渲染前執行
validate_recipe（--plan_only），顯示你的編輯計畫（步驟數量、時間長度、dock區域、旁白），並要求使用者確認或選擇語音與語調 — 除非使用者明確下達「auto proceed」（或「just render」）指令。 - 首次執行自動設定： 如果克隆後缺少
.venv，請執行python bootstrap.py一次（或直接執行tool_executor.py，它會自動啟動引導程序）。
逐步代理工作流程
階段 1 — 提取3-FPS幀並分析所有幀
執行 create_guide（透過MCP或CLI tool_executor.py）：
# 透過CLI / Codex / Cursor / Antigravity shell：
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py
這會自動：
- 透過內建的FFmpeg提取
3 fps幀（0001_frame.png ... 0NNN_frame.png，例如210秒的影片約630個幀）（engine.py --extract_frames --fps_extracted 3）。 - 使用全域差異和
8×6空間區塊檢測器掃描 100% 的提取幀（0 .. N-1）（因此下拉選單、按鈕點擊、核取方塊和彈出視窗都不會被遺漏）。 - 產出：
storyboard_01.png、storyboard_02.png、... — 帶有#frame、時間戳記、事件標籤（PAGE_TRANSITION/UI_ACTION/IDLE_HOLD）和青色變更區域框的標籤式聯絡頁面，涵蓋整個影片。analysis_3fps.json— 完整時間軸片段 + 變更的像素邊界框[x1, y1, x2, y2]+trim_candidate閒置暫停。recipe_draft.json— 起始的engine.pyrecipe結構。
階段 2 — 視覺檢查Storyboards與關鍵幀（強制）
- 打開並閱讀
storyboard_paths中列出的每個storyboard_*.png圖片。 - 從頭到尾追蹤使用者的完整操作流程：注意頁面載入、表單填寫、彈出視窗/模態框、長時間停頓（
trim_candidate: true），以及任何需要剪掉的誤點擊。 - 從
frames_dir打開特定全解析度的0NNN_frame.png圖片，用於你計畫強調的步驟（如果一個動作在狹窄的幀範圍內快速發生，請調用inspect_frame_slice），以便：- 讀取確切的UI按鈕/欄位/選單文字。
- 為
boxes、arrows、spotlight和zoom測量準確的[x1, y1, x2, y2]座標。
階段 3 — 編寫最終 recipe.json
儲存符合 schemas/recipe.schema.json 的乾淨 recipe.json（查看 examples/recipe_create_exam.json 中的實際範例）：
- 必需的頂層欄位：
source_video、frames_dir、fps_extracted: 3.0、input_source: "auto"、branding_text、preset（tech_hud|clean_light|minimal|high_contrast）、tone（friendly|professional|energetic|calm|corporate）、default_voice、dock_mode: "auto"、total_duration: "auto"、audio_timing_mode: "auto_shift"、export_subtitles: true。- （切勿將
"theme"設為字串 — 應使用"preset"。）
- （切勿將
timeline_mapping：將編輯後的輸出片段清晰地映射到3-FPS來源幀（start_sec、end_sec、source_frame_start_3fps、source_frame_end_3fps）— 跳過無聊的停頓，並加速處理重複的打字！steps：同步的條目（id、start_time、active_start、active_end、step_num、step_title、narration、sub、boxes、arrows、可選的spotlight/zoom）。- 避免將
boxes[].label放在密集的表格標題上，以免藥丸覆蓋相鄰的欄標籤。 - 確保
narration能舒適地容納在每個步驟的[active_start, active_end]時間視窗內。
- 避免將
階段 4 — 驗證計畫並確認語音/語調
執行預飛航驗證（合成Edge-TTS片段，檢查 [AGENT:] 佔位符和重疊，列印動態dock區域）：
python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<PATH_TO_RECIPE_JSON>"}'
語音： en-IN-NeerjaNeural（印度女聲）、en-IN-PrabhatNeural（印度男聲）、en-US-JennyNeural（美國女聲）、en-US-GuyNeural（美國男聲）、en-GB-SoniaNeural（英國女聲）、en-GB-RyanNeural（英國男聲）。
語調： friendly、professional、energetic、calm、corporate。
- 如果出現任何
[OVERLAP WARNING]或has_overlaps為 true，請擴展步驟時間視窗 / 修剪旁白，並重新驗證直到重疊為0。 - 除非使用者要求自動繼續，否則請分享簡短的編輯前計畫，並在渲染前確認語音與語調。
階段 5 — 渲染並視覺驗證輸出
python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<PATH_TO_RECIPE_JSON>","output_path":"<OUTPUT_MP4>","export_srt":true}'
透過FFmpeg快照檢查檢查2–3個渲染幀，確認框、箭頭、品牌藥丸和HUD dock從未與UI文字碰撞，然後傳遞 .mp4 和 .srt 路徑。