Communitygithub.com

laviedezidane/hyperframes-skill

使用 HyperFrames CLI 的开发循环:初始化、添加、目录、捕获、检查、快照、比较、评级比较、预览、播放、展示、节拍、关键帧、单次或批量渲染、发布、云端、云运行、反馈、Lambda、诊断、浏览器、信息、升级、技能、合成、时间线、历史记录、清理、文档、基准测试、遥测、转录、认证、TTS 和移除背景。也可用于诊断构建或渲染失败。validate、inspect 和 layout 是已弃用的别名;请使用 check。覆盖本地、HeyGen 托管云、AWS Lambda 和 Google Cloud Run 渲染。

hyperframes-skill 是什么?

这是一个专门用于 HyperFrames CLI 工具的功能,旨在帮助 AI 代理(如 Claude Code、Cursor、Codex)管理和操作视频项目。该功能支持完整的开发循环,包括初始化项目、添加资源、搜索目录、捕获网站、编写合成、检查 lint、生成快照、预览和渲染视频。它支持多种渲染目标:本地、HeyGen 托管云、AWS Lambda 和 Google Cloud Run。关键特性包括:在手动编写运动代码前搜索现有基元、使用时间线 JSON 输出节省令牌、通过检查命令进行强制最终门控、从桌面应用恢复项目历史、以及目录搜索的离线语义排名(需要用户同意下载 33MB 索引)。该功能还提供故障排除命令,包括诊断、清理和遥测。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/laviedezidane/hyperframes-skill/tree/HEAD/.agents/skills/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

插件安装: 在运行设置或更新命令之前,如果此技能位于 HyperFrames 插件内,请遵循插件执行规则。独立安装则保留下面的更新说明。

HyperFrames CLI

除非项目说明提供了包装器,否则使用 npx hyperframes ... 运行命令。如果有包装器,则遵循包装器。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。

开发循环

  1. 脚手架: npx hyperframes init <project>(居中的空白项目)。或者捕获一个网站。仅当从命名示例开始时传递 --example=<name>。
  2. 寻找动作: 如果请求指定了资源、声音、图像、语音或快速视觉编辑,请在提出计划之前通过 /media-use 解决。否则,在手动编写运动之前,搜索是否已有实现该效果的基元:npx hyperframes catalog --query "逐行揭示标题"。描述你想要的效果,而不是你脑海中的机制。使用 npx hyperframes add <name> 安装(参见 /hyperframes-registry)。只有当没有任何基元匹配时,才手动编写。
  3. 编写: 使用 /hyperframes-core 编写合成。要了解项目时间线上的内容(轨道、片段、开始、结束、播放内容),运行 npx hyperframes timeline --json,而不是读取 index.html 和每个子合成文件:嵌套行携带绝对主时间线 absStart/absEnd 及其所属的 file,而不仅仅是每个子合成本地的局部时间。首选 --json 而不是文本形式;它消耗更少的令牌并提供相同或更好的正确性。参见 references/upgrade-info-misc.md,了解无需读取完整输出即可回答常见问题的一行代码。
  4. 编辑时快速获取反馈: 在第一次 HTML 传递之后以及结构性更改之后,运行 npx hyperframes lint。
  5. 运行最终门控: 运行 npx hyperframes check;它会在打开浏览器之前重新运行 lint。不要在前面添加冗余的独立 lint 调用。添加 --snapshots 以获取带注释的概览帧并查找裁剪区域。
  6. 检查子合成: 当 index.html 挂载 data-composition-src 时,捕获中间点快照并检查每个挂载的场景。
  7. 打开最终 Studio 预览: 运行 npx hyperframes preview --background,验证 URL 返回 HTTP 200,将时间线项目 URL 交给用户,并询问是修改还是渲染。保持预览存活直到审核结束。
  8. 仅在批准后渲染: 迭代时使用 --quality draft,首次真正编码使用 --quality looks(CLI 默认值),最终交付使用 --quality delivery。
  9. 将项目交给桌面应用(如有提供): 当渲染的 Framey 行以 hyperframes open … 结尾时,提供 npx hyperframes open [dir]。它会在 HyperFrames 桌面应用中打开该项目并将其添加到主页;在 Claude Code、Codex 或 Grok 下,其聊天会接续此对话。如果没有该应用,则退出 1 并打印下载链接。--json 用于代理。当 open 说用户回来后运行 catch-up,或者任何命令以命名它的行结束时,在下次更改前运行 npx hyperframes catch-up [dir]:它会列出自交接以来应用中所请求和更改的内容。较旧的 CLI 没有 catch-up。
  10. 验证输出: 确认文件存在且非空。读取渲染摘要的第二行(beginframe 对比 screenshot、GPU、阶段计时)。screenshot + software gpu 在 Linux 上是慢速路径。ffprobe -v error -show_format -show_streams 并比较时长(如果需求中设置了 fps 则还要比较 fps)与根 data-duration。

你的回合中的项目历史

