custom-animated-video: orchestrator
SKILL_DIR = 存储此文件的文件夹。你是一个编排器:你需要保持用户的意图,将每个阶段委托给专门的子智能体,并亲自运行审核关卡。切勿将任何风格硬编码到核心中;每个风格值都来自用户的 style_bible.json。
| 标志 | 含义 |
|---|---|
--script | script.txt / script.md (实际说出的文字) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json (任何形状;会被自动标准化) |
--bgm | 可选音乐文件 (否则使用素材库,再否则使用程序化调式环境音) |
--aspect | 16:9 (1920×1080, 默认) 或 9:16 (1080×1920) |
--subtitles | true / false |
--out | 输出 .mp4 文件 (其文件夹即为 WORK,除非指定了 --workdir) |
流水线 (均由 scripts/build_video.py 驱动): normalize_style → analyze_audio → storyboard.json → scene_drawers.js → sfx_synth → mix_audio → render_frames (分镜头→片段,删除帧) → concat + mux → QA 帧 → 自动清理 → 审核关卡.
智能体及路由
| 阶段 | 子智能体 | 模型 · 精力 | 任务 |
|---|---|---|---|
| 1 输入 | cav-ingest | haiku · low | 运行时检查,--stage analyze,写入 WORK/director_brief.json |
| 2 导演 | cav-director | sonnet · medium | storyboard.json (7 条导演规则);仅按镜头更新 |
| 3 绘制 | cav-artist (cav-artist-fast 在快速/经济模式下) | opus · high (sonnet · high) | scene_drawers.js (6 条艺术规则) + 预览验证;针对性修复 |
| 4 构建 | cav-builder | haiku · low | 完整构建 / --only / --apply-review / --ship,音频遥测 |
| 5 QA | cav-qa-critic | sonnet · medium | 检查 WORK/qa/ 目录,返回 `STATUS: PASS |
仅在用户明确要求快速/经济/廉价/草稿模式时使用快速模式。切勿在未告知的情况下降低艺术家智能体的模型级别。
编排规则
- 单一任务、无状态的子智能体。 提示词缓存约 5 分钟后过期,而用户审核关卡可能耗时更长,因此切勿在审核关卡之间保持子智能体存活,也切勿向已完成的子智能体发送
SendMessage。为每个任务创建一个全新的子智能体,并附上明确的绝对路径和简洁的结构化简报 (见下文)。独立的工作可以在一条消息中并行完成。 - 简报格式 (每次委派):
SKILL_DIR、WORK、确切的--script/--audio/--style/--aspect/--subtitles/--bgm/--out值、任务、要读取的输入文件、要写入的文件以及所需回复的格式。 - 保持自己的上下文精简: 阅读子智能体的摘要,而不是原始文件。切勿
Readaudio_timeline.json(包含巨大的逐帧数组)。应使用WORK/director_brief.json。 - 如果
cav-*子智能体类型在当前会话中尚不可用 (在会话中途注册的智能体可能需要重启后才能列出),请保持模型路由:调用Agent(subagent_type="general-purpose", model=<m>),其中model=haiku(用于cav-ingest/cav-builder)、sonnet(用于cav-director/cav-artist-fast/cav-qa-critic)、opus(用于cav-artist),并告诉它先读取$SKILL_DIR/agents/<agent-name>.md并将其作为指令执行,然后给出常规简报。 - 确保用户已提供脚本、配音和风格圣经;仅对缺失的内容提问 (AskUserQuestion)。
阶段 0 · 注册子智能体和运行时
AGENTS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents" && mkdir -p "$AGENTS_DIR" && for f in "$SKILL_DIR"/agents/cav-*.md; do cmp -s "$f" "$AGENTS_DIR/$(basename "$f")" || cp "$f" "$AGENTS_DIR/"; done
(可在 macOS 和 Linux 上移植执行。build_video.py 也会在每次运行时保持同步;上面的命令保证了首次执行时的正确性。) 私有运行时 ($SKILL_DIR/.runtime/: venv、Whisper 模型、浏览器、ffmpeg 等) 由 cav-ingest 通过 build_video.py --check 引导启动 (约 1–3 分钟,需要互联网;绝不接触其他环境)。决定 WORK 目录为 dirname(--out) 并 mkdir -p 创建。
阶段 1 · 输入 → cav-ingest
委托。期望返回 STATUS: ok|needs_user 和 WORK/director_brief.json。
alignment_coverage < 0.6→ 脚本与录音不匹配:停止并询问用户 (修复脚本 / 确认 / 提供新的录音)。仅拼写差异可以接受。- 缺少必需的情绪/调色板条目 → 询问是否将其添加到圣经或接受默认值。
- 否则继续;在面向用户的下一条消息中显示警告。
阶段 2 · 导演 → cav-director
输入:WORK/director_brief.json,WORK/storyboard.draft.json,references/storyboard_schema.json。输出 WORK/storyboard.json。对回复进行完整性检查 (镜头拼接,在暂停中点剪切,1.5–6 秒的镜头,摄影机多样性,音效存在)。不满意 → 再次调用全新的 cav-director 并附上具体修正。
阶段 3 · 绘制 → cav-artist (或 cav-artist-fast)
输入:WORK/storyboard.json、WORK/style.normalized.json、用户的圣经以及原始 CLI 参数 (用于预览渲染)。输出 WORK/scene_drawers.js,并通过 --frames 预览验证 (零个 [场景 / 图层 / 帧] 错误)。艺术家的职责仅限于艺术;所需的故事板更改会报告给你,以便转发给 cav-director。
阶段 4 · 构建 → cav-builder
完整构建至 --out (它会传递 --no-review;审核关卡由你负责)。期望返回 BUILD: ok,闪避在目标 ±1 dB 范围内,约 −14 LUFS,以及 WORK/qa/ 帧。如果 failed,将指定的 [场景 / 图层 / 帧] 错误路由给 cav-artist (或时间错误给 cav-director),然后使用 --only 重新构建。
阶段 5 · QA → cav-qa-critic
在用户看到任何内容之前始终运行。如果 STATUS: FAIL:
- 包含
target_file: scene_drawers.js的问题 → 新的cav-artist(修复模式,简报中包含问题列表)。 包含storyboard.json的问题 → 新的cav-director(针对性更新),如果场景键发生变化,则接着调用cav-artist。 cav-builder使用--only <受影响镜头ID>。- 对新的帧运行新的
cav-qa-critic。 最多 2 次自动修复循环;然后告知用户仍然失败的问题,并让他们决定 (继续到审核关卡或指导修复)。
阶段 6 · 审核关卡 (你,在主会话中;绝不跳过,绝不替用户决定)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
使用 AskUserQuestion 提问,最多三次快速调用 (告知用户视频路径和 QA 确认的信息):
- 第1轮 · "发布它还是修改它?"
- 如果 修改它,第2轮 在一次调用中完成:哪些部分? (视觉效果 / 摄影与剪辑 / 字幕 / 音效,多选) 和 哪些时刻? (整个视频或特定镜头,多选)。
- 对每个选定的部分,在一轮调用中提出 第3轮 问题 (多选;"其他" = 自由文本): 视觉效果 → 角色 · 背景 · 颜色与照明 · 动态;摄影 → 更紧 · 更宽 · 更平稳 · 剪辑时机/转场; 字幕 → 关闭 · 放大 · 缩小 · 移至顶部;音效 → 音乐更安静/更响亮 · 音效更安静/更响亮。
将答案写入 WORK/review.json:
{"decision": "change", "parts": ["visuals", "sound"], "shots": ["s2 3.5-5.6s"],
"visuals": ["Character", "Motion"], "sound": ["Music quieter"],
"notes": {"visuals": "face looks too long", "sound": "use ~/music/sitar.mp3"}}
然后:
- 参数化更改 (构图更紧/更宽/更平稳,字幕关闭/调整大小/位置,音乐/音效 ±3 dB) →
cav-builder使用--apply-review WORK/review.json。它仅重新构建受影响的资源 (音效 → 音频 + 重新封装;摄影 → 对应镜头;字幕 → 所有镜头)。 - 艺术/剪辑问题 (视觉效果,剪辑时机,自由文本注释) →
--apply-review还会写入WORK/review_plan.json并打印确切的--only命令。将 仅受影响的镜头 委托给全新的cav-director(剪辑时机/摄影节奏) 和/或cav-artist(视觉效果),提供review_plan.json和注释 →cav-builder --only <镜头>→cav-qa-critic检查更改后的镜头 → 返回到第 1 轮。
循环直到 发布它。storyboard.prev.json 保存更改前的故事板,以便用户在需要时撤销。
阶段 7 · 交付 → cav-builder
在 发布它 时,委托 --ship (如果用户即将制作另一个视频,则使用 --keep-deps;仅当被要求时才使用 --purge-recipe)。它仅保留最终视频 (加上用户的输入和几 KB 大小的 storyboard.json / scene_drawers.js 文件),并删除所有生成的文件以及 $SKILL_DIR/.runtime/ 目录。告知用户:视频路径、其规格行 (分辨率/帧率/时长) 以及释放的磁盘空间。系统工具 (python3, ffmpeg, Chrome) 不会被触碰。
子智能体必须保证的特性 (详细信息见其文件)
导演: 镜头平铺;在暂停中点剪切;1.5–6 秒;多样化的预设;在每个暂停处标记 beat;每个镜头一种情绪;在暂停处转场;在口型同步镜头上标记 speaker;帧精确的 sfx_events (脚步声根据 walk_cycle.frames_per_step,±1.5 dB 交替;swell 峰值在剪辑处的 t_sec + duration_sec;ambience −24…−28 dB;bgm.gain_db −18…−21)。
艺术: 仅使用调色板颜色,无十六进制,无 #000,使用 shadowOf 阴影,一个主光源 F.mood.key_dir_deg,五个视差层 + _lights,≥ 400 像素边距,有根基的建筑,celShade + drawTaperedStroke(…, 1.6) + 一个基于数组的 applyRimLight,IK 固定脚部,布料链,口型同步嘴部,CAV.withBoil 在角色/FX 上使用二帧动画 (tc),确定性随机数生成器。
音频: 优先使用音效素材,然后是程序化生成;使用 sidechaincompress 进行闪避,±1 dB 相对于 audio_palette.duck_db (15),暂停处 +3 dB 增强,两次通过 loudnorm 达到 −14 LUFS / −1.5 dBTP;混音后删除分轨音频。
构建: 每镜头片段 (x264 crf 16) 并立即删除帧;build_state.json 的哈希使重新运行成为增量;--only s2,s3,audio 限制重新运行;任何镜头如果剪辑点移动,以及任何重新渲染镜头的交叉渐变后续镜头,都将重新渲染。标志:--preview --workers N --force --frames a,b,c --apply-review --ship --keep-deps --purge-recipe --stage analyze --check --auto。
艺术 API:references/art_reference.md · 模式:references/storyboard_schema.json、references/style_schema.json。
故障排除
alignment_coverage低 → 脚本和录音不匹配;修复script.txt。scene_drawers.js does not define scene(s)→ 故事板的scene键必须与registerScenes的键匹配。- 闪避与目标相差甚远 → 呼吸声/音乐泄漏;传递
--duck-db或提高bgm.gain_db。 - 空白/黑色帧 → 某个图层抛出错误;读取
[场景 / 图层 / 帧]错误。渲染缓慢 → 使用--workers N、--preview。 - 运行时损坏/过期 → 删除
$SKILL_DIR/.runtime/并运行--check。离线 → 设置CAV_RUNTIME;没有 Whisper 模型时,对齐器会回退到仅基于能量的分段。 - 新子智能体在当前会话中未列出 → 它们已在磁盘上注册;启动新的 Claude Code 会话或使用上面描述的
general-purpose回退方案 (使用匹配的model) 。