OpenMontage HyperFrames 正确性检查流水线lint、validate、inspect 与 snapshot 全解【免费下载链接】OpenMontageWorlds 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就是lintvalidate两条静态门。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. validateheadless 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:124px 及以上或 19px 以上加粗。文档给出的修复纪律很具体深色背景上把失败的颜色提亮直到越过阈值浅色背景上则调暗保持在调色板族内——不要发明新颜色只调整现有颜色反复运行validate直到干净。文档还给出两条战术建议动画涉及脚本、数据拉取或主题切换时先validate再inspectCI 中把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_latebefore(a, b)a的首次出现不严格早于b——motion_out_of_orderstaysInFrame(selector)元素一旦可见后其盒子离开画布 ——motion_off_framekeepsMoving(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">【免费下载链接】OpenMontageWorlds 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），仅供参考
OpenMontage HyperFrames 正确性检查流水线lint、validate、inspect 与 snapshot 全解【免费下载链接】OpenMontageWorlds 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就是lintvalidate两条静态门。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. validateheadless 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:124px 及以上或 19px 以上加粗。文档给出的修复纪律很具体深色背景上把失败的颜色提亮直到越过阈值浅色背景上则调暗保持在调色板族内——不要发明新颜色只调整现有颜色反复运行validate直到干净。文档还给出两条战术建议动画涉及脚本、数据拉取或主题切换时先validate再inspectCI 中把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_latebefore(a, b)a的首次出现不严格早于b——motion_out_of_orderstaysInFrame(selector)元素一旦可见后其盒子离开画布 ——motion_off_framekeepsMoving(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">【免费下载链接】OpenMontageWorlds 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），仅供参考
