vmake-smart-montage

智能蒙太奇

功能与准备

使用 mixed-cut analyze / generate 解读媒体素材和创作目标，安排画面与节奏，并在确认计划后生成视频。需要 vmake-labs-cli，目标版本为 0.1.11，兼容版本范围为 >=0.1.11 <0.2.0。

首次调用前请阅读 CLI 设置。检查版本，并分别查看 mixed-cut analyze --help 和 mixed-cut generate --help。如果不清楚 JSON 字段或媒体限制，请查询相关的 vmake contracts 条目。对于口播视频计划的编辑，请阅读生成答复；对于输出、交互或错误，请阅读运行时与恢复。

• 支持图片、视频和混合输入。多张图片可以组成完整视频。请遵循 CLI 媒体验证规则；服务会选择合适的分析分支。
• material_mixed_cut 使用实际的媒体排列、脚本和配音信息。talking_mixed_cut 使用 ARoll 视频，可选搭配 BRoll 图片/视频，并保留原始语音。ARoll 要求仅适用于口播视频分支。
• 可选的 --target-duration 用于指定 5-180 秒的目标时长。未指定时请省略。--language 提供内容语言背景；口播视频分支会保留原始语音。--lang 设置客户端语言。
• 在分析提示词中说明需要处理的停顿、节奏、宽高比、时长及其他目标。使用实际计划并征求用户确认。将识别出的 a_roll_text 视为只读内容，并交付实际返回的视频。

收集媒体并进行分析

1. 收集 1-20 个真实的图片/视频文件或 URL，以及一个主题。保留用户提供的文案、顺序、叙事和节奏。当输入和主题明确时，直接准备并分析；不要要求用户先将素材分类为 ARoll/BRoll。仅询问会影响结果的缺失信息。
2. 使用可读取的本地文件。根据 CLI 设置下载所有远程原始文件，包括会话媒体和历史输出。保留来源、本地路径、不同类型媒体的顺序以及重复输入。如果下载失败，请向用户索取原始本地文件；只有在所有选定输入都可用后才进行分析。如果输入超过 20 项，请帮助用户筛选，不要静默截断、分批处理或自行选择。
3. 按照用户提供的顺序排列 --image-file 和 --video-file，并根据需要重复使用这些标志。使用 -r '<session_id>' 复用会话；新建会话时省略它。在 -p 中填写主题和已知要求；可选标志请以当前帮助信息为准。
4. CLI 会验证整个批次，按顺序上传，并使用 CDN URL 提交一次分析请求。不要先调用 create-room 或 add-media，也不要使用 --item-id。请按位置描述素材角色，例如“第一个输入”；本地路径不是远程引用。不要臆造未见过的场景或剪辑点。

此示例混合了一张图片和一段视频。请根据实际输入调整文件参数，但不要改变其顺序；也支持纯图片或纯视频输入：

vmake mixed-cut analyze --image-file '<local-image-path>' --video-file '<local-video-path>' -p '<user-theme-and-requirements>'

分析会生成计划，而非最终视频。请保留实际返回的会话 ID、Task ID 以及原始媒体映射。默认值、登录和参数处理请遵循 CLI 设置。参数文件和单独验证均为可选项。

等待并确认计划

1. 从实际消息部分或任务 status.message 部分中读取 data.type=mixed_cut_brief。使用 (session_id, brief_id) 更新；不要根据文字描述、编号或示例猜测 ID。
2. 当状态为 pending 时，只读查询历史记录或已知任务。即使历史记录显示为空闲，也不要生成。按间隔依次查询；长时间没有更新时，说明当前状态并保留恢复所需的详细信息，不要反复分析。状态变为 failed 时停止。如果缺少 Brief，先恢复历史记录；如果仍然缺失，则报告问题。命令结束、Run 完成或 Session 空闲，都不代表 Brief 已就绪。
3. 状态为 ready 时，展示实际 brief_type 对应的计划。对于 talking-head，展示主视频、辅助媒体、目标时长和只读的 a_roll_text。对于 material montage，展示实际媒体编排、script、voice_id 和目标时长。不要臆造缺失字段，也不要声称看过无法查看的素材。
4. 返回素材计划的图片属于正常情况。遇到未知分支或缺少必需信息时，遵循实际问题，不要更改类型或捏造字段。
5. 展示就绪计划后，明确征求确认。笼统的“编辑一下”之类请求不能批准尚未展示的计划。若编辑了计划，说明最终更改；对于已明确接受的同一计划，不要再次询问。

生成与编辑

使用已确认的真实 session 和就绪的 Brief。两个分支使用相同命令；material 分支不需要 ARoll，因此省略 --answer：

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

在有效登录且用户已确认当前就绪的 Brief 后提交。可选择执行本地验证以进行诊断，但这无法证明 Brief 存在、已就绪、与输入内容对应或已获确认。CLI 会直接提交生成任务，不会先查询历史记录，因此调用方必须检查实际分析结果。

• 只有 talking-head 分支接受使用 --answer 编辑 a_roll_media、b_roll_media 和 target_duration。媒体项只包含真实的 short_id 和 kind。ARoll 至少需要一个视频；空的 BRoll 数组会明确清除辅助素材。未更改的字段应省略。直接标志参数的答案应序列化为单个参数，或者在参数文件中使用 answer 对象。参见生成答案。
• 只能选择当前计划中已分析过的输入。不要传入 type、a_roll_text、script、voice_id、confirmed_fields、URL 或本地路径。将答案随生成操作一起提交。
• 对于新的或替换的源媒体，或者对素材计划的主题、文案、选择内容或时长进行更改，先下载远程原始素材，再在同一 session 中使用更新后的要求重新分析完整的本地输入列表。生成前展示并确认新的 Brief。不要预先注册新媒体。
• reply --approve 用于处理当前权限请求；reply --answer 用于回答实际的原生问题。二者都不能替代 Brief 生成或这些计划编辑。

跟进并交付

• 分别读取原始 stdout 和 stderr，保留所有任务，避免第二个并发观察者。只有在状态为 TASK_STATE_COMPLETED 且视频 URL 当前可用时才交付。HTTP 200、退出代码 0、end.reason=result 和未知状态都不能单独证明成功。
• 及时交付每个实际可用的视频，保留完整 URL 和 viva.short_id。如果返回了实际的 room_url，也一并提供。只有在用户请求字幕且已安装该 Skill 时，才使用 vmake-dynamic-caption；否则说明等效的字幕工作流，不要默默添加处理步骤。
• 如果 URL 缺失或已过期，请查询 Task/历史记录；媒体 ID 或封面不等于视频。发生断连、超时或接受状态不确定时，只执行只读恢复操作。只有确认失败并获得授权后，才能重试分析或生成。
• 字幕或下载失败时，不要重复执行已成功的蒙太奇。交付成功结果并保留恢复上下文。不再需要时，移除任务创建的临时媒体或参数文件，同时保留用户原始文件。保存和恢复详情请参阅运行时与恢复。