企业官网建设流程全解析

HyperFrames Finalize 修复子代理：快照质检、就地修复与升级判定实战指南

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

本文围绕 HyperFrames 运动图形工作流（motion-graphics）中的最终质检与修复环节展开，完整解读 Finalize / repair 子代理（skills/motion-graphics/agents/finalize.md）的调度上下文、三步执行流程与 STOP/升级判定规则，并结合 CLI 的lint/check/snapshot命令族（skills/hyperframes-cli/references/lint-validate-inspect.md）与 Builder 契约（skills/motion-graphics/references/builder-contract.md）给出可落地的操作细节。读完本文，你将掌握：何时触发 Finalize、如何用证明快照定位画面缺陷、如何在不改动data-duration的前提下做一次就地修复、以及什么情况下必须升级而不是强行修补。

Finalize 在整个工作流中的位置

HyperFrames 的 motion-graphics 工作流是一条自主设计的多阶段流水线：初始化（Step 0）→ 规划（Step 1，Director Part 1）→ 素材源（Step 2，条件执行）→ 设计（Step 3，Director Part 2）→ 构建（Step 4，Builder）→ 验证（Step 5）→ 审批与渲染（Step 6）。

Finalize / repair 子代理位于Step 5 验证阶段的失败分支上。根据 SKILL.md 的 Step 5 定义，验证阶段依次执行三个门禁：

(cd "$PROJECT_DIR" && npx hyperframes lint .) (cd "$PROJECT_DIR" && npx hyperframes check .) (cd "$PROJECT_DIR" && npx hyperframes snapshot --at <proof-times>)

只有当 Step 5 的lint、check或快照审阅报告了缺陷时，编排器（orchestrator）才会分派 Finalize 子代理。其职责边界清晰：

• 执行快照质检与一次就地修复（in-place repair）；
• 不渲染——渲染与最终审批始终由编排器持有；
• 修复后返回结果给编排器，由编排器重跑失败的门禁。

从源码结构看，这种"验证失败 → 单一修复子代理 → 重跑门禁"的设计，是把"质检-修复"从"构建-渲染"中彻底解耦：Builder 只负责产出compositions/index.html，Finalize 只负责让它通过门禁，渲染权永远留在编排器手中，从而保证任何一次渲染都经过同一套审批闸门。

调度上下文（Dispatch context）

编排器分派 Finalize 时，会传入以下上下文：

• SKILL_DIR（当前技能目录，用于定位参考文档与脚本）；
• PROJECT_DIR（项目目录，即videos/<project-name>/）；
• proof snapshot times（证明快照时间点）；
• lint与check的输出尾部（output tails，存在时传入）。

这个上下文的用意是让 Finalize 无需重新探索项目即可直接定位问题：快照时间点指明"看哪些帧"，lint/check 输出指明"自动化门禁报告了哪些缺陷"。在 lint-validate-inspect.md 中，check的每个发现都携带选择器、元素的data-*身份、来源文件、包围盒（bbox）与采样时间，因此从 JSON 输出可以直接跳转到需要编辑的 HTML 行——这正是 Finalize 能在一次修复内完成工作的前提。

三步执行流程（Flow）

Finalize 的流程严格限定为三步：快照 → 一次就地修复 → 复检。

第一步：快照质检（Snapshots）

运行证明快照命令，检查指定的时间点画面：

npx hyperframes snapshot --at <proof-times>

proof-times应覆盖三个关键瞬间——开场状态、标志性动作、最终定格（opening state, signature move, final hold），这是 SKILL.md Step 5 对证明时间点的明确要求。例如一个 6 秒的作品可以传--at 0.3,2.5,5.8。

snapshot命令是独立的静止帧捕获工具，比渲染整段视频更快，专为视觉对比、缩略图或 PR 附图设计（详见 lint-validate-inspect.md）：

npx hyperframes snapshot # 默认 5 个关键帧 PNG npx hyperframes snapshot ./my-project # 指定项目 npx hyperframes snapshot --frames 10 # 均匀取 N 帧

快照输出落在项目的snapshots/目录（motion-graphics 项目最终生成snapshots/contact-sheet.jpg联系单）。检查快照时要逐项审阅以下典型缺陷：

