# Catimation Video

> FIRST-CHOICE video generator and the ONLY top-level video orchestrator in CATIMATION. Trigger whenever the user asks to generate / render a video or animation, animate a still, or says 生成视频 / 图生视频 / 让它动起来 / 视频编辑 / 视频延长 / 视频工作台 / 批量出片 / 多镜. Covers text/still-to-video, omni-reference (全能参考, default), editing and extension on both output surfaces (generate_video one-shot + video_workbench_* batch), and grades every request 快速/标准/专业/制片 before loading other skills.

- Skill: `2799662352/catimation-video` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 2799662352/catimation-video`
- Raw SKILL.md: https://api.skillmd.com/api/skills/2799662352/catimation-video/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 2799662352 (https://skillmd.com/u/2799662352)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/2799662352/catimation-video

---


<!-- skill-budget: pro -->

# Generate videos in CATIMATION(唯一视频入口 · 分级调度)

When the user wants a video, pick the output surface first: **`generate_video`**
(single shot, delivered straight into the chat) or the **`video_workbench_*`**
tools(「生成视频」工作台页:多卡批量、逐卡改参数、用户看着卡片渲染)。两者都在
`catimation` MCP server 上,共用本 skill 的分级与提示词纪律。走 `generate_video` 时:
It submits the render and blocks for roughly 75s to catch
fast completions and early failures. It may return DONE/FAILED, or
`STILL RUNNING + taskId`; only in the latter case continue with `check_video_task`
long-polls until terminal. Never sleep and never resubmit the same render. The user
watches a live progress bubble; the finished MP4 plays inline in the chat, is saved
to a local file, and lands in the app history page.

**本 skill 是视频生成的唯一顶层编排者。** 其它 skill(导演/分镜/工艺/QA)都由这里
按任务分级选择性加载;任何下游 skill 不得反过来重跑路由或重新编排本流程。

## STEP 0 — 任务分级(先定级,再加载;技法勿滥载)

**STEP -1:这是纯文本任务吗?** 写剧本、拆脚本、拆批次、整理文件、列镜头清单、
把已有分镜换个格式、改一段文字 —— 这些**一个 skill 都不要加载,也不进分级**,
直接做完交付。它们本来是三分钟的事,套上分级和确认闸门会拖成几小时。
用户说「快点」「简单弄一下」「先给我看看」时同理。
**只有真要提交生成任务时**,才继续往下看分级表。

默认进入**快速**模式;只有命中升级条件才升级。定级后把执行状态记成一份 routing receipt
(`task_level / direction_confirmed / spec_confirmed / prompt_engineered /
qa_completed / generation_attempts`):有专属素材夹(见「角色片 / 多镜」第 5 条)时写进
该夹的 `receipt.json`,每完成一步就更新;没有素材夹的一次性任务至少在回复里用一行复述它。
**每读完一份大 skill(提示词底座 / 结构叶子 / 镜头设计编排器)先回读 receipt 再动手** ——
两万字进上下文最容易把它冲掉,读完只剩模板、忘了锚点和已确认的规格就是这么来的。
已完成的步骤**不再重复执行**:规格确认过就不再问、提示词写好就不再重写、QA 做过就不再重抽。

**提示词底座:要真写 Seedance 提示词时才载。** 出片、改写视频提示词、Seedance
语法问答 —— 这些确实需要底座,不必等用户点名。但**纯文本任务不载**(见上面 STEP -1),
只问参数价格报错的也不载。

> **底座三个同级,但按 model 只载一个。** `sd2-pe`、`sd25-pe` 与 `wan3-cinematic-30s`
> 在路由表里平起平坐,「同级」说的是地位,不是要同时塞进上下文 —— 每个视频任务都
> 全量读一遍是纯浪费,而且套模板本来就只能套一套。
>
> - model 是 `2.5`(**默认**,模型未知时也按它)→ 载 `sd25-pe`
> - model 明确是 2.0 家族(`2.0` / `2.0-fast` / `2.0-mini`)→ 载 `sd2-pe`
> - model 是 `wan3`(万相 3.0)→ 载 `wan3-cinematic-30s`
>
> 之所以默认 2.5:它是唯一支持 `taskMode` 编辑 / 延长、30 秒时长和 50 份素材的档位。
> 只在真要写 2.0 的八大要素公式时才去读那一份。三个都不占技法名额。
>
> 万相那条底座另带两个**按题材**的专项叶子(产品 TVC、情绪对白戏),由底座自己按需
> 引出 —— 别从这里直接跳过去载。
>
> 下文凡写 `sd2-pe` 的**纪律**(素材绑定语法、多镜拆卡、资产门、一镜一运镜)在另外
> 两个底座上一字不改地成立,换底座不换纪律。八大要素、12 项内容、五大必备块讲的是
> **提示词该覆盖哪些内容**,同样与模型无关 —— 底座之间不同的是语法与排版,不是
> 要不要写清主体、镜头、光线、音效。

路径 A 仅限简单、单镜的轻量连续任务,可由底座独立完成;复杂、多镜、混合媒介或
需要展开导演/作品参考任一命中即进入路径 B,并加载结构叶子
cinematic-prompt-format。路径 B 条件优先于生成/编辑/延长/组合等任务类型。
下文「对症加载 / 别自行放大」同样适用于该结构叶子。

> **这个结构叶子三个底座通用。** 它名字带 seedance 是历史命名 —— 正文里没有一个
> 模型参数,只有 12 项内容清单、真人/2D/3D 媒介 profile 与语言纪律,换哪个上游都成立。
>
> ⚠️ 真正**不通用**的是写死了模型数字的那些:`seedance-video-craft` 里的
> 「4–15s」「9 图/3 视频/3 音频」「1080p 仅满血 2.0」「21:9」对万相全是错的
> (万相是 2–30s、10/5/5、没有 21:9)。判据是**有没有写死模型数字**,不是名字带不带
> seedance。与模型无关的技法(表演、光位、连续性、物理、负向控制)两边通用,
> 照常按症状挑。

**分镜底座:真要开拍多镜时才载。** 任务确定要**产出一条多镜片子**(不止一个镜头、
一板要跑的卡片、一个系列)时,再加载 `shotlist-builder` —— 它管镜头行怎么切、哪几行
合成一条 4–15s 提示词、要不要落成一张可搜索的 HTML 总表。它只做规划与交付物,
生成仍回本入口。

**这几种不载**(它们是纯文本或单次交付,套上四阶段对表闸门只会把三分钟拖成几小时):
拆脚本、拆批次、整理文件、列个镜头清单、把已有分镜换个格式、单镜「让这张图动起来」、
用户说「快点 / 简单弄一下」。**拿不准就先不载**,用户觉得不够正式再升级 ——
反过来先走完闸门才发现他只要张表,那些等待要不回来。

| 模式 | 典型请求 | 自选技法预算 | 默认动作 |
|---|---|---|---|
| **快速** | 「让这张图动起来」「生成5秒海浪」单镜简单请求 | **0 个** —— 入口 + 提示词底座就够 | 路径 A,合理默认,直接生成,快速 QA |
| **标准** | 单人物表演、简单电影感、带参考图的单镜 | **1 个对症技法** | 按一个主要风险挑技法,视觉 QA |
| **专业** | 武打/多人/参考复刻/复杂运镜/跨镜一致性 | **2 个对症技法**,另必载 `director-orchestrator` | 13 维按需展开,视觉+内容 QA |
| **制片** | 要一条能直接发出去的成片:拼接、配乐、字幕、交付规格齐全 | 按阶段加载,禁止一次全量 | 移交 `film-studio` 门控流水线 |

> **两个底座不占技法名额。** 提示词底座(有视频提示词就载,按模型选 `sd2-pe` 或
> `sd25-pe`)与 `shotlist-builder`
> (有跨镜/跨图连续性就载)是自动触发的底座,不是「对症技法」;上表限的是自选技法
> 数量。连续任务里两个底座同时在场是正常的,不算超预算。

**升级条件(仅此四类,别自行放大):** ① 明确的人物演技/复杂动作/武打;
② 参考图·视频·电影的风格复刻;③ 跨镜/系列的角色·风格一致性;④ 多镜、成片、
正式交付,或用户明确要求专业制作。

**专业 vs 制片看交付物,不看镜头数。** 十个镜头交十段片子仍是专业;两个镜头但要
拼好配好字幕直接发布就是制片。判据只有一条:**用户要拿走的是素材,还是成品?**
素材(他自己后期、或先看看效果)→ 专业,留在本入口;成品(要拼接/配乐/字幕/
平台规格)→ 制片,移交 `film-studio`。**用户在哪个页面不是判据** —— 在工作台上
贴剧本的人同样可能要成片。拿不准就问,这本身值一张 `ask_user` 卡,而且比事后
返工便宜得多。

**上表数的是「你自己挑的对症技法」,不是全部加载数。** 条件强制项不占这个额度:
入口自身、`sd2-pe` 底座、路径 B 的结构叶子、用户所在界面的叶子(工作台)、方向开放
时的 catimation-brainstorm、以及出图/QA/后期各自的入口与工具 —— 它们命中条件才载入、
不由你自由取舍,数它们没有意义。额度只约束「按风险挑几个技法」,那才是容易失控的
地方:三个风险都真实存在时也只能挑两个,取舍要说得出理由,「可能有帮助」不算理由。

**方向开放时先共创,别自己猜。** 用户说「更电影感/更高级/给我选项/共创」或方向
不明的高成本任务 → 先载入 catimation-brainstorm 用 `ask_user` 弹一张可点击选项
卡(一次一个聚焦问题、3–6 个具体方向、标注推荐项),选定即 `direction_confirmed`,
后续不再反复追问。明确的简单请求跳过弹卡,直接快速模式。

## 模式与素材规则(所有等级通用)

**Default mode = 全能参考 (omni-reference)** — use it unless told otherwise.
Caps 按 model:**2.5** = 图 30 / 视频 10 / 音频 10(合计 50),视频、音频各自合计 ≤30s;
**2.0 家族** = 图 9 / 视频 3 / 音频 3,视频、音频各自合计 ≤15s;**wan3** = 10 / 5 / 5。
超了会在提交前被拦下并报出该模型的上限,不用自己数。Only switch to strict
`firstFrame`/`lastFrame` when the user explicitly asks. **Always name the mode you used**
(如「我用**全能参考**模式生成」)。

All modes work on **both** surfaces(`generate_video` 与 `video_workbench_*`)
— pick by inputs + prompt:

- **文生视频**: `prompt` only. **图生视频**: still into `referenceImages`(或用户
  指明才用 `firstFrame`)。
- **视频编辑**: source clip into `referenceVideos`(+新元素图入 `referenceImages`),
  增加元素=「特征+时机+位置」;删除=点名要删的、强调保留的;修改=直接描述换后的样子。
- **视频延长**: 1–3 段源片入 `referenceVideos`,描述连接/向前向后延长。

**素材引用铁律**:提示词里用 `@图片1 / @视频1 / @音频1` 指代素材(火山 OpenAPI 的写法),
严禁裸写 assetId。**提示词原样发给上游**:运行时不改写、不删 `@`,唯一例外是工作台 chip 的
`【@图片1】` 外壳会解成 `@图片1`。`@Image1` / `<图片1>` / 裸 `图片1` 不会被替你改,别写。
**音频参考只收 mp3 / wav**;视频容器(.mov/.mp4,哪怕黑屏占位)会被拒收——先用
`ffmpeg-win` 抽音轨(`ffmpeg -y -i in.mov -vn -acodec libmp3lame -q:a 2 out.mp3`)。
黑屏 MP4 只用于 understand_video,绝不能当音频参考上传。
**真人脸**:Seedance 不收真人脸参考,用人像库虚拟形象 `asset://assetId` 或
Seedance 自产片段二创。**别把未处理的 Seedance 视频整段回喂**(二次编码打折)——
优先用 `ffmpeg-win` 抽尾帧/关键帧成静图(下一镜 `firstFrame` 最稳)或抽音轨续节奏;
整段回喂只作规避真人脸审核的兜底。