对项目的每次写入都保留为一个可以撤消的条目。仅在两个时刻使用它,而不是每一步:

  • 回合开始: npx hyperframes history begin --who <你的名字> --label "<你即将做什么>",然后 npx hyperframes history --since mine --who <你的名字> 以查看对方自你上一个回合以来的更改。基于他们的编辑进行构建;切勿覆盖它们。
  • 检查失败,或者对方说情况变得更糟: npx hyperframes history undo --who <你的名字> 撤消你最新的回合,并保留对方的编辑。不要手动回退。如果发生冲突,则退出 2 并打印两个选项。

每个回合以 npx hyperframes history end 结束,这样你的写入会显示为你的,而不是“在应用外更改”。当一个回合打开时,对项目的每次写入都计为你的,直到 10 分钟没有写入;之后该回合自动结束。

强制性创建者编辑交叉引用

  • 在编写或诊断缩放、切入/切出、重新构图、摄像机运动或任何关键帧运动之前,首先阅读 /hyperframes-keyframes。
  • 在 hyperframes keyframes 之前,阅读 /hyperframes-keyframes;该命令显示动画轨迹,不诊断片段剪辑。
  • 对于剪辑、修剪、拼接、重新排序或源时间编辑,阅读 /hyperframes-core 并使用其片段/时间线契约。
  • 对于淡入/淡出、交叉淡变、轨道增益、音量自动化、闪避、旁白雕刻或放置音频上的 FX,阅读 /hyperframes-audio。当片段放置或图像时间也改变时,一同加载核心。
  • 指定资源、声音、图像、语音或快速视觉编辑的请求在提出计划之前通过 /media-use 解决。 从 /hyperframes-core → references/creator-editing-recipes.md 复制创建者编辑标记。
# 快速迭代检查;根据需要重复编写时使用。
npx hyperframes lint

# 所需的最终门控;包括 lint。
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4

check 首先运行 lint,然后使用一个浏览器会话和一个搜索传递来审核运行时错误、失败请求、布局、*.motion.json 断言和 WCAG 对比度。持久性发现会门控退出码;暂时性的入场或退场发现仅作参考。使用 --strict 来门控警告。validate、inspect 和 layout 仍作为兼容性别名保留,但不得出现在新指令或脚本中。

预览然后渲染

