Video Guide Maker 技能
将任何原始屏幕录制转换为精美、带旁白、动态注释的用户指南视频（.mp4 + .srt）。
核心规则（始终遵守）
- 零 JSON / 零用户手动准备： 用户只需提供录制视频路径（例如
C:\recordings\demo.mp4或帧文件夹）以及可选的指南/流程说明。你负责提取帧、分析整个视频、编写 recipe JSON、验证时间线并最终渲染。 - 在编辑前分析所有 3 FPS 帧： 例如，一段 210 秒的录制视频以 3 FPS 提取，将产生 约 630 帧。通过 FFmpeg 提取每 3 FPS 一帧，扫描所有 630 帧，检查每个生成的故事板接触页 (
storyboard_*.png)，并检查全分辨率0NNN_frame.png帧（或使用inspect_frame_slice），然后再编写任何 recipe 步骤。 - 语音、语气与预编辑计划关卡： 在最终渲染前，运行
validate_recipe(--plan_only)，展示你的编辑计划（步骤数、时长、停靠区域、旁白），并要求用户确认或选择语音和语气 —— 除非用户明确指示了"auto proceed"（或"just render"）。 - 首次运行自动设置： 如果克隆后缺少
.venv，运行一次python bootstrap.py（或直接运行tool_executor.py，它会自动进行引导）。
分步 Agent 工作流
阶段 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 — 视觉检查故事板与关键帧（必需）
- 打开并读取
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 文件路径。