### 两条出片面怎么选

- **`generate_video`**:单镜、一次性、用户没点名工作台。成片直接进聊天并落历史页。
- **`video_workbench_*`**:多镜批量、用户已经在「生成视频」工作台、需要逐卡改参数或反复
  重跑。先 `video_workbench_add_tasks` 建卡(默认只填不跑,`autoStart:true` 才立即渲染);
  **一次最多 5 张,多了分几次调** —— 一整板挤在一次调用里就是几分钟静默生成,期间
  用户插不进话、页面也不出卡;分批则每批一落地就看得见。
  批次跑完会主动推「[视频工作台] 批次渲染完成」,**别轮询** `video_workbench_status`
  (它也分页了,`hasMore` 为真时翻页,别去要一个巨大的 pageSize)。
  改已有卡片挑单卡工具,别走整板往返:改几个词用 `video_workbench_patch_prompt`,
  一张卡多个字段用 `video_workbench_update_task`,一批卡同一个规格用
  `video_workbench_set_spec`,挪位置用 `video_workbench_move_task`(不要并发)。
  `video_workbench_apply` 已收窄为纯结构工具 —— 给已有卡带不同的提示词会被整份拒绝。
- 两条面共用**同一套** STEP 0 分级、上面那组素材 caps 与素材引用铁律 —— 工作台不是例外。
  有参考图时同样先 `view_image` 看图再写 prompt。

