OpenMontage HyperFrames 正确性检查流水线：lint、validate、inspect 与 snapshot 全解-港品优选

OpenMontage HyperFrames 正确性检查流水线：lint、validate、inspect 与 snapshot 全解

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

本文基于 OpenMontage 仓库中 vendored 的hyperframes-cli技能参考文档 lint-validate-inspect.md 展开。HyperFrames 是 OpenMontage 双渲染运行时之一（另一个是 Remotion，参见 .agents/skills/hyperframes/PROVENANCE.md），其 CLI 的lint→validate→inspect→snapshot四件套构成了动效合成物的"正确性流水线"。读完后你将掌握：如何在预览/渲染前用四层检查逐步拦截静态错误、运行时故障、布局溢出与动效意图偏差，以及如何用*.motion.jsonsidecar 把"渲染 MP4 后逐帧看"这一人工环节自动化。

1. 四个命令的定位与执行顺序

文档开宗明义：这是the correctness pipeline（正确性流水线），标准执行顺序为：

lint—— 静态、快速，不依赖浏览器；
validate—— 运行时检查，用 headless Chrome 真实加载并播放合成物；
inspect—— 布局扫描（layout sweep），在时间轴上逐点采样检测溢出；
snapshot—— 独立的抓帧工具，捕获 PNG 静帧，不属于前三者链。

这一顺序在 hyperframes-cli 主技能文档的 Workflow 中同样被强调："Run lint, validate, and inspect before preview"，且 render 之前的最小完成门槛（Minimum Completion Gate）就是lint+validate两条静态门。

1.1 动效密集型项目的检查纪律（Discipline）

原文档专设一节规范"motion-heavy work"的工作纪律，这些规则针对的是纯动效驱动的合成物——当时间轴上几乎每一帧都在变化时，人工盯预览的效率很低，必须把检查前置：

lint要在第一遍 HTML 写完就跑，宁早勿晚；
在有意义的时间轴状态上抓snapshot，并且要真的去看那些 PNG；
先看快照，再调自动化警告——人眼能发现审计器漏掉的问题；
布局警告应视为缺陷，除非快照能证明溢出是刻意的，此时用data-layout-allow-overflow显式标记；
用*.motion.jsonsidecar 声明动效意图，让inspect自动检查（入场是否触发、stagger 顺序、是否在画框内、是否有活性）。文档称之为"render-≠-preview bug 的最接近自动化的代理"——它能抓到人眼会漏的、预览正常但渲染出错的偏差（详见第 4 节）。

2. lint：静态快速检查

npx hyperframes lint # 检查当前目录 npx hyperframes lint ./my-project # 检查指定项目 npx hyperframes lint --verbose # 输出 info 级别发现 npx hyperframes lint --json # 机器可读输出

lint会扫描index.html以及compositions/目录下的所有文件，产出三级发现：error（必须修）、warning（应当修）、info（仅--verbose时展示）。它能抓到的典型问题包括：

缺失data-composition-id；
同一data-track-index上的轨道重叠（overlapping tracks）；
未注册的 timeline。

