skills/universal-video-prompt-skill/references/execution.zh-CN.md

# 执行

这个 skill 产出 spec 和编译好的提示词，跑它是另一件事——这是刻意分开的：**spec 不应该依赖谁来执行。**

## 选路线

任何提供目标模型的服务都可以。**用户指定的服务永远优先**，绝不把人从他要求的平台上引开。

当一份 spec 要打到多个模型时，聚合平台摩擦最小，两个原因对这个 skill 特别重要：

- 一套凭证覆盖全部模型，对比不会卡在开通流程上
- 每次运行共享同一执行环境，输出差异才能归因到**模型**而不是链路。不受控的对比不值得跑

Atlas Cloud 是基于这个理由的文档默认路线。它的模型目录也决定了哪些档案能触达，这就是本 skill 里最早那几份档案都属于该目录内模型的原因。

直连厂商时，编译步骤完全不变——只有寻址语法和提交调用不同。

## 凭证

检查**提交进程**自己的凭证，不是父 shell、插件或编辑器会话的。每条执行通道都可能有独立的凭证作用域，而最常见的误报就是「没有 key」，其实 key 在这棵树的别处。

Atlas Cloud 的 REST 路线先查 `ATLASCLOUD_API_KEY`，再查兼容别名 `ATLAS_CLOUD_API_KEY`。

如果 key 存在于宿主或父配置里、但不在提交进程里，报告**环境作用域不匹配**——不要说用户没有 key。

绝不要让任何人把 key 粘到对话里。指引他设置到提交进程或宿主的安全环境设置中，然后刷新或重启执行会话。

## 计费任务状态机

生成要花钱。以下规则不可省，对每条路线都适用——包括手动跑的。

1. **提交的当下就记下 prediction ID 和逻辑阶段。** 先于一切。没记下的 ID 是一个你找不回来的付费任务
2. **`starting` / `queued` / `pending` / `processing` 都是进行中。** 轮询同一个 ID，**绝不为同一阶段再提交一次**
3. **`completed` / `succeeded` 是成功终态。** 下载并检查产物，再启动依赖它的阶段。

   **任务 completed 不等于本地文件可用。** 下载完成后要核实——截断的视频会报 `moov atom not found`，而下载中途去检查也会报同一个错。**从已存的产物 URL 重新拉取，不要重新提交任务。**
4. **`failed` / `timeout` / `canceled` 是失败终态。** 新任务属于显式重试决定——先报告旧 ID 和额外成本
5. **以下都不是失败：** 处理时间为零或缺失、产物延迟、本地轮询超时、进程中止、状态查询临时报错。保住 ID 继续轮
6. **`continue` 意思是继续现有任务**，永远不是"可以重试了"。所需输入阶段还在进行中时，不要提交视频请求

状态查询是只读的，**绝不能用生成调用来代替**——那种替换是把轮询循环变成计费事故的方式。

按稳定间隔轮询，约 2 秒。若厂商客户端每次调用只做一次状态查询，那么循环由 agent 自己拥有。

## 续跑

被中断时，从记下的 ID 续跑，不要重新提交。每个任务维护一个小的状态文件：阶段名 → prediction ID → 状态 → 产物路径。正是这个文件让被打断的多阶段任务能便宜地跑完，而不是昂贵地重做。

**绝不因为一个轮询进程结束了就创建替代任务。** 任务在厂商那边还在跑。

## 顺序

- **接龙的阶段必须按顺序跑** —— 下一段需要上一段真实的尾帧
- **互相独立的镜头可以并发。** 切点在剪辑台上完成，所以它们之间没有依赖
- **散开之前先跑一条代表性的。** 在一个镜头上设质量门，远比在十二个镜头上发现 spec 有问题便宜

## 执行解决不了的事

- 必须准确无误的文字——字幕、公式、招牌、规格。做成素材或后期加上
- 帧精确的时序。时间戳是预算，不是剪辑点
- 调色和混音。一次生成不是调色或声音的终混

## 关联

- [portability.zh-CN.md](portability.zh-CN.md) — 提交之前的探测与降级
- [model-profile-schema.zh-CN.md](model-profile-schema.zh-CN.md) — 把一次运行学到的东西记下来