HyperFrames AGENTS.md 解析AI Agent 协作契约、Skills 体系与确定性渲染验证闭环【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFramesWrite 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 等编码代理的操作性规则文档覆盖四件事Skills 体系——Agent 写 composition 前必须安装框架专属的 skills并按/hyperframes路由选择工作流构建与测试——统一使用 bun 工具链校验闭环——lint 浏览器 gate 双通道通过才算完成项目结构与关键约定——包管理、提交格式、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-animation121 个文件、hyperframes-creative、hyperframes-cli、embedded-captions138 个文件、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 cloneHEAD避免走存在数小时滞后的 skills 注册表 blob 导致新装即过期。此外CLI 会在安装后把 skill 镜像到本机其他已装 Agent 的全局目录mirrorGlobalSkills并带GIT_CLONE_PROTECTION_ACTIVE0、GIT_LFS_SKIP_SMUDGE1等环境保护变量以规避企业环境 clone 钩子与 LFS 大对象问题。/hyperframes 路由器与创建工作流AGENTS.md 规定所有 make me a… 请求先经/hyperframes入口 skill 路由它先确认 brief意图层再把意图映射到具体工作流。各工作流的输入/输出契约如下表完整继承自 AGENTS.md工作流输入 → 输出/product-launch-video任意网站URL或预写脚本/文本 briefno-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 PRURL /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把 RemotionReact视频 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 Rulesdata-start定时、classclip、window.__timelines注册、muted视频 独立audio、data-composition-src子 composition、仅确定性逻辑。更完整的 skills 使用指南见 docs/guides/skills.mdx。构建与测试bun 是唯一入口AGENTS.md 明确指定包管理器为bun不是 pnpmbun 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:unitbun run --filter * test即按 workspace 扇出执行各包测试。此外还有细粒度入口producer:test:unit含 bun/vitest 两套、producer:test:integration、test:regressionproducer 回归、player:perfplayer 性能、test:scripts脚本自身的 node test vitest、test:skillsskills 目录下的*.test.mjs。Lint 与格式化oxlint oxfmt由 Lefthook 强制AGENTS.md 强调本仓库使用oxlint 与 oxfmt不是 eslint、prettier、biomebunx 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-patternformat*.{js,jsx,ts,tsx,json,md,yaml,yml}自动oxfmt格式化并git add -f重新暂存——注释明确解释了为什么用格式化重暂存取代--check只报不改会在 amend 快照后留下未格式化文件skills-manifestskills/**skill 变更时重新生成 skills-manifest.json 新鲜度指纹并重暂存杜绝 manifest 与skills/漂移CI 有同名校验 job无变更时零 diffcatalog-indexregistry/*/*/registry-item.jsonregistry 条目可搜索文本变化时重建本地搜索向量registry/catalog-artifact/local-vectors.{json,bin}exit 3本机无嵌入模型对外部贡献者直接放行不阻塞提交typecheck*.{ts,tsx}依次对packages/core、packages/studio、scripts/tsconfig.json跑tsc --noEmitfallowpackages/**/*.{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阻止被忽略的依赖树/平台元数据进提交filesizepackages/studio/**/*.{ts,tsx}studio 架构标准单文件 600 行上限排除测试与生成文件commit-msg—bunx commitlint --edit {1}配置见 commitlint.config.jsextendscommitlint/config-conventional其中skills-manifest与catalog-index两个钩子把 AGENTS.md 强调的 skills/registry 体系变成了提交即同步的机制Agent 或人改了 skill 或 registry 条目指纹/向量自动重算无需人工记得跑生成脚本。Composition 校验lint 与浏览器 gate 双通道AGENTS.md 规定创建或编辑任何.htmlcomposition 之后两条校验都必须通过才能进入预览或视为完成npx hyperframes lint # 静态 HTML 结构检查 npx hyperframes check # 浏览器 gateheadless Chrome——运行时错误、布局、动效、WCAG 对比度分工清晰lint是静态结构层data-*属性完整性、classclip缺失等check是运行时层——真实拉起 headless Chrome 验证渲染期错误、布局与动效、以及 WCAG 对比度。CLI 侧还提供--verbose含 info 级发现与--jsonCI 机器可读两种模式见 packages/cli/src/templates/_shared/AGENTS.md 中的命令清单。静态检查规则的实现在packages/lintpackages/lint/src/而 core 包同时承载 linter 与 runtime见下文项目结构校验能力在 Agent 项目模板中则被收拢成一条npm run checklint 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逐条都有仓库内佐证包管理器bunworkspace 操作不用 pnpm、不用 npm。bun.lock 与 package.json 脚本全线bun run印证。提交格式Conventional Commitsfeat:、fix:、docs:、refactor:、test:。由 commitlint.config.jsextendscommitlint/config-conventional lefthookcommit-msg钩子强制执行releases/ 目录按版本号的变更日志也配套了scripts/release-prepare.ts、scripts/draft-changelog.ts等发布流程脚本。TypeScript 风格避免any与as T断言优先类型守卫与收窄。这与typecheck钩子对 core/studio/scripts 三处tsc --noEmit的强制相辅相成。Composition 写法HTML data-*属性片段必须带classclipGSAP timeline 必须 paused 并注册到window.__timelines。这三点在 Agent 项目模板 packages/cli/src/templates/_shared/AGENTS.md 的 Key Rules 中有展开如data-start才是定时标记.clip类提供全屏盒模型且缺失会被 lint 告警且被 lint 规则与check浏览器 gate 双向兜底。Frame Adapters动画运行时通过按帧寻址seek-by-frame适配器模式接入GSAP 为主适配器。对应实现文档见 docs/concepts/frame-adapters.mdxcore 包负责 frame adapters项目结构一节。确定性渲染禁止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 的工程师而言这份文档即是必读的第一手规范。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考