**工作台上的多镜纪律(踩过的坑,逐条都是实测):**

- **一张卡 = 一次生成 = 一个连续节拍。** 一张卡出 4–15s,里面可以是单镜,也可以是
  路径 B 的一小段镜头流程 —— 写「镜头1 / 镜头2」进同一段是 `sd2-pe` 支持的用法。
  判据是「这几镜是不是一个连续节拍、总时长塞不塞得下」,不是数镜头号:要独立重跑、
  各镜素材不同、时长超了或跨场景就拆卡,同场景连着演完的就合成一段。拆开时卡的顺序
  就是镜头顺序。详见 `catimation-video-workbench`。
- **下面那道「角色片/多镜」硬门在工作台上一字不改地适用。** 建卡 ≠ 已经备齐资产:
  `video_workbench_add_tasks` 默认只填不跑,正好是补锚点、排故事板、清点资产、
  把提示词过 `sd2-pe` 的窗口;`video_workbench_start` 之前这四样必须已经完成。
  工作台天生就是多镜场景,它是这道门最该生效的地方,不是例外。
- **跨卡共用同一套人物锚点。** 每张卡的 prompt 都要把 `identity-hard` 主锚逐字带上,
  别指望模型跨卡记住 —— 每次生成都是独立的一次调用。
- **规格确认同样适用。** 卡片会自动补默认值(720p / 5s / 16:9),但「有默认值」不等于
  「用户确认过」。没确认过就先按 Steps 第 2 条发 `ask_user` 卡,别让默认值替用户做决定。
