菜单
从输入视频端到端生成中文解说成片。用户提供 .mp4 / .mov / .mkv / .webm，并要求添加旁白、 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 → Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、 视频 recap、video recap、voiceover、narration、auto-dub、recap。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录， 最后做响度标准化。作为最终合成阶段使用。输入源视频、tts_meta.json 与旁白位置； 输出 recap 成片和字幕。触发词：视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。
把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节，读取 clip_plan.json 与源视频， 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。单独调用且未传 --no-narration-map 时， 仍支持旧版单阶段路径，把原片时间的 narration.json 映射为 narration_mapped.json。 触发词：视频剪辑、剪辑式解说、video cut、clip plan、拼剪。
对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验。work_dir 已包含 agent_narration_brief.md 与 vlm_analysis.json 时使用。适用于故事方向、片段选择、画面/原声/旁白分工、 解说写作与复核。输入 work_dir 中的理解索引；输出 recap_story_plan.json、visual_audio_board.json、 cut 模式需要的 clip_plan.json，以及通过校验的 narration.json。触发词：解说词、写解说、视频旁白、 narration script、写稿、解说文案、剪辑思路、导演思路。
把视频分析为结构化理解索引：场景检测、ASR 转写、逐场景 VLM 观察、静音窗口、融合时间线和写作 brief。 用于理解、索引或总结视频，也作为后续创作前的分析阶段。输入视频文件；输出 scenes.json、 asr_result.json、vlm_analysis.json、silence_periods.json、timeline_fusion.json、agent_narration_brief.md。 触发词：视频理解、视频分析、视频索引、video understanding、analyze video、看懂视频。
把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）逐段生成语音， 按时间窗动态适配语速并处理响度；输入输出时间线上的旁白，产出 tts_segments 与 tts_meta.json。 旧版直接剪辑路径也可显式传入 narration_mapped.json。触发词：配音、语音合成、TTS、解说配音、 voiceover、text to speech、旁白配音。
| name | video-recap |
| description | 从输入视频端到端生成中文解说成片。用户提供 .mp4 / .mov / .mkv / .webm，并要求添加旁白、 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 → Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、 视频 recap、video recap、voiceover、narration、auto-dub、recap。 |
本技能是五个独立技能的轻量编排器。各技能只通过 work_dir 中的 JSON / MP4 产物通信，不共享代码：
video-understanding ─▶ Agent 按 video-script 制定方案并写稿 ─▶ [video-cut] ─▶ video-voiceover ─▶ video-assemble
流程支持断点续跑：写好 narration.json 后重复同一条命令即可继续。第二阶段会校验
recap_run_manifest.json，拒绝复用来自其他源视频或其他运行参数的旧工作目录；视频理解产物也只在来源一致时复用。
这不是单纯的 JSON / 渲染流水线。Agent 是本次内容的创作负责人，在进入昂贵的下游处理前，必须按顺序完成五次判断：
执行前阅读本技能的 references/creative-editing-playbook.md，并把简洁的创作决定写入：
recap_story_plan.json：导演意图、备选假设、选定主线和基于变化的 beat 图。visual_audio_board.json：每拍的画面任务、表演/反应选择、原声锚点、audio_owner 与 narration_job。这两个文件只记录可审计的决定，不记录冗长思维过程；它们不会增加服务或渲染依赖。现有工具可以忽略它们，Agent 与建议型解说评审会用它们保持创作一致。建立这条内容基线不需要平台数据。
# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***
同一个 MiMo key 驱动：
mimo-v2.5-asrmimo-v2.5mimo-v2.5-ttstp-* Token Plan 密钥默认使用中国区集群，可用 MIMO_TOKEN_PLAN_CLUSTER 覆盖。
可选能力：
--mimo-video-overview：按场景块补充 MiMo 视频理解。--mimo-qc pre-assemble|post-render|both：在合成前、成片后或两个阶段给出建议型复核。MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 mimo_qc.json。任何凭证缺失、限流、超时、格式错误或采样失败都只记录状态，不阻断流程。详细可覆盖配置见 references/config-playbook.md。
下面的 scripts/... 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本启动后会自行定位兄弟技能和资源。
若能识别影片、剧集或主题，先按本技能的 references/research-guide.md 调研并写入
work_dir/background_research.json。视频理解会把人物名和剧情背景折入 VLM 上下文，避免只得到“黑衣男子”一类模糊描述。无法识别来源时可跳过。
python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
命令完成视频理解、写出 agent_narration_brief.md，然后暂停。此时按以下顺序执行 video-script：
recap_story_plan.json 和 visual_audio_board.json。narration.json；cut 模式第一阶段只写 clip_plan.json。narration.json。不要从标题或旁白句子开始；先锁定故事体验和素材选择。
时间线有两条不可降级的硬约束：原声只能在可靠句末/静音边界被切入、切出或恢复；旁白必须使用
完整逐段音频，任何 clip 映射裁段、TTS 裁尾或剪映引用更长的加速前素材都阻断。Agent 收到
interrupts_source_sentence / unsafe_clip_sentence_boundary / no_safe_fit /
timeline_audio_mismatch 时，应移动边界、缩短整句或删除该块，而不是增加抢断 override。
多视频只支持 cut 模式。项目 brief 会列出稳定的 source_id，clip_plan.json 中每个片段都必须填写来源：
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
可选文件系统素材库：
python3 scripts/recap.py ep1.mp4 --material-library-dir .video-materials --save-materials
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir .video-materials --use-materials
素材检索只是对 JSON / MD / JSONL 做 grep，例如 grep -R "keyword" .video-materials。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。
写好所需产物后，重复同一条命令：
python3 scripts/recap.py <video> --work-dir <work_dir> # 可追加 --edit-mode cut / --no-burn-subtitles
流程会校验当前阶段的硬输入（clip_plan.json / narration.json）；两份创作计划仍是 Agent 与建议型评审使用的工作记录，不是渲染门禁。cut 模式随后生成 edited_source.mp4，再合成旁白并输出 recap_<name>.mp4。
若需要建议型 MiMo 复核：
python3 scripts/recap.py <video> --work-dir <work_dir> --mimo-qc both
合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。相同输入命中内容缓存，--mimo-qc-refresh 可强制刷新。帧的 base64 与凭证不会写入磁盘。
若要把旁白字幕固定在原片字幕区域，先在仓库根目录运行：
python3 tools/measure_subtitle.py <video>
再传入测得的 --subtitle-y-top/--subtitle-y-bot。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 [top, bot)，并要求底对齐 ASS 样式；显式设置后，该区域默认使用 60% 透明度的旁白窗口遮罩。
解说模式如需克隆参考声音，使用 --voice-ref <audio>；它与 dub 模式不同。
--edit-mode dub 把英文视频翻译为中文，并用原说话者的克隆音色替换人声；它不是在压低原声上叠加解说。
python3 scripts/recap.py <video> --edit-mode dub --work-dir <work_dir>
准备阶段会转写英文、提取一段参考音频，并写出 dub_brief.md 与 dub_transcript.json。Agent 随后写：
[{"start": 0.0, "end": 2.0, "zh": "中文译文"}]
要求：
[start, end]，相邻句不重叠。重复同一命令后输出 dub_<name>.mp4。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。
python3 scripts/recap.py --doctor
主要输出：
recap_<video>.mp4：最终成片。subtitles.srt / subtitles.ass：字幕。work_dir/：全部中间产物，契约见 references/data-schema.md。work_dir/recap_story_plan.json / visual_audio_board.json：Agent 创作意图与剪辑决定。work_dir/mimo_qc.json：可选的建议型复核，不作为发布门禁。可透传参数：
--context、--scene-threshold、--style、--edit-mode {full,cut,dub}、--target-duration、
--skip-asr、--mimo-video-overview、--mimo-qc {off,pre-assemble,post-render,both}、
--mimo-qc-refresh、--consolidate、--consolidate-asr、--mimo-tts-voice、--voice-ref、
--allow-partial-tts、--review-narration、--no-review-narration、--require-narration-review、
--subtitle-y-top、--subtitle-y-bot、--no-burn-subtitles、--output-dir、
--export-jianying、--jianying-bundle-media、--jianying-no-bundle-media、
--material-library-dir、--use-materials、--save-materials。
--style 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。
narration.json / clip_plan.json；具体写作遵循创作 brief 与写作阶段契约。work_dir 产物通信。