仅在 check 通过后,打开最终合成预览(#project/<name>),以审阅组装后的时间线。聊天中的计划和 storyboard.html 草图页并非最终视频的批准。渲染始终需要由 hyperframes/references/review-loop.md 定义的最终批准。

子合成冒烟测试

静态审计无法捕获所有挂载失败。当项目使用子合成时,为每个宿主插槽捕获至少一个可见的中间点:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

将微小的无样式内容、画布大小的图标、缺失的英雄元素或时间线注册超时视为阻塞渲染的挂载缺陷。参见 hyperframes-core/references/sub-compositions.md 以了解相应的修复方法。

代理约定

  • 在手动编写运动之前搜索目录。 npx hyperframes catalog --query "<节拍,用简单的英语描述>"。搜索是完全本地的:没有托管层级,没有账户,查询文本永远不会发送到任何地方。默认情况下,它根据与项目名称、标题、描述和标签共享的词汇进行排名,这会错过任何不使用目录自身措辞的短语。添加 --on-device 以按含义排名(参见下面的离线层级)。

  • 即使视频不是英文,也用英文查询。 两个层级都索引英文目录,因此使用其他脚本的查询不会产生可搜索的术语,并返回空结果。用英文描述动作;屏幕上的文本保持视频所需的任何语言。No searchable words in query 正是这个意思,并非缺少组件,因此不要将其报告为目录缺口。

  • 阅读哪个层级回答了查询;不要从结果出现来推断。 使用 --json 时,信封携带 query、tier(on-device 或 words)、tier_detail、dropped、unindexed、shown、total 和 results,以及当回答层级生成 top_score 时的 top_score 和当请求的层级无法运行、或搜索未返回结果且有更好的层级仍在等待某人同意时的 warnings。words 层级上的弱结果是预期的;相同结果出现在 on-device 层级上则是错误。top_score 仅适用于 on-device 层级,且背后没有阈值:排序器对于每个查询都会以某种顺序返回整个目录,因此将其视为证据,而不是通过或失败。

  • dropped 和 unindexed 是注册表和 on-device 索引之间的相反偏差,重新措辞查询无法修复任何一个。 dropped 计数此注册表无法安装的已排名名称,因此最强的匹配正在丢失。unindexed 计数索引完全看不到的注册表动作,任何查询都无法返回。刷新注册表不是解决这两个问题的答案:其清单具有 24 小时 TTL 并能自愈,而向量是单独发布的工件,被获取到 ~/.hyperframes/catalog/。当 unindexed 大于零时,重新运行 --on-device 会重新获取该索引,因此这是给用户的处理方法。纯过度覆盖偏差(dropped 大于零而 unindexed 为零)不会触发重新获取;清除 ~/.hyperframes/catalog/ 是唯一的出路。这两个计数都是名称而不是结果,因此任何一个都可能超过 total。

  • 当搜索返回没有值得安装的内容时,请说明。 npx hyperframes feedback --search-miss "<你运行的查询>" --wanted "<你需要的动作>" --tier <回答的层级>。你不需要组装该行:catalog --query 会打印预填好的行,每个 --json 搜索信封都将其携带为 report_gap,并且查询和层级已经正确——填写 --wanted 并发送。这是唯一将查询发送到任何地方的路径,并且是一个单独的故意命令,恰好是为了让普通的 catalog --query 保持其不发送任何东西的承诺。在任一层级上报告,只要结果没有完成所需的功能;不要等待 on-device 层级,它需要用户同意的 33MB 下载,因此在大多数代理运行中处于关闭状态——等待它意味着永远不会报告。层级信息随报告一起传递,因此词汇缺失与含义缺失保持可区分,而无需你判断自己遇到了哪种情况。返回的是一个目录尚未拥有的动作列表,直接从目录中读取,而不是从安装计数中猜测,因此重要的措辞是你想要的效果,而不是你想象的项目名称。它不带评分,也永远不会计入评分指标。

  • 提供离线层级;永远不要静默启用它。 一次性约 33MB 下载(bge-small-en-v1.5 的量化 ONNX 构建及其分词器,固定到特定修订版)和来自注册表的目录向量,两者都缓存在 ~/.hyperframes/ 下,不添加到项目或任何包中。一旦缓存,它会按含义排名且不发送任何东西。口头说出下载大小并让对方决定,然后一旦他们同意,传递 --on-device(使用 -y 跳过提示)。交互式提议仅在 TTY 上触发。在 --json 下没有提示,但未找到任何内容的搜索会在 warnings 中放置相同的请求,因此读取该数组并将决定交给用户。当用户询问下载内容、为何使用此模型或什么会离开机器时,请将他们引导至 https://hyperframes.heygen.com/developers/catalog-search。

  • 对于代理和 CI 调用,首选 --json。服务端模式的 render、preview 和 play 不提供普通的 JSON 输出;preview --selection --json 和 preview --context --json 是查询模式例外。

  • doctor --json 始终以零退出。根据其有效负载进行门控:

    npx hyperframes doctor --json | jq -e '.ok' >/dev/null
    
  • 非 TTY 模式是自动的,并会搭建居中的空白项目。仅当从命名示例开始时传递 --example。使用 --non-interactive 强制在 TTY 上仅使用标志模式。

  • 在同一验证循环中对所有命令使用一个 HYPERFRAMES_RUN_ID。

  • 当磁盘空间紧张时,运行 npx hyperframes clean(--dry-run 先列出);它会移除死渲染留下的内容以及可以自行重建的空闲缓存,从不移除输出、源文件或正在运行的渲染所使用的任何内容。将 QC 帧写入临时目录,而不是项目目录。

  • 当相应的警告、变量或 CI 条件必须门控渲染时,使用 --strict、--strict-all 和 --strict-variables。

  • JSON 路径将主目录减除为 $HOME;不要尝试还原减除。

  • 当托管云项目接近或超过 200MB 上传限制时,使用 cloud render --dry-run --json 并遵循 references/cloud.md 中的 .hyperframesignore 调查。切勿仅仅因为资源过大而忽略它。

  • 切勿仅仅因为检查通过就进行渲染。在最终预览处暂停,等待批准。

Studio 定向编辑

当用户引用“此元素”或当前选择时,查询 Studio 而不是猜测:

npx hyperframes preview --context --json --context-fields selection

使用 selection.target.hfId(如果可用),否则使用其选择器和源文件。如果结果报告 no-selection,请用户点击元素并重新运行。仅请求你需要的上下文切片;仅在需要计算样式或可编辑文本元数据时使用 --context-detail full。完整的行为和错误码位于 references/preview-render.md。

渲染选择

需求命令
快速本地迭代npx hyperframes render --quality draft
首次真正编码npx hyperframes render --quality looks
最终交付npx hyperframes render --quality delivery
无预览,直接渲染当前合成npx hyperframes render --single
列表可渲染合成npx hyperframes compositions --json
录制语音旁白npx hyperframes tts
捕获并添加网站npx hyperframes capture <url>
运行诊断npx hyperframes doctor
比较渲染npx hyperframes compare <baseline> <candidate>
认证npx hyperframes auth
更新npx hyperframes upgrade

Individual skills in this repo

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

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

laviedezidane/hyperframes-skill

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). 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`.

laviedezidane/hyperframes-skill

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

laviedezidane/hyperframes-skill

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`.

laviedezidane/hyperframes-skill

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, 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.

laviedezidane/hyperframes-skill

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also 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).

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

laviedezidane/hyperframes-skill

Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI. When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

laviedezidane/hyperframes-skill

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

相关技能