Frame N — Title【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes解析器接受 Frame / Beat / Scene 三种关键词作为小节标记且允许出现在 **H2 或 H3** 层级见 [FRAME_HEADING_RE](https://link.gitcode.com/i/de90c94f27582fdd9fccefd28c9d4654)。帧号 N 既可以是普通整数如 3也支持 1.1 这类编号parseHeading 会提取前导整数。 每个帧小节的构成如下 - 标题下方是元数据行格式为 - key: value也接受 * key: value见 [META_RE](https://link.gitcode.com/i/22895477b3b23b88db09060ec2926c23) - 元数据下方直到下一个同层或更浅层标题之间的内容是自由形式的**叙事**narrative文本。 markdown ## Frame 1 — Hook - scene: Big type punches in on the beat - duration: 3s - poster: 2s - transition_in: cut - status: animated - voiceover: Ship a launch video in an afternoon. - src: compositions/frames/01-hook.html Open cold on the promise. This is the thesis — everything after pays it off.已知元数据键键含义statusoutline→built→animated默认outlinesrc指向该帧 HTML 子合成的项目相对路径contact-sheet 缩略图由此渲染duration例如4stransition_in入场转场crossfade/cut/wipe…别名transitionscene一行式 contact-sheet 图注别名description/summary/captionvoiceover该帧的旁白指引别名vo/voice_over/narrationposter用于生成缩略图的定位秒数需跳过开场动画其他任意键原样保留在帧的extra下——工作流可在此携带自己的逐帧数据特效、素材等别名的源码实现这些别名并非文档层面的建议而是解析器的硬编码映射转场键集合TRANSITION_KEYS {transition_in, transitionin, transition}场景键集合SCENE_KEYS {scene, description, summary, caption}旁白别名VOICEOVER_ALIASES [voiceover, vo, voice_over, narration]——定义在 parseStoryboard.ts并被 editStoryboard.ts 导入复用确保读、写两侧对字段名的理解永远一致、不会漂移。关键解析细节可从源码确认status规范化解析器会将值转为小写并与FRAME_STATUSES[outline, built, animated]比对applyStatus。若出现未知状态值不会报错而是把原值塞进frame.extra.status并记录一条 warning同时回退到默认状态outline。duration解析applyDuration同时保留原始字符串duration和解析出的数值秒数durationSeconds当无法从中提取数字时会记录 warning但不会中断解析。voiceover与引号旁白值会经过stripQuotes剥掉最外层的一对或。poster解析同样用数字正则提取数值得到秒数。未知元数据键一律落入frame.extra逐字保留——这是工作流携带自有数据的官方通道。帧生命周期的三种状态outline → built → animated是每帧的生命周期Studio 会依据它渲染进度outline仅计划尚无实际 HTML。status: outline且没有src的帧在 contact sheet 中渲染为轮廓占位符outline placeholderbuilt中间档——帧的 HTML 已存在且布局已确认至少是线框草图级别但动画尚未添加Studio 用蓝色 chip 标记该状态animated完成动画。驱动这些状态流转的过程计划 → 草图 → 构建每轮都在板上评审见 review-loop.md。四、解析后的 ManifestStoryboardManifest解析器 parseStoryboard 的核心设计原则是宽松lenient它从不抛异常任何意外内容都记录为warning。完整的类型定义在 types.tsStoryboardManifest { globals: { format?, message?, arc?, audience?, extra: {…} } frames: Array{ index, number?, title?, status, // outline | built | animated src?, duration? / durationSeconds?, transitionIn?, scene?, voiceover?, poster?, narrative, // metadata 下方的 markdown extra: {…} // 未知键原样保留 } warnings: Array{ message, line?, frameIndex? } }值得注意的字段语义均与源码一一对应index1 基序号按文档顺序分配与作者写的Frame N中的number相互独立number/title从标题文本中拆解出的帧号与标题narrative元数据行之下的自由 Markdown 正文解析器不做任何结构假设warnings解析过程中遇到的非致命问题未知状态、无法解析的时长、未闭合的 Frontmatter 等每条可携带 1 基的行号与帧号方便定位globals/frames的extra分别是 Frontmatter 与帧元数据中未知键的逐字保留区。读取 API 的增量字段GET /api/projects/id/storyboard返回的 JSON 会在 Manifest 基础上增加两层信息storyboard.tssrcExists逐帧路由会用resolveWithinProject将src解析为项目内的绝对路径并检查文件是否存在供 Studio 判断缩略图能否渲染SCRIPT.md载荷当项目根目录存在可选的SCRIPT.md时以script: { exists, path, content }形式一并返回。此外当项目里根本没有STORYBOARD.md时API不会返回 404而是返回exists: false、空帧数组让 Studio 可以渲染一个可选的空状态opt-in而不是报错。五、SCRIPT.md锁定旁白文件不在分镜解析范围内SCRIPT.md是可选的、自由格式的锁定旁白文件它驱动 TTS但不会被解析进 Manifest。关键边界无旁白/TTS 的视频不生成该文件其格式定义在 script-format.md分镜中每帧的voiceover元数据是分镜自身的旁白指引与SCRIPT.md是两套东西。仓库中 storyboard-sample 夹具 给出了真实示例包含 Voice如Rachel (ElevenLabs)、Voice settingsstability / similarity / style、Voice direction以及按行组织的## Line N — 标题每行带时间区间如3.0 – 7.0s、delivery 提示和最终文案。它与STORYBOARD.md同为项目的兄弟文件位于项目根目录。六、帧评论通道.hyperframes/frame-comments.json分镜评审的结构化反馈通道是.hyperframes/frame-comments.json——Studio 的逐帧评论框提交时写入的文件聊天反馈遵循同一规则见 brief-contract.md 第 1 节的评论通道约定。与SCRIPT.md一样它是分镜的兄弟文件不解析进 Manifest{ version: 1, pass: sketch, submitted_at: 2026-07-09T12:04:00Z, comments: [ { frame: 3, src: compositions/frames/03-mechanism.html, title: Mechanism, text: Swap the bar chart for a before/after slider. } ] }字段含义pass这批评论所属的评审轮次storyboard文本层/sketch静态帧/final成片comments[].frame帧在 Manifest 中的 1 基index——这是评论的主键comments[].src、title提交时从帧上拷贝而来——若提交后帧被重排不匹配就会暴露出来comments[].text反馈原文逐字保留生命周期契约工作流在检查点checkpoint发现该文件时将其视为修订反馈——只修订被点名的帧、删除该文件、重新呈现。写作者只在提交时创建它它绝不跨轮次残留。七、完整示例与仓库真实夹具以下是 storyboard-format.md 提供的完整示例--- format: 1920x1080 message: Ship a launch video in an afternoon arc: Hook → Problem → Solution → Proof → CTA audience: indie devs on X --- ## Frame 1 — Hook - scene: Big type punches in on the beat - duration: 3s - poster: 2s - transition_in: cut - status: animated - voiceover: Ship a launch video in an afternoon. - src: compositions/frames/01-hook.html Open cold on the promise. This is the thesis — everything after pays it off. ## Frame 2 — The problem - scene: A 20-minute timer spins on a stack of rejected takes - duration: 4s - transition_in: crossfade - status: built - voiceover: The old way? Prompt, wait twenty minutes, get something that misses. - src: compositions/frames/02-problem.html The old way: prompt, wait, get something that misses. Establish the pain we remove.仓库中还有一份真实运行的分镜文件storyboard-sample/STORYBOARD.md。这份 5 帧夹具完整演练了分镜契约的端到端行为见其 README前 4 帧都有对应的 HTML 子合成01-hook.html 等状态为built/animated第 5 帧05-cta.html故意缺失且状态为outline用于让网格渲染出一个轮廓占位符Frontmatter 中额外携带了voice: Rachel — 5 lines from SCRIPT.md这样的未知键——它不会报错而是被保留在globals.extra中直观展示了自定义字段的携带方式。你可以用下面的命令预览分镜视图或检查解析结果# 预览 Storyboard 视图 npx hyperframes preview packages/studio/fixtures/storyboard-sample # 查看 Studio 实际消费的解析后 Manifest curl localhost:port/api/projects/id/storyboard | jq【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考