视频指南制作 Skill
将任何原始屏幕录制转化为精美、带旁白、动态注释的用户指南视频（.mp4 + .srt）。
核心规则（始终遵守）
- 零 JSON / 零用户手动准备： 用户只需提供录制路径（如
C:\recordings\demo.mp4或帧文件夹）和可选的指南/流程笔记。你负责提取帧、分析整个视频、编写recipe JSON、验证时间并渲染。 - 在编辑前分析所有3 FPS帧： 例如，210秒的录制在3 FPS下会产生约630帧。通过FFmpeg提取每3 FPS的帧，扫描所有630帧，检查每个生成的Storyboard Contact Sheet（
storyboard_*.png），并检查全分辨率0NNN_frame.png帧（或使用inspect_frame_slice），然后再编写任何recipe步骤。 - 语音、语调与预编辑计划门控： 在最终渲染之前，运行
validate_recipe（--plan_only），展示你的编辑计划（步骤数、时长、停靠区、旁白），并让用户确认或选择语音和语调——除非用户明确指示"auto proceed"（或"just render"）。 - 首次运行自动设置： 如果
.venv缺失，克隆后运行一次python bootstrap.py（或直接运行tool_executor.py，它会自动进行引导）。
分步代理工作流程
阶段1 — 提取3 FPS帧并分析所有帧
通过MCP或CLI tool_executor.py 运行create_guide：
# 通过 CLI / Codex / Cursor / Antigravity shell：
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py
这将自动：
- 通过捆绑的FFmpeg（
engine.py --extract_frames --fps_extracted 3）提取3 fps的帧（0001_frame.png ... 0NNN_frame.png，例如210秒产生630帧）。 - 扫描100%的提取帧（
0 .. N-1），同时使用全局差异和8×6空间块检测器（因此下拉菜单、按钮点击、复选框和模态框都不会被遗漏）。 - 输出：
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 — 视觉检查故事板和关键帧（必需）
- 打开并读取
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
保存一个干净的recipe.json，符合schemas/recipe.schema.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:]占位符和重叠情况，打印动态停靠区）：
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，则扩展步骤窗口/修剪旁白并重新验证，直到重叠为零。 - 除非用户指示自动继续，否则在渲染前分享简短的预编辑计划并确认语音和语调。
阶段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停靠区不会与UI文本冲突，然后交付.mp4和.srt路径。