影片提示建構器 (Video Prompt Builder)
通用、與供應商無關的影片生成提示調度器。讀取 .specs/architecture/PROVIDERS.md 中的路由矩陣,決定由哪個供應商執行該片段,並委派給正確的專用技能(higgsfield-prompt-builder、topview-prompt-builder、wavespeed-batch、hyperframes-prompt-builder)。
何時呼叫
- 管線中的任何影片生成步驟(
brief -> script -> creative,當創意類型是影片時)。 - 當某個片段在
.specs/pieces/*.md中宣告type: video時。 - 跨供應商進行影片鉤子的 A/B 測試,且協調器需要一個單一入口點。
- 在選出 A/B 勝出者後,使用相同的簡報但更換供應商重新執行。
- 當上游代理有簡報但不知道該選擇哪個供應商時。
輸入
brief:物件。至少包含subject、motion、mood、aspect、duration_seconds的視覺簡報。task_kind:字串。可以是cinematic_reel、motion_control、ugc_product_holder、product_demo、talking_head、batch_hook_test、motion_typography、data_viz_reel、programmatic_short其中之一。piece_path:字串,可選。片段檔案的路徑。可能包含provider_override.video。dry_run:布林值,可選。若為 true,則僅返回解析後的供應商和參數,而不呼叫 MCP。
流程
- 讀取
.specs/architecture/PROVIDERS.md並將影片矩陣解析為task_kind -> provider的映射表。 - 如果
piece_path已設定且包含provider_override.video,則使用該覆寫值。 - 否則在矩陣中查詢
task_kind。若未知,則回退使用cinematic_reel的矩陣預設值。 - 驗證所選供應商已設定環境變數(
HIGGSFIELD_MCP_ACTIVE、TOPVIEW_API_KEY、WAVESPEED_API_KEY、HYPERFRAMES_ACTIVE)。 - 將供應商對應到專用技能:Higgsfield ->
higgsfield-prompt-builder、Topview ->topview-prompt-builder、Wavespeed ->wavespeed-batch、Hyperframes ->hyperframes-prompt-builder。 - 將
brief欄位轉譯成專用技能所預期的輸入格式。 - 呼叫專用技能並擷取其
params和mcp_tool輸出。 - 如果是
dry_run,則返回解析後的供應商、參數和 MCP 工具。否則呼叫 MCP 並回傳成品參考。 - 將執行記錄寫入
data/video-usage.jsonl,包含時間戳記、供應商、task_kind 和結果。
輸出
provider_used:字串。params:物件。準備好供 MCP 呼叫使用的最終參數物件。mcp_tool:字串。MCP 工具名稱。artifact_ref:字串,非 dry_run 時存在。產出影片的路徑或 URL。cost_estimate_usd:數字。
範例
範例 1:電影風片段路由至 Higgsfield
輸入:{ brief: { subject: "model in linen suit", motion: "tracking shot", mood: "editorial", aspect: "9:16", duration_seconds: 6 }, task_kind: "cinematic_reel" }
輸出:{ provider_used: "higgsfield", mcp_tool: "higgsfield_seedance_generate", params: {...} }
範例 2:UGC 廣告路由至 Topview
輸入:{ brief: { subject: "skincare bottle held by avatar", motion: "static", mood: "friendly", aspect: "9:16", duration_seconds: 15 }, task_kind: "ugc_product_holder" }
輸出:{ provider_used: "topview", mcp_tool: "topview_avatar_generate", params: {...} }
範例 3:每週 KPI 片段路由至 Hyperframes
輸入:{ brief: { headline: "Semana 21 em números", aspect: "9:16", duration_seconds: 12, variables: { leads: 42, delta_pct: 12 } }, task_kind: "programmatic_short" }
輸出:{ provider_used: "hyperframes", mcp_tool: "hyperframes_render", params: { composition_spec: {...}, render_args: {...} } } — 透過 hyperframes + hyperframes-cli 技能進行本地渲染。
失敗模式
- task_kind 不在矩陣中:記錄警告並使用 cinematic_reel 預設值。
- 所選供應商的必要環境變數缺失:降級至矩陣中的下一個供應商,並顯示警告。
- 專用技能回傳錯誤:顯示錯誤,除非呼叫者選擇,否則不會自動在其他供應商上重試。
- 時長超過供應商限制:裁剪至供應商上限並顯示提示。
相關技能
higgsfield-prompt-builder:Soul、DoP、Seedance 的專用建構器。topview-prompt-builder:UGC 和虛擬角色驅動廣告的專用建構器。wavespeed-batch:低成本批次鉤子測試的專用技能。hyperframes-prompt-builder:HTML 渲染動態排版、資料視覺化片段和參數化程式化短片的專用建構器。llm-router:獨立的文字生成調度器;相同模式,不同領域。qa-tech-specs:根據平台規格驗證最終影片。