HyperFrames 提示构建器 (Prompt Builder)
专门的技能,用于桥接营销引擎的片段模型(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 原生任务)。- 某个片段在其前置元数据中声明了
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的路径。前置元数据可能包含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且前置元数据包含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>计算composition_id(转换为 URL 友好格式)。 - 构建渲染参数,格式为
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 中提取设计 Token;渲染参数目标路径为 outputs/saas-consultoria-imagem/<date>/<piece-id>/final.mp4。
示例 3:提供商覆盖
输入:一个声明了 provider_override.video: hyperframes 但 task_kind 不在对应矩阵中的片段。
输出:仍然路由至此,默认 task_kind 为 programmatic-short,记录此回退。
不可协商的规则
- 绝不可虚构设计 Token。如果
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,然后此技能再组装合成规范。