Communitygithub.com

HyperFrames CLI 技能包

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

HyperFrames CLI 技能包 是什么?

该技能封装了 HyperFrames CLI 的完整开发工作流,帮助开发者和 AI 代理高效地创建、迭代和渲染基于超帧的视频合成。它支持本地和多种云渲染目标,包括 HeyGen 托管云、AWS Lambda 和 Google Cloud Run。技能强调严格的验证流程,包括 lint 和 check 命令,确保最终渲染前捕获所有错误。此外,它还提供 Studio 集成、子合成烟雾测试、批处理、反馈收集和基于上下文的编辑查询,适合从快速原型到生产级交付的多种场景。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dbillion/hermes-skills-public/tree/HEAD/skills-external/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

HyperFrames CLI

通过 npx hyperframes ... 运行命令,除非项目说明提供了包装器。当包装器存在时,请遵循它。CLI 需要 Node.js 22 或更新版本以及 FFmpeg。

开发循环

  1. 脚手架: npx hyperframes init <项目> 或捕获网站。在非 TTY 模式下,传递 --non-interactive --example=<名称>。
  2. 创作: 使用 /hyperframes-core 编写合成。
  3. 编辑时获取快速反馈: 在第一次 HTML 传递后和结构更改后运行 npx hyperframes lint。
  4. 运行最终关卡: 运行 npx hyperframes check;它会在打开浏览器之前重新运行 lint。不要预先添加多余的独立 lint 调用。添加 --snapshots 以获取带注释的概览帧和查找裁剪。
  5. 检查子合成: 当 index.html 挂载 data-composition-src 时,捕获中点快照并检查每个挂载的场景。
  6. 打开最终 Studio 预览: 运行 npx hyperframes preview,将时间线项目 URL 交给用户,并询问是修改还是渲染。
  7. 仅在批准后渲染: 迭代使用草稿质量,交付使用高质量。
  8. 验证输出: 确认文件存在、非空且具有合理的持续时间。
# 快速迭代检查;在创作过程中根据需要重复。
npx hyperframes lint

# 必需的最终关卡;包含 lint。
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4

check 首先运行 lint,然后使用一个浏览器会话和一次查找传递来审计运行时错误、失败的请求、布局、*.motion.json 断言和 WCAG 对比度。持久性发现会阻塞退出码;瞬态进入或退出发现仅供参考。使用 --strict 来阻塞警告。validate、inspect 和 layout 仍然是用于兼容性的别名,但不得出现在新指令或脚本中。

两种不同的预览界面

不要混淆这些状态:

界面可能打开的时间目的
故事板在合成检查之前,仅当 storyboard: yes 时审查计划卡和线框图。打开 ?view=storyboard#project/<名称>。
最终合成预览在 check 通过后在渲染前审查组装好的时间线。打开 #project/<名称>。

早期故事板不是最终视频的批准。渲染始终需要 hyperframes-core/references/review-loop.md 定义的最终批准。

子合成烟雾测试

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

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

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

代理约定

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

  • doctor --json 总是以零退出。根据其有效载荷进行判断:

    npx hyperframes doctor --json | jq -e '.ok' >/dev/null
    
  • 非 TTY 模式是自动的。在那里 init 需要 --example;在 TTY 上使用 --non-interactive 来强制确定性行为。

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

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

  • JSON 路径会将 home 目录编辑为 $HOME;不要试图反转编辑。

  • 永远不要仅仅因为检查通过就渲染。在最终预览处暂停并等待批准。

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 high --output out.mp4
可重现的容器渲染npx hyperframes render --docker --strict --output out.mp4
本地变量驱动的批量渲染npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
HeyGen 托管的零基础设施渲染npx hyperframes cloud render
自管理的分布式 AWS 渲染npx hyperframes lambda render <项目> --width 1920 --height 1080 --wait
自管理的分布式 GCP 渲染npx hyperframes cloudrun render <项目> --width 1920 --height 1080 --wait

当用户希望在没有本地 Chrome、FFmpeg 或 AWS 的情况下进行托管渲染时,使用云渲染。仅当需要对 AWS 的所有权时,才使用 Lambda。仅当需要对 GCP 的所有权时,才使用 Cloud Run。在运行任何云路径之前,请阅读匹配的参考。

验证渲染成功后,发送一份反馈报告,除非遥测已禁用或用户已选择退出:

npx hyperframes feedback --rating <0-10> --comment "<具体结果或摩擦>"

保持干净运行的反馈简洁。对于任何错误或摩擦,在提交之前捕获一个重现包;不要只发送症状摘要。包括可重新运行的命令和工作目录、预期行为与实际行为、确切错误、输出是否完成/回退/失败、解决方法以及重现项目状态。如果问题没有再次重现,说明情况并仍然包括上次失败的命令和日志。仅在有同意时使用 --file-issue:它会将最小重现发布到公共 URL。必需的包格式和隐私警告位于 references/preview-render.md。

在运行命令之前阅读匹配的参考

以下参考和所属技能是强制性的命令契约,不是可选的背景阅读。在运行表中的命令之前,请阅读其对应的行。

需求参考
init、capture、skillsreferences/init-and-scaffold.md
lint、check、动作 sidecar、snapshotreferences/lint-validate-inspect.md
compare、grade-compare、变量驱动的 render --batchreferences/compare-and-batch.md
现有项目 Studio 节拍网格的 beatsreferences/beats.md
preview、play、render、publish、Studio 上下文、反馈references/preview-render.md
doctor、浏览器管理references/doctor-browser.md
auth、HeyGen 托管的云渲染和模板变量references/cloud.md
AWS Lambda 部署和渲染references/lambda.md
Google Cloud Run 部署和渲染references/cloudrun.md
info、upgrade、compositions、docs、benchmark、遥测、媒体预处理references/upgrade-info-misc.md

对于合成变量,也请阅读 /hyperframes-core → references/variables-and-media.md。对于 hyperframes add 和 hyperframes catalog,请使用 /hyperframes-registry。在 hyperframes present 之前,阅读 /slideshow;在 hyperframes keyframes 之前,阅读 /hyperframes-keyframes。对于 TTS、转录、字幕或背景移除选项,请使用 /media-use。

专用命令由其所属工作流明确记录:

npx hyperframes present <项目目录> --port 3004 --no-open
npx hyperframes beats <项目目录> --json
npx hyperframes keyframes <项目目录> --json

present 提供一个可导航的演示文稿,带有演示者和观众同步。beats 是独立的 Studio 节拍网格工具,定义在 references/beats.md 中。keyframes 展示搜索安全的动画和运动路径诊断。

Individual skills in this repo

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

dbillion/hermes-skills-public

Edit an existing image based on a text prompt.

dbillion/hermes-skills-public

Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.

dbillion/hermes-skills-public

Expert in video composition, editing, and format conversion. Use when the user wants to generate high-quality video, overlay images on video, concatenate clips, create GIFs, or sync audio to video using mcp-avtool-go and mcp-veo-go.

dbillion/hermes-skills-public

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.

dbillion/hermes-skills-public

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. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

dbillion/hermes-skills-public

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

相关技能