Communitygithub.com

AlessandroFare/fluxychat

HyperFrames 合成合约 — 构建一个可渲染的项目。用于合成结构、`data-*` 时间属性、`class="clip"`、轨道、子合成、变量、框架拥有的媒体播放、确定性渲染规则及验证。也涵盖 Tailwind 项目和 STORYBOARD.md / SCRIPT.md 计划格式。在编写合成 HTML 之前请先阅读。

fluxychat 是什么?

该技能是 HyperFrames 核心合成协议的技术合约,指导开发者如何构建一个可渲染的 HyperFrames 项目。它定义了使用 HTML 声明视频合成的基本规则:DOM 元素通过 `data-*` 属性控制时间线,动画运行时支持随机定位,媒体播放由框架统一管理。内容涵盖两种根形式(独立合成与子合成)、根元素尺寸要求、同步时间线注册、常见 lint 陷阱,以及一系列不可协商的规则,例如禁止运行时时钟、非确定性行为,以及仅允许动画化特定视觉属性。该技能还维护着一个全面的参考文档索引,涵盖最小合成骨架、数据属性、轨道与剪辑、子合成、变量与媒体、确定性规则、全屏动画、故事板格式、生产流程等。它与相邻领域的技能(如 `hyperframes-animation`、`hyperframes-creative`、`hyperframes-cli`)配合使用,共同构成完整的 HyperFrames 功能体系。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AlessandroFare/fluxychat/tree/HEAD/.agents/skills/hyperframes-core

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames Core

HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件,其 DOM 使用 data-* 属性声明时间,其动画运行时是可随机定位的,并且媒体播放由框架拥有。

本技能是技术合约——如何构建一个 HyperFrames 项目。以下正文是构建指南;每个主题的详细信息位于 references/(索引见下文),按需阅读。其他关注点位于兄弟领域技能中——hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力映射说明了每个技能涵盖的内容。

参考文献

文件阅读目的…
references/minimal-composition.md从最小的可渲染合成骨架开始
references/composition-patterns.md选择整体式 vs 模块化;构建模块化 index.html;选择子合成原型
references/data-attributes.md查找任何 data-*(根 / 剪辑 / 子合成宿主 / 遗留别名);使用 class="clip"
references/tracks-and-clips.md选择 data-track-index,处理同轨道重叠 / z-index,使一个剪辑相对于另一个剪辑的时间
references/sub-compositions.md连接子合成(宿主属性、<template>、实例变量)并在其内部运行动画
references/variables-and-media.md声明变量;放置 <video>/<audio>,设置音量,裁剪
references/determinism-rules.md构建可随机定位的时间线;确定性禁令;可动画属性允许列表;布局 / 文本适应
references/full-screen-motion.md使用共享背景编写全帧动画
references/storyboard-format.md编写 STORYBOARD.md 计划(+ 解析后的清单)
references/review-loop.md在活动看板上运行计划 → 草图 → 构建审查循环——由每个故事板规划工作流共享
references/production-loop.md将批准的计划转化为交付的视频——阶段依赖关系(音频、帧、装配、转场、字幕、验证、交付),自由形式构建直接遵循
references/brief-contract.md简报的基本规则——模式推导(协作 / 自主)、共享字段注册表、问题不变量(提问本身位于 /hyperframes → 意图层)
references/brief-format.md编写 BRIEF.md——工作流的 Setup 编写且每个后续步骤读取的已确认意图文档
references/script-format.md编写可选的 SCRIPT.md 锁定旁白
references/subagent-dispatch.md将子代理派遣动词(并行扇出 / 后台 / 等待)映射到你的工具集
references/frame-worker-core.md共享的帧工作者角色合约——每个叙事工作流的数据包构建器将其附加到该工作流的 sub-agents/frame-worker.md 增量中
references/tailwind.md在 Tailwind v4 项目中工作(init --tailwind;运行时合约与 Studio 的 v3 不同)

