OpenMontage 中 logo-reveal 分类模块实战：用 motion-graphics 流水线打造 3–5 秒 Logo Sting 与品牌 Lockup

在 OpenMontage 的 .agents/skills/motion-graphics 技能体系中，logo-reveal 是一个面向 Logo 品牌开场动画（logo sting / brand lockup） 的表单分类模块，其规划与构建规则集中在 categories/logo-reveal/module.md。它代表一类"运动即信息"的短动画：通常 3–5 秒、无旁白、以 Logo 为主体，产出物常导出为带透明通道的 overlay（alpha-overlay），用于叠放到其他成片片头或片尾。本文从该模块出发，结合 motion-graphics 技能的编排流程、复用优先的构建契约，以及 hyperframes-animation 规则库中的 svg-path-draw、scale-swap-transition 等实现级细节，梳理一套可以直接落地的 Logo sting 制作方案。

一图定位：logo-reveal 在 motion-graphics 分类树中的位置

motion-graphics 技能的入口 SKILL.md 把"是否需要联网搜索素材"作为第一道分类分叉：不需要搜索、由用户直接提供内容的称为"表单分类（form category）"；需要搜索真实素材的称为"搜索驱动分类"。logo-reveal 属于前者：

表单分类	创作意图	主要依赖
kinetic-type	冲击力金句 / 引言 / 标题，文字为主角	caption-* 块 + 动画规则
stat	单个英雄数字 / 计数 + 圆环	apple-money-count / 计数与条形规则
charts	基于数据的柱 / 线 / 饼 / 排行 / 百分比	data-chart 块
logo-reveal	Logo sting / 品牌 lockup（用户提供的 Logo）	logo-outro 块 / rules/svg-path-draw
lower-thirds	姓名 / 标题条、callout、社媒 overlay	caption-* + registry 叠加块

导演（Director）子代理的意图分类表（见 agents/director.md）把该分类的触发条件写得很明确："a logo sting / brand lockup (user supplies the logo)"——即当用户诉求是"给一个已有 Logo 做开场动画/品牌锁定版式"时选择本分类。它的资产策略也因而不走搜索通道：logo-reveal 的 asset_needs 是用户指定的单个 Logo 来源（source），而不是一条搜索 query。

概念定义：Logo sting / Brand lockup 与资产约束

module.md 开篇即定义本分类的产出：

• logo sting：一段短促的品牌标记动画，视觉主体只有一个品牌标志；
• brand lockup：Logo 与 tagline、URL 等元素组合成一套静态锁定版式，动画负责把它们"装配"到位。

关键约束与默认值如下（继承自 module.md，并结合 director 的 envelope 定义）：

属性	默认 / 取值
素材来源	asset_needs = 一个 Logo source（用户提供，非搜索）
时长	约 3–5 秒
常用导出	export: alpha-overlay（把 sting 叠到其他成片上）
content 结构	{ logo: <asset path>, tagline, url }
视觉基调	品牌色板（或从 Logo 取色的 eyedropper）、优雅的节奏

注意 module.md 的"约 3–5 秒"针对的是 sting 这一类短促开场；而导演分类表把表单分类的 envelope 时长范围放宽到 3–30 秒，具体落点由分镜计划（shot-plan）的节奏设计决定。更长的多场景品牌片不属于本分类管辖，应转向 general-video（对应 SKILL.md 顶部的分流说明）。

导演规划：content 结构与 Envelope 字段

Director 第一部分（Plan）产出一份草稿 shot-plan.json，其 schema 定义在 references/shot-plan-ir.md。对 logo-reveal 而言，module.md 要求 content 形如：

{
  "content": {
    "logo": "<asset path>",   // 用户提供的单个 Logo 资源
    "tagline": "…",           // 副标语
    "url": "…"                // URL pill 中展示的网址
  }
}

Envelope 字段（继承自 agents/director.md Part 1 第 3 步）构成动画的全局骨架：

字段	说明
duration_s	时长（3–30 秒；logo sting 通常取 3–5 秒）
fps	帧率，默认 30
canvas	画布，默认 1080×1920；按平台可选 16:9 / 1:1
style	风格描述
palette	hex 色板列表，或 "derive-from-asset"（从素材取色）
font	从 HF embed 列表中选择的字体
beats	节奏点
export	mp4 或 alpha-overlay

