HyperFrames AGENTS.md 解析：AI Agent 协作契约、Skills 体系与确定性渲染验证闭环

HyperFrames（"Write HTML. Render video. Built for agents."）的根目录 AGENTS.md 是整个仓库面向 AI Agent 的协作契约：它规定了 Agent 在编写 composition 前必须安装哪些 skills、如何路由到正确的创建工作流、用哪套命令构建/测试/校验代码，以及确定性渲染等硬性约定。本文基于该文档逐节展开，并结合 package.json、lefthook.yml 与 packages/cli 中的 skills 安装实现，把每一条约定落到可验证的仓库证据上。读完本文，你可以独立完成：skills 的按需安装与刷新、monorepo 的构建与测试、composition 的静态检查与浏览器级校验，并理解 HyperFrames 为什么强制确定性渲染。

为什么需要 AGENTS.md：以文档约束 Agent 行为

HyperFrames 的官方定位是"写 HTML、渲染视频、为 Agent 而生"的开源视频渲染框架。AGENTS.md 正是这一定位的落点：它不是一般性的贡献指南，而是一份写给 AI Agent（如 Claude Code 等编码代理）的操作性规则文档，覆盖四件事：

1. Skills 体系——Agent 写 composition 前必须安装框架专属的 skills，并按 /hyperframes 路由选择工作流；
2. 构建与测试——统一使用 bun 工具链；
3. 校验闭环——lint + 浏览器 gate 双通道通过才算完成；
4. 项目结构与关键约定——包管理、提交格式、TypeScript 风格、确定性渲染规则。

Skills 体系：先安装核心集，再按需装工作流

安装命令

AGENTS.md 的第一条硬性规则是：在编写 composition 之前先安装 skills，因为这些 skills 编码了通用文档不会覆盖的框架专属模式（如 window.__timelines 注册、data-* 属性语义）。默认只装核心集（core set），/hyperframes 路由器会在需要时按需安装各个创建工作流；只有用户明确要求全套时才安装全部。

npx hyperframes skills update           # 默认：安装/刷新核心集——工作流按需安装
npx skills add heygen-com/hyperframes   # 交互式选择器（仅限终端——不带 --skill 的非交互模式会安装全部）

两条命令的分工在 CLI 源码中可以得到印证。packages/cli/src/commands/skills.ts 中，hyperframes skills 系列子命令的示例本身就说明了"按需安装"的语义：

export const examples: Example[] = [
  ["Install all HyperFrames skills", "hyperframes skills"],
  ["Check whether installed skills are up to date", "hyperframes skills check"],
  ["Check, machine-readable (for agents / CI)", "hyperframes skills check --json"],
  ["Update the core set + everything already installed", "hyperframes skills update"],
  ["Also install one workflow (on-demand install)", "hyperframes skills update pr-to-video"],
];

其中 check --json 专门面向 Agent/CI 场景提供机器可读输出；update <name> 则是路由器进入具体工作流前的"定向安装"入口。

核心集与定向安装引擎

从 skills-manifest.json（仓库根目录）可以看到当前 skills 的完整清单与新鲜度指纹，例如：hyperframes（路由入口，17 个文件）、hyperframes-core、hyperframes-animation（121 个文件）、hyperframes-creative、hyperframes-cli、embedded-captions（138 个文件）、media-use、music-to-video、motion-graphics 等，每个条目带内容 hash 与文件数，供 skills check 比对本地是否过期。物理文件全部位于 skills/ 目录下，与 manifest 一一对应。

安装底层机制值得细看。skills.ts 中定义了定向安装引擎 updateSkills，其保证范围是"一个小而明确的集合"：

• 请求的 skill 名（如路由到 pr-to-video 时传入）；
• 核心集（入口路由器 + 共享领域 skills）；
• 当 refreshInstalled 为真时，已安装的 skill 一并刷新——"一次 update 绝不把刻意保持精简的安装扩成全量"。