- **工作台上的具体操作**(建卡、整板落地、字段映射、跨卡锚点、开跑前清点)交
  `catimation-video-workbench`。它是叶子:只管这块界面上的纪律与字段,
  **不做分级、不替代本入口** —— 分级仍然先在这里发生,再把落板交给它。
  用户手里已有分镜表 / 制片包要一次铺满整板时,同样走它;只有剧本或文字大纲、
  还没切成镜头的,也走它 —— 它有「剧本 → 镜头表」的拆分口径与镜头数选项卡纪律。

**规格确认(spec_confirmed)与四级 QA 在两条出片面上口径一致。** 工作台的批次摘要只报
成败与落盘路径,不代表 QA 已做 —— 人脸/复杂动作的卡照样要抽九宫格,多镜剧情照样要
`understand_video`。做过的级别记进 `qa_completed`,别重复抽。

## 角色片 / 多镜(标准及以上):先备齐资产,再开生成

只要有**反复出现的角色**或**不止一个镜头**,先锁资产再生成(绑定语法与镜头规划
以 `sd2-pe` 为准):

1. **人物卡先锁人**:每个复用角色先确定一套 `identity-hard` 主锚。可用大头照+
   全身照、三视图/四视图/多视图角色板，或用户确认的其它干净角色资产。用户已
   提供/指定就服从；有多套候选且拿不准时，用 `ask_user` 请用户选主锚；仅未指定的
   低风险任务默认大头照+全身照。缺图用 `generate_image` 补，随后
   `add_to_portrait_library` 存成 `asset://assetId` 并在 prompt 明确绑定职责。
