1实现原理 · 为什么它能做到
本技能是 HyperFrames 的『技术契约』：把 HTML 写成可渲染视频的规则全集——单一 paused 时间线、data-* 时序属性、class=clip、sub-composition、确定性渲染禁令。SKILL.md 正文是构建指南，细节全部按需下沉 references/ 19 张卡。
skills/hyperframes-core/SKILL.md
This skill is the **technical contract** — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in `references/` (index next), read on demand.
注：References 索引表 19 行（minimal-composition/data-attributes/tracks-and-clips/sub-compositions/variables-and-media/determinism-rules/storyboard-format/review-loop/production-loop/brief-contract/brief-format/script-format/subagent-dispatch/frame-worker-core/tailwind 等）。
核心模型：composition = HTML 文件，DOM 用 data-* 属性声明时序、每 composition 恰注册一条 `gsap.timeline({ paused: true })` 到 window.__timelines["<id>"]，渲染长度以根 data-duration 为准（不是时间线长度）。
skills/hyperframes-core/SKILL.md
Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`).
注：配套规则：Render length is the root's `data-duration`, **not** the timeline's length——超长被截断、提前结束停在最后一帧；runtime 会在 inline scripts 前建好 registry。
能力落点包含真实 lint 规则集：SKILL.md 逐条列出 lint 能抓的坑（gsap_css_transform_conflict、media_crossorigin_breaks_preview、video_nested_in_timed_element、media_missing_id 等），并警告 lint error 会连带关掉 layout/contrast 审计。
skills/hyperframes-core/SKILL.md
Never put `crossorigin` on `<video>`/`<audio>`. `lint` rejects it unconditionally with `media_crossorigin_breaks_preview` (error), including for canvas/WebGL/WebAudio readback. There is no suppression.
注：这些规则与 packages/core、packages/engine 的真实编译器/校验器对应（SKILL 中引用 packages/core/src/compiler/compositionAssembly.ts 的 hasTemplate gate 说明装配器行为），SKILL 是契约层不是实现层。
确定性渲染是硬规则（不是建议）：禁渲染期时钟/无种子 Math.random/网络/输入态，禁 repeat: -1；禁对 clip 元素 tween display/raw visibility；禁 body 文本 <br>。
skills/hyperframes-core/SKILL.md
No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count).
注：SKILL 分『lint 会抓』与『silent bugs automated gates may miss』两档，把自动化覆盖不到的规则（如 flat query 找 video/audio、assembled page 全局唯一 id、shader transition 路径下 root fill 被丢）单独列出。
sub-composition 装配契约精确到文件形态：standalone 根不能包 <template>（lint error standalone_composition_wrapped_in_template），sub-composition 必须包 <template> 且 style/script 放 template 内（hasTemplate gate 会丢文件头 style/script），host/inner/timeline key 用同一 id。
skills/hyperframes-core/SKILL.md
for a **templated** sub-composition the assembler drops the file's own `<head>` `<style>`/`<script>` (`packages/core/src/compiler/compositionAssembly.ts`, the `hasTemplate` gate), so put `<style>`/`<script>` **inside** the template.
注：直接引源码路径作行为依据——skill 文档与编译器实现同仓演进，杜绝文档漂移（同段还注明 frame injection 的 data-hf-render-id 机制与 <source> 子元素例外）。
验证闭环真实存在且分级：npx hyperframes check 一次性跑 lint/runtime/layout/motion/contrast 五类、snapshot 抽帧目检、preview --background 供人审、render 需用户批准后执行。
skills/hyperframes-core/SKILL.md
- [ ] `npx hyperframes check` passes (0 findings across lint, runtime, layout, motion, and contrast) - [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
注：『render 只在用户批准后』的闸门写进核心契约——与生态里 music-to-video/product-launch 等 workflow 的 Gate 结构一致。
2核心能力
01最小可渲染 composition 骨架教学（standalone 根、sized box、clip+tween）
02data-* 时序/轨道/媒体属性查表与 class=clip 语义
03sub-composition 装配（host attrs、<template>、per-instance vars、动画边界）
04确定性渲染规则与 seek-safe 时间线构建（单 timeline/data-duration/有限 repeat/无运行时测量）
05creator 编辑配方（cut/trim/reorder/retime/freeze/camera/mask/crossfade/audio）
06计划/剧本格式（STORYBOARD.md/SCRIPT.md/BRIEF.md 契约）与 review-loop/production-loop 流程
07frame-worker 角色契约与 subagent 分发原语（narrative workflow 共享）
08五类验证 gate：lint/runtime/layout/motion/contrast + snapshot 目检 + preview
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | hyperframes CLI（check/snapshot/preview/render；命令细节在 /hyperframes-cli） |
| network | GSAP 经 CDN 进 composition（示例/骨架引 jsdelivr gsap；渲染时在 headless 浏览器加载——产物运行依赖，非 skill 自身外发） |
| package | @hyperframes/core / engine（同仓 packages/，真实校验/装配/渲染实现） |
4风险提醒 风险提醒：蓝色 · 知晓即可
风险提醒：蓝色 · 知晓即可
- 规则量大且分散正文/references 两层，简单任务可能漏读关键禁令（如 <br>、visibility tween） — SKILL 用『non-negotiable + silent bugs』高亮缓解，但 agent 若跳过 references 仍会踩坑。
- 产物依赖 CDN 库（gsap 等），离线/内网渲染需 vendor — minimal-composition 直接引 jsdelivr；企业内网渲染环境须预置本地副本。
- preview/render 在宿主环境驱动 headless 浏览器跑作者内联 JS — 作品脚本在渲染进程执行（有沙箱与用户批准 gate），但来源不可信的 composition 文件仍是执行面，宿主应限制项目来源。
风险提醒：蓝色，知晓即可。纯本地契约/读写技能：无凭证读取、无第三方外发；运行的是官方 hyperframes CLI 的本地 lint/check/snapshot/preview/render（render 需用户批准，preview 会留本地服务进程），产物为项目内 HTML/计划文件。唯一的网络是产物运行期按需从 jsdelivr 拉 gsap 等公开 CDN 库（作品级依赖，可本地 vendor），以及 CLI 官方渠道更新，均不碰 token/密钥。
5第二遍独立确认
- [ok] lint 规则名与真实校验器对应 — SKILL.md 引用的编译器路径 packages/core/src/compiler/compositionAssembly.ts 在仓库 packages/core 下实测存在（仓库级 glob 复核）；规则命名风格与 .oxlintrc/engine 校验一致。
- [discrepancy] 『document.fonts.ready 内构建可接受』与『禁 async 构建』是否矛盾 — 首轮将两条规则并置易误读：SKILL.md 正文允许在 async callback（fonts.ready）里构建但『register only after the build completes』；animation SKILL.md 的『no timeline construction inside async/setTimeout』指不能把注册放进未完成的异步流。两条实质一致（注册须在构建完成后同步完成），已在 how_it_works 注明而非判定矛盾。
- [ok] preview 进程存活行为 — SKILL.md 'the server survives the invoking command' 复核一致——preview 是常驻本地服务，属预期行为已列入 file_writes 描述。
- [ok] 有无隐藏脚本/网络（纯文档声称） — find 实测 skills/hyperframes-core 含 1 个共享 lib（scripts/lib/frame-packets-core.mjs，packet 数据组装，无 IO 外发）；无网络代码。
- [ok] 与其它 skill 的契约引用一致性 — music-to-video frame-worker.md、hyperframes 路由、hyperframes-audio SKILL 均引用 core 的 determinism/sub-composition 契约且无互相矛盾的定义。
6结论
适合：适合任何要写 HyperFrames composition 的 agent 会话（写 HTML 前的必读契约层）、需要 cut/crossfade 等编辑配方的 creator 场景、以及想理解『文档即契约、契约可 lint』设计范式的 skill 作者。
不适合：不适合不需要写 composition 的场景（纯音频混合→audio、素材获取→media-use、纯视觉方向→creative）；命令操作细节（渲染/发布/Studio）在 hyperframes-cli；运行时 API 细节（GSAP/Lottie/Three）在 hyperframes-animation/adapters。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-09
方式 A · 人下载镜像包下载 hyperframes-core.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent74bec24a87c21ea7…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库heygen-com / heygen-com/hyperframes
原始 GitHubheygen-com/hyperframes ↗
Stars48297
最近推送2026-09-09
本 skill commit
b8328f9573许可Apache-2.0（仓库根 LICENSE；GitHub API spdx Apache-2.0）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。