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

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 个阶段阶段执行方式主要产物initBashhyperframes.jsonplan子代理shot-plan.json草案category、asset_needs查询、briefsource ◇Bash — media-use resolveassets/assets/index.mddesign子代理shot-plan.json最终block、layout、motion、positionsbuild子代理compositions/index.htmlverifyBashsnapshots/contact-sheet.jpgapprove询问用户显式渲染批准renderBashrenders/video.mp4或透明叠加层其中 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_needssource 阶段的唯一输入是 DirectorPart 1plan 阶段产出的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 2source继续。三、按素材类型分派的检索策略guide.md 把asset_needs按kind分成两大阵营各自走完全不同的获取路径3.1 视觉素材image / icon / logo / svg→ media-useresolve对于图片、图标、Logo 与 SVGsource 阶段直接驱动 media-use 的resolve流程三种来源按需选择search搜索通过 asset_scoutGoogle Images / SerpAPI与 Noun Project 检索generate生成调用图像生成模型user-supplied用户提供Logo 类素材通常直接由用户给出。可选的treatment后处理包括cutout去背景、recolor重着色与vectorize矢量化。这里包装的底层命令是 media-use 的 resolve 入口脚本其完整用法记录在 skills/media-use/references/resolve.mdnode 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极点词数用途示例atomic原子查询1–3 词可组合的通用元素肖像、Logo、物体rocket、portrait CEOspecific具体查询5–15 词一个具体新闻事件 / 一条具体推文SpaceX starship flight 4 launch date永远不要落在两极之间的模糊地带——这是从搜索实践中总结出的铁律在 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依次执行analyze分析理解需求本质——这张素材在镜头里扮演什么角色search检索按 3.1 / 3.2 的策略获取候选review评审在候选集中做出 use / maybe / reject 三级判定。guide.md 特别强调选择是最难的部分不要直接采用第一个或生成出来的结果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.mp4media-use 侧对应的清单式产物是.media/index.md见 skills/media-use/references/resolve.md两者结构一致每行一条id · type · 尺寸/时长 · 路径 · 描述。步骤 4asset-fusion 专属测量几何 吸取色板当类别为asset-fusion真实素材的几何形状变成图表时source 阶段还需要额外捕获两类信息供 Director Part 2 设置element_positions可测量的几何measurable geometry素材中关键特征的 center / extent / safe-zones / avoid-zoneseyedropper 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 loopnode 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-freeguide.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 阶段的输入**Director Part 2design**以assets/index.md为依据设计镜头挑选 catalog block、布局、动效并针对检索驱动的类别确认最终 category——webpage网页/UI 动画、news头条揭示 来源卡片 关键事实标注、tweet动效推文卡片或asset-fusion素材几何变成图表Builderbuild按reuse-first原则合成npx hyperframes add block 就地定制素材一律引用冻结的项目本地路径绝不引用远程 URL 或 prompt见 skills/motion-graphics/agents/builder.md 的 IR → composition 规则。以三个检索驱动类别的落地为例newscategory module真实文章以可读字号排版绝不放大 zoom关键词用background-size驱动的 marker band 原地高亮box-decoration-break: clone让色带跨行连续包裹并在文本落定之后才扫入——--hlw 0%→100%由 GSAP 补间 CSS 变量tweet复用 registry 中现成的x-postblock填入作者/句柄/头像/正文/互动指标头像与嵌入媒体一律使用冻结的本地文件asset-fusioncategory 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/本地冻结。Q4provider 不可用怎么办标记 unmet 到context.log类别回退到 asset-free如 news 退化为纯排版头条。整个 source 阶段在没有任何外部检索技能时整体降级为 asset-free。Q5asset-fusion 的几何数据从哪来永远走 grounding 定位协议 的网格循环overlay → region → final → mark不目测坐标mark校验不可跳过。Q6冻结素材的台账长什么样assets/index.md格式为role → 冻结路径 provenancemedia-use 侧对应.media/index.mdid · type · 尺寸/时长 · 路径 · 描述表格。十、相关资源source 阶段指南本文主体motion-graphics 技能总入口与完整流水线media-use resolve 参考类型、flags、复用、清单media-use resolve 实现shot-plan IRasset_needs 契约与各类别 content 形态DirectorPart 1 规划 / Part 2 设计grounding 定位协议asset-fusion 几何测量asset-fusion 类别模块news 类别模块marker-band 高亮技术tweet 类别模块catalog-mapDirector → catalog block 复用映射【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考