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	子 Agent — 决定是否搜索？ + 分类 + 素材策略	shot-plan.json（草稿：类别、asset_needs 查询、简报）	agents/director.md（第 1 部分）
source ◇	Bash — 解析媒体使用情况（若 asset_needs 为空则跳过）	assets/ + assets/index.md	phases/source/guide.md
design	子 Agent — 围绕已解析的素材设计镜头	shot-plan.json（最终版：区块 + 布局 + 动效 + 位置）	agents/director.md（第 2 部分）
build	子 Agent — 优先复用进行合成	compositions/index.html	agents/builder.md
render	Bash — hyperframes render（MP4；叠加层可用 --format webm/mov）	renders/video.mp4	步骤 5
verify	Bash — lint / inspect -> 失败时由修复子 Agent 处理	（就地修复）	agents/finalize.md

◇ source 仅在所选类别声明了素材时运行。纯代码/文本类别（例如 kinetic-type、大多数 charts/stat）的 asset_needs: []，会从 plan 直接跳到 design。

分类——按搜索决策划分

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 — 初始化

当前工作目录是 Agent 工作区根目录；将所有产物写入 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 --example=blank

init 会检查已安装的技能是否为 GitHub 上的最新版本；若有过期项，则更新全局技能集。

**约束：**绝不要在工作区根目录运行 hyperframes init；绝不要在 PROJECT_DIR 内再嵌套一个 hyperframes/；每条 Bash 命令（主 Agent + 子 Agent）都必须在 (cd "$PROJECT_DIR" && ...) 子 Shell 中运行——绝不要单独运行 cd。

步骤 1 — 规划（子代理：Director Part 1）

派发一个子代理。prompt = 完整的 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 + 一段镜头简述）。Schema：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。

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

优雅降级：如果搜索/提供方不可用，则类别回退为无素材模式（在 context.log 中注明）。

步骤 3 — 设计（子代理：Director Part 2）

派发一个子代理（prompt = agents/director.md Part 2 + 派发上下文，其中包含已解析的 assets/index.md（如果运行了步骤 2）+ catalog-map.md）。它围绕可用素材设计镜头：选择目录区块 + hyperframes-animation 规则/蓝图、布局、动作、节拍，以及（对于 asset-fusion）element_positions + 吸管调色板。完成 shot-plan.json（content.block + content.customize + 各类别内容）。

步骤 4 — 构建（子代理：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)、确定性）。

步骤 5 — 渲染（Bash）

(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q draft -o ./renders/video.mp4)
# transparent overlay variant: --format webm  (or 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; or `npx hyperframes play` for a shareable link

标志位位于 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 都依赖媒体用途搜索（新闻/网页/推文/图像），这符合媒体用途文档中记录的 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            # the IR (Director output)
    assets/  assets/index.md  # media-use output (if sourced)
    compositions/index.html   # Builder output
    renders/video.mp4
  

• **注册：**在 hyperframes 路由器中添加“设计驱动的短篇动态图形”意图和工作流说明；从 /general-video 中划分出动态图形触发条件；添加反向的禁止使用关联。参见 motion-graphics-genre.md §5-7。