videokit 契约 v0（草案）

状态：草案，未实现 · contract 版本 0.0.1-draft · as_of 2026-09-24 本文是 EXECUTION-PLAN M0-A2 的交付物。所有厂商字段来自官方文档核实（数据源：video-ai-landscape/data/capabilities.json），未核实处标【未核实-缺口】，禁止编造。

0. 一句话

把五家视频生成 API 的「提交—等待—取货」收敛成同一套任务句柄：vk submit / poll / cancel / resume / artifacts，让北极星成立——一条命令、跨 ≥3 家厂商、失败可重试、结果可验收、产物本地留档。

1. 范围与非目标

v0 只定义契约（状态机 + 字段 + CLI 表面），不实现二进制（M1 起步）。

• 范围：veo / kling / seedance / wan(阿里百炼) / cogvideo(智谱) 五家云 API。Wan2.2 自托管路径没有云任务系统【官方源】，不进状态机——本地文件即产物，无过期问题。
• 非目标（v0）：不做厂商请求代理/中转计费层（直连）；不做回调服务器（CLI 本地场景轮询优先）；不做 judge/verdict（M2）；不做 character_id/LoRA（M3）。

2. 设计原则（五条，全部来自调研实证）

1. 轮询优先。五家中仅 Kling、Seedance 支持回调，Veo/智谱纯轮询，百炼未载明【缺口】。本地 CLI 没有公网端点，v0 一律本地轮询；各家的回调能力记入能力表（§8），不做依赖。
2. 幂等靠本地兜底。五家中仅 Kling 提供 external_task_id 天然去重句柄【官方源】。其余四家重试只能靠 vk 本地 journal 短路：同幂等键 + 同参数指纹、任务未终态 → 直接返回既有句柄，不发请求、不重复花钱。
3. 超时 ≠ 失败。网络断、轮询窗口尽、执行超时（如 Seedance execution_expires_after 48h）→ 一律进 unresolved，不静默标 failed。计费是否已经发生，是用户必须看到的真相。
4. 产物立即归档。Veo 服务端只留 2 天（延长操作重置计时）、Kling 30 天，Seedance/百炼/智谱未载明。succeeded 的下一个默认动作就是下载 + 写 manifest，不赌厂商 URL 存活。
5. 价格先报。submit 前必须产出成本行（--dry-run 或确认后执行）；能力表里没有价的（如 Veo 页面缺口）就明说没有，不编。

3. 统一状态机

             submit                      poll 命中
  [created] ───────▶ [queued] ──────────────▶ [running] ──────▶ [succeeded] ─▶ [archived]
     │                   │                        │                  （自动下载+manifest）
     │                   │  厂商说没这个任务        │  显式失败 / 轮询超窗 / 执行超时 / 厂商失联
     │                   ▼                        ▼
     └─────▶ [failed]                 [unresolved] ⇄ 可再轮询 / 同幂等键重提（人工确认）
                     ▲
  cancel 请求 ───▶ [canceled]（尽力而为，见 §5）

• 终态 = succeeded | failed | canceled；archived 是 succeeded 后的本地完结标记。
• unresolved 是稳定的非终态：必须由人或 agent 显式处置（继续轮询 / 同键重提 / 标记放弃），vk 不替用户决定，退出码与之区分（§4）。

统一态 → 各家原生值映射：

百炼整列未载明是 v0 最大的对照缺口，M1 第一件事就是补齐（§11）。

4. 统一句柄（CLI 表面）

五个动词，全部支持 --json（机器可读输出，是后续绑 MCP 的前提）：

vk submit  <params...> --provider auto|veo|kling|seedance|wan|cogvideo
           [--dry-run] [--yes] [--idempotency-key K]

• 返回 Handle JSON：task_id（vk 本地 ID）+ provider + provider_task_id + state + cost_estimate + as_of。
• 规则：无 --yes 且非 --dry-run → 先打印成本行、等确认再发（价格先报红线）。

vk poll  <task_id> [--wait] [--interval 10s] [--deadline 10m]