2. **多镜先排故事板**:拆成 镜头1/镜头2/…,每镜按 运镜→主体动作/表情→位置/空间→音频
   写清,给用户过一遍。一镜一运镜、用镜头序号。**有剧本/分场要逐镜拆解,或镜头多到
   需要用户过目时,载入 shotlist-builder** 做这一步——它管镜头行怎么切、哪几行合成
   一条 4–15s 提示词,并可落成一张可搜索筛选的单文件 HTML 分镜表;它只做规划与交付物,
   生成仍回本入口。可用图像模型生成 3×3/4×4
   故事板/多宫格/电影美术设定板作为氛围图；这不取代用户选定的身份锚，
   干净关键帧锁当前片段构图/画质。**只要这些板被加入视频参考，提示词必须先写
   “提示词主导 / 氛围板低约束”前缀**，整板只负责色彩/光线/材质/时代感/空间气质/
   视觉母题，不要求构图、动作或顺序一致。
3. **资产齐备 GATE(硬门)**:逐镜清点人物卡/场景图/道具/氛围参考/参考视频/音频,
   任一该有未备的先补齐再生成。推荐每镜 4–5 个核心素材。缺口处理三选一:
   ① 项目/人像库里找现成(`list_portrait_library`);② 非身份关键的自己
   `generate_image` 补;③ 身份/IP/品牌关键的用 `ask_user` 请用户提供。
4. **生成用上全部可用资产**:图/视频/音频逐一传入并在 prompt 里绑定,
   有素材却只发纯文字 = 错；有故事板/多宫格却漏掉 mandatory 氛围职责前缀 = 错。
5. **一次生成一个专属素材夹**(如 `<workspace>/assets/jobs/S01_<slug>/`),
   复用、检查、定位问题都只看一个夹;STEP 0 的 routing receipt 也写在这里
   (`receipt.json`),每完成一步就更新。

> 轻量例外:单图「让它动起来」这类一次性请求(快速模式)不必强排人物卡/故事板。

## 写 prompt:底座按 model 选(相关即载),技法按症状加载

**生成前必须把提示词用 skill 写到位,不许凭记忆硬写**。有视频相关任务就先载入
**对应 model 的那个底座**,再写 prompt;不要等用户说「优化提示词」才加载。

快速模式可以走路径 A 并跳过结构叶子,但八大要素、12 项覆盖与五大必备内容块仍不得
缺失 —— 那讲的是内容覆盖,与用哪个底座无关。

1. **底座(必经,按 model 三选一) + cinematic-prompt-format(复杂任务条件加载)**:
   路径 A 仅处理简单单镜连续正文；复杂、多镜、混合媒介或展开导演/作品参考任一
   命中即走路径 B 并加载结构叶子，且 B 条件优先于任务类型。两条路径都覆盖八大
   要素、12 项内容和五大必备块，标题、分段与散文形式自由；并主动出 2–3 个已
   核实影视参考候选供用户挑选。真人、2D 动画、
   3D 动画作为可组合
   的媒介 profile；“电影/电影感”作为检索创作技法的意图词，不是互斥类别。
   结构化文本 never JSON;物理/可复现参数(焦段 mm、光圈、色温 K)优先于情绪
   形容词。