对于本分类，module.md 强调两个规划要点：色板优先采用品牌色板，若未提供则用 eyedropper 从 Logo 中吸取主色与强调色；节奏走优雅路线（elegant pacing），避免急促。这是与 kinetic-type 那种"重击式"动效形成对比的关键导演决策。

视觉词汇（Vocabulary）：本分类"靠什么做动画"

module.md 将本分类的动画实现依赖分三层列出，这也是规划时"先命名能力、再写代码"的依据：

1. Catalog 块：logo-outro——提供"逐块装配 + 辉光 bloom + tagline 淡入 + URL pill"的整套组合；
2. 动画规则（rules）：
   • rules/svg-path-draw——矢量 Logo 的描线绘制（draw-on）；
   • rules/scale-swap-transition——缩放替换过渡；
   • rules/3d-text-depth-layers——为带深度的字标/tagline 提供纵深层级（从 blueprint 的映射关系可推断其在 lockup 中负责深度排序，属于锦上添花的次级规则）；
3. 运动原语（primitives）：draw-on / mask-reveal / particle-assemble 入场，配合 glow bloom、underline_sweep、以及末尾的 hold（定格）。

这套词汇在共享文档 references/motion-vocabulary.md 中以"命名原语 → GSAP 配方"的表格式书写，其中与本分类直接相关的几条为：

原语	GSAP 配方	适用语境
glow	to({ textShadow:"0 0 46px <ink/accent>", yoyo:true, repeat:1 })	强调、"魔法感"，即 Logo 的辉光 bloom
underline_sweep	fromTo({scaleX:0},{scaleX:1}, transformOrigin:"left center")	强调色下划线扫过（accent underline sweep）
scale_grow	from({ scale:0, opacity:0, duration:.6, ease:"power2.out" })	冷静、优雅的 Logo 放大入场
fade_blur	from({ opacity:0, filter:"blur(14px)" })	电影感、梦幻的进画

motion-vocabulary 同时给出"优先使用 HF registry 组件"的忠告：凡是 caption-*、shimmer-sweep 等已渲染验证的组件能覆盖的需求，不要手写等价物——这正是整个技能复用优先哲学在单个分类内的体现。

规则深潜一：svg-path-draw——矢量 Logo 的"手绘描线"

当 Logo 是 SVG/矢量路径时，module.md 明确建议首选 draw-on。其底层实现规则在 rules/svg-path-draw 中有完整可复制的 HTML/CSS/GSAP 骨架。核心原理只有两条 SVG 描边属性的配合：

1. stroke-dasharray = <pathLength>——把整条路径设成"一段长划"，等于路径总长；
2. stroke-dashoffset 从 pathLength 动画到 0——先把整条路径偏移出视野（不可见），再逐步收回直到完全画出。

路径长度通过 DOM API path.getTotalLength() 实测，不要猜测数字。关键代码形态：

const paths = document.querySelectorAll(".logo-mark path");
paths.forEach((p) => {
  const len = p.getTotalLength();
  p.style.strokeDasharray = `${len}`;
  p.style.strokeDashoffset = `${len}`;
});

const tl = gsap.timeline({ paused: true });

// 多段路径交错绘制：后一段在前一段收尾前 ~70–80% 时启动，
// 视觉上才是"连续一笔"而不是 N 段孤立动画
tl.to("#bar-left",  { strokeDashoffset: 0, duration: SEGMENT_DRAW_DUR, ease: "power2.out" }, SEG_1_START);
tl.to("#bar-right", { strokeDashoffset: 0, duration: SEGMENT_DRAW_DUR, ease: "power2.out" }, SEG_2_START);
tl.to("#bar-mid",   { strokeDashoffset: 0, duration: FINAL_SEGMENT_DUR, ease: "power2.out" }, SEG_3_START);

该规则还给出每个时间参数的取值区间，可直接套用到 sting 设计：

参数	取值范围	备注
SEGMENT_DRAW_DUR	0.3–0.8 s	短段偏快（0.5 s 附近）、长曲线偏慢；>1 s 对 Logo 揭示显得拖沓
FINAL_SEGMENT_DUR	0.25–0.6 s	约为段长比例的 60–80%
SEG_1_START	0–0.4 s	约 0.2 s 的留白先让观众落位
SEG_2_START	上一段起点 + 50%–100% 段时长	取约 70–80% 交叠读起来最连续
BRAND_FADE_DUR	0.3–0.8 s	字标淡入；冷静 lockup 约 0.5 s
BRAND_FADE_START	≥ 末段完成时刻 + 0.2 s	必须等描线落定再入场，避免抢戏

其设计要点与红线同样值得注意：轮廓绘制时 CSS 必须 fill: none；描线缓动只能用 power2.out，严禁 back.out / elastic.out（"笔不会弹跳"）；若追求恒定速率可用 ease: "none"；stroke-linecap: round 可柔化端点。若需要"描完再填充"，可在描线结束后补一段 fillOpacity 动画。

规则深潜二：scale-swap-transition——遮罩/缩放替换过渡

当 Logo 需要"从某个画面形态切换到 lockup 形态"，module.md 列出的第二规则 scale-swap-transition 提供一个轻量级"伪变形"方案——不需要 SVG 路径插值，只需在同一个触发时刻重叠执行两段协调动画：

1. 离开元素：scale 1.0 → EXIT_SCALE + opacity 1 → 0（快速 power2.in）；
2. 进入元素：scale EXIT_SCALE → 1.0 + opacity 0 → 1（带过冲的 back.out(1.4~2.2)）。

两者共用同一 transform-origin: 50% 50%，进入元素 z-index 在上、且入场提前 OVERLAP（0.1–0.2 s）开始，重叠窗口形成"原地互换"的视觉欺骗。

// Outgoing: shrink + fade fast
tl.to("#outgoing", { scale: EXIT_SCALE, opacity: 0, duration: EXIT_DUR, ease: "power2.in" }, TRIGGER);
// Incoming: pop in with overshoot, starts slightly BEFORE exit finishes
tl.to("#incoming", { scale: 1.0, opacity: 1, duration: ENTER_DUR, ease: "back.out(1.8)" }, TRIGGER + EXIT_DUR - OVERLAP);

该规则的调参表对 sting 设计直接可用：EXIT_DUR 0.3–0.5 s、ENTER_DUR 0.45–0.7 s（要长于退场以便过冲落定）、EXIT_SCALE 0.6–0.8（过小会读成"消失"而非"变形"）、BOUNCE_FACTOR 1.4（软）–1.8（硬）–2.2（卡通）。对位图上（canvas 相同或适配）可做 logo-outro 的收尾衔接或 Logo 图标的形态替换。

构建（Build）路线：复用 logo-outro 还是手写？

module.md 的 Build 段落给出了两条路线，默认复用优先（reuse-first）：

路线 A —— 复用 logo-outro 块：Director 在 shot-plan 中命名块并列出"要换什么"。按 catalog-map.md 中"brand reveal"分类映射，借用的正是 logo-outro（逐块装配 + 辉光 + tagline + URL pill），需要定制的只有四项：Logo 资源、tagline、URL、色板。执行上等价于 npx hyperframes add logo-outro 把块源码落到 compositions/ 后原地改内容——大多数块把内容数据烘进自身脚本，因此"复用 = add + edit"，而非纯变量注入。块以固定画布交付（1920×1080 / 1080×1920 / 1080×1080），需匹配或适配。

路线 B —— 手工编排（仅当复用块覆盖不了时）：module.md 给出了逐帧设计要点，可作为最精炼的分镜脚本：

1. 把 Logo 放到 hero 帧（用 CSS 定位/布局）；
2. 揭示入场：SVG 用 draw-on（stroke-dashoffset），否则用 mask/scale；
3. 叠加 glow bloom 与强调色 underline sweep；
4. 末尾 hold 定格。

格式决策（module.md 的 Build 段是硬性规则）：

Logo 类型	首选揭示方式
SVG 矢量	draw-on（描线绘制）
位图/栅格	mask/scale + glow
导出为 overlay 时	背景透明（transparent bg）

所有产物必须遵守 HF 契约（references/builder-contract.md 与 hyperframes-core 文档中的写法）：paused GSAP timeline 注册到 window.__timelines、元素使用 class="clip" 与稳定 id、支持 tl.seek(0)、保持确定性。module.md 提到的 scale_grow、fade_blur、glow、underline_sweep、hold 均可在 references/motion-vocabulary.md 中查到成对 GSAP 配方。

端到端流水线与渲染验证

把 logo-reveal 放进 motion-graphics 的整体流程（SKILL.md）中，其流水线为 init → plan → (source，本分类跳过) → design → build → render → verify：

阶段	主执行	主要产物
init	Bash	hyperframes.json
plan	导演子代理	shot-plan.json（草稿：分类、asset_needs、brief）
source ◇	Bash（media-use resolve）	assets/ + assets/index.md（logo-reveal 跳过）
design	导演子代理	shot-plan.json（终稿：块 + 布局 + 动效 + 位置）
build	构建子代理（复用优先）	compositions/index.html
render	Bash	renders/video.mp4
verify	Bash lint/inspect → 修复子代理	就地修复

初始化与渲染命令（均在独立项目目录内以子 shell 执行，禁止在 workspace 根目录 hyperframes init）：

PROJECT_DIR="videos/<project-name>"
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank

# 渲染为 MP4
(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q draft -o ./renders/video.mp4)

# 透明通道 overlay 变体（Logo sting 叠到其他成片上时使用）
(cd "$PROJECT_DIR" && npx hyperframes render . --format webm -o ./renders/video.webm)  # 或 --format mov

验证与预览：

(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)
(cd "$PROJECT_DIR" && npx hyperframes preview)   # Studio UI；运行结束后再打开

系统前提为 macOS Apple Silicon 或 Linux x64，先 brew install node ffmpeg 并执行一次 npx hyperframes doctor。由于本分类 asset_needs 为用户提供 Logo，不触发媒体搜索/生成，因此无需配置图片生成类 API key。渲染与预览 flag 的细节可查 hyperframes-cli/references/preview-render.md。失败时的修复子代理契约见 agents/finalize.md：快照 QA + 单轮就地修复 + 重渲染，且修复中不得改动已固定的时长。

更强的变体参考：logo-assemble-lockup blueprint

当需求超出 3–5 秒基础 sting（例如要做"Logo 由零件逐块自组装、字标级联、随后推入 URL/CTA"的复杂开场），同仓库 hyperframes-animation 技能提供了时间码级的分镜蓝图 blueprints/logo-assemble-lockup.md。该蓝图覆盖 Product_Intro（居中固定标记 + 轨道粒子 + 摄像机倾斜）、CTA push（穿越负空间的镜头推进 + 运动模糊 + URL pill 擦除揭示）、Brand_Outro（清场 → 标记逐段描线 → 字标补齐 lockup）等变体，时长参考 4.6–11.0 秒，并把每个运动动词映射回对应规则（svg-path-draw、spring-pop-entrance、multi-phase-camera、center-outward-expansion 等）。它是把 logo-reveal 分类做深做高级时的"素材库"，与 motion-graphics 侧的 logo-outro 块、module.md 构建规则形成互补。

实战决策速查

把全文压缩成一份可直接执行的清单：

1. 判定：用户提供了 Logo、要求做 sting/brand lockup → 走 logo-reveal；Logo 素材写入 asset_needs 的 source，不触发搜索。
2. 规划：content 填 logo + tagline + url；色板取品牌色或用 eyedropper 从 Logo 取色；节奏定为 elegant；导出目标想清楚是 MP4 还是 alpha-overlay。
3. 定方案：优先命名 logo-outro 块并只定制四项；SVG Logo 用 svg-path-draw 描线，栅格 Logo 用 mask/scale + glow；把 underline_sweep、末尾 hold 写进 beats。
4. 构建：遵守 HF 契约（paused timeline、稳定 id、确定性）；块画布与目标画布不匹配时先适配。
5. 验证：hyperframes lint + inspect 通过后，才把 renders/video.mp4（或 webm/mov 透明版）作为最终交付。