motion-graphics

motion-graphics — 调度入口

在步骤0之前确认路线。 此技能制作一个简短、以设计为主导、无旁白的动态图形（运动本身就是信息；约10秒以内，无画外音）。较长、多场景或带旁白的处理方式 → /general-video；带旁白的网站视频 → /website-to-video；主题讲解 → /faceless-explainer；产品推广 → /product-launch-video；为现有素材添加字幕 → /embedded-captions。超出范围：实时/渲染时数据，或无法捕获的素材。不确定是动态优先还是带旁白？先阅读 /hyperframes。

一个简短、以设计为主导的动态图形。资产优先：在设计镜头之前确定资产策略并获取真实素材，然后根据已有素材设计镜头，最后通过重用目录能力进行合成。所有工件放在 PROJECT_DIR = videos/<project-name>/（在步骤0创建）；以下所有路径均相对于该目录。

阶段	执行方式	主要工件	详细流程
init	Bash	hyperframes.json	步骤0
plan	子代理 — 决定是否搜索？ + 分类 + 资产策略	shot-plan.json（草稿：类别、asset_needs 查询、简要说明）	agents/director.md（第1部分）
source ◇	Bash — media-use resolve（如果 asset_needs 为空则跳过）	assets/ + assets/index.md	phases/source/guide.md
design	子代理 — 围绕已解析资产设计镜头	shot-plan.json（最终版：block(s) + 布局 + 运动 + 位置）	agents/director.md（第2部分）
build	子代理 — 优先重用合成	compositions/index.html	agents/builder.md
render	Bash — hyperframes render（MP4，或 --format webm/mov 用于叠加层）	renders/video.mp4	步骤5
verify	Bash — lint / inspect -> 失败时修复子代理	（原地修复）	agents/finalize.md

◇ source 仅在所选类别声明需要资产时运行。纯代码/文本类别（例如 kinetic-type、大多数 charts/stat）的 asset_needs: []，直接从计划跳到设计。

类别 — 按搜索决策划分

plan 的第一个决策是：是否需要搜索？ 这个分支将类别分为两组；然后选择具体类别——对于搜索驱动型，根据搜索返回的内容类型。每个类别是一个 categories/<id>/module.md（其规划+构建规则）；共享的运动词汇表位于 references/motion-vocabulary.md（→ hyperframes-animation 规则/蓝图 + 注册表块）。

形式类别 — 无需搜索；用户提供内容：

类别	意图	依赖
kinetic-type	有力的台词/引用/标题，运动优先的文字	caption-* 块 + 动画规则
stat	单个英雄数字/计数 + 环形	apple-money-count / rules/{counting-dynamic-scale, stat-bars-and-fills}
charts	条形/折线/饼图/竞赛/百分比来自数据	data-chart 块
logo-reveal	Logo 出场/品牌组合（用户提供的 Logo）	logo-outro / rules/svg-path-draw
lower-thirds	姓名/标题栏、标注、社交媒体叠加层	caption-* + 注册表叠加层块

搜索驱动类别 — 先搜索，然后按内容类型动画化（RWA 路径）：

返回的内容	类别	动画
网页/链接	webpage	网页/UI 动画（滚动、揭示、光标、标注）
新闻文章	news	标题揭示 + 来源卡片 + 关键事实标注
推文	tweet	动画推文卡片
图片/实体	asset-fusion	资产的几何形状_变成_图表（RWA 融合）

构建顺序：一次一个，覆盖优先（粗糙也可以）。kinetic-type 从原型移植；其余后续跟进。

先决条件

macOS Apple Silicon 或 Linux x64。系统工具：brew install node ffmpeg。运行一次 npx hyperframes doctor。macOS GPU 渲染：export PRODUCER_BROWSER_GPU_MODE=hardware。

可选密钥（未设置时使用本地回退）——仅当类别通过 media-use 获取/生成资产时需要：

密钥	用途	回退
GEMINI_API_KEY / GOOGLE_API_KEY	图像生成（media-use resolve）	跳过生成 / 仅搜索
(asset_scout / 搜索提供商)	webpage/news/tweet + asset-fusion 真实资产搜索	类别降级为无资产

流程

步骤0 — 初始化

当前工作目录是代理工作区根目录；所有工件写入 PROJECT_DIR = videos/<project-name>/。<project-name>：使用用户提供的目录名，否则从意图中取一个简短的 kebab-case 名称（<subject>-motion）。不是工作区基名或时间戳。

仅当 $PROJECT_DIR/hyperframes.json 不存在时：

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

约束： 永远不要在 workspace 根目录执行 hyperframes init；永远不要在 PROJECT_DIR 内嵌套另一个 hyperframes/；每个 Bash 命令（主代理 + 子代理）都是一个 (cd "$PROJECT_DIR" && ...) 子 shell — 永远不要裸 cd。