只有真正缺失或过期的 target 才会被交给 skills add（一次 spawn、每个名字一个 --skill 参数）；若 manifest 不可达（离线），则退化为"仅校验存在性"的降级保证（presenceOnly 标记）。安装参数尾部 GLOBAL_INSTALL_ARGS_TAIL 固定了 --global --agent claude-code universal --copy --full-depth --yes：--copy 保证落盘的是真实文件而非符号链接（使已安装 bundle 与发布 manifest 字节一致），--full-depth 强制完整 git clone HEAD，避免走存在数小时滞后的 skills 注册表 blob 导致新装即"过期"。此外，CLI 会在安装后把 skill 镜像到本机其他已装 Agent 的全局目录（mirrorGlobalSkills），并带 GIT_CLONE_PROTECTION_ACTIVE=0、GIT_LFS_SKIP_SMUDGE=1 等环境保护变量以规避企业环境 clone 钩子与 LFS 大对象问题。

/hyperframes 路由器与创建工作流

AGENTS.md 规定所有 "make me a…" 请求先经 /hyperframes 入口 skill 路由：它先确认 brief（意图层），再把意图映射到具体工作流。各工作流的输入/输出契约如下表（完整继承自 AGENTS.md）：

工作流	输入 → 输出
/product-launch-video	任意网站 URL（或预写脚本/文本 brief，no-capture 模式）→ 产品发布/宣传视频，或展示网站自身截图的站点巡礼；最长约 3 分钟（甜区约 30–90 秒）
/faceless-explainer	任意文本，无 URL、无网站截图 → 无人脸讲解视频；所有视觉由 LLM 生成（排版/抽象图形/图表/数据可视化），最长约 3 分钟（甜区约 30–90 秒）
/embedded-captions	既有口播视频（MP4）→ 同一段素材加上字幕/内嵌标题（verbatim rail + 高潮内嵌，或纯电影感内嵌）；素材本身零剪辑
/talking-head-recut	既有口播/访谈/播客视频（MP4）→ 同素材加上与转录同步的设计化图形覆盖层（动态标题、lower-third、数据标注、引言卡、侧栏、pip）；底层素材原样播放。纯字幕需求走 /embedded-captions
/pr-to-video	一个 GitHub PR（URL / owner/repo#N / "this PR"）→ 代码变更讲解视频，最长约 3 分钟（changelog / 功能发布 / 修复 / 重构）。注意是 PR 链接，不是产品网站
/motion-graphics	短于 10 秒左右、设计主导的动态图形，motion 即信息、无旁白：动态排版、数字计数、图表、logo sting、lower-third/覆盖层、动画推文/头条/截图页高亮；输出 MP4 或透明覆盖层。更长/有旁白/定制 → /general-video
/music-to-video	一条音乐轨道（音频文件、需提取音频的视频、或按 mood brief 生成）→ 节奏同步视频（歌词/幻灯片/动态宣传）；音乐驱动节奏，用户提供的图/视频切到同一拍点网格
/slideshow	演示文稿/pitch deck/交互式 deck——离散幻灯片、fragment 揭示、分支、热点导航、演讲者模式。输出是可导航的 deck，不是渲染视频
/general-video	其余一切视频创作的兜底（标题卡、更长的品牌 sizzle reel、多场景蒙太奇、静态循环、自定义 composition），也是 companion mode 的所在地——用完整 HyperFrames 工具箱共创：设计 → 计划 → 布局 → 构建 → 校验，不限时长

迁移已有 composition 走另一条线：/remotion-to-hyperframes 把 Remotion（React）视频 composition 翻译成 HyperFrames HTML——这是一次源码迁移，与上面的创作工作流相互独立。

这些 skills 的物理形态可以在 skills/ 下逐一查看（如 skills/pr-to-video/、skills/motion-graphics/），而 CLI 生成项目时写入用户项目的 Agent 指引模板 packages/cli/src/templates/_shared/AGENTS.md 与根文档一脉相承——它同样要求"先调用 skill 再写 composition"，并补充了项目级命令（npm run check、npx hyperframes preview --background 等）与六条 Key Rules（data-start 定时、class="clip"、window.__timelines 注册、muted 视频 + 独立 <audio>、data-composition-src 子 composition、仅确定性逻辑）。更完整的 skills 使用指南见 docs/guides/skills.mdx。

构建与测试：bun 是唯一入口

AGENTS.md 明确指定包管理器为 bun（不是 pnpm）：

bun install     # 安装依赖（切勿用 pnpm——不要创建 pnpm-lock.yaml）
bun run build   # 构建全部包
bun run test    # 运行全部测试

bun.lock 的存在印证了这一约定。构建的实际执行链路在 package.json 的 build 脚本中可见——它是按依赖顺序分波构建的：