关于动画运行时的具体信息(GSAP API、Lottie、Three.js 等),请参阅 hyperframes-animation → adapters/<runtime>.md。

构建合成

两种根形式(不可互换)

  • 独立合成(顶级 index.html)——根 <div data-composition-id="…"> 直接位于 <body> 中,没有 <template> 包裹(包裹它会隐藏所有内容并破坏渲染)。
  • 子合成(通过 data-composition-src 加载)——根必须包裹在 <template> 中。

⚠ 传输规则:运行时仅克隆 <template> 内容;之外的所有内容(包括 <head> 样式/脚本)都会被丢弃——请将 <style>/<script> 放在模板内部。 ⚠ 宿主 ID 规则:宿主插槽的 data-composition-id 必须完全等于内部模板的 data-composition-id 以及 window.__timelines["<id>"] 键——不要添加 -mount/-slot/-host 后缀。

文件形状、宿主连接和预渲染检查清单 → references/sub-compositions.md。

根元素必须有尺寸(静默布局错误)

独立合成根元素需要一个显式的尺寸框(以 px 为单位的 width/height),并且直到 height:100% 元素的每个祖先元素都必须具有已解析的高度——否则 flex/100% 子元素会折叠到约 0,内容堆积到左上角。不要仅依赖自动化门控来发现此问题;检查快照。骨架 → references/minimal-composition.md。

一个暂停的时间线

每个合成在 window.__timelines["<id>"](键 = 根元素的 data-composition-id)处注册恰好一个 gsap.timeline({ paused: true }),在页面加载时同步构建。渲染时长 = 根元素的 data-duration,而不是时间线的长度。不要手动将子时间线嵌套到宿主中。完整合约(包括非 GSAP 运行时)→ references/determinism-rules.md + hyperframes-animation/adapters/。

第一遍 lint 陷阱(保证第一次构建失败)

两个 lint 确实会捕获的规则,但只会在事后发现——第一次就写对它们:

  • 根合成元素必须携带 data-start="0"(与 data-composition-id/data-width/data-height 一起);省略它会导致 lint 失败并显示 root_composition_missing_data_start。
  • 切勿将 CSS 初始 transform 与 GSAP 对同一属性的补间配对——CSS 值和补间的起始值冲突,lint 会以 gsap_css_transform_conflict 拒绝它。请使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在补间内设置初始状态,而不是使用 CSS transform: translateX(-40px)。

不可协商的规则(自动化门控可能遗漏的静默错误)