步骤1 — 规划（子代理：导演第1部分）

调度一个子代理。提示 = 完整的 agents/director.md + ## Dispatch context（SKILL_DIR / PROJECT_DIR / 用户请求 / Schema: <SKILL_DIR>/references/shot-plan-ir.md）。它必须：

1. 决定：是否需要搜索？（第一个分支）
   • 否 → 选择一个形式类别（kinetic-type / stat / charts / logo-reveal / lower-thirds）；内容由用户提供；asset_needs: []。
   • 是 → 将搜索计划输出到 asset_needs[]（news / web / tweet / image；两极查询）。具体的搜索驱动类别（webpage / news / tweet / asset-fusion）由步骤2返回的内容类型确认，并在步骤3最终确定。
2. 编写草稿 shot-plan.json（信封 + 所选形式类别 或 搜索意图 + asset_needs + 一段镜头简要说明）。模式：references/shot-plan-ir.md。

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

步骤2 — 素材获取 ◇（Bash: media-use，条件执行）

如果 shot-plan.json.asset_needs 非空，则解析资产（搜索/生成/获取 → 冻结的项目本地路径 + 账本）。参见 phases/source/guide.md（封装 media-use resolve；搜索驱动类别使用 news/web/tweet/image 搜索）。如果 asset_needs 为空，则跳到步骤3。

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

优雅降级：如果搜索/提供商不可用，类别回退到无资产（在 context.log 中注明）。

步骤3 — 设计（子代理：导演第2部分）

调度一个子代理（提示 = agents/director.md 第2部分 + 调度上下文，包括已解析的 assets/index.md（如果步骤2运行过）+ catalog-map.md）。它根据可用资产设计镜头：选择目录块 + hyperframes-animation 规则/蓝图、布局、运动、节拍，以及（对于 asset-fusion）element_positions + 取色器调色板。最终确定 shot-plan.json（content.block + content.customize + 每个类别的内容）。

步骤4 — 构建（子代理：构建器，优先重用）

调度一个子代理。提示 = 完整的 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 契约（暂停的 GSAP 时间线在 window.__timelines 上，class="clip" + 稳定 ID，tl.seek(0)，确定性）。

步骤5 — 渲染（Bash）

(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q draft -o ./renders/video.mp4)
# 透明叠加层变体：--format webm（或 mov）

步骤6 — 验证（Bash → 失败时修复子代理）

(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)

exit 0 → 完成。如果 lint/inspect 出错，调度修复子代理（agents/finalize.md：快照 QA + 一次原地修复 + 重新渲染）。修复中绝不更改固定时长。

报告 + 可选预览

报告最终输出（renders/video.mp4，或 .webm / .mov 叠加层变体）+ 时长。运行期间不要打开预览。 仅在请求时提供，在渲染之后启动，以便提供最终文件：

(cd "$PROJECT_DIR" && npx hyperframes preview)   # Studio UI；或 `npx hyperframes play` 获取可共享链接

标志位于 hyperframes-cli 技能中（references/preview-render.md）。

恢复表

状态	从中继续
没有 shot-plan.json	步骤1（规划）
shot-plan.json 有 asset_needs，没有 assets/	步骤2（素材获取）
shot-plan.json 最终版，没有 compositions/index.html	步骤3/4（设计+构建）
compositions/index.html 存在，没有 renders/video.mp4	步骤5（渲染）+ 步骤6
renders/video.mp4 存在	报告 + 停止

设计说明（维护者 — 执行时不读取此内容）

• 资产优先理由： 素材获取前置并指导镜头设计（RWA 流程：分析 → 搜索 → 审查 → 合成）。搜索驱动类别（webpage/news/tweet）和 asset-fusion 都依赖 media-use 搜索（news/web/tweet/image），这是 media-use 记录的 RWA 血统。
• 优先重用： 生态内相当于 LLM 生成模板的是“组合目录块 + hyperframes-animation 规则”。HF 的暂停 GSAP 时间线 ≙ Remotion 的 useCurrentFrame。
• 类别模块契约： 一个 categories/<id>/module.md（规划+构建），共享 references/motion-vocabulary.md（+ 可选评估）。添加一个类别 = 放入文件夹 + 在 agents/director.md 中注册其分类器行 + 在 catalog-map.md 中注册其行；阶段流水线不变。
• 目录结构：

  videos/<project-name>/
    hyperframes.json  context.log
    shot-plan.json            # IR（导演输出）
    assets/  assets/index.md  # media-use 输出（如果获取了素材）
    compositions/index.html   # 构建器输出
    renders/video.mp4
  

• 注册： 在 hyperframes 路由器中 — 添加“以设计为主导的简短动态图形”意图 + 工作流描述；从 /general-video 中划出 motion-graphics 触发器；添加反向“请勿使用”边。参见 motion-graphics-genre.md §5-7。