OpenMontage 网站转视频流水线 Step 6 质量门禁：从 DoD 清单到 w2h-verify 的可量化交付验证实战

OpenMontage 网站转视频流水线 Step 6 质量门禁从 DoD 清单到 w2h-verify 的可量化交付验证实战【免费下载链接】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 开源仓库中 website-to-video 技能的最后一道质量关卡step-6-validate.md展开完整解析Definition of Done交付门禁的每一项检查、w2h-verify验证脚本的底层判定逻辑以及 lint / snapshot / 音频动效 / 评论子代理 / 预览与渲染的完整实操流程。读完你可以掌握一套 Agent 在交付视频前必须逐项执行、不可跳过的可量化验证方法论并能直接复用在任意 website-to-video 项目上。Step 6 在流水线中的位置这是最后一道质量门OpenMontage 的 website-to-video 技能SKILL.md把把一个网站 URL 变成一支品牌视频拆成 7 个步骤每个步骤产出一个工件并作为下一阶段的闸门gateStep 0 Capture用无头 Chrome 截图抓取站点理解品牌与产品step-0-capture.mdStep 1 Brand Identity产出 DESIGN.md 品牌速查表Step 2 Strategy Messaging锁定视频类型、时长、格式、信息与叙事弧Step 3 Storyboard Script产出 STORYBOARD.md SCRIPT.md 并经用户确认Step 4 VO, Timing CaptionsTTS 生成配音、转写、时间轴映射Step 5 Build Compositions构建 index.html 与各 beat 合成Step 6 Validate Deliver本指南的主题 —— lint、validate、snapshot、审查、交付Step 6 是整个流水线的质量出口在用户看到任何东西之前Agent 必须自己先证明视频与分镜一致、与 Step 2 的创意方向和 DESIGN.md 一致。SKILL.md 特别强调即便用户开启 autonomous mode自主模式以下质量验证闸门依然不可跳过逐 beat 的 HTML 通读、DoD 清单含 animation-map、逐条 WCAG 警告验证、音频/动效回放、以及最终摘要中必须出现的 What I did NOT verify诚实披露小节。自主模式覆盖的只是用户偏好类问题TTS 提供商、音色、色彩侧重、beat 数量、是否配乐绝不等于可以跳过验证。Definition of Done预览前的强制检查清单Step 6 的核心规则是在每一项都检查通过之前不得声称视频已就绪、不得给出预览 URL。逐项打分 1–5 分任何一项低于 3 分必须先修复再继续。原文档给出了完整的 DoD 检查清单完整继承如下[ ] Every beat HTML read top-to-bottom → 见下方 Per-beat file read粘贴逐 beat 判定 [ ] Lint: zero errors → 粘贴 lint 输出不是写 lint passed [ ] Snapshot taken, N frames confirmed → 说明确切的帧数 [ ] descriptions.md read in full → 逐字引用 Gemini 描述得最差的那一帧 [ ] Contact sheet viewed cell-by-cell → 对每个 beat 写一句话画面里有什么、什么在动、哪些品牌资产在场 [ ] No mid-video dark frames → 明确说明哪些帧如有是暗的及原因 [ ] Brand assets actually visible → 对每个 beat点名哪张捕获的 SVG / 插图 / 截图在屏幕上、在哪个时间戳。若某 beat 零品牌资产给出理由 [ ] Audio duration matches video ±0.5s → 粘贴两个数值 [ ] animation-map.json generated → 运行 animation-map.mjs确认每个 beat 都有事件列表、无 bbox/flag 警告 [ ] w2h-verify report → 运行 w2h-verify.mjs把完整输出每一行、每一个百分比逐字粘贴进最终用户摘要 [ ] Audio motion verification done → 完整播放预览确认 SFX 落在分镜标注的时间戳 [ ] Critic sub-agent run → 逐字粘贴它给出的最严重质量问题文档反复强调一个纪律不要用总结性印象代替证据。每个 checkbox 都是对工件的一次独立检查要慢下来看每一帧、写下实际观察。视频看起来不错不是证据第 7 帧在 14.2s 处显示 Raycast logo SVG 以 0.85 不透明度画完最后一笔位于 #07080A 背景之上Crush your sprint 标题以 96px Inter SemiBold 落定才是证据。w2h-verify唯一事实来源The Source of TruthDoD 清单中的第十项是整个门禁的核心。这个技能在真实项目中运行了数月Agent 经常看到 REQUIRED 字样却仍然跳过检查w2h-verify脚本存在的意义就是计算 Agent 无法伪造的事实。脚本实现在 .agents/skills/website-to-video/scripts/w2h-verify.mjs是纯文件分析脚本不 spawn 子进程以project-dir为唯一参数node repo-root/skills/website-to-video/scripts/w2h-verify.mjs project-dir在仓库中脚本实际路径为.agents/skills/website-to-video/scripts/w2h-verify.mjs。如果你从项目子目录定位仓库根可用find $HOME -path */skills/website-to-video/scripts/w2h-verify.mjs -maxdepth 10 2/dev/null | head -1脚本判定的 8 项检查与源码逐条对应从源码main()函数可以看到脚本依次执行 8 项检查每项都有明确的阈值常量见源码 L26–L30检查项源码函数判定逻辑捕获的失败模式Required artifactscheckRequiredArtifacts项目根必须存在 STORYBOARD.md、DESIGN.md、SCRIPT.md、index.html工件缺失就宣称交付Brand visuals usedcheckBrandVisualsUsed至少 1 个 beat 引用捕获的hero-*、image-*或svgs/*.svg资产logo 不算9% 资产使用率 / 品牌视觉不在场Headline font-sizecheckPerBeatHeadlineSize逐 beat 最大 CSSfont-size必须 ≥80pxHEADLINE_MIN_PX且只在最大字号 ≥40px 时判定标题太小读不清后续会在 inspect 中暴露为clipped_text错误Timeline coveragecheckPerBeatTimelineCoverage逐 beatGSAP 事件位置必须覆盖 beat 的data-duration的 ≥70%TIMELINE_COVERAGE_MIN网页没被拍下来——入场 tween 结束后画面静止Shader transitionscheckShaderTransitionsConsistencySTORYBOARD.md 中声明的 shader 必须出现在 index.html 中且 HyperShader 运行时必须在场仅作为 SFX 文件名引用不算分镜声明了转场但根本没接入SFX timestampscheckSfxTimestampConsistency分镜tX.Xs与 index.htmldata-startX.X对比多时间戳 SFX 取每个文件最近的时间戳漂移阈值±0.1sSFX 与画面错位Beat durationscheckBeatDurationConsistency分镜中 beat 时间区间如B4 — Name | 16.600 – 21.000s |与 index.htmldata-duration须在±0.5s内分镜过期storyboard stalenessRendered MP4checkMp4Exists仅 INFO 级别检查项目根 / output / renders 下是否存在 .mp4未渲染却声称已验证动效几个值得注意的源码细节品牌资产正则L102–L103刻意排除字体、logo、favicon、apple-touch-icon 文件专门匹配hero-*.jpg、image-*.png、svgs/*.svg这类捕获到的真实品牌视觉。FAIL 时提示语建议打开capture/assets/contact-sheet-*.jpg检查——因为用 CSS 重画一切会抹掉品牌的可辨识度。Timeline coverageL190–L291是八项中最复杂的它会先检测forEach/for循环中动态创建 tween 的模式这类事件静态解析器看不到以及单个时长 ≥ 70% beat 时长的长 tween如运镜、呼吸动画命中则跳过该项检查不算 FAIL算 SKIP对静态事件则用平衡括号扫描提取tl.to/set/fromTo/from/call/add的尾部位置参数避免rgba(...)之类的嵌套括号误匹配。Beat durations的解析有三种回退策略独立行B4 — Name | 16.600 – 21.000s |区间格式 → 子行B3.1 / B3.2求和 → 裸数字表格| 1 | 0.00s | 5.20s | 5.20s |。解析不到的 beat 记为 skipped 而非 FAIL绝不猜测。输出格式printReport是 26 列 Check / 8 列 Status / 60 列 Detail 的表格每行带✓ PASS/✗ FAIL/· INFO符号最后是SUMMARY: N PASS · N FAIL · N INFOFAIL 时附加 Step 6 NOT done 提示。运行顺序、退出码与禁止事项w2h-verify应作为 DoD 检查的最后一道门运行——等所有其他问题修复之后再跑。脚本退出码约定0 全部通过1 至少一项 FAIL2 脚本错误如项目目录不存在。如果带着 exit1 交付用户会从报告里清楚地知道他们拿到的是什么。关于输出文档给出四条严禁手写一份与脚本输出不一致的验证总结挑选性摘取某些行cherry-picking把百分比替换成形容词用了大部分资产而不是8%跑了脚本、看到 FAIL 却闭口不提脚本的输出本身就是交付物。最终用户摘要的 What I verified / What I did NOT verify 小节必须逐字粘贴整个报告——表格、百分比、FAIL 行——用户会直接阅读它你没有资格去总结、简化或删行。若某行 FAIL要么修复后重跑直到 PASS要么把 FAIL 行原样放进 What I did NOT verify 并附一句不修复的理由。Per-beat file read逐文件通读才是验证验证在这个技能里的定义非常具体打开每个compositions/beat-N.html对照 DESIGN.md 和 STORYBOARD.md从头到尾读一遍。Step 5 已经要求过一次Step 6 要作为最终检查重复一次——因为 Step 5 期间的修复可能引入新问题。每个 beat 都要写出结构化判定verdictBeat N (Ns–Ns) — name CSS bg: hex (DESIGN.md says hex, matches: yes/no) CSS accent: hex (DESIGN.md says hex, matches: yes/no) Headline font-size: px (≥80: yes/no) Captured assets referenced: list of paths from img, inline SVG, background-image (storyboard called for: list) GSAP timeline coverage: events from first t to last t, beat duration Ns (full coverage: yes/no) Storyboard alignment: one sentence — does this beat deliver what its STORYBOARD.md section described VERDICT: PASS / NEEDS FIX (what specifically)文档点破了为什么必须如此严格人的自然倾向是看一眼 contact sheet、确认内容在场就宣布完成——那叫对完成信号的模式匹配不叫验证。验证意味着打开子代理产出的每一个文件、读每一行、报告原始结果。旧时代不修复先交付的流程之所以更慢恰恰是因为它捕获了这些问题——不要为了一个绿色对勾而放弃认真观察。Lint Validate Snapshot错误全修警告逐条裁决hyperframes技能Step 5 已加载覆盖 lint、validate、snapshot 的机制细节Step 6 在其之上叠加流水线专属验证。快照数量按视频长度缩放公式为max(beats × 3, ceil(duration_seconds / 2))例如 3 个 beat、10 秒视频max(9, 5) 9 帧8 个 beat、60 秒视频max(24, 30) 30 帧。Errors全部修复。它们是真实问题——时间线注册缺失、脚本损坏、资产缺失。Warnings逐条阅读、自行裁决。有些是必须修的真实质量缺陷GSAP tween 重叠——多个元素争抢同一属性 视觉闪烁未限定作用域的选择器unscoped selectors——打包时会命中所有合成造成数据丢失缺少classclip——元素会在整个视频期间可见而不是只在调度的时间出现根节点缺少data-start——播放根本不会开始有些是可以安全忽略的风格建议文件过大——合成能正常工作只是难读废弃属性data-layer、data-end——仍可用只是不推荐密集轨道dense tracks——纯信息提示不是 bugWCAG 对比度警告逐条验证而非整批驳回验证器在固定时间戳采样文本颜色。处于opacity: 0入场前或淡入淡出中途的元素会被当成完全可见来测量——真实的误报确实存在。但这是逐条警告的判断不是整批原谅的借口。对验证器发出的每一条警告都要粘贴如下判定块Warning N: quote the validator output verbatim Element: selector Sampled timestamp: tn At tn, is this element on-screen at full opacity? (yes/no — confirm by viewing snapshot at that timestamp) Verdict: REAL ISSUE / SAMPLING ARTIFACT (justify in one sentence) Action: hex change at line N OR NONE because reason严禁写这 N 条警告大多是过渡窗口的误报而不提供逐条证据——这句话本身就会让门禁失败。验证器不会把 158 条警告作为一组报告它是一条一条报告的你也必须一条一条验证。不盲目忽略也不盲目修复。Visual Verificationsnapshot亲眼看见自己的输出lint 和 validate 通过后抓取快照帧来看见输出。快照数量要按视频规模缩放公式见上目标至少每个 beat 3 帧入场、驻留、临近退场。命令如下# CLI 会从当前工作目录自动加载 .env所以 project-dir 里放一个 # 含 GEMINI_API_KEY... 的 .env 文件即可无需显式 export。 # 若已在 shell 环境设置 GEMINI_API_KEY同样生效。 npx hyperframes snapshot project-dir --frames N # 向 Gemini 传自定义问题替代默认提示词 npx hyperframes snapshot project-dir --frames N \ --describe Is the brand logo visible in every beat? Is any beat showing a black or blank frame?输出落在project-dir/snapshots/Gemini 会自动写snapshots/descriptions.md。如果 snapshot 后 descriptions.md 缺失或为空说明GEMINI_API_KEY未设置——确认它在project-dir/.envCLI 从 CWD 加载 .env或 shell 环境中修复后重跑。Gemini 真正不可用时的降级方案如果 Gemini 确实不可用无 key、key 无效、配额耗尽使用你自己的图像读取能力直接检查snapshots/中每一帧每帧写一句屏幕内容描述聚焦 Gemini 会捕获的维度空白/暗帧、品牌资产缺失、文字可读性、布局问题。把这些描述存为snapshots/descriptions.md让清单其余部分仍有单一事实来源。但必须在判定中明确声明这些描述是 Agent 撰写而非 Gemini 撰写让用户知道需要抽查。两个预期中的黑帧不是 bugGemini 描述会把以下两帧标记为blank/black这两个是预期行为不是缺陷frame-00-at-0.0s.png—— 始终是暗的动画还没开始视频的最后一帧 —— 始终是暗的s-end 哑场景dummy scene被故意设为不可见其余任何被描述为 black / blank / no visible content / loading screen 的中间帧都是 bug必须调查并修复。两处必读 逐 beat 判定通读snapshots/descriptions.md——Gemini 对每一帧的客观书面分析逐行读不要跳读。逐格查看snapshots/contact-sheet.jpg——不是扫一眼。过往 Agent 在扫一遍就说 contact sheet 没问题之后漏掉过某 beat 在 80% 时长里视觉全黑、logo 放在屏幕外、标题被画布边缘裁切、字幕溢出底部。contact sheet 是这些失败唯一能同时显影的地方。对每个格子写一句话画面里有什么、什么在动、哪些品牌资产在场、哪里看起来不对劲。如果你发现自己想整体总结 contact sheet停下来回去逐格看。读完两处后为每个 beat 写判定Beat 1 (0.0s–4.5s): [what Gemini described] | [what contact sheet shows] | PASS / NEEDS FIX Beat 2 (4.0s–9.5s): ... Beat 3 ... CTA beat: ...一个 beatPASS 必须同时满足Gemini 描述与 STORYBOARD.md 的规划一致contact sheet 显示可见内容不黑、不空白、不是 loading品牌颜色/字体可见无元素被裁切或错位有点内容不会自动通过——要对照规划了什么来比较而不是确实有东西。任一 beat 失败修复 → 重新快照 → 重读 descriptions.md →从头重写该 beat 的判定。修复可能破坏相邻 beat不要沿用旧判定。持续迭代直到每个 beat 通过没有时间上限——一个 CTA beat 是黑的视频不算完成。Critic Sub-Agent不可跳过的独立评审逐 beat 判定全部通过后、开始预览之前必须启动一个评论子代理使用文档给出的逐字提示词原文档 L188–L210。该子代理扮演资深动效设计师 创意总监需要读取 STORYBOARD.md规划、DESIGN.md品牌规则、snapshots/descriptions.mdGemini 所见、snapshots/contact-sheet.jpg视觉证据并按 6 个维度打分 1–5Beat execution每个 beat 是否兑现了 STORYBOARD.md 的规划点名欠交付的 beat 和具体问题Brand accuracy这是为这个品牌量身定做的还是任何公司都能用各点名一个独特品牌元素和一个通用元素Captured asset utilization用户把真实 SVG logo、hero 插图和截图捕获进了capture/assets/它们上屏了吗还是 Agent 用 div 和 CSS 重画了一切列出哪些捕获资产出现在哪些 beat缺失的要标记——全 CSS 重画 通用、无品牌感Visual quality空帧、文字裁切、居中失败、隐形元素引用确切帧时间戳Motion design动画是有意为之还是默认机械点名最弱的转场及原因CTA beat最后一拍是否清晰、居中、可读、驻留足够久描述 CTA 帧上实际可见的内容子代理必须以交付前最该修的一件事是什么——点名 beat、元素、具体改动结尾且提示词明确警告如果你找不到任何问题、想全给 4–5 分那是你没认真看再看一遍。主 Agent 必须阅读每个分数低于 3 分的一律修复再展示给用户——CTA 低于 3 分就修 CTA不允许用让用户自己决定来合理化低分。Audio Motion 验证三条路径必须选一条快照是无声的静帧。30 秒 30fps 视频的 18 张 PNG 快照 18/900 ≈ 2% 的帧其余 98%——所有动效、所有转场、所有音频——靠快照是验证不到的。已通过快照确认不是覆盖率。声明完成前必须执行以下三条路径之一路径 1首选播放预览通过 Playwright或其它浏览器工具打开 Studio URL以 1.0× 速度从头到尾完整播放不是拖拽确认[ ] 全片以 1.0× 从头到尾真实播放不是 scrubbed [ ] STORYBOARD.md 中每个 SFX 都在视觉时刻 ±0.1s 内落点 (Beat N SFX file: storyboard says txs → heard at tys → drift zs) [ ] 旁白逐 beat 对应正确无错位或漏句 [ ] 无有音频但画面意外处于转场中的时刻 [ ] 音频可闻且未削波/爆音路径 2渲染低清 MP4 逐帧阅读Playwright 不可用时渲染 540p很快——30 秒视频约 30 秒node /repo-root/packages/cli/dist/cli.js render project-dir \ --width 960 --height 540 --quality medium然后以至少 5fps采样 MP4必要时ffmpeg -i mp4 -r 5 frames/frame-%04d.png顺序阅读这些帧。对 STORYBOARD.md 中每个 SFX 时刻找到对应帧并确认视觉匹配。路径 3最后手段显式延后披露 量化缺口两条路径在本会话都不可能时最终摘要必须逐字包含**Audio motion verification: NOT POSSIBLE in this session.** - Snapshots cover: N frames out of video_duration × fps total (percentage% coverage) - NOT verified: motion between snapshots, SFX/visual timing alignment, shader transition smoothness, audio mix levels, narration sync to beats - Recommended user action: open the preview URL above and play start-to-end; flag anything that feels off任何地方都严禁用 Confirmed via snapshot / snapshots look right 充当音频/动效证据Preview is running, looks good 而没有真正播放过路径 3 披露省略量化覆盖缺口百分比是强制的Preview始终启动预览交付 Studio URL无论走哪条验证路径都要启动预览让用户查看和拖拽浏览npx hyperframes previewStudio URL 才是交付物最终回复中必须包含http://localhost:port/#project/project-name端口和项目名取自 preview 命令的实际输出。不要把 index.html 当作项目链接——那是源文件对用户可见的项目是运行中的 Studio 预览。SKILL.md 还提醒这个 Studio URL 只在交接时刻给出——它是最终稳定的预览构建阶段的快照是无头的不要在构建中途弹出预览。诚实披露Honest Disclosure最终摘要的强制结尾即使一切通过最终消息也必须以以下两个小节结尾位置在预览 URL 之后、停止说话之前**What I verified:** - 每项通过的 DoD 条目一个 bullet内联引用实际证据 (e.g. Lint: zero errors — output pasted above) (e.g. Per-beat read: 7/7 beats PASS, evidence blocks above) (e.g. WCAG: 3 warnings flagged, all 3 verified as sampling artifacts — see verdicts above) **What I did NOT verify (spot-check these):** - 每项跳过/延后/无法完成的条目一个 bullet并说明原因 (e.g. Audio motion verification deferred — no Playwright in this session. SFX timing is computed but unconfirmed in playback.) (e.g. animation-map.json skipped — script not found at expected path; manually confirmed timeline coverage in per-beat reads instead.) (e.g. Beat 5 has a 0.4s window where the doc card is visible but contents are still opacity 0 — sub-agent flagged it, I chose not to fix because it was below my threshold; worth your eye.)用户靠这一节知道该抽查什么。不可接受的最终摘要只说Looks great, ready to ship无披露All checks pass实际跳过了某项Sub-agents confirmed everything把信任外包而不验证因为恰好全验证了就省略 What I did NOT verify 小节全部通过也要保留标题写 None 即可。文档的态度很明确在这里说谎或省略比诚实跳过某项检查更糟——一次简短的用户抽查永远好过一部藏着坏点的视频。Render按需渲染绝不自动不要自动渲染。预览即交付——用户拖拽浏览、发现微调点、你迭代。每次渲染都要花几分钟如果用户要改就白费了。只有用户明确要求——render it、make the final、export the MP4、Im happy, produce the file——才渲染。渲染时必须显式指定质量与分辨率不要默默使用默认值# 标准质量1080p 横屏多数视频的默认 npx hyperframes render --skillwebsite-to-video --output renders/name.mp4 --quality standard --fps 30 # 最终交付的高质量 npx hyperframes render --skillwebsite-to-video --output renders/name.mp4 --quality high --fps 30 # Instagram Stories / TikTok 竖屏 npx hyperframes render --skillwebsite-to-video --output renders/name.mp4 --quality standard --fps 30 --resolution portrait # 4K 高端输出 npx hyperframes render --skillwebsite-to-video --output renders/name.mp4 --quality high --fps 30 --resolution 4k可用选项完整继承如下FlagValuesNotes--qualitydraft,standard,highdraft 快/低质standard 均衡high 慢/最好--fps24,30,6030 是标准24 有电影感60 动作更顺滑--resolutionlandscape(1920×1080),portrait(1080×1920),landscape-4k(3840×2160),portrait-4k别名1080p、4k、uhd--formatmp4,webm,mov,png-sequencemp4 默认。mov/webm 用于透明通道。png-sequence 用于 AE/Nuke--outputpath始终设为renders/project-name.mp4以便命名可读--gpuflag可用时使用 GPU 编码更快--crfinteger覆盖编码器质量越低越好与--video-bitrate互斥--video-bitrate如10M目标码率与--crf互斥同时要告诉用户你在渲染什么、为什么以标准质量、1080p 横屏、30fps 渲染——这能在合理渲染时间下给出不错的质量。要改用 high 或 4K 吗小结把交付质量变成可验证的工程纪律回顾整个 Step 6其方法论可以浓缩为四句话证据代替印象每项 DoD 粘贴原始输出而非总结、脚本代替记忆w2h-verify 计算 Agent 无法伪造的事实SUMMARY行与 exit code 就是交付契约、逐条代替整批每条 lint 警告、每个 WCAG 警告单独裁决、披露代替隐瞒What I did NOT verify 是强制小节宁可诚实跳过也不说谎。这套流程与 animation-map.mjs逐 tween 枚举、bbox 采样、产出 animation-map.json 供 DoD 校验和 w2h-verify.mjs 构成完整的质量证据链——它解决的不是能不能做出视频而是Agent 如何证明自己交付了一支自己愿意署名发布的视频。【免费下载链接】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），仅供参考