Communitygithub.com

安装 HyperFrames

一键引导技能,将 HyperFrames 作为视频提供商集成到 marketing-engine 克隆中。幂等的,当你需要添加或重新应用 HyperFrames 集成时调用。

安装 HyperFrames 是什么?

该技能旨在简化和自动化将 HyperFrames 作为视频提供商集成到 marketing-engine 项目中的过程。它遵循项目 `CLAUDE.md` 中定义的“添加新提供商”三步合同,通过一个自包含的检查清单确保所有必要工件的存在并创建缺失部分。技能覆盖了从预检(验证仓库结构)到添加运行时技能、更新调度器技能、扩展提供商层、更新路由矩阵、环境变量和项目文档的完整流程。支持 HyperFrames,一个本地的 HTML 到 MP4 渲染器,无需 API 密钥。技能完全幂等,可安全地在已集成的仓库上重新运行而不产生副作用,并严格禁止在 `main` 分支上提交。它为开发人员提供了一个可重复、命令化的剧本,替代了手动推导集成或阅读多个提交的繁琐过程。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/install-hyperframes

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

安装 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 — 预检

  1. 确认 repo_root 包含 CLAUDE.md 且其中有行 ## How to Add a New Provider。如果缺失则拒绝运行——这不是 marketing-engine 仓库。
  2. 确认 lib/providers/video.ts、lib/providers/matrix.ts、lib/providers/types.ts 和 lib/providers/__mocks__/video.ts 存在。如果任何文件缺失则拒绝运行。
  3. 确认当前活动分支不是 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 hyperframes lint → 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 中:

  1. 将 hyperframes-prompt-builder 添加到开头段落和相关技能部分的专家列表中。
  2. 将 task_kind 输入枚举扩展为包含 motion_typography、data_viz_reel、programmatic_short。
  3. 在验证环境变量的流程步骤中,将 HYPERFRAMES_ACTIVE 添加到列表中。
  4. 在提供商到专家的映射中,添加行 Hyperframes -> hyperframes-prompt-builder。
  5. 添加一个示例:一个路由到 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

  1. 在技术栈表中,将 Video 行的提供商单元格更改为包含 hyperframes (local HTML→MP4)。
  2. 在可用技能中,在 wavespeed-batch 之后插入三行:
    • hyperframes — HTML 作为真相来源的动态合成创作。
    • hyperframes-cli — 运行 npx hyperframes lint/inspect/preview/render。
    • hyperframes-prompt-builder — 当矩阵解析为 hyperframes 时由 video-prompt-builder 选择。

步骤 8 — 验证

  1. 通过以下测试解析 .specs/architecture/PROVIDERS.md 并断言 motion-typography、data-viz-reel、programmatic-short 都解析为 hyperframes。
  2. 运行 npm run typecheck——接受任何与更改无关的预存失败(例如缺少 @types/node);如果任何新 TS 错误引用提供商层,则失败。
  3. 如果仓库中存在 .env,则运行 npm run router:check;否则跳过(该脚本需要 .env,且与集成形状无关)。
  4. 确认 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 — 提交并推送

  1. 暂存此技能接触的确切文件。绝不要 git add -A。
  2. 使用规范消息提交:
    feat(skills): wire HyperFrames as a video provider
    
    加上描述三步合同执行的主体(参见合并的参考提交以获取措辞)。
  3. 推送到 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 在合并参考提交处比对,并逐字复制规范版本。不要凭记忆重打。

上游参考

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相关技能