• 打印统一态 + 原生态 + 剩余轮询预算。--wait 阻塞至终态或 deadline；到 deadline 进 unresolved。
• 退出码契约：0=succeeded（含已归档），1=failed/canceled，3=unresolved，2=用法错误。脚本可以据此分支，不会把「没等到」误读成「成功」。

vk cancel  <task_id>

• 尽力而为：适配器核实到厂商 cancel 端点就调用（v0 五家均未核实到公开 cancel 端点【未核实-缺口】）；没有则记 cancel_requested 并继续轮询到终态。两种情况都必须向用户明说。

vk resume  [--all]

• 读本地 journal，重挂所有非终态任务（进程被杀 / 机器重启后续接）。这是 M1 验收命令 vk submit → kill → vk resume 的核心半截。

vk artifacts  <task_id> [--verify]

• 打印 / 校验 manifest（§6）。succeeded 后 vk 自动下载并写入。

5. 幂等键规范

• 生成：vk submit 未显式给键时自动生成 vk-<UTC时间戳>-<8位随机>，随 Handle 与 journal 持久化。
• 去重两层： 1. 厂商层（仅 Kling）：幂等键 → external_task_id 透传【官方源】。 2. 本地层（全部厂商）：submit 前查 journal——同键 + 同参数指纹（规范化 params JSON 的 sha256）且任务未终态 → 返回既有 Handle，不发请求。
• 重提规则：unresolved 任务允许同键重提（需人工确认）；新提交产生新 task_id，journal 里以 supersedes 字段链到原任务，审计链不断。

6. Artifact Manifest v0

{
  "manifest_version": 0,
  "task_id": "vk-20260924T101500Z-ab12cd34",
  "provider": "kling",
  "provider_task_id": "…",
  "idempotency_key": "vk-20260924T101500Z-ab12cd34",
  "requested": { "model": "kling-v3", "duration_s": 5, "resolution": "720p", "audio": true },
  "state": "succeeded",
  "artifacts": [
    { "kind": "video",
      "url": "https://…",
      "url_expires_at": "2026-10-24T10:15:00Z",
      "url_expires_note": "30 天后清除【官方源】",
      "local_path": "archive/2026-09-24/vk-….mp4",
      "sha256": "…", "bytes": 0 }
  ],
  "cost": { "amount": 0.63, "currency": "USD",
            "basis": "kling v3 720p 含音频 0.126 $/s × 5s",
            "as_of": "2026-09-22", "estimated": true },
  "timing": { "submitted_at": "…", "finished_at": "…", "polled_times": 7 },
  "supersedes": null
}

字段规则： - url_expires_at：核实到就填；没核实到 → null + url_expires_note: "未载明-缺口"。禁止编保留期。 - cost.estimated: true 表示这是报价而非厂商账单回执（v0 拿不到账单，估计值就要标成估计值）。 - as_of 沿用技能矩阵惯例：价格/能力的核实日期，不是生成日期。

7. 到期与归档对照

8. 五家厂商字段对照表（M0-A2 验收物）

数据源：data/capabilities.json（官方文档核实，as_of 2026-09-22/24）。

读法：这张表就是适配器的工作量地图——每一格【缺口】都是 M1 要补的一脚，每一格已核实值都是适配器可以直接翻译的映射源。

9. 适配器最小实现清单

接入一个新厂商 = 填满 §8 一列 + 实现五个动词的映射：

• [ ] 提交端点 + 参数映射（含首尾帧形态翻译：contents[].type ↔ image+lastFrame ↔ 双元素数组……）
• [ ] 原生态 → 统一态映射，含 unresolved 触发条件
• [ ] 幂等：厂商原生句柄，或声明「仅本地层」
• [ ] cancel：有端点给端点；没有则声明「尽力而为」
• [ ] 成本行：能算给公式（含隐性系数，如 Seedance IP 加价 ×1.1/×1.5），算不了给【缺口】
• [ ] URL 保留期：同上

10. MCP Tasks 兼容方向（非 v0 目标）

submit / poll / cancel / resume 与 MCP Tasks 扩展的任务生命周期（create / get / result / cancel）同构。v0 只承诺一条：--json 输出形状与状态名保持稳定，后续薄封装即可绑成 MCP server。此节为方向性说明，不是承诺。

11. 未决问题