• 溢出（overflow）：文本或元素超出容器或画布边界；
• 画布外内容（off-canvas content）：元素被动画带到画布外；
• 文本碰撞（text collisions）：两个文本块在定格时重叠遮挡；
• 空帧（empty frames）：某个采样时间点画布近乎空白；
• 错误内容（wrong content）：文案、数据或素材与 shot-plan 不符；
• 不可读的动效（unreadable motion）：动效过快、被裁剪或时序错乱导致信息不可读。

如需放大某个具体缺陷，可以使用快照的缩放能力（独立于check --snapshots的 finding 裁剪）：

npx hyperframes snapshot --zoom "#cta" # 用 CSS 选择器裁出元素，3x 高密度 npx hyperframes snapshot --zoom "100,50,400,300" --zoom-scale 2 # 或精确像素区域

--zoom通过提高deviceScaleFactor实现真正的高密度裁剪，而不是 CSS 缩放或视口调整，因此不会影响构图的布局与渲染确定性；选择器未命中会报错，目标帧元素不可见时会跳过并给出说明，而不是静默产出残片。

第二步：一次就地修复（One in-place repair pass）

针对快照中可见的问题，编辑compositions/index.html进行修复。Finalize 的修复哲学是就地、最小化、不动时基：

• 只修可见问题：对准快照/门禁指出的具体元素；
• 绝不修改固定的data-duration：时基（timing）在更上游已确定（由 Director/Builder 依据 shot-plan 设定），用改时长来掩盖缺陷属于被明令禁止的行为。这与 builder-contract.md 的 Builder 交接条款一致："When redispatched with a finding, fix the offending element and never change a fixeddata-durationduring repair."

修复时应遵循 Builder 契约的纠错规范（builder-contract.md）：

• 根节点必须有确定尺寸：#stage需要position: relative; width: <W>px; height: <H>px，否则 flex 子元素塌陷为 0，内容堆在左上角——自动化门禁可能漏掉它，所以必须结合证明快照人工确认；
• 内容容器用 flex + padding，禁止绝对定位偏移：position:absolute; top:Npx会造成溢出，保留 ≥80px 的 title-safe 内边距；
• 延迟元素要做 seek-safe 的显式fromTo()：用{ autoAlpha: 0 }起始、{ autoAlpha: 1, ... }结束，不要在页面加载时gsap.set()后续.clip，也不要直接控制.clip的可见性（其生命周期归框架所有）；
• 计数动画必须用 proxy +onUpdate，绝不能用墙钟计数器，且渲染宿主必须以启用事件的方式 seek（tl.time()/ 非抑制 seek），否则计数会冻结在 0；
• tween 边界要收敛：在保持值处截断，不允许弹簧过冲越过保持值；
• 调色板纪律：所有颜色集中在 palette 对象 / CSS 自定义属性中，禁止散落内联十六进制色值；
• 意图性溢出需显式声明：确属有意的布局行为应标记data-layout-allow-overflow="true"等转义属性（详见下文"转义阀门"），而不是靠巧合通过检查。

第三步：复检（Recheck）

修复完成后，重跑全部相关门禁，然后把结果返回编排器：

npx hyperframes lint npx hyperframes check npx hyperframes snapshot --at <受影响的时间点>

其中check是最终门禁（内部会先重跑 lint，因此无需在check前冗余再跑一次独立 lint）：

npx hyperframes check # 完整浏览器门禁 npx hyperframes check --json # agent 可读的 {ok, lint, runtime, layout, motion, contrast, snapshots} npx hyperframes check --snapshots # 同时写出标注过 finding 的概览帧 + 逐 finding 裁剪 npx hyperframes check --at 1.5,4,7.25 # 显式 hero-frame 时间戳

一次check只启动一次 Chrome，先跑 lint（lint 有错则直接跳过浏览器），再以一次 seek 网格对每个采样点执行四类审计：

