custom-animated-video: 編排者
SKILL_DIR = 存放此檔案的資料夾。你是編排者:你負責維護使用者的意圖,將每個階段委派給專門的子代理,並自行執行審查閘門。切勿將任何風格寫入核心;每個風格值都來自使用者的 style_bible.json。
| 旗標 | 意義 |
|---|---|
--script | script.txt / script.md(實際口說的文字) |
--audio | voiceover.wav / .mp3 |
--style | style_bible.json(任何形狀;會自動正常化) |
--bgm | 可選的音樂檔案(否則使用資產庫,否則使用程序產生的模態 drone) |
--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 (per shot → clip, frames deleted) → concat + mux → QA frames → auto-clean → review gate。
代理與路由
| 階段 | 子代理 | 模型 · 力度 | 任務 |
|---|---|---|---|
| 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對於cav-ingest/cav-builder使用haiku,對於cav-director/cav-artist-fast/cav-qa-critic使用sonnet,對於cav-artist使用opus,並指示它先讀取$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/:虛擬環境、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 預覽驗證(零個 [scene / layer / frame] 錯誤)。美術師的工作僅限於美術;所需的故事板變更將回報給你,再由你轉給 cav-director。
階段 4 · 建置 → cav-builder
完整建置至 --out(它會傳入 --no-review;閘門是你的責任)。預期收到 BUILD: ok,壓縮目標在 ±1 dB 內,約 −14 LUFS,以及 WORK/qa/ 幀。失敗時,將指定的 [scene / layer / frame] 錯誤路由至 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。 - 使用
--only <受影響鏡頭 ID>執行cav-builder。 - 對新的幀執行新的
cav-qa-critic。 最多 2 次自動修復循環;然後告知使用者哪些仍失敗,並讓他們決定(繼續進行審查閘門或直接修復)。
階段 6 · 審查閘門(由你,在主會話中執行;絕不跳過,絕不為使用者決定)
python3 "$SKILL_DIR/scripts/review.py" --questions --storyboard WORK/storyboard.json --video project/final_video.mp4
使用 AskUserQuestion 提問,最多三次快速呼叫(告訴他們影片路徑和 QA 確認的內容):
- 第一輪 · "發佈它還是修改它?"
- 如果是修改它,則在單一呼叫中進行第二輪:哪些部分?(視覺 / 攝影與剪輯 / 字幕 / 音效,可複選)以及哪些時間點?(整部影片或特定鏡頭,可複選)。
- 針對每個選擇的部分,在一個呼叫中提出第三輪問題(可複選;"其他" = 自由文字): 視覺 → 角色 · 背景 · 顏色與燈光 · 動作;攝影 → 更緊 · 更寬 · 更平穩 · 剪輯時機/轉場; 字幕 → 關閉 · 更大 · 更小 · 移至頂部;音效 → 音樂更安靜/更大聲 · 效果音更安靜/更大聲。
將答案寫入 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)→ 使用
--apply-review WORK/review.json執行cav-builder。它只重建受影響的目標(音效 → 音訊 + 重新混合;攝影 → 那些鏡頭;字幕 → 所有鏡頭)。 - 美術/剪輯問題單(視覺、剪輯時機、自由文字備註)→
--apply-review也會寫入WORK/review_plan.json並印出確切的--only指令。將僅受影響的鏡頭委派給新的cav-director(剪輯時機/攝影節奏)和/或cav-artist(視覺),提供review_plan.json和備註 →cav-builder --only <shots>→ 對變更後的鏡頭執行cav-qa-critic→ 回到第一輪。 循環直到發佈它。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 px 邊距,腳踏實地的建築,celShade + drawTaperedStroke(…, 1.6) + 一個基於陣列的 applyRimLight,IK 生根的腳步,布料鏈,嘴型同步的嘴巴,僅對角色/FX 在二格 (tc) 上使用 CAV.withBoil,確定性 RNG。
音訊: 首選音效資產,其次才程序生成;使用 sidechaincompress 進行 ±1 dB 的 audio_palette.duck_db (15) 壓縮,+3 dB 暫停處的 swells,兩次通過的 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)→ storyboardscene鍵必須與registerScenes鍵匹配。- 壓縮遠離目標 → 呼吸或音樂滲入;傳入
--duck-db或提高bgm.gain_db。 - 空白/黑色幀 → 某個圖層拋出錯誤;閱讀
[scene / layer / frame]錯誤。渲染緩慢 →--workers N,--preview。 - 執行時期壞掉/過時 → 刪除
$SKILL_DIR/.runtime/並執行--check。離線 → 設定CAV_RUNTIME;對齊器在沒有 Whisper 模型的情況下會回退到僅依能量進行分割。 - 新的子代理未在目前會話中列出 → 它們已在磁碟上註冊;啟動新的 Claude Code 會話,或使用上述的
general-purpose後備方案(搭配匹配的model)。