Communitygithub.com

Emasoft/ai-maestro-webdesign

将 HTML 合成内容渲染为 MP4 视频,通过外部 Hyperframes 单体仓库实现。当用户输入“将 HTML 渲染为视频”、“HTML 转 MP4”、“网站转视频”、“从 HTML 创建视频”、“将合成栅格化为 MP4”时触发。不会响应普通的“动画”/“视频”请求——这些会路由到 pretext 或用户的管线。

ai-maestro-webdesign 是什么?

该技能(skill)充当 Hyperframes 单体仓库的桥接层,允许 AI 智能体(如 Claude Code、Coder、Cursor 等)通过 Shell 调用将 HTML 合成内容渲染为 MP4 视频文件。它不会重新实现 Hyperframes 的渲染管线,而是严格以外部依赖的方式使用。技能会验证外部仓库是否存在且 CLI 可用,然后根据输入(单个 HTML 文件或完整的 Hyperframes 项目目录)解析出项目目录。执行渲染前,会按顺序运行 `lint → validate → inspect → render` 的门控序列(pre-render gate),确保合成内容符合规范。最后返回生成的 MP4 文件路径和一份作业完成报告。该技能支持多个平台,通常作为 Phase B(输出阶段)的最后一步被设计原则编排器调用,但任何智能体(主智能体、子智能体或外部编排器)均可通过阅读本 SKILL.md 独立使用。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Emasoft/ai-maestro-webdesign/tree/HEAD/skills/amw-hyperframes-bridge

在你喜欢的 AI 中提问

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

文档

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 调用。

指令

  1. 执行两项检查来验证外部仓库:external/hyperframes/package.json 必须存在,且 npx hyperframes render --help 必须给出响应;如果任一检查失败,立即失败退出。
  2. 解析项目目录:如果提供了 project_dir,则直接使用;否则从 html_scene_path 搭建一个临时项目;如果两者都未提供,立即失败。
  3. 按顺序运行预渲染门控序列:lint → validate → inspect → render(如果任何步骤返回非零值,则中止)。
  4. 执行 cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>;收集输出路径。
  5. 确认 MP4 文件存在且非空;报告输出路径以及任何 inspect 警告。
  6. 有关权威的执行步骤,请参阅下面的 ## 调用模式 部分。

激活

没有专用的斜杠命令——本技能没有匹配的 /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. 验证外部仓库——需要两项检查:

    # 检查 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"
    

    如果任一检查失败,立即失败退出。不要继续。

  2. 解析项目目录。

    • 如果提供了 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"
      
    • 否则:立即失败。
  3. 运行预渲染门控序列: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(一种开发者循环原语)。

  1. 渲染。 在解析后的项目目录内执行:
    cd "$HF_PROJ_DIR"
    npx hyperframes render --output <abs-mp4-path>
    
    根据需要附加其他标志(--fps、--quality、--format、--hdr 等)——参见 TECH-hyperframes-cli-render。

[TECH-hyperframes-cli-render.md] 功能 · 何时使用 · 工作原理 · 标志 · 质量指南 · 透明视频 · 最小示例 · 工作线程调优 · 陷阱 · 交叉引用

  1. 将 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。两个强制输出项:

  1. 工件——hyperframes 项目文件夹 + 渲染的 MP4。路径从项目推断(用户路径 → 框架约定 → ./design/<subtype>/ → 回退 ./design/videos/)。
  2. 作业完成报告位于 $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 属性解析错误、视频编码失败、陈旧克隆。

相关技能