• Runtime：JS 控制台错误、未处理异常、失败的网络请求（过滤掉媒体文件的ERR_ABORTED）、HTTP 4xx/5xx；
• Layout：文本伸出容器/画布、文本被自身盒裁剪、持久的文本重叠与遮挡、子元素逃逸裁剪容器；
• Motion：*.motion.json副作用文件断言（见下文）；
• Contrast：对可见文本做 WCAG AA 对比度采样（普通文本 4.5:1，大文本 3:1 或 19px+ 粗体 3:1），失败即 error，且给出建议合规色。

复检完成后，Finalize 返回结果给编排器，由编排器决定是否重新分派、审批或渲染——Finalize 自身不渲染。

严重性判定与转义阀门

check的严重性是持久性感知的：只在单个采样点出现的动态问题（如入场/退场瞬态）降级为 info 且不阻断；跨采样点持续的问题才会阻断退出码。例如持续的content_overlap是 error，持续且超出画布 ≥5% 的canvas_overflow会升级为 warning；3 秒以上构图在所有采样点都无几何变化时，check会以sweep_static失败——冻结的时序会让一切绿色结论失效，所以门禁拒绝放行。

Finalize 修复时若确认"自动化误报 / 布局有意为之"，应使用转义阀门在 HTML 中显式声明意图，而不是删除元素：

其中data-layout-allow-overlap必须标记具体的叠层参与方，绝不能在 scene/root 包装器上滥用，否则无关后代的碰撞也会被静默。

Motion 断言：把"动效意图"变成可复检的事实

对于动效驱动的运动图形，"看一眼 MP4"无法自动化，但*.motion.json副作用文件可以让check在同一根 seek 时序上自动验证动效意图——这是"渲染后再看"最接近的自动化代理，能抓住布局采样抓不到的渲染-预览不一致（如入场揭示被 seek 跳过、stagger 顺序错乱、元素中途漂出画布、画面冻结）。修复后重跑时，把这些断言放进 sidecar（与 html 同名放置，check自动发现，无需 flag）：

{ "duration": 6, "assertions": [ { "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 }, { "kind": "before", "a": "#headline", "b": "#cta" }, { "kind": "staysInFrame", "selector": ".card" }, { "kind": "keepsMoving", "withinSelector": ".scene" } ] }

断言失败码分别对应：motion_appears_late（超过bySec才可见）、motion_out_of_order（顺序错乱）、motion_off_frame（可见后出画布）、motion_frozen（静止窗口超过默认 2s 的maxStaticSec）；选择器未命中会以motion_selector_missing响亮失败，绝不会静默通过。对 Finalize 而言，这相当于把"修复后动效是否恢复正确"变成一条可重跑、可引用的客观事实。

STOP / 升级（Escalate）规则

Finalize 不是万能的修补工，其边界由升级规则硬性划定：

• 仅当镜头"根本性错误"时升级——例如整体内容错误、需要重新构图（recomposition）——此时不得靠堆编辑硬修，而是返回 Step 3/4（重新设计与重建），把问题交还给 Director 与 Builder；
• 小问题绝不升级：文本溢出、轻微碰撞、单个元素位置、对比度等可见小缺陷，一律在 Finalize 内就地修复。

这条规则的工程意义在于：避免在错误的地基上做昂贵的装修。如果 shot-plan 本身选错了块（block）、布局或动效方向，Finalize 层的逐元素修补不仅低效，还可能把data-duration或时序拖向不可维护的状态。修复是战术动作，重构是战略回退——Finalize 只做前者。

与整体流水线的衔接

在 production-loop.md 的生产循环中，Verify 阶段以lint、check通过 +snapshot --at <frame-midpoints>联系单审阅为交付条件，Deliver 阶段则在审批后render。Finalize 正是夹在两者之间的修复闸门：它让"验证失败"成为一个可收敛、有边界、不越权的子流程，确保最终进入渲染的任何构图都经过"自动化门禁 + 人工快照审阅"的双重确认。

一次典型的 Finalize 会话可以概括为：读取 dispatch context →snapshot --at定位可见缺陷 → 就地修改compositions/index.html（绝不改data-duration）→ 重跑lint/check/ 受影响快照 → 返回结果给编排器。若发现镜头根本性错误，则立即升级回设计与构建阶段，而不是继续堆砌小修补。

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