在此列出;完整理由见链接的参考文献。不得违反:

  • 禁止运行时时钟 / 未播种的 Math.random / 网络 / 输入状态;禁止 repeat: -1(使用有限计数)。→ determinism-rules.md
  • 仅对视觉属性允许列表进行动画;永远不要对 display 或原始 visibility 进行补间。GSAP autoAlpha 和零时长时间线边界设置是唯一的可见性例外,并且仅适用于非剪辑元素或剪辑内的包装器。框架单独控制 .clip 可见性。不要在页面加载时 gsap.set 后期场景的剪辑。→ determinism-rules.md
  • 正文中无 <br>;变换后的元素必须是块级且具有尺寸;脉动的绝对定位装饰元素需要峰值间隙。→ determinism-rules.md
  • <video>/<audio> 在任何嵌套深度下均可工作(包括在子合成 <template> 或包装器内部);框架拥有播放权并可在任何位置查找/解码媒体。唯一的注意事项是时间线,而不是放置位置:子合成时间线不能对宿主根元素进行动画。→ variables-and-media.md
  • 每个 id 在装配后的页面中必须是唯一的;在子合成内部,为 id 添加合成 id 前缀(#<id>-hero)。重复的 <video>/<img> 的 id 会导致渲染为空白——生产者通过 getElementById 注入帧,跨文件重复会绕过 lint。→ composition-patterns.md
  • 全屏场景填充应放在一个全出血的子元素上(position:absolute; inset:0),永远不要放在合成根元素本身上——生产者的帧合成可能会丢弃根元素自身的 background(帧渲染为黑色),即使预览/snapshot 显示正确。→ composition-patterns.md

编辑现有合成

  • 首先阅读文件。保留不相关的时间、轨道、ID、变量、媒体路径。
  • 匹配现有的合成 ID 和时间线键。
  • 添加剪辑:选择一个不重叠的 data-track-index 或有意调整周围时间。
  • 任何合成元素上的 data-hidden 会在预览和渲染中同时隐藏它,覆盖其时间窗口;它是非破坏性/可逆的,并由 Studio 的时间线眼睛图标切换。
  • 添加子合成:在连接宿主之前验证其内部 data-composition-id。

验证

使用 hyperframes-cli 获取命令详情

  • npx hyperframes check 通过(lint、运行时、布局、动画和对比度方面无发现)
  • 包含子合成的项目:npx hyperframes snapshot --at <midpoints> 并目视检查每一帧
  • npx hyperframes preview 用于审查(用户可以在 Studio 的时间线中编辑任何内容)
  • 仅在用户批准后运行 npx hyperframes render

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

AlessandroFare/fluxychat

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.\n

AlessandroFare/fluxychat

Use when audio already placed in a HyperFrames composition needs to be mixed: a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.\n

AlessandroFare/fluxychat

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.\n

AlessandroFare/fluxychat

Install, discover, and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

AlessandroFare/fluxychat

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.\n

AlessandroFare/fluxychat

Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions.

AlessandroFare/fluxychat

Turn a weekly changelog .md into a finished branded changelog video (square 1080, ~45-60s, Annie VO, animated brand background, mock-UI visualizations, lowkey captions). Use when the user provides a changelog/digest markdown and wants the weekly video, or says "changelog video". Self-contained — fonts, background, lexicon, and scripts ship in this skill.

AlessandroFare/fluxychat

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

AlessandroFare/fluxychat

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

AlessandroFare/fluxychat

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

AlessandroFare/fluxychat

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

AlessandroFare/fluxychat

Use when a HyperFrames composition needs seek-safe 2D/3D keyframes, GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

AlessandroFare/fluxychat

GATEWAY — load FIRST before composing any HyperFrames animation or video. The high-level motion law that makes a multi-scene video feel like ONE continuous camera move instead of a stack of independently-animated slides. Covers the vector law (how you exit determines how you enter, incl. the Z scale-sign rule), the film's current, carrier elements, causal motion, the Seam Gate (build-gate enforcement), the ban on idle wobble (motion must PERFORM, not breathe), stillness-before-climax, and the sustained-motion routes. Routes to the low-level technique skills (cut-the-curve — the full catalog incl. waterfall entry + nudge curve, oversized-cursor, seam-craft). These rules SUPERSEDE generic / upstream motion guidance. [continuity, direction, vector, momentum, seam, transition, ease, performance, idle-motion, narrative-motion, film-grammar]

AlessandroFare/fluxychat

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

AlessandroFare/fluxychat

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

AlessandroFare/fluxychat

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

AlessandroFare/fluxychat

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

AlessandroFare/fluxychat

Design and improve user interfaces using the concrete rules from Refactoring UI (Wathan & Schoger) — constrained spacing/type/color/shadow scales, visual hierarchy through weight and color rather than size, and depth through emulated light. Use when building or styling any UI (web, app, dashboard, landing page, component), when picking font sizes, spacing, colors, shadows or border radius, when designing a color palette or design tokens, and whenever someone says a UI "looks off", "looks amateur", "feels cluttered/plain/unfinished", or asks to "make this look better".

AlessandroFare/fluxychat

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

AlessandroFare/fluxychat

Use before UI-related work to select the smallest useful UI Skills context through the ui-skills CLI.

相关技能