Hyperframes 桥接层
编排者: SKILL。 外部依赖包装器。 实际的 Hyperframes 单体仓库位于
../../external/hyperframes/(由/amw-init第 6 步克隆,如果用户选择加入;或者由本技能在首次渲染时作为一个备选方案克隆)。本技能记录 Shell 调用的模式,它不会内嵌该单体仓库。
概述
通过 Shell 调用 Hyperframes 单体仓库(external/hyperframes/),将 HTML 合成内容渲染为 MP4 视频。接受单个 HTML 场景文件或一个完整的 Hyperframes 项目目录。在调用 npx hyperframes render --output <mp4> 之前,必须运行预渲染门控序列(lint → validate → inspect → render)。返回 MP4 路径和一份作业完成报告。不在插件内重新实现 Hyperframes 管线——仅通过 Shell 调用。
指令
- 执行两项检查来验证外部仓库:
external/hyperframes/package.json必须存在,且npx hyperframes render --help必须给出响应;如果任一检查失败,立即失败退出。 - 解析项目目录:如果提供了
project_dir,则直接使用;否则从html_scene_path搭建一个临时项目;如果两者都未提供,立即失败。 - 按顺序运行预渲染门控序列:
lint → validate → inspect → render(如果任何步骤返回非零值,则中止)。 - 执行
cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>;收集输出路径。 - 确认 MP4 文件存在且非空;报告输出路径以及任何
inspect警告。 - 有关权威的执行步骤,请参阅下面的
## 调用模式部分。
激活
没有专用的斜杠命令——本技能没有匹配的 /amw-* 快捷方式。由 design-principles 编排器在 Main-agent 模式下,当已批准的设计需要 MP4 视频输出时,作为 Phase B 的最终步骤调用。编排器可以应用本技能中的完整 Hyperframes Shell 调用管线和合成技术,不受命令层限制。
此技能是自主且自包含的——任何智能体(主智能体、子智能体或外部编排器)都可以通过阅读本 SKILL.md 及其引用来使用它。该技能的技术不受匹配命令的限制。
在流程中的位置
输出(Phase B——终端)。HTML 到 MP4 视频渲染管线。仅当用户明确希望将 HTML 合成内容栅格化为视频文件时触发。在合成创作完成之后运行。
触发条件
仅当请求匹配以下之一时,才调用本技能:
- “将这个 HTML 渲染为视频” / “渲染为 MP4”
- “HTML 转 MP4” / “网站转视频” / “页面转视频”
- “从这个 HTML 合成内容创建视频”
- “将合成内容栅格化为视频”
- 明确提及 Hyperframes /
hyperframes render/.hf.html
如果只是泛泛地提及“动画”、“运动”、“视频播放”或“动画组件”,不要调用——那些属于:
../amw-design-principles/starter-components/animations.html(浏览器内的 Stage + Sprite 时间线)../amw-pretext/(排版动画——pretext-art/是一个已弃用的重定向)- 用户自己的管线
先决条件
-
运行时二进制文件(系统先决条件): Node.js >= 22, git
-
运行时二进制文件(由
/amw-init安装): Bun(Hyperframes 的包管理器),FFmpeg。Chrome 由 Hyperframes 自身通过hyperframes browser ensure管理(内部使用 Puppeteer +@puppeteer/browsers——而非 Playwright)。 -
外部来源:
../../external/hyperframes/——从https://github.com/heygen-com/hyperframes克隆的 Hyperframes 单体仓库。固定到 v0.4.30 或更高版本以支持inspect、--hdr和data-variable-values。如果该文件夹不存在,/amw-init或本技能必须在继续之前克隆它:git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes cd external/hyperframes && bun install
输入契约
桥接层接受两个互斥的输入。只能提供其中一个。
| 字段 | 类型 | 描述 |
|---|---|---|
html_scene_path | 字符串(可选) | 单个 HTML 文件的绝对路径。桥接层通过 mktemp -d -t hf-XXXXXX(POSIX 可移植)创建一个临时的 hyperframes 项目目录,将 HTML 写入为 index.html,进行渲染,然后在写入报告后清理。 |
project_dir | 字符串(可选) | 预先存在的 hyperframes 项目目录的绝对路径(包含 index.html,以及可选的 compositions/、assets/ 目录)。桥接层直接 cd 进入——无需搭建。支持子合成、音频和外部资源。 |
如果同时提供了两者,project_dir 优先。如果两者都未提供,立即失败。
调用模式
-
验证外部仓库——需要两项检查:
# 检查 1——package.json 存在(单体仓库已克隆) test -f "external/hyperframes/package.json" || exit-fail "未找到单体仓库" # 检查 2——CLI 响应(安装正常) # @hyperframes/cli 未发布到 npm——必须从单体仓库工作区内运行 (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "hyperframes CLI 不可用——在 external/hyperframes/ 内运行 bun install"如果任一检查失败,立即失败退出。不要继续。
-
解析项目目录。
- 如果提供了
project_dir:直接使用。设置HF_PROJ_DIR="$project_dir"。 - 如果提供了
html_scene_path:搭建一个临时项目:HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)" cp "$html_scene_path" "$HF_PROJ_DIR/index.html" - 否则:立即失败。
- 如果提供了
-
运行预渲染门控序列:
lint → validate → inspect → render。cd "$HF_PROJ_DIR" npx hyperframes lint npx hyperframes validate npx hyperframes inspect --json # 如果有任何错误则中止(使用 --strict 时非零退出)参见 TECH-hyperframes-cli-lint、TECH-hyperframes-cli-validate、TECH-hyperframes-cli-inspect。
[TECH-hyperframes-cli-inspect.md] 功能 · 何时使用 · 工作原理 · 标志 · 输出(JSON 模式) · 最小示例 · 选择退出的属性 · 陷阱 · 交叉引用 [TECH-hyperframes-cli-validate.md] 功能 · 何时使用 · 工作原理 · 输出 · 何时出现警告 · 最小示例 · 陷阱 · 交叉引用 [TECH-hyperframes-cli-lint.md] 功能 · 何时使用 · 工作原理 · 最小示例 · 陷阱 · 交叉引用
门控序列说明: 桥接层的顺序(
lint → validate → inspect → render)有意扩展了上游的顺序(lint → inspect → preview → render——参见内嵌的external/hyperframes/单体仓库中的上游 Hyperframes CLI SKILL.md),通过添加validate用于无人值守的 Phase B 管线,并移除了preview(一种开发者循环原语)。
- 渲染。 在解析后的项目目录内执行:
根据需要附加其他标志(cd "$HF_PROJ_DIR" npx hyperframes render --output <abs-mp4-path>--fps、--quality、--format、--hdr等)——参见 TECH-hyperframes-cli-render。
[TECH-hyperframes-cli-render.md] 功能 · 何时使用 · 工作原理 · 标志 · 质量指南 · 透明视频 · 最小示例 · 工作线程调优 · 陷阱 · 交叉引用
- 将 MP4 路径返回给调用者。如果项目目录是一个临时搭建的(
html_scene_path路径),则在写入报告后删除它。
HTML 合成规则(Hyperframes 专用)
合成内容使用纯 HTML,在 #stage 根元素及其子元素(轨道/剪辑/覆盖层)上带有 data-* 时间线属性。这与 ../amw-design-principles/starter-components/animations.html 中的 Stage + Sprite 心智模型相同——Hyperframes 通过多轨音频/视频混合和屏幕外确定性渲染对其进行了扩展。
关键属性(权威模式位于克隆后的 external/hyperframes/packages/core/ 中):
data-composition-id——舞台级标识符data-start、data-duration——秒,适用于每个剪辑data-track-index——图层排序(视频/覆盖层/音频轨道)data-width、data-height——舞台级画布尺寸
不要将 Framer Motion、GSAP 作为依赖项或任何第三方动画运行时引入桥接层。Hyperframes 有自己的帧适配器模式;如果用户希望在合成中使用 GSAP,那是 Hyperframes 的事情,不是桥接层的。
参考资料
完整参考索引:INDEX.md——32 个 TECH-*.md 文件,按捕获管线(7 步)、CLI 命令(12 个)、合成创作(7 个)、注册表(4 个)分组。每个文件都有自己的目录;只加载你需要的那一个。
示例
参见每个步骤的参考文件中的工作示例,位于 ./references/TECH-hyperframes-capture-step-*.md(7 步网站到视频管线)以及合成创作指南 TECH-hyperframes-composition-core。
[TECH-hyperframes-composition-core.md] 功能 · 何时使用 · 工作原理 · 方法(叙述顺序) · 单文件骨架 · 视觉标识门(必须——在编写 HTML 之前) · 陷阱 · 交叉引用
输出
一个渲染好的 MP4 视频文件加上一份作业完成报告。MP4 由 npx hyperframes render --output <mp4> 从解析后的项目目录生成;桥接层在报告成功之前会确认文件存在且非空。完整契约见下文。
输出与完成检查清单
完整输出契约(工件路径推断规则、作业完成报告格式、强制性检查清单)位于 TECH-output-contract。两个强制输出项:
- 工件——hyperframes 项目文件夹 + 渲染的 MP4。路径从项目推断(用户路径 → 框架约定 →
./design/<subtype>/→ 回退./design/videos/)。 - 作业完成报告位于
$MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.md,列出每个工件以及每个项目的检查清单判定。
在报告完成之前,TECH-output-contract 中的每个检查清单项目必须为通过或不适用。任何失败都会触发修复循环。
资源
../amw-design-principles/starter-components/animations.html——用于浏览器内预览的约 50 行 Stage + Sprite 时间线引擎;Hyperframes 共享相同的节奏。../../bin/amw-html-export.py——不是替代品。html-export将单个帧渲染为 PNG/PDF;Hyperframes 使用 Puppeteer + Chrome(由hyperframes browser ensure管理)+ FFmpeg 渲染多帧 MP4。../amw-dev-browser/——不是替代品。dev-browser用于输入/自动化;Hyperframes 是输出栅格化器。/amw-init——安装 Bun、FFmpeg,并在首次使用时克隆external/hyperframes/。用于渲染的 Chrome 由 Hyperframes 自身通过hyperframes browser ensure提供。- 外部仓库:
https://github.com/heygen-com/hyperframes
不可协商事项
- 通过 Shell 调用使用外部单体仓库。不要在插件内部重新实现其管线。
- 不要将 Hyperframes 源代码内嵌到
skills/中——500+ 个文件对于一个技能来说范围过大。 - 不要用
dev-browser替代 Hyperframes——它们解决的是相反的问题(输入 vs. 输出)。 - 不要用
html-export.py替代——单帧 PNG 不是视频。 - 用户必须在首次使用前运行
/amw-init以安装 Bun + FFmpeg 并克隆外部仓库。Chrome 在克隆后通过运行(cd external/hyperframes && npx hyperframes browser ensure)提供一次。
错误处理
常见故障模式及修复步骤见 TECH-error-handling。涵盖:缺少外部仓库、Bun/FFmpeg/Chrome 配置、HTML 属性解析错误、视频编码失败、陈旧克隆。