@hyperframes/{parsers,lint,studio-server} → @hyperframes/core
→ {core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}
→ @hyperframes/cli → @hyperframes/sdk-playground

而根级 test 实际转发到 test:unit（bun run --filter '*' test），即按 workspace 扇出执行各包测试。此外还有细粒度入口：producer:test:unit（含 bun/vitest 两套）、producer:test:integration、test:regression（producer 回归）、player:perf（player 性能）、test:scripts（脚本自身的 node test + vitest）、test:skills（skills 目录下的 *.test.mjs）。

Lint 与格式化：oxlint + oxfmt，由 Lefthook 强制

AGENTS.md 强调本仓库使用 oxlint 与 oxfmt（不是 eslint、prettier、biome）：

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # Format
bunx oxfmt --check <files> # 格式检查（CI / pre-commit）

规则是提交前必须 lint 并格式化改动文件，Lefthook pre-commit 钩子会自动执行。打开 lefthook.yml 可以看到钩子的完整清单，远比"自动执行"一句更精细：

钩子	范围	行为
lint	*.{js,jsx,ts,tsx}	对暂存文件跑 bunx oxlint --no-error-on-unmatched-pattern
format	*.{js,jsx,ts,tsx,json,md,yaml,yml}	自动 oxfmt 格式化并 git add -f 重新暂存——注释明确解释了为什么用"格式化+重暂存"取代 --check（只报不改会在 amend 快照后留下未格式化文件）
skills-manifest	skills/**	skill 变更时重新生成 skills-manifest.json 新鲜度指纹并重暂存，杜绝 manifest 与 skills/ 漂移（CI 有同名校验 job）；无变更时零 diff
catalog-index	registry/*/*/registry-item.json	registry 条目可搜索文本变化时重建本地搜索向量（registry/catalog-artifact/local-vectors.{json,bin}）；exit 3（本机无嵌入模型）对外部贡献者直接放行，不阻塞提交
typecheck	*.{ts,tsx}	依次对 packages/core、packages/studio、scripts/tsconfig.json 跑 tsc --noEmit
fallow	packages/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}	审计脚本，--base origin/main --fail-on-issues，与 CI 门禁同基线，--gate new-only 只拦分支引入的问题
largefiles	全部	scripts/check-large-files.sh 拒绝绕过 LFS 直接提交的大二进制（阈值可用 HF_MAX_NONLFS_KB 调）
tracked-artifacts	全部	bun run check:tracked-artifacts 阻止被忽略的依赖树/平台元数据进提交
filesize	packages/studio/**/*.{ts,tsx}	studio 架构标准：单文件 600 行上限（排除测试与生成文件）
commit-msg	—	bunx commitlint --edit "{1}"，配置见 commitlint.config.js（extends @commitlint/config-conventional）

其中 skills-manifest 与 catalog-index 两个钩子把 AGENTS.md 强调的 skills/registry 体系变成了"提交即同步"的机制：Agent 或人改了 skill 或 registry 条目，指纹/向量自动重算，无需人工记得跑生成脚本。

Composition 校验：lint 与浏览器 gate 双通道

AGENTS.md 规定：创建或编辑任何 .html composition 之后，两条校验都必须通过才能进入预览或视为完成：

npx hyperframes lint       # 静态 HTML 结构检查
npx hyperframes check      # 浏览器 gate（headless Chrome——运行时错误、布局、动效、WCAG 对比度）

分工清晰：lint 是静态结构层（data-* 属性完整性、class="clip" 缺失等），check 是运行时层——真实拉起 headless Chrome 验证渲染期错误、布局与动效、以及 WCAG 对比度。CLI 侧还提供 --verbose（含 info 级发现）与 --json（CI 机器可读）两种模式（见 packages/cli/src/templates/_shared/AGENTS.md 中的命令清单）。静态检查规则的实现在 packages/lint（packages/lint/src/），而 core 包同时承载 linter 与 runtime（见下文项目结构），校验能力在 Agent 项目模板中则被收拢成一条 npm run check（lint + runtime + layout + motion + contrast 一次跑完）。

项目结构：从 AGENTS.md 到仓库实况

AGENTS.md 给出的结构总览：