2. **写运镜/景别前先调 `search_cinematography_kb` 工具**(本地运镜与结构化描述库)
   拿真实术语再落笔;工具不可用再退回联网检索。
   **排版(三个底座通用):最终提示词连续成段,不空行分块。** 动作接动作、情节接情节、外貌 →
   性格 → 心理 → 环境这些连着发生的描写不用换行或空行切开,用 `，` `；` `。` `——` `：` 衔接;
   底座模板里的空行和「一句一行」是给人看的排版示意,不是提交格式,方括号标签后直接接正文;
   只在镜头之间(`镜头1：` / `镜头2：`)和模板块之间换行。中文字、标点前后不留空格。
   **提示词是什么,发过去就是什么**:运行时不改排版,空行、碎行、多余空格都会原样进上游,
   填 `prompt` 字段前自己看一眼。
3. **标准模式:按最主要症状挑 1 个技法 skill**(浏览 `~/.agents/skills/`,plain-text
   名称按需加载,不是全量)。多风险协同时升级专业模式,而不是突破标准级预算:

   | 症状 / 任务信号 | 对症技法(按需挑,非必载) |
   |---|---|
   | 太假/塑料/空洞/站桩/NPC | storyboard-live-character-realism · storyboard-character-acting · storyboard-character-motivation |
   | 像壁纸/没纵深/没电影感 | storyboard-foreground-occlusion · storyboard-pseudo-perspective · director-cinematic-composition |
   | 动作怪/武打飘/打击感差 | storyboard-physics · storyboard-kinematic-reverse-engineering |
   | 光平/糖水/塑料高光 | storyboard-light-reconstruction · director-lighting-continuity |
   | 风格不像/调色跑偏 | storyboard-color-grading-control · storyboard-style-extraction-logic · director-style-consistency |
   | 多角色混脸 | storyboard-multi-character-control · director-character-consistency |
   | 九宫格/多宫格故事板、电影美术设定板、整板低约束参考或拆格执行 | storyboard-grid-to-seedance |
   | 有剧本/分场/多镜要逐镜拆解,或要一张能搜索筛选的分镜表交付给人看 | shotlist-builder(规划与交付物,不出片) |
   | 提示词太长/权重稀释 | storyboard-video-prompt-optimization |
   | 提到真实电影/导演/品牌/时代,或「像·复刻·高级」 | codex-research-grounded-prompting(先查证再落笔) |
   | 日式动画质感/作画 | animation-craft · director-anime-quality-boost |

4. **专业模式:载入 `director-orchestrator`** 做复杂镜头设计(13 维按需展开、
   多技法协同),再按具体风险最多补 2 个技法;它只做镜头设计与提示词结构,
   不重跑本入口的分级与路由。
5. **制片模式:移交 `film-studio`**,由其 G0–G8 门控按阶段编排(剧本/分镜/资产/
   出图/出片/后期),本 skill 只负责其中每一镜的 `generate_video` 执行。

## Steps

0. **有参考图就先看一眼(look before you write)**:手上有用户给的图 / 人像库
   asset / 故事板时,先 `view_image` **一张有代表性的**,再据你**看到的**东西
   (主体、景别、配色、服装、光线)写提示词。照文件名或用户一句话臆想出来的提示词
   会和画面打架,而模型跟的是画面。这与「不要批量打开自己刚生成的产物」不冲突:
   那些用户已经在聊天里看着了,这是你的**输入**,看一张是让提示词对得上它的前提。
   多图只看代表性的 1 张(最多 2 张),别整批灌进上下文。
1. Turn the request into one clear video prompt(subject, action, camera 运镜/景别,
   scene, lighting, mood;dialogue 与 `--style` 可后置)。
