安装 HyperFrames 是做什么的?
一次性复现将 HyperFrames 作为视频提供商集成的过程,遵循 CLAUDE.md 中三步“添加新提供商”合同。自包含的检查清单列出了每个必须存在的工件;验证每一个并仅创建缺失的部分。
运行此技能,而不是从头开始重新推导集成。它是该仓库中“HyperFrames 已连接”含义的权威记录。
何时调用
- 尚未集成 HyperFrames 的 marketing-engine 新克隆。
- 变基或合并操作删除了以下任何一个工件(
router:check报错,视频路由在排版任务时回退到higgsfield,或.skills/hyperframes*/丢失)。 - 新客户需要程序化短片/运动排版/数据可视化卷轴,并且矩阵需要连接这三种任务类型。
- 为新操作员提供单个可命令的剧本,替代阅读三个提交。
输入
repo_root:字符串。marketing-engine 克隆的绝对路径。默认为process.cwd()。branch:字符串,可选。要提交的分支。默认为claude/install-hyperframes。如果分支不存在则创建;绝不提交到main。dry_run:布尔值,可选。当为 true 时,打印计划更改并退出而不写入。
流程
按顺序执行每个步骤。每个步骤都是幂等的——在已集成的仓库上重新运行该步骤是空操作。
步骤 1 — 预检
- 确认
repo_root包含CLAUDE.md且其中有行## How to Add a New Provider。如果缺失则拒绝运行——这不是 marketing-engine 仓库。 - 确认
lib/providers/video.ts、lib/providers/matrix.ts、lib/providers/types.ts和lib/providers/__mocks__/video.ts存在。如果任何文件缺失则拒绝运行。 - 确认当前活动分支不是
main。如果在main上,先创建并切换到branch。
步骤 2 — 添加三个运行时技能
创建这三个包含 SKILL.md 文件的目录。每个文件已经存在于树内规范版本中——从下面“参考工件集”部分逐字复制。如果文件已存在且其 frontmatter name 匹配,则跳过。
.skills/hyperframes/SKILL.md— 合成创作规则(布局优先于动画、时间线暂停并注册到window.__timelines、没有Math.random()/基于时间的逻辑、通过data-composition-variables声明变量)。.skills/hyperframes-cli/SKILL.md—npx hyperframeslint → inspect → render 开发循环。始终使用--strict --strict-variables渲染。.skills/hyperframes-prompt-builder/SKILL.md— 当矩阵解析为hyperframes时由video-prompt-builder调用的专家;从clients/<slug>/design.md加载品牌令牌,按task_kind选择模板,返回合成规范 + 渲染参数。
步骤 3 — 更新调度器技能
在 .skills/video-prompt-builder/SKILL.md 中:
- 将
hyperframes-prompt-builder添加到开头段落和相关技能部分的专家列表中。 - 将
task_kind输入枚举扩展为包含motion_typography、data_viz_reel、programmatic_short。 - 在验证环境变量的流程步骤中,将
HYPERFRAMES_ACTIVE添加到列表中。 - 在提供商到专家的映射中,添加行
Hyperframes -> hyperframes-prompt-builder。 - 添加一个示例:一个路由到 HyperFrames 且
task_kind: programmatic_short的每周 KPI 卷轴。
如果目标字符串已存在,跳过任何子步骤。
步骤 4 — 扩展提供商层
在 lib/providers/types.ts 中,向 VideoTask 联合类型添加三个成员:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
在 lib/providers/matrix.ts 中:
- 向
EMBEDDED_DEFAULTS.video添加三行:motion-typography、data-viz-reel、programmatic-short——每个默认为hyperframes。 - 向
TASK_LABEL_MAP添加标签别名:"motion typography"、"kinetic typography"、"data viz reel"、"data-viz reel"、"programmatic short"、"parametrized short"。
在 lib/providers/video.ts 中:
- 添加一个扩展
RealVideoBase的HyperframesVideoProvider类,由process.env.HYPERFRAMES_ACTIVE === "true"控制,在realGenerate中抛出一个"local CLI render required in caller context; stub"错误(匹配现有的 higgsfield/topview 存根模式)。 - 在
REAL_VIDEO_REGISTRY中注册hyperframes: () => new HyperframesVideoProvider()。
在 lib/providers/__mocks__/video.ts 中:
- 添加一个扩展
BaseMockVideo且name = "hyperframes"的MockHyperframesVideoProvider类。 - 在
MOCK_VIDEO_REGISTRY中注册hyperframes: () => new MockHyperframesVideoProvider()。
步骤 5 — 更新路由矩阵文件
在 .specs/architecture/PROVIDERS.md 中,向视频路由表追加三行:
| Motion typography | hyperframes | HTML/GSAP kinetic type, brand-faithful, deterministic |
| Data viz reel | hyperframes | declared variables → re-renderable charts (NYT-style) |
| Programmatic short | hyperframes | parametrized HTML composition; byte-identical re-renders |
步骤 6 — 更新 .env.example
在 WAVESPEED_API_KEY= 之后追加:
# HyperFrames 是本地 HTML→MP4 渲染器;无需 API 密钥。
# 当 `npx hyperframes doctor` 在本地通过后设置 HYPERFRAMES_ACTIVE=true
# (Node >= 22, FFmpeg on PATH)。请参阅 https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false
步骤 7 — 更新 CLAUDE.md
- 在技术栈表中,将
Video行的提供商单元格更改为包含hyperframes (local HTML→MP4)。 - 在可用技能中,在
wavespeed-batch之后插入三行:hyperframes— HTML 作为真相来源的动态合成创作。hyperframes-cli— 运行npx hyperframeslint/inspect/preview/render。hyperframes-prompt-builder— 当矩阵解析为hyperframes时由video-prompt-builder选择。
步骤 8 — 验证
- 通过以下测试解析
.specs/architecture/PROVIDERS.md并断言motion-typography、data-viz-reel、programmatic-short都解析为hyperframes。 - 运行
npm run typecheck——接受任何与更改无关的预存失败(例如缺少@types/node);如果任何新 TS 错误引用提供商层,则失败。 - 如果仓库中存在
.env,则运行npm run router:check;否则跳过(该脚本需要.env,且与集成形状无关)。 - 确认
git status只显示预期文件。
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
console.error('MISSING:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
步骤 9 — 提交并推送
- 暂存此技能接触的确切文件。绝不要
git add -A。 - 使用规范消息提交:
加上描述三步合同执行的主体(参见合并的参考提交以获取措辞)。feat(skills): wire HyperFrames as a video provider - 推送到
origin <branch>。如果该分支不存在 PR,则打开一个草稿 PR。
输出
branch:字符串。包含提交的分支。pr_url:字符串。如果创建或已存在,则为草稿 PR URL。files_written:实际创建或修改的相对路径数组。files_skipped_idempotent:已经正确的相对路径数组。verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }。
不可协商的规则
- 幂等。 在已集成的仓库上重新运行不接触任何文件。
- 绝不在
main上提交。 先创建功能分支;引擎的分支策略在上游强制执行。 - 任何技能主体在合同外不得提及
hyperframes。 提供商选择仍然通过PROVIDERS.md+lib/router.ts进行。此技能是引导程序;运行时选择保持提供商无关。 - 不要编辑已渲染的 MP4 或
outputs/下的任何文件。 此技能仅更改引擎管道。 - 永远不要删除现有的
compliance-<active client>技能或任何客户特定的工件。 集成是增量的。
失败模式
- 步骤 1 预检失败(不是 marketing-engine 仓库):显示缺失文件并停止。不要尝试“修复”。
- 文件已存在但内容冲突(例如手动编辑了
.skills/hyperframes/SKILL.md):与规范内容比对;显示差异;在覆盖之前询问操作员。 npm run typecheck报告lib/providers/中的新 TS 错误:停止,显示错误,不要提交。git push由于非网络原因失败:停止。网络失败根据项目 git 策略重试(2s、4s、8s、16s 回退,最多 4 次尝试)。
相关技能
hyperframes:运行时创作(由本技能在步骤 2 中安装)。hyperframes-cli:运行时 lint/inspect/render(由本技能在步骤 2 中安装)。hyperframes-prompt-builder:运行时专家(由本技能在步骤 2 中安装)。video-prompt-builder:由本技能在步骤 3 中更新的调度器。llm-router:无关;LLM 提供商路由是并行的调度器。
参考工件集
此技能写入的每个文件的规范内容位于 main 上的合并提交中:
- 技能:
.skills/hyperframes/SKILL.md、.skills/hyperframes-cli/SKILL.md、.skills/hyperframes-prompt-builder/SKILL.md - 提供商层:
lib/providers/types.ts、lib/providers/matrix.ts、lib/providers/video.ts、lib/providers/__mocks__/video.ts - 路由矩阵:
.specs/architecture/PROVIDERS.md - 环境变量:
.env.example - 章程:
CLAUDE.md
如有疑问,与 origin/main 在合并参考提交处比对,并逐字复制规范版本。不要凭记忆重打。