HyperFrames motion-graphics 技能实战：用 HTML 构建 10 秒级设计主导动态图形

HyperFrames motion-graphics 技能实战：用 HTML 构建 10 秒级设计主导动态图形

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

导读

本文围绕 HyperFrames 仓库中的motion-graphics技能（skills/motion-graphics/SKILL.md）展开，它是项目为 Agent 准备的一套「短时长、设计主导、无旁白」动态图形（kinetic type、数字跳动、图表命中、Logo sting、地图动画、推文/新闻高亮等）的端到端工作流。读完本文，你将掌握该技能的完整 7 阶段流水线（init → plan → source → design → build → verify → render）、shot-plan.json中间表示（IR）的结构、Agent 如何「复用优先」地组合 catalog 块与动画规则，以及渲染确定性（determinism）与 GSAP 时间线契约背后的底层原理。

一、技能定位：什么时候走 motion-graphics

motion-graphics是 HyperFrames 意图路由层（skills/hyperframes/references/routes/motion-graphics.md）下的一个具体路由：它处理短、设计主导、无旁白、以动效本身传达信息的单镜头动态图形，通常 10 秒以内（最长约 30 秒），最终产出 MP4 或带透明通道的叠加层（WebM/MOV）。

典型触发词包括："an 8s logo sting"、"animate this stat"、"kinetic-type intro"、"animate this title"、"transparent lower-third overlay"。如果内容更长、带旁白、多场景，应路由到general-video；不确定时统一走/hyperframes入口（意图层拥有所有路由决策权）。

该技能是默认全自动的设计：全程最多允许一个澄清问题（由 Director 步骤提出），随后一路构建到验证环节，不做中间评审。由于单镜头很短，故事板与伴随会话（companion session）没有额外价值。但渲染仍然由用户把关：校验与证据截图通过后，会询问标准的「先预览，还是直接渲染？」问题（见 skills/hyperframes-core/references/brief-contract.md）。

分类系统：先回答「是否需要搜索」

plan阶段的第一决策是是否需要搜索，这一分叉把 10 个类别分成两组，随后再按返回的内容类型确定具体类别：

Form 类别（无需搜索，内容由用户提供）：

Search-driven 类别（先搜索，再按内容类型动画，即 RWA 路径）：

纯代码/文字类别（如kinetic-type、大部分charts/stat）的asset_needs: []，会直接从 plan 跳到 design，跳过 source 阶段。构建顺序采用「逐个类别、覆盖优先」策略（粗糙可用即可），kinetic-type从原型迁移而来，其余类别随后跟进。

二、前置条件与环境变量

技能要求macOS Apple Silicon 或 Linux x64环境，系统工具依赖 Node 与 FFmpeg：

brew install node ffmpeg npx hyperframes doctor # 一次性健康检查

macOS GPU 渲染需设置export PRODUCER_BROWSER_GPU_MODE=hardware。

以下可选密钥仅在未设置时使用本地回退，且只对通过 media-use 获取/生成素材的类别必需：

三、端到端 7 阶段流水线

技能在 skills/motion-graphics/SKILL.md 中把整个流程定义为 7 个阶段，核心原则是asset-first（素材先行）：先决定素材策略并获取真实素材，再围绕已有素材设计镜头，最后通过复用 catalog 能力完成合成。所有产物写入PROJECT_DIR = videos/<project-name>/（Step 0 创建），文中所有路径均相对它：

Step 0 — 初始化

cwd 为 Agent 工作区根目录，所有产物写入PROJECT_DIR = videos/<project-name>/。项目名使用用户给出的目录名，否则从意图提炼一个短 kebab-case 名称（<subject>-motion），不要用工作区 basename 或时间戳。仅当$PROJECT_DIR/hyperframes.json不存在时初始化：

PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}" mkdir -p "$(dirname "$PROJECT_DIR")" npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=motion-graphics

init会把已安装技能与 GitHub 最新版本比对，若过期则更新全局技能集。两条硬约束：绝不在工作区根目录执行hyperframes init；绝不在PROJECT_DIR内再嵌套一个hyperframes/；所有 Bash 命令（主代理与子代理）都必须以(cd "$PROJECT_DIR" && ...)子 shell 形式执行，禁止裸cd。

Step 1 — Plan（子代理：Director Part 1）

分派一个子代理，prompt = 完整 agents/director.md +## Dispatch context（SKILL_DIR/PROJECT_DIR/ 用户请求 /Schema: <SKILL_DIR>/references/shot-plan-ir.md）。它必须完成两件事：

1. 决策：是否需要搜索？
   • 否→ 选择 form 类别（kinetic-type / stat / charts / logo-reveal / lower-thirds / maps），内容用户提供，asset_needs: []；
   • 是→ 在asset_needs[]中输出搜索计划（news / web / tweet / image，两极性查询），具体 search-driven 类别（webpage / news / tweet / asset-fusion）由 Step 2 返回的内容类型确认，Step 3 最终定稿。
2. 写一份草稿shot-plan.json（envelope + 所选 form 类别或搜索意图 +asset_needs+ 一段镜头 brief），schema 见 references/shot-plan-ir.md。