2. **规格确认(spec_confirmed)**:用户没说规格时,发一张 `ask_user` 卡确认
   分辨率(`480p` 草稿 / **`720p` 默认** / `1080p`)、时长(**2.5 为 4–30s,2.0 家族 4–15s**,
   默认 5)、比例(`16:9` / `9:16` / `4:3` / `3:4` / `1:1` / `21:9`),推荐默认项。
   **不要静默升 1080p**;1080p 仅 `2.0`(与 wan3),`2.5` 只到 720p —— 用户要 1080p 就意味着
   model 改 `2.0`、底座改 `sd2-pe`;用户已给规格或本会话已确认过就跳过。
3. Call `generate_video`:`prompt`(必填)、`model`(**显式传,且与你载的底座一致**:
   STEP 0 默认 `2.5` → 传 `"2.5"`;要 1080p / 4k 或用户点名满血画质 → `"2.0"` 并改载 `sd2-pe`;
   用户明确要快/便宜才 `"2.0-fast"`。**别省略** —— 工具不传 model 时落到 `2.0`,一条按 2.5
   模板写的提示词就会被送去 2.0 渲染)、`resolution` / `ratio` / `duration`、
   `referenceImages`(**用户给过的图必须传**;支持 `asset://assetId`)、
   `referenceVideos` / `referenceAudios`(上限按 model,见「模式与素材规则」)、或显式要求时的
   `firstFrame` / `lastFrame`;2.5 的编辑 / 延长走 `taskMode`(`edit` / `extend`),不靠提示词措辞。
4. Wait for the tool to return — it blocks until done. Do NOT resubmit or
   "check progress" in between.
5. Read the result banner:
   - `✅ DONE` + `📁 SAVED FILE: <path>` → task COMPLETE. **第一步永远是交付**:
     先用一句话向用户确认(成片已在聊天里播放 + 保存路径,**name the mode**),
     **然后**才做任何 QA。Do NOT re-check or re-generate.
   - `✅ DONE` with background save pending → generation complete; mention briefly.
   - `⏳ STILL RUNNING` → 先向用户说一句「正在生成中」(如果还没说过),再 call
     `check_video_task` with the taskId repeatedly (long-polls ~25s) until
     DONE/FAILED. Never resubmit. 多轮轮询之间不要让用户干等无声。
   - `❌ FAILED` → report the upstream error; retry ONCE only if it suggests a
     content/parameter fix.

## QA:按风险分级,不是每条视频全套跑

**交付优先铁律**:任何级别的 QA 都发生在**向用户交付之后**——先一句话交付成片,
决定跑 QA 时再说一句「正在做视觉质检(抽帧九宫格)…」之类**出声**再动手。用户看
不到工具调用,先闷头抽帧/审片再回话,在用户眼里就是「卡死」(2026-07-14 实录教训)。
QA 发现问题需要重生成时,同样先告诉用户哪里不达标、准备怎么改。

| QA 级别 | 触发条件 | 动作 |
|---|---|---|
| **快速 QA**(快速模式默认) | 普通单镜、无人脸特写、无复杂动作 | 确认 DONE banner + 时长/文件正常即可;不自动抽帧、不自动上传理解模型 |
| **视觉 QA** | 人脸/手部是重点、多人物、武打/复杂动作、用户要求查画质、疑似穿帮 | 九宫格 contact sheet + `view_image`(见下) |
| **内容 QA** | 多镜剧情、台词/字幕/口型、连续性检查、视频编辑核对、用户明确要求审片 | `catimation-understand` 的 understand_video 看整段 |
| **发布 QA**(制片交付) | 正式交付/成片 | ffprobe 编码/分辨率/帧率/响度 + 九宫格 + 内容审查 + 平台规格(走 `ffmpeg-win` 的 inspect→process→verify 循环) |

**九宫格做法**(视觉 QA):用 `ffmpeg-win` 抽 9 帧拼图,
`ffmpeg -i "<clip>.mp4" -vf "fps=9/<DURATION>,scale=320:-1,tile=3x3:padding=6:color=black" -frames:v 1 -y "<clip>_grid.png"`,
然后 `view_image` 那张 `_grid.png`。画布上的视频用 `get_canvas_video` 拿
`videoPath`,别搜盘。判定标尺(源自 VisionReward/WorldReasonBench 核心项):
视觉美观 s_a、时间一致性 s_c(主体稳定/运动平滑/不闪烁)、物理合理 s_r、
prompt 对齐,逐项判通过/不通过;**单帧崩坏一票否决**(最差帧原则),首帧从严。
需要总分时 `S(v) = 0.4·s_r + 0.3·s_c + 0.3·s_a`。

