promo-video
从原始片段拼接短视频宣传片。支持竖屏、横屏或方形。 可选Blender渲染的开场/结尾，可选AI生成的音乐。
该技能与宿主智能体无关：它必须在每个实现了Agent Skills标准（https://agentskills.io）的运行时上以完全相同的方式工作——Claude、Claude Code、OpenAI Codex、Gemini CLI、Cursor、GitHub Copilot、Cline、OpenCode、OpenHands、Goose、Kiro、Junie等。切勿依赖宿主特定工具（不使用AskUserQuestion、斜杠命令，除非明确可用，不支持MCP）。所有用户交互均以普通聊天消息进行。
何时使用
- "把这些片段剪成一个30秒短片。"
- "帮我做一个竖屏黑客马拉松宣传视频。"
- "我有一个手机视频文件夹——制作一个1080x1920的社交片段，带音乐。"
- "生成一个带Logo开场+心形结尾+背景曲目的宣传片。"
- 用户提到包含
.mov/.mp4文件的目录，希望得到一个成品。
前置条件
ffmpeg已加入PATH，且编译时包含libx264、aac和prores_ks（最后一个仅用于含Alpha通道的开场/结尾MOV文件）。- Python 3.9+。
- 安装Python依赖一次：在技能目录内执行
pip install -r requirements.txt。 - 可选：在项目根目录放置包含
SUNO_API_KEY的.env文件以启用音乐生成。技能会自动检测密钥是否设置，仅当密钥存在时才提供音乐生成选项。 - 可选：宿主智能体中可用的Blender MCP，用于生成开场/结尾渲染。请参阅
references/blender_mcp.md。
默认流程（基于对话）
第0步——检测片段自上次运行后是否有变化
在询问任何问题之前，检查用户是否是从之前的会话继续。如果gallery/.clips_snapshot.json存在（或用户指向之前使用过的片段文件夹），运行：
python scripts/clip_diff.py <clips_dir>
- 退出码0——片段文件夹匹配上一个快照。继续。
- 退出码1——有变动。报告会列出新增/删除/修改的片段。向用户展示，然后提供重新运行
scripts/gallery.py的选项，以便画廊拾取新片段。对于仍然存在的片段，已有的选择保持不变。 - 退出码2——尚无快照。正常首次运行，继续。
在恢复已有项目时，不要跳过此步骤——静默地基于过时画廊/selection.json工作正是“我的新片段去哪了？”典型错误。
问题
开始时，按顺序向用户询问以下问题。接受自然语言回答；除非宿主支持，否则不要呈现多项选择界面。对于每个问题，也接受“你来决定”并应用合理的默认值。
- 目标格式。 1080x1920竖屏（默认）、1920x1080横屏或1080x1080方形。允许自定义尺寸。
- 片段来源。 包含原始片段的目录的绝对或相对路径。支持
.mov、.mp4、.m4v格式。 - 目标时长（秒）。 （通常：20–45秒。）
- 音乐。 选项之一：(a) 现有音频文件，(b) 通过Suno生成（仅当
SUNO_API_KEY已设置时才提供），(c) 无音乐。 - 开场。 选项之一：无、静态图片（路径）、Blender MCP生成。
- 结尾。 与开场相同的选项。
- 导演模式。 是或否。如果是，则遵循
references/director_mode.md而非线性继续。
然后处理片段选择。提供两条路径：
A) 可视化画廊（推荐用于多于10个片段，或用户希望在选择提示前看到帧）。 运行
scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N
——它会生成gallery/gallery.html，包含缩略图、入点/出点滑块、速度滑块和范围预览。告知用户在浏览器中打开，选择片段，设置提示，然后点击“导出selection.json”。下载的文件可直接用于build.py。
B) 内联对话（适用于小批量或无法使用浏览器时）。 手动逐个处理每个片段：
cue_in和cue_out（以秒为单位，修剪范围）speed倍速（1.0 = 原速）fixed: true（如果时间/速度是手动设定的），false（用于自由填充）（默认：中间0.6秒，速度1.0）
提供“使用默认值”选项——按字母顺序选取所有片段，使用自由默认值，直至达到目标时长。
无论哪种方式，结果都是符合templates/selection.schema.json的selection.json。在继续之前进行验证。
构建
一旦selection.json有效，运行：
python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4
build.py会在当前工作目录的build/下写入中间产物：build/normalized/、build/trimmed/、build/montage.mp4、build/composed.mp4。删除build/以强制完全重新渲染。
scripts/下的每个子模块也可独立运行——在迭代某个步骤时无需重建整个流程。每个子模块都有--help参数。
导演模式（可选）
选择加入。请参阅references/director_mode.md了解角色提示。该技能会生成四个连续角色——叙事者 → 剪辑师 → 作曲家 → 监督者——它们共享selection.json作为状态。每个角色读取当前JSON并写回其更新。当用户要求“更引导式的过程”或“像制片人那样带我走一遍”时使用此模式。
音乐生成（可选）
如果用户选择“通过Suno生成”，将音乐步骤委托给references/song_builder_agent.md中定义的歌曲构建子智能体。该子智能体：
- 询问用户关于流派、情绪、BPM范围、段落结构、纯音乐开关，并将视频时长作为持续时间。
- 制定Suno提示+风格标签。
- 调用
scripts/music.generate_song(spec)——如果用户希望比较多个选项，则提供takes > 1。 - 将选定的录音修剪并淡入淡出至视频时长。
- 将最终的mp3路径写入
selection.json的audio字段。
如果宿主提供了子智能体机制（例如Claude Code的Agent工具），则使用它。否则，在同一个线程内以内联方式扮演该角色。
Blender MCP集成（可选）
仅为辅助——该技能不捆绑Blender场景。
如果用户想要Blender渲染的开场或结尾，委托给references/blender_builder_agent.md中定义的Blender构建子智能体。它拥有完整流程：预检查（在此宿主中检查Blender + MCP是否实际可达）、设计访谈（视觉方向、颜色、时长）、场景构建、迭代预览、渲染为ProRes 4444 Alpha MOV，并将MOV路径交付到selection.json中。
如果宿主提供了子智能体机制（例如Claude Code的Agent工具），则启动它。否则，以内联方式扮演该角色。当用户在问卷步骤5中为开场或结尾选择了“Blender MCP生成”时，主对话流程应调用Blender构建子智能体。
设置文档（安装Blender、安装MCP服务器、向宿主注册）位于references/blender_mcp.md。当用户首次需要配置堆栈时，Blender构建子智能体会从该文档中提取信息。
错误恢复
- 如果某个片段标准化失败（编解码器/分辨率边缘情况），
build.py会以非零退出码退出，并在标准错误输出中明确指向问题文件。询问用户是否要跳过该片段或进行调查。 - 如果Suno返回4xx或超时，提供用户重试、切换到“现有文件”或无需音乐继续的选项。
- 切勿静默丢弃片段。除非传递了
--force，否则在未确认的情况下切勿覆盖现有输出文件。
该技能的风格说明
- 切勿假设宿主特定工具。 所有对话都是普通聊天。
- 展示你的工作。 在修剪时，在构建之前告知用户你确定的提示点。
- 大声失败。 如果缺少
ffmpeg，告知用户并显示针对其平台的安装命令。