尧图网页设计 
HyperFrames v0.8.23 版本解读Vertex 视觉字幕、字幕区碰撞检测与时间线 lint 加固【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 是一个Write HTML. Render video.的开源项目——用 HTML 编写合成渲染为确定性、逐像素一致的视频。v0.8.23发布于 2026-09-01是一次聚焦服务端抓取素材质量与时间线安全的版本抓取Capture流程接入 Google Vertex AI 服务账号进行视觉字幕生成CLI 的hyperframes check校验新增字幕区caption zoneDOM 框重叠检测lint 规则则堵住了一类会让模板播放意外中断的时间线误用。本文以该版本为核心结合仓库源码逐条拆解这三处变更的用法、参数与底层原理。版本概览v0.8.23 的变更集中在三条主线Capture抓取以 Vertex 服务账号为视觉字幕能力认证并保证 SVG 栅格化流程的安全CLIhyperframes check在检测到文本 DOM 框与预留字幕区重叠时给出标记Lint拒绝把时间线返回值当作子补间child tween使用的写法避免其脱离子帧导致模板播放中断。此外Registry 在八个推广模板上标注了承载品牌身份的插槽identity-bearing slot并让交换式合成器exchange composer中的长提示保持完整可见内部则优化了 Windows 测试流水线。Capture 视觉字幕接入 Vertex 服务账号服务端部署环境里抓取素材后需要为图片生成一行式说明文字caption供下游 Agent 理解这个文件里到底是什么。v0.8.23 之前视觉字幕只支持 OpenRouter 与 Gemini API Key 两种认证方式本次为服务端部署补齐了 Vertex AI 服务账号认证。凭据优先级与判定逻辑从 contentExtractor.ts 的源码可以确认完整的提供方选择逻辑OPENROUTER_API_KEY → OpenRouter优先级最高显式 opt-in HYPERFRAMES_VERTEX_PROJECT_ID HYPERFRAMES_VERTEX_SERVICE_ACCOUNT → Vertex AI GEMINI_API_KEY / GOOGLE_API_KEY → Gemini API源码注释明确解释了为什么 Vertex 排在裸 API Key 之前服务端部署持有的是服务账号与项目 ID通常没有可用的 Gemini API Key而一个被拒绝的 Key 与未设置 Key 在输出上无法区分——每次请求都会静默返回空抓取报告只会显示0 images captioned问题极难排查。环境变量与模型选择环境变量作用默认值HYPERFRAMES_VERTEX_PROJECT_IDVertex 项目 ID无HYPERFRAMES_VERTEX_SERVICE_ACCOUNT服务账号 JSON以 JSON 字符串形式传入无HYPERFRAMES_VERTEX_LOCATIONVertex 区域us-central1HYPERFRAMES_VERTEX_MODELVertex 视觉模型gemini-2.5-flash其余提供方同样支持模型覆盖HYPERFRAMES_OPENROUTER_MODEL默认google/gemini-3.1-flash-lite、HYPERFRAMES_GEMINI_MODEL默认gemini-3.1-flash-lite-preview。源码特别指出 Vertex 发布的模型集合与 Gemini API 不同——API 上的 flash-lite 预览 id 在 Vertex 里无法解析因此 Vertex 携带独立的默认模型。认证与调用细节Vertex 分支通过google/genai的GoogleGenAI客户端完成contentExtractor.tscredentials JSON.parse(process.env.HYPERFRAMES_VERTEX_SERVICE_ACCOUNT); ai new GoogleGenAI({ vertexai: true, project: vertexProject, location: process.env.HYPERFRAMES_VERTEX_LOCATION || us-central1, googleAuthOptions: { credentials }, });若HYPERFRAMES_VERTEX_SERVICE_ACCOUNT不是合法 JSON会推入一条明确警告并跳过视觉字幕而不是崩溃或静默吞掉。请求配置里thinkingConfig: { thinkingBudget: 0 }被显式关闭——单行事实性说明不需要推理而且思考 token 会占用maxOutputTokens预算模型可能花光预算返回空文本最终表现为请求成功但 0 字幕。三种提供方共享同一个单图 → 一行字幕契约captionOne因此批量与 SVG 栅格化循环对提供方无感图片按 20 张一批并行请求、批间暂停 2 秒以适配 Gemini 免费层约 5 RPM 的限速超时与失败的请求会被聚合为净化后的警告contentExtractor.ts。SVG 栅格化安全与资产描述产物抓取流程会为内联 SVG 与外部img src*.svg生成 SVG 联系表contact sheetv0.8.23 保证该栅格化路径的安全。抓取结束时生成asset-descriptions.mdcapture/index.ts有视觉凭据时写入一行一个文件的 Vision 字幕并提示用grep -i brand asset-descriptions.md快速定位品牌素材无凭据时退化为 catalog 派生的描述alt 文本、标题、章节上下文、文件名文件头部会明确提示设置GEMINI_API_KEY/GOOGLE_API_KEY或HYPERFRAMES_VERTEX_PROJECT_IDHYPERFRAMES_VERTEX_SERVICE_ACCOUNT后重跑以获取更丰富描述。文件还提醒logo-hash.svg文件名前缀只是 DOM 结构线索header、首页链接a、aria-label匹配品牌不是内容声明——很多logo-*文件其实是导航图标或装饰形状选品牌素材应信任字幕而非文件名。CLI 字幕区碰撞检测--caption-zonev0.8.23 让hyperframes check能标记文本 DOM 框与预留字幕区重叠的问题。字幕区caption zone是画面底部预留给字幕的安全区域若正文文本侵入该区域字幕上屏时就会与画面内容打架。参数语法与解析规则hyperframes check的--caption-zone参数语法定义于 commands/check.ts--caption-zone x00;y0.82;x11;y11[;severitywarning|error][;seek.5,1]字段含义说明x0,y0字幕区左上角0–1 的分数坐标相对画布x1,y1字幕区右下角0–1 的分数坐标severity命中等级warning默认或errorseek采样时间点逗号分隔的分数时间列表默认1末尾解析器强制约束见 check.ts 的parseCaptionZone四个坐标必填且必须落在 0–1x0 x1或y0 y1会被拒绝severity仅接受warning/error字段不可重复。任何非法语法都会抛错而不是静默禁用门禁——测试用例 check.test.ts 验证了y11.2这类越界输入会报Invalid --caption-zone。典型用法# 默认警告级别检查画布底部 18% 区域 hyperframes check --caption-zone x00;y0.82;x11;y11 # 把字幕区命中升级为错误并额外采样 0.5s 与 1s 两个时间点 hyperframes check --caption-zone x00;y0.8;x11;y1.95;severityerror;seek.5,1相关校验项与逃生阀字幕区碰撞在 lint 问题码体系中对应caption_zone_collisionlayoutAudit.ts。该问题码不参与静态问题的持久化分层persistence tiering即它不会被折叠规则重新解读为持续时长信号。同时存在一个数据属性逃生阀设置了data-layout-allow-caption-zone的元素可跳过该项检查check.test.ts。hyperframes check还支持--frame-check裸用或severityerror;seek.25,.75;tol4调参与--layout proseCoverageFloor0.05等配套校验项全部与--caption-zone共用同一套分号分隔 keyvalue语法便于 Agent 以 JSON 形式消费统一报告--json。Lint 加固拒绝时间线返回值被当作子补间第三处核心变更是新的 lint 错误码gsap_timeline_return_used_as_tweenrules/gsap.ts。问题的本质GSAP 中gsap.timeline().to()返回的是时间线自身而gsap.to()返回的才是真正的 Tween。二者写法几乎一样、行为截然不同。源码注释描述的真实事故形态一个跟随文档字体加载而重建的光标跟随滚动合成把tl.to()的返回值收集进数组后统一kill()——每次 push 进去的都是主时间线tl本身于是重建过程对主时间线调用了 49 次kill()随后把新关键帧叠加在它本想替换的旧关键帧之上。kill()会中断时间线并使其脱离父级detach父级驱动的 seek 因此卡死而显式tl.progress()仍能工作——于是打包默认值的渲染看起来正常只有直播播放会坏。检测规则与豁免检测只针对已知时间线句柄上的to|from|fromTo|set|call|add返回值gsap.ts收集进数组.push(tl.to(...))直接命中这是收集后丢弃的典型危险形态绑定到命名变量后只有再被 tween 作用域调用kill|revert|invalidate|pause|resume|restart|seek|progress|timeScale才命中——避免误报绑定但从未当 tween 用的无害写法Array.from与链式tl.to().to()返回值从未被捕获不标记。修复方案来自 fixHint测试用例 gsap.test.ts 验证了三种通过写法// ✅ 可丢弃的关键帧组用嵌套时间线kill 只影响自身 let caretTl null; const layout () { if (caretTl) caretTl.kill(); caretTl gsap.timeline(); caretTl.to(#typed, { x: -40, duration: 0.08 }, 1); tl.add(caretTl, 0); // 在 0 处加入子级保持绝对时间 }; layout(); document.fonts.ready.then(layout); // ✅ 真正要持有的单个补间用 gsap.to() 创建再 tl.add(tween, at) const tween gsap.to(#card, { opacity: 1, duration: 0.5, paused: true }); tl.add(tween, 0); document.fonts.ready.then(() tween.kill());嵌套时间线在 0 处add可让每个子级保持绝对时间nested.kill()只替换它自己的关键帧无法触及主时间线tl。Registry品牌插槽标注与交换合成器长提示v0.8.23 在八个推广模板ad-template标签上标注了承载品牌身份的插槽。以 ai-chat-reveal 为例其portrays字段把变量与品牌角色绑定变量portrays语义botNamehost_identity主持产品身份不属于被推广品牌ecCtasubject_name被推广品牌真实名称ecSubsubject_tagline品牌定位句ecFootersubject_domain品牌真实域名brandLogosubject_logo品牌透明标识同类标注还出现在 claude-exchangeanswer4–answer8的subject_name与 message-thread-reveal链接卡标题的subject_name等模板中。这样 Agent 在混排remix时能精确区分哪些插槽必须换成客户品牌、哪些属于宿主产品从而保证成片品牌一致。同批还修复了交换式合成器如 Claude 对话模拟中长用户提示被截断的问题保持提示文本完整可见。工程细节与验证路径测试验证字幕区语法的解析、非法输入拒绝、data-layout-allow-caption-zone逃生阀、gsap_timeline_return_used_as_tween的命中与豁免分别由 check.test.ts 与 gsap.test.ts 覆盖内部优化Windows 测试流水线lane得到优化缩短了跨平台 CI 耗时验证入口本地对任意合成项目运行hyperframes check即可一次性执行 lint、运行时、布局、运动与 WCAG AA 对比度校验--json输出面向 Agent 的单一报告信封commands/check.ts。小结v0.8.23 的三处核心变更各司其职Vertex 服务账号让服务端抓取在没有 API Key 的环境下也能获得视觉字幕并提供asset-descriptions.md供 Agent 检索--caption-zone把字幕上屏前的文本重叠前移到校验阶段且提供了severity/seek精细控制与数据属性逃生阀gsap_timeline_return_used_as_tween则从静态分析层面杜绝了收集时间线返回值批量 kill这一隐蔽播放故障。对使用 HyperFrames 做模板生产与素材抓取的团队升级后应关注抓取环境变量配置并在 CI 中加入带字幕区的hyperframes check门禁。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HyperFrames v0.8.23 版本解读：Vertex 视觉字幕、字幕区碰撞检测与时间线 lint 加固
HyperFrames v0.8.23 版本解读Vertex 视觉字幕、字幕区碰撞检测与时间线 lint 加固【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 是一个Write HTML. Render video.的开源项目——用 HTML 编写合成渲染为确定性、逐像素一致的视频。v0.8.23发布于 2026-09-01是一次聚焦服务端抓取素材质量与时间线安全的版本抓取Capture流程接入 Google Vertex AI 服务账号进行视觉字幕生成CLI 的hyperframes check校验新增字幕区caption zoneDOM 框重叠检测lint 规则则堵住了一类会让模板播放意外中断的时间线误用。本文以该版本为核心结合仓库源码逐条拆解这三处变更的用法、参数与底层原理。版本概览v0.8.23 的变更集中在三条主线Capture抓取以 Vertex 服务账号为视觉字幕能力认证并保证 SVG 栅格化流程的安全CLIhyperframes check在检测到文本 DOM 框与预留字幕区重叠时给出标记Lint拒绝把时间线返回值当作子补间child tween使用的写法避免其脱离子帧导致模板播放中断。此外Registry 在八个推广模板上标注了承载品牌身份的插槽identity-bearing slot并让交换式合成器exchange composer中的长提示保持完整可见内部则优化了 Windows 测试流水线。Capture 视觉字幕接入 Vertex 服务账号服务端部署环境里抓取素材后需要为图片生成一行式说明文字caption供下游 Agent 理解这个文件里到底是什么。v0.8.23 之前视觉字幕只支持 OpenRouter 与 Gemini API Key 两种认证方式本次为服务端部署补齐了 Vertex AI 服务账号认证。凭据优先级与判定逻辑从 contentExtractor.ts 的源码可以确认完整的提供方选择逻辑OPENROUTER_API_KEY → OpenRouter优先级最高显式 opt-in HYPERFRAMES_VERTEX_PROJECT_ID HYPERFRAMES_VERTEX_SERVICE_ACCOUNT → Vertex AI GEMINI_API_KEY / GOOGLE_API_KEY → Gemini API源码注释明确解释了为什么 Vertex 排在裸 API Key 之前服务端部署持有的是服务账号与项目 ID通常没有可用的 Gemini API Key而一个被拒绝的 Key 与未设置 Key 在输出上无法区分——每次请求都会静默返回空抓取报告只会显示0 images captioned问题极难排查。环境变量与模型选择环境变量作用默认值HYPERFRAMES_VERTEX_PROJECT_IDVertex 项目 ID无HYPERFRAMES_VERTEX_SERVICE_ACCOUNT服务账号 JSON以 JSON 字符串形式传入无HYPERFRAMES_VERTEX_LOCATIONVertex 区域us-central1HYPERFRAMES_VERTEX_MODELVertex 视觉模型gemini-2.5-flash其余提供方同样支持模型覆盖HYPERFRAMES_OPENROUTER_MODEL默认google/gemini-3.1-flash-lite、HYPERFRAMES_GEMINI_MODEL默认gemini-3.1-flash-lite-preview。源码特别指出 Vertex 发布的模型集合与 Gemini API 不同——API 上的 flash-lite 预览 id 在 Vertex 里无法解析因此 Vertex 携带独立的默认模型。认证与调用细节Vertex 分支通过google/genai的GoogleGenAI客户端完成contentExtractor.tscredentials JSON.parse(process.env.HYPERFRAMES_VERTEX_SERVICE_ACCOUNT); ai new GoogleGenAI({ vertexai: true, project: vertexProject, location: process.env.HYPERFRAMES_VERTEX_LOCATION || us-central1, googleAuthOptions: { credentials }, });若HYPERFRAMES_VERTEX_SERVICE_ACCOUNT不是合法 JSON会推入一条明确警告并跳过视觉字幕而不是崩溃或静默吞掉。请求配置里thinkingConfig: { thinkingBudget: 0 }被显式关闭——单行事实性说明不需要推理而且思考 token 会占用maxOutputTokens预算模型可能花光预算返回空文本最终表现为请求成功但 0 字幕。三种提供方共享同一个单图 → 一行字幕契约captionOne因此批量与 SVG 栅格化循环对提供方无感图片按 20 张一批并行请求、批间暂停 2 秒以适配 Gemini 免费层约 5 RPM 的限速超时与失败的请求会被聚合为净化后的警告contentExtractor.ts。SVG 栅格化安全与资产描述产物抓取流程会为内联 SVG 与外部img src*.svg生成 SVG 联系表contact sheetv0.8.23 保证该栅格化路径的安全。抓取结束时生成asset-descriptions.mdcapture/index.ts有视觉凭据时写入一行一个文件的 Vision 字幕并提示用grep -i brand asset-descriptions.md快速定位品牌素材无凭据时退化为 catalog 派生的描述alt 文本、标题、章节上下文、文件名文件头部会明确提示设置GEMINI_API_KEY/GOOGLE_API_KEY或HYPERFRAMES_VERTEX_PROJECT_IDHYPERFRAMES_VERTEX_SERVICE_ACCOUNT后重跑以获取更丰富描述。文件还提醒logo-hash.svg文件名前缀只是 DOM 结构线索header、首页链接a、aria-label匹配品牌不是内容声明——很多logo-*文件其实是导航图标或装饰形状选品牌素材应信任字幕而非文件名。CLI 字幕区碰撞检测--caption-zonev0.8.23 让hyperframes check能标记文本 DOM 框与预留字幕区重叠的问题。字幕区caption zone是画面底部预留给字幕的安全区域若正文文本侵入该区域字幕上屏时就会与画面内容打架。参数语法与解析规则hyperframes check的--caption-zone参数语法定义于 commands/check.ts--caption-zone x00;y0.82;x11;y11[;severitywarning|error][;seek.5,1]字段含义说明x0,y0字幕区左上角0–1 的分数坐标相对画布x1,y1字幕区右下角0–1 的分数坐标severity命中等级warning默认或errorseek采样时间点逗号分隔的分数时间列表默认1末尾解析器强制约束见 check.ts 的parseCaptionZone四个坐标必填且必须落在 0–1x0 x1或y0 y1会被拒绝severity仅接受warning/error字段不可重复。任何非法语法都会抛错而不是静默禁用门禁——测试用例 check.test.ts 验证了y11.2这类越界输入会报Invalid --caption-zone。典型用法# 默认警告级别检查画布底部 18% 区域 hyperframes check --caption-zone x00;y0.82;x11;y11 # 把字幕区命中升级为错误并额外采样 0.5s 与 1s 两个时间点 hyperframes check --caption-zone x00;y0.8;x11;y1.95;severityerror;seek.5,1相关校验项与逃生阀字幕区碰撞在 lint 问题码体系中对应caption_zone_collisionlayoutAudit.ts。该问题码不参与静态问题的持久化分层persistence tiering即它不会被折叠规则重新解读为持续时长信号。同时存在一个数据属性逃生阀设置了data-layout-allow-caption-zone的元素可跳过该项检查check.test.ts。hyperframes check还支持--frame-check裸用或severityerror;seek.25,.75;tol4调参与--layout proseCoverageFloor0.05等配套校验项全部与--caption-zone共用同一套分号分隔 keyvalue语法便于 Agent 以 JSON 形式消费统一报告--json。Lint 加固拒绝时间线返回值被当作子补间第三处核心变更是新的 lint 错误码gsap_timeline_return_used_as_tweenrules/gsap.ts。问题的本质GSAP 中gsap.timeline().to()返回的是时间线自身而gsap.to()返回的才是真正的 Tween。二者写法几乎一样、行为截然不同。源码注释描述的真实事故形态一个跟随文档字体加载而重建的光标跟随滚动合成把tl.to()的返回值收集进数组后统一kill()——每次 push 进去的都是主时间线tl本身于是重建过程对主时间线调用了 49 次kill()随后把新关键帧叠加在它本想替换的旧关键帧之上。kill()会中断时间线并使其脱离父级detach父级驱动的 seek 因此卡死而显式tl.progress()仍能工作——于是打包默认值的渲染看起来正常只有直播播放会坏。检测规则与豁免检测只针对已知时间线句柄上的to|from|fromTo|set|call|add返回值gsap.ts收集进数组.push(tl.to(...))直接命中这是收集后丢弃的典型危险形态绑定到命名变量后只有再被 tween 作用域调用kill|revert|invalidate|pause|resume|restart|seek|progress|timeScale才命中——避免误报绑定但从未当 tween 用的无害写法Array.from与链式tl.to().to()返回值从未被捕获不标记。修复方案来自 fixHint测试用例 gsap.test.ts 验证了三种通过写法// ✅ 可丢弃的关键帧组用嵌套时间线kill 只影响自身 let caretTl null; const layout () { if (caretTl) caretTl.kill(); caretTl gsap.timeline(); caretTl.to(#typed, { x: -40, duration: 0.08 }, 1); tl.add(caretTl, 0); // 在 0 处加入子级保持绝对时间 }; layout(); document.fonts.ready.then(layout); // ✅ 真正要持有的单个补间用 gsap.to() 创建再 tl.add(tween, at) const tween gsap.to(#card, { opacity: 1, duration: 0.5, paused: true }); tl.add(tween, 0); document.fonts.ready.then(() tween.kill());嵌套时间线在 0 处add可让每个子级保持绝对时间nested.kill()只替换它自己的关键帧无法触及主时间线tl。Registry品牌插槽标注与交换合成器长提示v0.8.23 在八个推广模板ad-template标签上标注了承载品牌身份的插槽。以 ai-chat-reveal 为例其portrays字段把变量与品牌角色绑定变量portrays语义botNamehost_identity主持产品身份不属于被推广品牌ecCtasubject_name被推广品牌真实名称ecSubsubject_tagline品牌定位句ecFootersubject_domain品牌真实域名brandLogosubject_logo品牌透明标识同类标注还出现在 claude-exchangeanswer4–answer8的subject_name与 message-thread-reveal链接卡标题的subject_name等模板中。这样 Agent 在混排remix时能精确区分哪些插槽必须换成客户品牌、哪些属于宿主产品从而保证成片品牌一致。同批还修复了交换式合成器如 Claude 对话模拟中长用户提示被截断的问题保持提示文本完整可见。工程细节与验证路径测试验证字幕区语法的解析、非法输入拒绝、data-layout-allow-caption-zone逃生阀、gsap_timeline_return_used_as_tween的命中与豁免分别由 check.test.ts 与 gsap.test.ts 覆盖内部优化Windows 测试流水线lane得到优化缩短了跨平台 CI 耗时验证入口本地对任意合成项目运行hyperframes check即可一次性执行 lint、运行时、布局、运动与 WCAG AA 对比度校验--json输出面向 Agent 的单一报告信封commands/check.ts。小结v0.8.23 的三处核心变更各司其职Vertex 服务账号让服务端抓取在没有 API Key 的环境下也能获得视觉字幕并提供asset-descriptions.md供 Agent 检索--caption-zone把字幕上屏前的文本重叠前移到校验阶段且提供了severity/seek精细控制与数据属性逃生阀gsap_timeline_return_used_as_tween则从静态分析层面杜绝了收集时间线返回值批量 kill这一隐蔽播放故障。对使用 HyperFrames 做模板生产与素材抓取的团队升级后应关注抓取环境变量配置并在 CI 中加入带字幕区的hyperframes check门禁。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考