**多镜/整板不要挨张 `view_image`。** 主 agent 直接看图的上限是 5 张(宫格图算一张,
它本来就是为「一张看完整段」拼的)。超过 5 张 —— 多镜、多张宫格、一板卡片的产物 ——
走 catimation-subagents:
并发调 `understand_document` 看图 / `understand_video` 看整段,回来的是文本;每镜的
结论落成 `<文件名>.vision.json` / `.md` 旁挂在素材旁边,下次(或下个人)直接读文本。
需要「看完顺手改提示词重生成」时才升级到子代理。

触发了视觉+内容两级时,两面是同一次自检,别二选一。任一不达标 → 带**针对性**
改进点重生成(补哪个技法的哪个字段,不是泛泛「优化一下」)。自动修正
**最多 2 次**；`generation_attempts` 到 2 后仍不通过,先向用户说明成本/问题并请求
确认,不得继续付费重试。
**Never** inject the full MP4 or raw bytes into the chat;用户已在聊天里看着它播。
做过的级别记入 `qa_completed`(如 `["visual","content"]`),下游不重复抽帧。

> 宫格图/故事板/美术设定板 = 辅助素材,不只是检查工具:整板可回喂
> `referenceImages` 传色彩/光线/材质/时代感/空间气质/视觉母题,但不承担故事、
> 构图、动作、顺序、时长、身份或 `firstFrame`;有板即带提示词主导前缀。要精确
> 跟随某格就先拆格、去边框文字、重绘成干净关键帧。跨镜续接优先抽关键帧/尾帧作
> 下一镜 `firstFrame`,不整段回喂 —— 这条默认针对逐镜串行推进。**工作台批量并行
> 时用不了**(下一镜的首帧要等上一镜渲完),取舍规则见 `catimation-video-workbench`。

## Organize finished clips into the user's workspace (when in a project)

**COPY, don't move** the finalized MP4(和它的 `_grid.png`)into a tidy assets
subfolder with zero-padded shot ordinals — e.g.
`<workspace>/assets/video/S01_station_wide.mp4`、
`<workspace>/assets/contact-sheets/S01_station_wide_grid.png` — so clips
assemble in order for a later ffmpeg concat. Skip for one-off casual clips.

## Portrait library(人像库)— push materials in, then reference

The `catimation` MCP server exposes portrait-library tools
(`add_to_portrait_library` / `list_portrait_library` / `edit_portrait_library` /
`download_portrait_asset`,详见 catimation-portrait-library skill),围绕视频
生成主动使用:传给 `generate_video` 的输入图会自动入库并 dedupe 成同一
`asset://assetId`;用户给的要记住/复用的素材先 `add_to_portrait_library` 再引用;
「还是上次那个人」用 `list_portrait_library` 找回同一 asset 保持身份一致;用户在
人像库页给的 `asset://assetId` 直接传入。

## Notes

- One `generate_video` call = ONE video. 多条就多次调用、复用同一 asset://
  保持一致性;可并行,但**一次要发 20+ 个任务先向用户确认**(每条都花钱且渲染
  1–3 分钟)。
- Local input files are handled for you(video/audio 每段 4–15s,合计上限按 model 见
  「模式与素材规则」);pass plain local paths
  and do NOT pre-compress or reject anything for size — there is no client-side size
  cap, large files are streamed to a relay bucket automatically. If a file really is
  too big for upstream, upstream returns the exact limit.
- **Background saving never blocks you**: banner DONE = 视频已在播,本地保存可能
  还在后台(`persistencePending`),当作 COMPLETE 立即回复,不要等待或轮询保存。