HyperFrames 提示建構器
專門橋接行銷引擎素材模型(brief、task_kind、provider_override)與 HyperFrames 組合合約的專家。在結構上與 higgsfield-prompt-builder 和 topview-prompt-builder 相同——使用相同的調度器,但目標不同——因此 video-prompt-builder 可以在不變更自身邏輯的情況下切換供應商。
何時呼叫
video-prompt-builder將某個素材的影片供應商解析為hyperframes。task_kind是motion-typography、data-viz-reel、programmatic-short(PROVIDERS.md中的 hyperframes 原生任務)之一。- 某個素材在其 frontmatter 中宣告了
provider_override.video: hyperframes。 - 一個已批准的靜態圖(來自
gpt-image的引言卡、來自topview的輪播圖)正在被提升為動態內容,且類型系統必須與原始內容保持位元一致。 - 協調器需要以新的變數值(每週 KPI 影片、每日價格更新、A/B 變體文案)重新渲染相同的組合,而無需重新提示 AI 生成器。
輸入
brief:物件。素材簡報,至少包含headline、body?、cta?、aspect、duration_seconds。task_kind:"motion-typography" | "data-viz-reel" | "programmatic-short"。piece_path:字串,可選。指向.specs/pieces/<piece-id>.md的路徑。Frontmatter 可能包含provider_override、compliance_flags、variables。client_slug:字串。用於載入.marketing-engine/clients/<slug>/design.md(或引擎倉庫中的clients/<slug>/design.md)。output_dir:字串。專案和最終 MP4 的存放位置(預設為outputs/<client>/<date>/<piece-id>/)。dry_run:布林值,可選。若為 true,則返回組合規格和渲染引數,而不呼叫hyperframes-cli。
流程
- 載入品牌上下文。 讀取
clients/<client_slug>/design.md並解析{ colors, type_pairing, spacing_scale, brand_voice }。如果缺少,則拒絕繼續——指出缺失的路徑。品牌違規無法在下游修復。 - 解析覆寫設定。 如果設定了
piece_path且 frontmatter 包含provider_override.video,確認其值為hyperframes;否則此技能不應執行。 - 將 task_kind 對應至組合模板。
motion-typography→kinetic-type模板,單場景,類型驅動。data-viz-reel→nyt-graph模板,主體場景包含已宣告的數值變數。programmatic-short→play-mode模板,鉤子/主體/CTA,所有客戶文案宣告為變數。
- 宣告變數。 簡報中任何可能在每次重新渲染時變化的內容(標題、主體、KPI 數字、CTA、日期戳記)都應放入
variables,並附上明確的類型、標籤和預設值。當變數可以工作時,禁止使用硬編碼的文案。 - 建構組合規格,格式為
hyperframes所期望:{ composition_id, aspect, duration_seconds, scenes, design_tokens, variables, assets, output_dir }。根據<piece-id>(安全 slug)計算composition_id。 - 建構渲染引數,格式為
hyperframes-cli所期望:{ project_path, mode: "render", render_opts: { fps, quality, format, variables, strict: true, strict_variables: true, output } }。對被提升的素材選擇quality: "high",對初稿審查選擇"draft"。 - 成本估算。 本地渲染——從
duration_seconds × workers × $0.00估算(零自付額;改為將牆鐘時間分鐘數報告為latency_estimate_min)。 - 記錄解析結果 至
data/video-usage.jsonl,包含{ ts, provider: "hyperframes", piece_id, task_kind, composition_id, dry_run }。 - 如果是
dry_run,則返回而不呼叫hyperframes-cli。否則,依序呼叫hyperframes(以編寫專案)然後hyperframes-cli(模式lint→inspect→render)。
輸出
provider_used:"hyperframes"。composition_spec:物件。傳遞給hyperframes技能的輸入。render_args:物件。傳遞給hyperframes-cli技能(模式render)的輸入。expected_artifact:字串。渲染後將存在的 MP4 路徑。latency_estimate_min:數字。渲染的牆鐘時間估計值。cost_estimate_usd:0(本地渲染;僅營運成本)。
範例
範例 1:每週 KPI 影片(programmatic-short)
輸入:{ brief: { headline: "Semana 21 em números", aspect: "9:16", duration_seconds: 12 }, task_kind: "programmatic-short", client_slug: "saas-consultoria-imagem", piece_path: ".specs/pieces/2026-05-22-kpi.md" }
輸出:組合規格包含 composition_id: "kpi-weekly-2026-05-22"、三個場景(鉤子/主體/CTA)、數值變數(leads、delta_pct);渲染引數包含 --strict --strict-variables --quality high --variables '{"leads":42,"delta_pct":12}'。
範例 2:動態引言卡(motion-typography)
輸入:{ brief: { headline: "Coloque a sua marca onde os olhos já estão.", aspect: "1:1", duration_seconds: 6 }, task_kind: "motion-typography", client_slug: "saas-consultoria-imagem" }
輸出:組合規格包含單一動態排版場景、遮罩文字入場、設計權杖取自當前客戶的 design.md;渲染引數目標為 outputs/saas-consultoria-imagem/<date>/<piece-id>/final.mp4。
範例 3:供應商覆寫
輸入:一個包含 provider_override.video: hyperframes 的素材,其 task_kind 不在矩陣中。
輸出:仍路由至此,將 task_kind 預設為 programmatic-short,記錄回退。
不可協商的規則
- 絕不憑空發明設計權杖。如果缺少
design.md,則拒絕繼續。 - 始終將每個素材的文案宣告為
variable,即使它看起來是靜態的——組合必須能夠在不修改程式碼的情況下重新渲染。 - 始終在渲染引數中傳遞
--strict-variables。變數 ID 中的打字錯誤將導致硬失敗。 - 絕不繞過
lint → inspect → render序列直接呼叫hyperframes-cli。
失敗模式
- 未知的
task_kind:預設為programmatic-short,記錄警告,然後繼續。 design.md缺失:停止。不要挑選色板;要求操作員新增檔案。- 簡報包含品牌禁止的主張(根據
compliance-<active client>):在編寫前阻止;合規檢查在渲染上游執行。 - HyperFrames CLI 未安裝:顯示安裝命令(
npm i -g hyperframes或npx hyperframes@latest)並停止。
相關技能
hyperframes:組合編寫規則(由此技能使用)。hyperframes-cli:lint/inspect/render 執行(由此技能使用)。video-prompt-builder:選擇此技能的調度器。qa-tech-specs:針對最終 MP4 執行。compliance-<active client>/compliance-generic:針對已解析的變數和已渲染的成品執行。llm-router:不在此直接使用,但可能選擇在此技能組裝組合規格之前起草標題/主體的 LLM。