packages/
  cli/                  → hyperframes CLI (create, preview, lint, render)
  core/                 → 类型、解析器、生成器、linter、runtime、frame adapters
  engine/               → 可寻址（seekable）的页面转视频捕获引擎（Puppeteer + FFmpeg）
  player/               → 可嵌入的 <hyperframes-player> web component
  producer/             → 完整渲染管线（捕获 + 编码 + 音频混音）
  shader-transitions/   → composition 的 WebGL shader 转场
  studio/               → 浏览器端 composition 编辑器 UI（先读 packages/studio/AGENTS.md）
registry/
  blocks/               → 可安装子 composition 场景（50+）
  components/           → 可安装特效与代码片段
  examples/             → 起步项目模板
docs/                   → Mintlify 文档站
skills/                 → AI agent skill 定义

对照仓库实况：packages/ 下确实包含 cli、core、engine、player、producer、shader-transitions、studio 七大主包，另有 studio-server、sdk、sdk-playground、aws-lambda、gcp-cloud-run 等部署与生态包（package.json 的 workspaces: ["packages/*"] 统一纳入）。registry 侧可安装内容以 registry/registry.json 为索引，registry/blocks/ 中可看到 50+ 具体场景（如 data-chart、code-diff、whip-pan、lower-third-bild 等），registry/components/ 存放特效与片段；docs/ 为 Mintlify 文档站（docs/docs.json 为站点配置）。studio 包自带 packages/studio/AGENTS.md，与根文档形成分层 Agent 指引。

关键约定：六条硬性规则及其仓库证据

AGENTS.md 最后列出六条 Key Conventions，逐条都有仓库内佐证：

1. 包管理器：bun（workspace 操作不用 pnpm、不用 npm）。bun.lock 与 package.json 脚本全线 bun run 印证。
2. 提交格式：Conventional Commits（feat:、fix:、docs:、refactor:、test:）。由 commitlint.config.js（extends @commitlint/config-conventional）+ lefthook commit-msg 钩子强制执行；releases/ 目录按版本号的变更日志也配套了 scripts/release-prepare.ts、scripts/draft-changelog.ts 等发布流程脚本。
3. TypeScript 风格：避免 any 与 as T 断言，优先类型守卫与收窄。这与 typecheck 钩子对 core/studio/scripts 三处 tsc --noEmit 的强制相辅相成。
4. Composition 写法：HTML + data-* 属性；片段必须带 class="clip"；GSAP timeline 必须 paused 并注册到 window.__timelines。这三点在 Agent 项目模板 packages/cli/src/templates/_shared/AGENTS.md 的 Key Rules 中有展开（如 data-start 才是"定时"标记，.clip 类提供全屏盒模型且缺失会被 lint 告警），且被 lint 规则与 check 浏览器 gate 双向兜底。
5. Frame Adapters：动画运行时通过"按帧寻址（seek-by-frame）适配器"模式接入，GSAP 为主适配器。对应实现文档见 docs/concepts/frame-adapters.mdx，core 包负责 frame adapters（项目结构一节）。
6. 确定性渲染：禁止 Date.now()、禁止未播种的 Math.random()、禁止渲染期网络请求。这是"HTML → 可寻址视频"的根基——引擎按帧 seek 重放页面，任何运行时随机性都会让同一时间码渲染出不同像素，破坏可复现性。概念性说明见 docs/concepts/determinism.mdx。

延伸阅读路径

• docs/guides/skills.mdx——skills 的安装/刷新/按名安装，含 Antigravity、Copilot CLI 等宿主的具体用法；
• packages/cli/src/commands/skills.ts——skills update/check 的完整实现（定向安装引擎、离线降级、Agent 镜像）；
• packages/lint/src/——静态 lint 规则实现；
• packages/producer/——捕获 + 编码 + 音频混音的完整渲染管线及其大规模回归测试集；
• docs/——面向用户的完整 Mintlify 文档站，与 AGENTS.md 的 Documentation 一节互为表里。

AGENTS.md 的价值在于把"Agent 该怎么协作"从口头约定变成了可执行、可门禁化的规则：skills 指纹由 pre-commit 钩子自动同步，lint/format/类型检查在提交时强制执行，composition 校验给出双通道通过标准，六条约定中每一条都指向仓库里真实存在的机制。对使用 Agent 开发 HyperFrames composition 的工程师而言，这份文档即是必读的第一手规范。