smart-montage

视频混剪｜美图出品

能力与准备

使用 mixed-cut analyze / generate 理解素材与创作目标，智能编排画面和叙事节奏，经方案确认后生成视频。依赖 meitu-kaipai-cli，已验证目标版本 0.1.11，兼容 >=0.1.11 <0.2.0。

首次执行先按平台接入运行CLI 准备脚本：缺失时默认全局安装，兼容时复用。目标、必要素材和授权齐全后沿用返回入口直接调用 CLI，不主动校验输入或运行独立预检；调用格式不明确时再按平台说明查询 help／contracts。修改口播方案时读取生成答案。遇到 CLI 输入错误、输出解析、服务端问询或执行异常时读取运行与恢复。

• 每次分析支持 1–20 个图片、视频或混合素材（合计），多张图片可直接创作成片；具体媒体格式按 CLI 校验。服务端根据素材自动选择适合的分析分支。
• 素材分支 material_mixed_cut 使用实际素材安排、脚本及配音信息；口播分支 talking_mixed_cut 以 ARoll 视频为主轴，可选 BRoll 图片／视频，保留原口播。ARoll 视频约束只适用于口播分支。
• 可选 --target-duration 传入用户指定的目标时长，由服务端结合素材规划节奏；未指定时省略。--language 提供内容语言上下文，口播分支保留原口播；--lang 设置客户端语言。
• 将停顿优化、节奏、画幅和时长等创作诉求完整写入分析 Prompt，结合服务端返回的方案与用户确认推进。a_roll_text 作为识别出的口播原文只读使用，交付以实际返回的成片为准。

收集素材与分析

1. 从当前请求提取用户选定的全部图片／视频文件或 URL 及主题，承接用户已给出的完整文案、素材顺序、故事主线和节奏要求。素材与主题齐全时直接准备素材并分析，不要求先划分 ARoll/BRoll；只补问影响结果的缺失信息。
2. 本地素材直接使用用户提供或上下文取得的真实路径；远程素材先按平台接入逐项下载原资源，包含已有会话和历史产物 URL。保留原始来源、本地路径、跨类型顺序及重复项；下载失败时请用户自行下载并提供本地文件，全部选定素材齐备后再分析。不按本地数量规则提前筛选，不截断、不擅自分批生成、不自动代选；若 CLI 返回数量错误，再按实际错误请用户选择。
3. 按用户顺序排列 --image-file / --video-file，同类参数也可重复出现；不按类型重新分组。复用原会话时添加 -r '<session_id>'，新任务省略。将主题及已知要求合并到 -p，可选参数按当前 help 传入。
4. CLI 整批校验后按顺序上传，取得自有 CDN URL 再一次提交分析，不先 create-room / add-media，不使用 --item-id。以“第一个素材”等说明角色，不将本地路径当作远端引用，也不虚构尚未识别的画面或剪辑点。

下面展示图片、视频混合输入；按实际素材增减文件参数并保持顺序，纯图片或纯视频同样适用：

kaipai mixed-cut analyze --image-file '<本地图片路径>' --video-file '<本地视频路径>' -p '<用户主题与要求>'

分析只创建方案，不开始最终视频生成；保存返回的真实会话、Task ID 和原始素材映射。默认值、登录与安全传参按平台说明处理；复杂输入按需使用参数文件，输入错误按 CLI 实际反馈处理。

等待并确认方案

1. 从真实 Message Parts 或 Task status.message Parts 读取 data.type=mixed_cut_brief，按 (session_id, brief_id) 更新；不从普通文本、编号或示例猜 ID。
2. pending 时只读查询历史或已知 Task；即使历史因 idle 退出也不能生成。适度间隔串行查询，长期无更新时说明状态并保留恢复信息，不循环重新分析。failed 时停止；缺失 Brief 时先恢复历史，仍缺失则报告问题。命令退出、Run 完成和 Session idle 不代表 Brief ready。
3. ready 时按真实 brief_type 展示方案：口播展示主视频、补充素材、目标时长和只读 a_roll_text；素材分支展示实际素材安排、script / voice_id 及目标时长。未返回的字段不猜测，不声称看过未取得的画面。
4. 图片返回素材分支属于正常流程；未知类型或缺少服务要求的信息时按实际问询处理，不强改类型、不补造字段。
5. 展示 ready 方案后取得用户明确确认。此前笼统的“帮我剪辑”或“一键成片”不能替代对尚未展示方案的确认；用户修改方案时先说明最终变更，不重复确认已经明确接受的同一方案。

生成与修改

使用用户已确认的真实会话和 ready Brief，通过已解析的 CLI 入口生成。两种分支均使用同一命令；素材分支省略 --answer，无需提供 ARoll。

kaipai mixed-cut generate -r '<session_id>' --brief-id '<brief_id>'

登录有效且当前 ready Brief 已获用户确认后直接提交，不运行独立预检。CLI 不预查历史；调用方仍须使用实际分析返回的当前 Brief 和用户确认，不能把输入校验交给 CLI 视为省略方案确认。

• 仅口播分支可通过 --answer 调整 a_roll_media / b_roll_media / target_duration。媒体项仅含真实 short_id / kind；ARoll 表示口播主视频，BRoll 可为空数组表示清空。未修改字段省略；直接 flags 将完整答案序列化为一个参数，复杂答案可用参数文件中的 answer 对象，详见生成答案参考。
• 答案只选择当前方案已分析素材；不得传 type / a_roll_text / script / voice_id / confirmed_fields、URL 或本地路径。完整约束见生成答案参考，答案与生成 action 同次提交。
• 新增或替换源素材，或修改素材分支主题、文案、选材或时长时，先按平台说明下载远程原资源，在原会话重新分析完整本地素材及更新要求，展示并确认新 Brief 后生成；不先登记新素材。
• reply --approve 仅处理当前权限批准，reply --answer 仅回复实际原生问询，均不能代替 Brief 生成或上述方案修改。

跟进与交付

• 分别持续读取原命令 stdout 与 stderr，保存全部任务，避免同时另开观察器。TASK_STATE_COMPLETED 且取得本次可用视频 URL 才交付；HTTP 200、退出码 0、end.reason=result 和未知状态都不能单独证明成功。
• 及时交付每个真实可用视频，保存完整 URL 和 viva.short_id，有实际 room_url 时附会话入口。仅在用户需要字幕时交给 dynamic-caption；若未安装对应 Skill，告知需使用同等字幕流程，不擅自追加处理。
• 缺少或过期 URL 时先查询 Task／历史，不用媒体 ID 或封面替代视频。断线、超时或受理未知时只读恢复，不自动重新分析或生成；失败原因已修复且用户授权后才重试。
• 字幕或下载失败不重做成功混剪，保留并交付成功部分。处理结束且无需恢复后清理本次临时素材或参数文件，保留用户原文件；具体恢复与保存见运行说明。