实战指南:场景发明、Design Truth 与 motion 侧车输出契约)
HyperFrames general-video 帧工作器Frame Worker实战指南场景发明、Design Truth 与 motion 侧车输出契约【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes导读本文讲解 HyperFrames 开源项目中 general-video 工作流的帧工作器frame worker角色——它是多场景叙事视频生产管线中负责一个场景一个文件的并行子代理。文章以 skills/general-video/sub-agents/frame-worker.md 这份角色增量delta为主干完整还原其输入边界、设计真源design truth解析规则、双文件输出契约与职责边界并结合 skills/general-video/scripts/frame-packets.mjs、skills/hyperframes-core/scripts/lib/frame-packets-core.mjs 等源码与测试讲清packet 从哪来、_role.md 如何拼接、motion 侧车如何被下游校验。读完你既能照此规范编写或审查自己的场景合成也能理解 HyperFrames 并行生产管线的分层设计。一、角色定位core contract delta 的双层契约general-video 的帧工作器不是一个独立的完整角色而是两个文档拼接成一个_role.md运行core contract共享主体skills/hyperframes-core/references/frame-worker-core.md——所有叙事视频工作流共用的法律负责通用规则子合成形态、时间线注册、clip 属性、确定性渲染、根节点尺寸等与工作流无关的规则只写在这里一次delta本工作流增量skills/general-video/sub-agents/frame-worker.md——只承载 general-video 场景特有的内容即本文主角。从源码看拼接动作由 frame-packets-core.mjs 的buildRolePayload完成读取frame-worker-core.md与各工作流自己的sub-agents/frame-worker.md以核心契约 \n\n---\n\n delta的形式逐字拼接concatenated verbatim写入.hyperframes/frame-packets/_role.md避免两份文档被手工二次维护。general-video 的薄包装器 frame-packets.mjs 用corePath/deltaPath两个配置项把路径钉死其余逻辑全部委托给共享实现。对应地测试 frame-packets.test.mjs 中专门有一条断言_role.md同时包含# Frame worker — core contract与# Frame worker — general-video delta两个标题。delta 文档开篇点明三层纪律这也是帧工作器最基本的行事准则一场景一 workerN-up 并行时每个 worker 只负责一个场景dispatch 恰好携带一个 packet不贪多通用规则不落地在此想往 delta 里塞一条通用的 GSAP / timeline 规则那是错误的家——它属于 core contract 或hyperframes-core两份文档按一份角色阅读packet 构建器把 core contract 前置到 delta 之前worker 拿到的是合成后的完整角色。并行调度的落点N-up 调度本身由工作流编排层驱动当计划超过约 6 个短场景时general-video 的 SKILL.md 会运行node SKILL_DIR/scripts/frame-packets.mjs --project $PROJECT_DIR --storyboard $PROJECT_DIR/STORYBOARD.md该命令为每个场景写一个有界 packet默认上限 48,000 字节见 frame-packets-core.mjs 的maxPacketBytes超限会抛错且不产生任何部分输出测试packet validation is atomic验证了这一点外加_role.md。随后按 subagent-dispatch.md 的规则把_role.md全文 dispatch context 完整交给子代理并行扇出并以磁盘产物存在而非完成通知作为等待完成的判据。二、你的场景是发明的不是捕获的general-video 帧工作器没有产品捕获capture管线。它的全部输入只有两个来源packet 内的storyboard block即该场景在STORYBOARD.md中的## Frame N块由编排层抽取进 packetProject inputs 中指定的design truth 文件。由此推出三条硬规则只使用 block 自身点名的媒体路径绝不自行解析或抓取新媒体——编排层orchestrator在 dispatch 之前已经把 block 引用的所有媒体全部 staging 就绪场景元素完全从上述两个来源发明出来而不是去某个素材库查找。从 frame-packets-core.mjs 的注释可以看到设计动机packet 项目输入 该帧精确的## Frame Nblock blueprint 正文 所有被引用的 rule 配方内联worker 永远不需要打开共享的STORYBOARD.md或任何技能文档——多个兄弟 worker 并行编辑同一工程时谁都不该碰共享文件这是并发安全的根基。Packet 里到底有什么splitFrames把STORYBOARD.md按## Frame N切块frame-packets-core.mjs每块生成一个frame_id.md。对 worker 而言packet 中的核心字段包括字段含义对 worker 的意义scene一行式接触表contact-sheet说明设计意图绝不是可见的 DOM 文案voiceover旁白行只作计时参考让入场对齐语音绝不渲染为文字——字幕是独立的根轨道duration渲染时长秒上游固定绝不可改也不得用补间去填不同长度transition_in转场信息仅供了解由注入器injector盖在根节点上worker 不写转场时间码镜头序列Scene 1 (0.0–Xs): … → Scene 2: …就是构建规格每个 Scene 窗口都是必须实现的阶段blueprint:镜头模板 id 或字面量compose镜头整体形状 标志性动作compose表示无模板focal:/roles:谁是主角、各元素是什么语义由 delta 定义sfx:音效归属编排层的worker 不挂载任何音频规则配方只复现不猜名packet 还会内联## Selected motion rule: id配方段。worker 对 Scene 行中每个点名动作必须复现配方机制绝不靠名字猜猜会丢掉标志性动作。若引用的配方缺失才回退去读RULES_DIR/id.md路径在 packet 头部的RULES_DIR字段。citedRules的查找是机械的显式rules:字段 block 中出现的合法 rule id 文件名见 frame-packets-core.mjs测试则验证了 Scene 中出现的spring-pop-entrance、counting-dynamic-scale会被正确内联。三、Design truth谁的品牌权威解析顺序与裁决规则Project inputs 指名设计文件解析顺序为frame.mddesign.mdDESIGN.md取第一个存在的文件作为品牌真相brand truth负责 token、字体、调色板、处理手法treatment而 storyboard block 拥有内容。冲突时的裁决规则清晰且重要内容冲突 → block 赢风格冲突 → 设计文件赢。这一顺序并非文档口头约定而是被代码钉死的general-video 的 frame-packets.mjs 中designTruthLine就按frame.md → design.md → DESIGN.md遍历项目根目录并把找到的文件写进 packet 的Design truth:行frame-packets.test.mjs 中design truth resolves frame.md → design.md → DESIGN.md测试专门验证了当项目里只有design.md时packet 内联的必须是design.md而绝不能回退到frame.md。设计文件的双重禁令core contract 同时强调frame-worker-core.md视觉 token 全部取自frame.md不得发明绝不把frame.md里的词、标签或 wordmark 当作自己的文案抬出来——它是风格规格不是内容可见文案来自该帧的scene/ 叙事。四、输出契约composition motion 侧车delta 的核心输出契约极其明确恰好写两个文件然后停手。1.compositions/frame_id.html— 子合成按 core contract 的要求这是一个裸 fragment整个文件恰好是一个template…/template首字节是template末字节是/template禁止!doctype、html、head、body或 template 之外的任何标记。为什么如此苛刻sub-compositions.md 解释了运行时行为宿主通过data-composition-src加载子合成时运行时fetch文件 →DOMParser解析 →只克隆template的内容进宿主槽位template 之外的整棵head都会被丢弃。所以template不只是包裹层而是运输容器transport container样式、脚本、GSAP 加载都必须住在 template 内否则渲染时静默缺失。文件名即契约frame_id要原样用作合成 id、window.__timelines的 key 和文件名——因为该路径正是STORYBOARD.md里该帧的src写到这里装配器才能找到这帧。2.compositions/frame_id.motion.json— 运动台账侧车第二个文件是一个 JSON 对象编排层会把它合并进项目级 motion ledger运动台账{ scene: frame_id, duration_s: 0.0, rules: [rule ids you actually used], exit: { vector: direction px/s at your last frame, still_moving: true }, entry: { vector: direction px/s at your first frame, from_rest: false } }字段语义字段含义填写要求scene场景标识与frame_id一致duration_s场景时长秒与实际时间线一致rules实际用到的 motion rule id 列表只列真正用到的不要照抄计划里的愿望清单exit.vector最后一帧的运动方向 px/s从自己的时间线实测exit.still_moving末帧是否仍在运动如实上报entry.vector首帧的运动方向 px/s从自己的时间线实测entry.from_rest入场是否从静止开始如实上报delta 特别强调上报的是你实际创作的东西——来自时间线的实测值而不是计划中的期望值。这是因为在安装了 doctrine 链motion-doctrine的地方下游会有一个**数值接缝门numeric seam gate**来校验各帧的 exit/entrysidecar 写错会在下游响亮地失败loud fail而不是在这一层静默通过。侧车如何被下游自动校验这份*.motion.json不是摆设。hyperframes-cli 的check命令会自动发现与合成同名的*.motion.json侧车并在与渲染器相同的 seek 时间线上验证运动意图见 lint-validate-inspect.md这是渲染 MP4 再看一遍最接近的自动化代理。未安装 sidecar 时check行为与从前完全一致安装了则支持四类断言appearsBy迟到即motion_appears_late、before乱序即motion_out_of_order、staysInFrame出画即motion_off_frame、keepsMoving静置超时即motion_frozen。worker 侧车的entry/exit向量正是这类接缝校验与场景拼接盖章的数据来源。五、边界音频与场景接缝归编排层delta 的最后一条铁律是职责边界防止并行 worker 互相踩踏音频是编排层所有场景里绝不编写audio。旁白、BGM、SFX 全部在根层由编排层装配core contract 同款规则Noaudioelement in your composition。场景接缝由编排层从 ledger 盖章worker 只在自己的时间线内创作入场/出场运动绝不伸手改相邻场景的文件。core contract 补充得更细非末帧场景被禁止做 exit 补间根转场本身就是 exit中途卸载会截断成毛刺只有末帧才允许 settle / 淡出。六、落地检查清单交付前自检core contract 提供了帧工作器写完文件前的硬性自检清单lint/check作用于装配完成后的整项目帧未接线时无法真正验证自身所以必须在写入时自查到位Template 运输每个style与script含 GSAP 加载都住在template内根节点用#root而非 class渲染时 CSS 被作用域化到data-composition-id的后代选择器根节点上的 class 无法匹配整场会无样式渲染Studio 预览仍正常勿信预览全出血背景放classclip层#root上的 background 不可靠——装配时帧根被 clip 门控到自己的场景窗口深色内容可能落到宿主黑底上变得不可见每个classclip带data-start/data-duration/data-track-index恰好一条 paused 时间线注册在window.__timelines[frame_id]且同步构建无 CSS transition、无 repeat/yoyo、无不确定性逻辑渲染器逐帧 seekGSAP 变换与 CSS transform 不冲突GSAP 会整体覆写transformCSS 居中会被静默丢掉——用margin/inset、xPercent/yPercent或fromTo主角在t ≤ 0.5s内可见入场用fromTo而非 CSS 隐藏起点非末帧无 exit 动画不前置堆料画面按 voiceover 提示逐段揭晓而非前 25% 铺满全画布否则读起来就是 PowerPoint 幻灯片字体必须有同文件font-face只使用随项目发布的字体文件assets/fonts/或capture/assets/fonts/下的.woff2绝不指名无文件的中日韩系统字体Hiragino Sans、Yu Gothic、Noto Sans CJK等——渲染机是干净的 headless Chrome静默回退会导致 MP4 里排版错误83% 安全区 不重复旁白文字内容不得低于y ≈ 0.83 × height截断线1080 高帧为 9001920 竖屏为 1600字幕轨道已经同步显示语音屏幕上不得再印旁白句子。以上检查点对应的lint错误码如missing_template_wrapper、subcomposition_root_styled_by_class、exit_animation_on_non_final_scene、gsap_css_transform_conflict、font_family_without_font_face等是编排层可能回引的引用依据。七、从文档到管线的完整链路把上面的角色契约放回 general-video 生产流程完整链路是计划编排层在STORYBOARD.md里为每个场景写一个## Frame Nblockstatus: outline、src:、blueprint/rules 引用、节拍文本打包node SKILL_DIR/scripts/frame-packets.mjs --project $PROJECT_DIR --storyboard $PROJECT_DIR/STORYBOARD.md生成 bounded packetblock blueprint 正文 引用的 rule 配方内联与_role.mdcore delta 逐字拼接并行派发每个 worker 一个 packet2–3 个场景/worker 亦可所有 worker 单波次扇出只读自己的 packet 与 design truth 文件绝不打开STORYBOARD.md或技能文档产出worker 写完compositions/frame_id.htmlcompositions/frame_id.motion.json即终局动作——不编辑STORYBOARD.md、不生成音频、不装配 index、不跑 CLI、不回执合并与装配编排层收集各侧车把 duration 与 exit/entry 向量带入装配有 doctrine 链则先翻译进项目 ledger 再盖章接缝验证npx hyperframes lint快速反馈npx hyperframes check作为最终门禁内部重跑 lint并校验 motion 侧车断言与对比度子合成逐帧检查中间帧快照最终审批与渲染检查全绿后打开 Studio 预览用户批准后才渲染。结语general-video 帧工作器是 HyperFrames 并行生产架构的缩影用两文档拼一角色解决规则单一所有权frame-worker-core.md frame-worker.md 拼接成_role.md用一场景一 packet解决并行隔离frame-packets-core.mjs 内联所有必要上下文用composition motion 侧车双输出解决下游接缝校验。无论你是要为自己的多场景视频工程编写帧工作器角色还是想理解这套基于 HTML 渲染视频的 Agent 管线如何保证确定性与并行安全这份 delta core 的组合契约都是最佳切入点——而仓库中的源码与测试frame-packets.mjs、frame-packets.test.mjs、sub-compositions.md则是验证每一处契约的最佳证据。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考