企业官网建设流程全解析

HyperFrames v0.8.23 版本解读：Vertex 视觉字幕、字幕区碰撞检测与时间线 lint 加固

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames 是一个"Write HTML. Render video."的开源项目——用 HTML 编写合成，渲染为确定性、逐像素一致的视频。v0.8.23（发布于 2026-09-01）是一次聚焦"服务端抓取素材质量"与"时间线安全"的版本：抓取（Capture）流程接入 Google Vertex AI 服务账号进行视觉字幕生成，CLI 的hyperframes check校验新增字幕区（caption zone）DOM 框重叠检测，lint 规则则堵住了一类会让模板播放意外中断的时间线误用。本文以该版本为核心，结合仓库源码逐条拆解这三处变更的用法、参数与底层原理。

版本概览

v0.8.23 的变更集中在三条主线：

1. Capture（抓取）：以 Vertex 服务账号为视觉字幕能力认证，并保证 SVG 栅格化流程的安全；
2. CLI：hyperframes check在检测到文本 DOM 框与预留字幕区重叠时给出标记；
3. 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_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.ts）：

credentials = 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 sheet），v0.8.23 保证该栅格化路径的安全。抓取结束时生成asset-descriptions.md（capture/index.ts）：

• 有视觉凭据时，写入一行一个文件的 Vision 字幕，并提示用grep -i 'brand' asset-descriptions.md快速定位品牌素材；
• 无凭据时，退化为 catalog 派生的描述（alt 文本、标题、章节上下文、文件名），文件头部会明确提示"设置GEMINI_API_KEY/GOOGLE_API_KEY，或HYPERFRAMES_VERTEX_PROJECT_ID+HYPERFRAMES_VERTEX_SERVICE_ACCOUNT后重跑以获取更丰富描述"。

文件还提醒：logo-<hash>.svg文件名前缀只是 DOM 结构线索（<header>、首页链接<a>、aria-label匹配品牌），不是内容声明——很多logo-*文件其实是导航图标或装饰形状，选品牌素材应信任字幕而非文件名。

CLI 字幕区碰撞检测：--caption-zone

v0.8.23 让hyperframes check能标记"文本 DOM 框与预留字幕区重叠"的问题。字幕区（caption zone）是画面底部预留给字幕的安全区域，若正文文本侵入该区域，字幕上屏时就会与画面内容打架。

参数语法与解析规则

hyperframes check的--caption-zone参数语法（定义于 commands/check.ts）：

--caption-zone "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]"

解析器强制约束（见 check.ts 的parseCaptionZone）：四个坐标必填且必须落在 0–1；x0 > x1或y0 > y1会被拒绝；severity仅接受warning/error；字段不可重复。任何非法语法都会抛错而不是静默禁用门禁——测试用例 check.test.ts 验证了y1=1.2这类越界输入会报Invalid --caption-zone。

典型用法

# 默认：警告级别，检查画布底部 18% 区域 hyperframes check --caption-zone "x0=0;y0=.82;x1=1;y1=1" # 把字幕区命中升级为错误，并额外采样 0.5s 与 1s 两个时间点 hyperframes check --caption-zone "x0=0;y0=.8;x1=1;y1=.95;severity=error;seek=.5,1"

相关校验项与逃生阀

字幕区碰撞在 lint 问题码体系中对应caption_zone_collision（layoutAudit.ts）。该问题码不参与静态问题的持久化分层（persistence tiering），即它不会被折叠规则重新解读为"持续时长"信号。同时存在一个数据属性逃生阀：设置了data-layout-allow-caption-zone的元素可跳过该项检查（check.test.ts）。

hyperframes check还支持--frame-check（裸用或severity=error;seek=.25,.75;tol=4调参）与--layout "proseCoverageFloor=0.05"等配套校验项，全部与--caption-zone共用同一套"分号分隔 key=value"语法，便于 Agent 以 JSON 形式消费统一报告（--json）。

Lint 加固：拒绝时间线返回值被当作子补间

第三处核心变更是新的 lint 错误码gsap_timeline_return_used_as_tween（rules/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字段把变量与品牌角色绑定：

同类标注还出现在 claude-exchange（answer4–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