校验命令：[ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing。

Director 的素材策略要点：asset-free类别（kinetic-type、多数stat/charts）→asset_needs: []；maps的vector 车道无需素材（D3/TopoJSON 在 HF 内实时运行），basemap 车道（卫星/暗色/缩放到地点）需要asset_needs: [{ type: "map-bake", … }]；webpage/news/tweet搜索真实来源 + 一张辅助图片，只用两极性查询——原子查询（1–3 词、可组合：肖像、logo、物体）或特定查询（5–15 词：某新闻事件、某推文），绝不用中间地带；失败的特定查询直接丢弃而非放宽。

Step 2 — Source ◇（Bash：media-use，条件执行）

若shot-plan.json.asset_needs非空，则解析素材（搜索 / 生成 / 抓取 → 冻结的项目内路径 + 台账），详见 phases/source/guide.md（封装media-use resolve）。若asset_needs为空则直接跳到 Step 3。

# illustrative — see phases/source/guide.md (cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)

每个素材需求的处理流程是analyze → search → review（use/maybe/reject——选择才是最难的部分，不要取第一个/生成的结果）→ freeze（冻结进assets/，远程 URL 需重新托管），最后写assets/index.md台账（role → frozen path + provenance）。若搜索/服务商不可用，在context.log记录未满足需求，类别优雅降级为无素材（例如news降级为纯排版标题）。

Step 3 — Design（子代理：Director Part 2）

分派子代理（prompt =agents/director.mdPart 2 + 调度上下文，含 Step 2 运行后的assets/index.md+catalog-map.md）。它围绕可用素材设计镜头：选择 catalog 块 +hyperframes-animation规则/蓝图、布局、动效、节拍与退场；对asset-fusion还要产出element_positions+ 从素材吸取的色板。最终定稿shot-plan.json（content.block+content.customize+ 各类别专属 content）。

Director 的设计启发式（design-led short motion）值得注意：

• 动效即信息（Motion IS the message），无旁白叙事弧；钩子需快速落地（约前 0.5s）；一个主导母题；若片段超过约 2.5s 需要 pattern-interrupt（只改变一件事）；动效强度匹配能量；关键元素可读时长 ≥ 约 0.3s；节拍可提前约 0.1s 以获得感知上的同步。
• 复用优先：指名一个 catalog 块；只在空白处与asset-fusion专门逻辑处手写动效。

Step 4 — Build（子代理：Builder，复用优先）

分派子代理，prompt = 完整 agents/builder.md + 调度上下文（shot-plan.json、catalog-map.md、该类别的module.md、references/motion-vocabulary.md、references/builder-contract.md）。复用优先：npx hyperframes add <block>+ 就地定制；只对空白处与 asset-fusion 逻辑手写。输出compositions/index.html，并遵守 HF 契约（在window.__timelines上注册暂停的 GSAP 时间线、class="clip"+ 稳定 id、tl.seek(0)、确定性）。

Step 5 — Verify（Bash → 失败则分派修复子代理）

(cd "$PROJECT_DIR" && npx hyperframes lint .) (cd "$PROJECT_DIR" && npx hyperframes check .) (cd "$PROJECT_DIR" && npx hyperframes snapshot --at <proof-times>)

证据时刻应覆盖开场状态、标志性动作和最终定格。继续前需人工检查生成的 contact sheet / 截图。lint、check或截图失败时，分派修复子代理（agents/finalize.md）做一次就地修复，然后重跑失败的门禁。绝不允许为了掩盖缺陷而改动已固定的时长——只有镜头从根本上错误（整体内容偏离、需要重新合成）才回到 Step 3/4 重新设计与构建。

Step 6 — Approve and render（Bash）

先问一个问题：「先预览，还是直接渲染？」用户选择预览则打开 Studio，修订后回到同一批准门禁：

(cd "$PROJECT_DIR" && npx hyperframes preview --background)

只有在用户明确给出渲染答复后才渲染：

(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q high -o ./renders/video.mp4) # transparent overlay variant: --format webm (or mov)

渲染后校验输出存在、非空、时长符合预期。最终交接需说明产物名、实际时长、合成或帧 id、证据时刻，以及已检查的 contact sheet。渲染/预览旗标细节见hyperframes-cli的references/preview-render.md。

四、shot-plan IR：Director 与 Builder 之间的单一契约

references/shot-plan-ir.md 定义了这份文件——它是 Director 与 Builder 之间的唯一契约，一个文件承载从意图到可渲染合成的全部信息：

{ // ── envelope (every category) ── "category": "kinetic-type | stat | charts | logo-reveal | lower-thirds | webpage | news | tweet | asset-fusion", "duration_s": 6, "fps": 30, "canvas": { "w": 1080, "h": 1920, "aspect": "9:16" }, "style": "free-form visual direction (mood / energy / reference)", "palette": ["#…"], // or "derive-from-asset" "font": "<HF embed-list font>", "beats": [12, 37], // optional accent frames/seconds "export": "mp4", // or "alpha-overlay" (transparent webm/mov) // ── sourcing seam (Director Part 1) — [] means skip the source phase ── "asset_needs": [ { "role": "hero", "kind": "image|icon|logo|svg|news|web|tweet", "query": "…", "source": "…", "treatment": "cutout|recolor|vectorize|none", }, ], // ── build directive (Director Part 2, reuse-first) ── "block": "<catalog block id, e.g. contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes