企业官网建设流程全解析

HyperFrames motion-graphics source 阶段深度指南：asset-first 素材采集、双极检索与优雅降级

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

导读：本文聚焦 HyperFrames 仓库中motion-graphics技能的素材采集阶段（source phase）——它是整个"asset-first"（素材先行）工作流的入口，负责在动效设计之前把每一条asset_needs需求解析成冻结到项目本地的素材文件与可审计的台账。读完本文，你将掌握 source 阶段的触发条件、四步执行流程（analyze → search → review → freeze）、面向image/icon/logo/svg与news/web/tweet两类素材的不同检索策略（含 RWA 双极查询规范）、assets/index.md台账结构，以及搜索/生成能力缺失时的优雅降级路径。

一、source 阶段在 motion-graphics 流水线中的位置

motion-graphics技能用于制作"短小、以设计为主导、无旁白"的动效短片（通常 <10s），它的核心工作流是asset-first：先决定素材策略、在镜头设计之前拿到真实素材，再围绕"已经拥有的素材"设计镜头，最后复用 catalog 中的现成能力完成合成。整个流水线在 skills/motion-graphics/SKILL.md 中被定义为 8 个阶段：

其中 source 是唯一带◇标记的条件阶段：它只在shot-plan.json.asset_needs非空时运行。纯代码/纯文字类别（如kinetic-type、大部分charts/stat）的asset_needs: []，会直接从 plan 跳到 design，完全不经过素材采集——这是流水线内建的短路机制。

source 阶段的完整定义见 skills/motion-graphics/phases/source/guide.md，它"包装"了 media-use 技能的resolve能力：当仓库中安装了类似 media-use 这样的外部素材检索技能时，调用其resolve步骤；如果没有任何检索能力可用，则降级为 asset-free（无素材方案）。

二、触发条件与输入：shot-plan.json.asset_needs

source 阶段的唯一输入是 Director（Part 1，plan 阶段）产出的shot-plan.json草案。其中asset_needs数组是 Director 与 source 阶段之间的"素材需求契约"，其结构定义在 skills/motion-graphics/references/shot-plan-ir.md：

{ "asset_needs": [ { "role": "hero", // 该素材在镜头中的角色 "kind": "image|icon|logo|svg|news|web|tweet", // 素材类型 "query": "…", // 检索/生成查询词 "source": "…", // 用户指定来源（如 logo） "treatment": "cutout|recolor|vectorize|none" // 可选后处理 } ] }

IR 中有一条硬性不变量：空asset_needs⇒ source 阶段被跳过。这条不变量在 skills/motion-graphics/SKILL.md 的 Step 2 中有明确说明，也体现在 resume 表里："shot-plan.json有asset_needs但没有assets/⇒ 从 Step 2（source）继续"。

三、按素材类型分派的检索策略

guide.md 把asset_needs按kind分成两大阵营，各自走完全不同的获取路径：

3.1 视觉素材：image / icon / logo / svg→ media-useresolve

对于图片、图标、Logo 与 SVG，source 阶段直接驱动 media-use 的resolve流程，三种来源按需选择：

• search（搜索）：通过 asset_scout（Google Images / SerpAPI）与 Noun Project 检索；
• generate（生成）：调用图像生成模型；
• user-supplied（用户提供）：Logo 类素材通常直接由用户给出。

可选的treatment后处理包括cutout（去背景）、recolor（重着色）与vectorize（矢量化）。

这里"包装"的底层命令是 media-use 的 resolve 入口脚本，其完整用法记录在 skills/media-use/references/resolve.md：

node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project . # → resolved image_001 → .media/images/image_001.jpg (image) node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project . # → resolved icon_001 → .media/images/icon_001.png (icon, transparent) node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project . # → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)

值得注意的一个实操纪律：media-use 的resolve要求"先复用、再解析"——运行前先用--candidates列出项目与全局缓存里已有的素材，由 agent 自己判断语义契合度，再用--reuse <sha>导入全局缓存素材；只有没有任何候选契合时才新鲜解析。其底层实现有一条"确定性底线"：对大小写/空白归一化后完全一致的重复需求会自动复用（project manifest 与~/.media/全局缓存），但模糊匹配永远不会自动套用，语义层面的复用始终是 agent 的显式决定。这一"reuse-first"原则同样贯穿整个 motion-graphics 工作流，见 skills/motion-graphics/catalog-map.md。

3.2 内容素材：news / web / tweet→ RWA 风格检索

新闻、网页与推文走的是RWA 风格检索（Real-Web-Article，真实网络内容），这条血统在 skills/media-use/references/resolve.md 中有文档化线索。其查询规范是整个 source 阶段最需要纪律的部分——双极查询（two-pole queries）：

永远不要落在两极之间的模糊地带——这是从搜索实践中总结出的铁律（在 skills/motion-graphics/agents/director.md 与 guide.md 中重复强调）。另外一条纪律是：一条失败的具体查询应当被丢弃，而不是放宽。这背后是对"检索精度优先"的坚持：素材检索的质量决定了镜头设计的质量，放宽查询只会把噪声带进后续的 asset-free 降级决策。

四、source 阶段四步执行流程

guide.md 给出了 source 阶段的完整执行步骤：

步骤 1：读取asset_needs

从shot-plan.json中读出 Director 声明的全部素材需求。这一步决定了本阶段是否运行、以及要解析哪些素材。

步骤 2：逐条 analyze → search → review → freeze

对每一条asset_needs，依次执行：

1. analyze（分析）：理解需求本质——这张素材在镜头里扮演什么角色；
2. search（检索）：按 3.1 / 3.2 的策略获取候选；
3. review（评审）：在候选集中做出 use / maybe / reject 三级判定。guide.md 特别强调："选择是最难的部分；不要直接采用第一个或生成出来的结果"；
4. freeze（冻结）：把保留的素材写入assets/目录，并将远程 URL 重新托管（rehost）为项目本地文件，保证渲染时的确定性（后续 render 阶段不能依赖任何网络）。

步骤 3：写assets/index.md台账

产出一份 agent 可读的台账：role → 冻结路径 + 出处（provenance）。这是 source 阶段的核心产物之一——design 阶段（Director Part 2）与 build 阶段（Builder）都依赖这份台账，而不是去猜assets/里有什么。台账文件与素材目录一起构成 skills/motion-graphics/SKILL.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

media-use 侧对应的清单式产物是.media/index.md（见 skills/media-use/references/resolve.md），两者结构一致：每行一条id · type · 尺寸/时长 · 路径 · 描述。

步骤 4（asset-fusion 专属）：测量几何 + 吸取色板

当类别为asset-fusion（真实素材的几何形状"变成"图表）时，source 阶段还需要额外捕获两类信息，供 Director Part 2 设置element_positions：

• 可测量的几何（measurable geometry）：素材中关键特征的 center / extent / safe-zones / avoid-zones；
• eyedropper palette（吸管色板）：从素材本身提取配色，而不是套用通用的 #FFF/#000。

这两项在asset-fusion类别中是硬性要求，详见 skills/motion-graphics/categories/asset-fusion/module.md。

五、asset-fusion 素材的几何定位：为什么不能"目测坐标"

guide.md 只点出"捕获素材的可测量几何"，而具体的测量协议由 grounding 子目录提供——这是 source 阶段为 asset-fusion 准备素材时最关键的底层机制，见 skills/motion-graphics/grounding/PROTOCOL.md。

背景问题：视觉模型在杂乱的全图上回归像素坐标极不可靠（弱视觉模型中心误差约 16–24%，导致高亮环落偏），但在"从编号条带中选择"这种离散任务上却很可靠（配合下述循环约 3–4% 误差）。因此该协议的原则是：永远不要目测坐标，用离散选择完成定位。

路由：若环境变量中恰好存在GEMINI_API_KEY等强检测器，可走auto快速路径（一次调用完成）；绝不假设 key 存在。正常情况下走网格循环（grid loop）：

node grounding/locate.mjs overlay <img> --out /tmp/g → 读取 /tmp/g/gv.png（垂直条带 1-9）与 gh.png（水平条带 1-9）， 判定目标横跨哪些条带（列出它触达的每一条）。 node grounding/locate.mjs region <img> --vids 4,5 --hids 6,7 --out /tmp/g → 读取 /tmp/g/gc.png（裁剪放大后的区域，更细的 6×6 网格），再次选择更细条带。 node grounding/locate.mjs final <img> --region <上一步> --vids 3,4 --hids 3,4 → 产出最终 {box, center}。 node grounding/locate.mjs mark <img> --box <最终 box> --out /tmp/g/check.png → 校验：读取 check.png，红框必须落在目标上；偏了就用修正后的条带重跑。

最后一步mark校验绝不可跳过——它把静默失败转化为一次廉价的单次重试。仓库给出的实测数据是：同一 agent、同一模板、仅定位步骤不同时，目测法平均中心误差 6.5%，协议法降至 2.3%，且没有更差的个案。该协议的消费者是samples/asset-fusion/_ref-circle-highlight.html模板——它直接消费final/auto输出的CFG.box，自动计算径向 wash、琥珀色双描边环、连接线、标注与角落括号准星。如果locate.mjs本身不可用，协议退化路径仅有 5 行：画 9×9 编号网格 → 选条带 → 裁剪（+约 0.4 条带 padding）放大 → 画更细的 6×6 网格 → 再次选择 → 映射回全局坐标 → 画框并目检。

六、优雅降级：能力缺失时的 asset-free 回退

source 阶段是高度依赖外部服务的阶段，因此 guide.md 把"优雅降级"设计为一级公民：

如果某个 provider / 检索不可用，在context.log中把该需求标记为 unmet；类别在可能的情况下回退到 asset-free——例如news类别退化为"不含检索图的排版头条"（typographic headline without the sourced image）。

这条规则在流水线上下文中被多次呼应：

• skills/motion-graphics/SKILL.md 的 Step 2 明确："如果搜索/provider 不可用，类别回退到 asset-free（在context.log中记录）"；
• 其前置条件章节列出了可选 API key 表：GEMINI_API_KEY/GOOGLE_API_KEY用于图像生成（缺失时跳过生成、只走搜索），asset_scout / 搜索 provider 缺失时"类别降级为 asset-free"；
• guide.md 首段即声明：若仓库未安装外部素材检索技能，source 阶段整体降级为 asset-free。

这意味着 source 阶段永远不会让整个流水线卡死——素材采集失败不阻断渲染，而是让后续设计阶段（Director Part 2）在一个"知道手里没有素材"的前提下工作。

七、执行入口与调用形态

guide.md 给出了一条示意性调用命令，展示 source 阶段在项目目录内的实际执行形态：

(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)

要点拆解：

• --plan ./shot-plan.json：传入 Director 产出的素材需求清单；
• --out ./assets：冻结素材的输出目录（同时产出assets/index.md台账）；
• (cd "$PROJECT_DIR" && ...)：这是整个流水线的硬性约束——所有 Bash 命令（主流程与子代理）都必须在$PROJECT_DIR子 shell 中执行，绝不裸用cd（见 skills/motion-graphics/SKILL.md 的 Step 0 约束），避免污染 agent 工作区根目录。

guide.md 同时说明：也可以直接驱动 media-use 的resolve流程（即不经过<SKILL_DIR>/phases/source/resolve.mjs包装层）。此时对应的是 skills/media-use/references/resolve.md 中的类型化调用：--type image|icon|logo|...+--intent+--project，并享受其--candidates/--reuse复用、--adopt批量导入、--local-only离线模式等能力。

八、source 产物如何驱动下游：从台账到镜头设计

source 阶段的产出不是终点，而是 design 与 build 阶段的输入：

1. **Director Part 2（design）**以assets/index.md为依据设计镜头：挑选 catalog block、布局、动效，并针对检索驱动的类别确认最终 category——webpage（网页/UI 动画）、news（头条揭示 + 来源卡片 + 关键事实标注）、tweet（动效推文卡片）或asset-fusion（素材几何变成图表）；
2. Builder（build）按"reuse-first"原则合成：npx hyperframes add <block>+ 就地定制，素材一律引用冻结的项目本地路径，绝不引用远程 URL 或 prompt（见 skills/motion-graphics/agents/builder.md 的 IR → composition 规则）。

以三个检索驱动类别的落地为例：

• news（category module）：真实文章以可读字号排版（绝不放大 zoom），关键词用background-size驱动的 marker band 原地高亮（box-decoration-break: clone让色带跨行连续包裹），并在文本落定之后才扫入——--hlw 0%→100%由 GSAP 补间 CSS 变量；
• tweet：复用 registry 中现成的x-postblock，填入作者/句柄/头像/正文/互动指标，头像与嵌入媒体一律使用冻结的本地文件；
• asset-fusion（category module）：素材在 z0 全幅铺底，数据图形在 z1+ 融合到素材几何上，由element_positions锚定；素材保持可见，连接线与手绘涂鸦把数据"物理地"系在素材上。

从源码结构看，source 阶段的"analyze → search → review → freeze → ledger"五要素（引导文档把 review 与 freeze 合并为第 2 步）与 media-useresolve的实现（manifest 去重 → 本地 assets 扫描 → 全局缓存 → provider 检索 → 冻结 + 注册 + 生成 index + 提升到全局缓存）形成了清晰的两层关系：前者是面向镜头设计的决策层，后者是面向文件系统的执行层。

九、常见问题与实操要点速查

Q1：什么情况下 source 阶段完全不运行？shot-plan.json.asset_needs为空数组时。纯文字/纯代码类别（kinetic-type、多数 charts/stat）天然满足；maps的矢量 lane 也无需素材（D3/TopoJSON 运行时绘制）。

Q2：搜索查询应该怎么写？只允许两极：1–3 词的可组合原子查询，或 5–15 词的具体事件/推文查询；中间地带是被明令禁止的。具体查询失败即丢弃，不放宽。

Q3：素材应该"挑第一个结果"吗？不应该。review 是四步中最难的一步：在候选集中做 use/maybe/reject 三级判定，远程 URL 必须 rehost 到assets/本地冻结。

Q4：provider 不可用怎么办？标记 unmet 到context.log，类别回退到 asset-free（如 news 退化为纯排版头条）。整个 source 阶段在没有任何外部检索技能时整体降级为 asset-free。

Q5：asset-fusion 的几何数据从哪来？永远走 grounding 定位协议 的网格循环（overlay → region → final → mark），不目测坐标；mark校验不可跳过。

Q6：冻结素材的台账长什么样？assets/index.md，格式为role → 冻结路径 + provenance；media-use 侧对应.media/index.md（id · type · 尺寸/时长 · 路径 · 描述表格）。

十、相关资源

• source 阶段指南（本文主体）
• motion-graphics 技能总入口与完整流水线
• media-use resolve 参考（类型、flags、复用、清单）
• media-use resolve 实现
• shot-plan IR（asset_needs 契约与各类别 content 形态）
• Director（Part 1 规划 / Part 2 设计）
• grounding 定位协议（asset-fusion 几何测量）
• asset-fusion 类别模块
• news 类别模块（marker-band 高亮技术）
• tweet 类别模块
• catalog-map（Director → catalog block 复用映射）

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