motion-graphics — 调度入口
在进入步骤 0 之前确认路由。 本技能制作 简短、设计主导、无旁白的动态图形(运动即是信息;时长约在 10 秒以内,无画外音)。对于 较长、多场景或带旁白 的内容 →
/general-video;带旁白的网站视频 →/website-to-video;话题讲解 →/faceless-explainer;产品宣传 →/product-launch-video;为现有素材添加字幕 →/embedded-captions。超出范围:实时/渲染时获取数据,或无法捕捉的素材。不确定是动态优先还是带旁白?请先阅读/hyperframes。
一个简短的设计主导动态图形。资产优先:在设计镜头之前,先确定资产策略并获取真实素材;然后根据已有的素材进行镜头设计;最后通过复用目录能力进行组合。所有产物均放入 PROJECT_DIR = videos/<project-name>/(在步骤 0 中创建);以下所有路径都相对于此目录。
| 阶段 | 执行方式 | 主要产物 | 详细流程 |
|---|---|---|---|
| 初始化 | Bash | hyperframes.json | 步骤 0 |
| 计划 | 子代理 — 决定是否需要搜索? + 分类 + 资产策略 | shot-plan.json(草案:类别、asset_needs 查询、简要) | agents/director.md(第 1 部分) |
| 素材 ◇ | Bash — media-use 解析(如果 asset_needs 为空则跳过) | assets/ + assets/index.md | phases/source/guide.md |
| 设计 | 子代理 — 基于已解析的资产进行镜头设计 | shot-plan.json(最终版:block(s) + 布局 + 运动 + 位置) | agents/director.md(第 2 部分) |
| 构建 | 子代理 — 复用优先的组合 | compositions/index.html | agents/builder.md |
| 渲染 | Bash — hyperframes render(MP4,或 --format webm/mov 用于叠加) | renders/video.mp4 | 步骤 5 |
| 验证 | Bash — lint / inspect -> 失败时启动修复子代理 | (原地修复) | agents/finalize.md |
◇ 素材 仅在选择类别需要资产时运行。纯代码/文本类别(例如 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 解析) | 跳过生成 / 仅搜索 |
| (asset_scout / 搜索提供商) | webpage/news/tweet + asset-fusion 真实资产搜索 | 类别降级为无资产版本 |
流程
步骤 0 — 初始化
当前工作目录为 agent 工作区根目录;所有产物写入 PROJECT_DIR = videos/<project-name>/。<project-name>:使用用户提供的目录名,否则从意图中提取一个简短的短横线命名名称(<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 --example=blank
init 会检查已安装的技能是否与 GitHub 上的最新版本一致,并在任何技能过时时更新全局集合。
约束: 永远不要在 workspace 根目录中执行 hyperframes init;永远不要在 PROJECT_DIR 内部嵌套另一个 hyperframes/;每个 Bash 命令(master + 子代理)都是一个 (cd "$PROJECT_DIR" && ...) 子 shell — 永远不要单独使用 cd。
步骤 1 — 计划(子代理:Director 第 1 部分)
启动一个子代理。提示 = 完整 agents/director.md + ## Dispatch context(SKILL_DIR / PROJECT_DIR / 用户的请求 / Schema: <SKILL_DIR>/references/shot-plan-ir.md)。它必须:
- 决定:是否需要搜索?(第一个分支)
- 不需要 → 选择一个 表单类别(kinetic-type / stat / charts / logo-reveal / lower-thirds);内容由用户提供;
asset_needs: []。 - 需要 → 将 搜索计划 写入
asset_needs[](新闻 / 网页 / 推文 / 图片;双极查询)。具体的 搜索驱动类别(webpage / news / tweet / asset-fusion)将由步骤 2 返回的内容类型确认,并在步骤 3 最终确定。
- 不需要 → 选择一个 表单类别(kinetic-type / stat / charts / logo-reveal / lower-thirds);内容由用户提供;
- 编写一个
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;搜索驱动类别使用新闻/网页/推文/图片搜索)。如果 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 — 设计(子代理:Director 第 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 — 构建(子代理:Builder,复用优先)
启动一个子代理。提示 = 完整 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 辅助功能。输出符合 HF 合约的 compositions/index.html(暂停的 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 搜索(新闻/网页/推文/图片),这是 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(Director 输出) assets/ assets/index.md # media-use 输出(如果已获取素材) compositions/index.html # Builder 输出 renders/video.mp4 - 注册: 在
hyperframes路由中 — 添加“设计主导的简短动态图形”意图 + 工作流描述;从/general-video中分割出 motion-graphics 触发器;添加反向“请勿使用”边。详见motion-graphics-genre.md§5-7。