HyperFrames 合成物用 HTML 属性描述时间轴（data-start、data-duration、data-track-index、data-composition-id等），这些data-*契约在 hyperframes-core 技能的>grep -nE '<(video|audio)\b' compositions/*.html # 期望：无任何匹配

非空结果即缺陷。随后对每个含视频的 scene 执行snapshot，确认面板里真的在播画面——"应该出画面的位置出现空白/黑块是 bug，不是占位符，应视为阻塞渲染（render-blocking）"。这一手动 grep + 快照核实的组合拳，是文档给出的在 lint 规则落地之前的临时对策。

3. validate：headless Chrome 运行时检查

npx hyperframes validate # 当前目录 npx hyperframes validate ./my-project # 指定项目 npx hyperframes validate --json # agent 可读的发现 npx hyperframes validate --timeout 5000 # 等待脚本完成的毫秒数（默认 3000） npx hyperframes validate --no-contrast # 迭代期跳过 WCAG 对比度审计

静态 lint 快但对运行时故障是"盲"的。validate会把合成物加载进 headless Chrome 并完整播放一遍，报告三类问题：

JavaScript console 错误与未捕获异常；
失败的网络请求（媒体文件的ERR_ABORTED已被过滤，不算数）;
可见文本的WCAG AA 对比度违规——在时间轴上的5 个时间点采样检测；迭代频繁时可用--no-contrast跳过。

3.1 对比度警告的修复方法

阈值：常规文本 4.5:1，大文本 3:1（24px 及以上，或 19px 以上加粗）。文档给出的修复纪律很具体：

深色背景上把失败的颜色提亮直到越过阈值；浅色背景上则调暗；
保持在调色板族内——不要发明新颜色，只调整现有颜色；
反复运行validate直到干净。

文档还给出两条战术建议：动画涉及脚本、数据拉取或主题切换时，先validate再inspect；CI 中把validate与render --strict组合使用（--strict让 lint error 直接失败，--strict-all连 warning 也失败，详见 hyperframes-cli SKILL.md 的 Agent Conventions 一节）。

4. inspect：时间轴布局扫描与动效意图验证

npx hyperframes inspect # 沿时间轴检查渲染后布局 npx hyperframes inspect ./my-project # 指定项目 npx hyperframes inspect --json # agent 可读（含 schemaVersion、samples、issues、bboxes） npx hyperframes inspect --samples 15 # 更密的时间轴扫描（默认 9 个采样点） npx hyperframes inspect --at 1.5,4,7.25 # 显式指定关键帧时间戳 npx hyperframes inspect --tolerance 4 # 报告前允许的溢出像素（默认 2） npx hyperframes inspect --strict # warning 也非零退出（默认仅 error 退出非零）

inspect的定位是在lint和validate之后运行，尤其适合带对话气泡、卡片、字幕或紧凑排版的合成物。它报告四类布局缺陷：

文本伸出最近的视觉容器或气泡之外；
文本被自己的固定宽/高盒子裁切；
文本伸出合成物画布；
子元素逃逸出裁剪容器。

error 必须在渲染前修复；warning 交给 agent 人工复核，加--strict后 warning 也会导致非零退出。重复出现的静态问题默认会折叠，使--json输出保持紧凑——这一点在 SKILL.md 中被解释为"为 LLM 上下文窗口留空间"，可见该命令的 JSON 输出是明确面向 Agent 消费的。

4.1 逃生舱口（Escape hatches）及其副作用

文档列出两个显式豁免属性：

data-layout-allow-overflow—— 当溢出是入场/退场动画的刻意设计时，标记该元素或其祖先；
data-layout-ignore—— 标记永不参与审计的装饰性元素。

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

四种断言与失败码：

断言	何时失败（错误码）
`appearsBy(selector, bySec)`	`bySec`时刻仍未可见（opacity ≥ 0.5 才算可见）——`motion_appears_late`
`before(a, b)`	`a`的首次出现不严格早于`b`——`motion_out_of_order`
`staysInFrame(selector)`	元素一旦可见后，其盒子离开画布 ——`motion_off_frame`
`keepsMoving(withinSelector?)`	存在超过`maxStaticSec`（默认 2s）的完全静止窗口 ——`motion_frozen`

关键语义补充：

duration、withinSelector、maxStaticSec均为可选字段；
发现默认按 error 处理——一条失败断言会让整次运行失败，与布局 error 同级（--strict仍然只管 warning 闸门）；
发现结果与布局发现走同一套人类可读和--json输出通道；
选择器匹配不到任何元素时报告motion_selector_missing，而不是静默通过——写错的选择器会响亮地失败。

文档最后给出使用姿态：把它放进反馈循环，替代肉眼盯渲染——"断言动效应该做什么，让inspect告诉你 seek 何时偏离了意图"。

5. snapshot：静帧捕获与子合成的视觉冒烟测试

npx hyperframes snapshot # 捕获 5 个关键帧为 PNG npx hyperframes snapshot ./my-project # 指定项目 npx hyperframes snapshot --frames 10 # 等距采样 N 帧

snapshot从合成物捕获 PNG 静帧，用于视觉 diff、缩略图或附到 PR 上；只需几张关键帧时，它比渲染整段视频快得多。输出落在项目的 snapshots 目录，文件命名为snapshots/frame-NN-at-Xs.png。

hyperframes-cli SKILL.md 的"Minimum Completion Gate"一节进一步解释了snapshot在检查体系中的不可替代性：lint/validate/inspect都是逐个隔离评估每个合成物的，它们从不加载index.html去通过data-composition-src挂载子合成，因此抓不到跨文件挂载失败。唯一能抓到这类问题的门，是真正加载index.html并 seek 时间轴的检查——而snapshot恰好以与render相同的方式加载项目（走同一条挂载路径），却只捕获你要求的时间戳，几秒钟而不是完整渲染。

推荐的用法（子合成项目的视觉冒烟测试）：

# 在每个子合成的中点各抓一帧：中点 = index.html 各宿主槽位的 contenteditable="false">【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析