Communitygithub.com

1999AZZAR/designer-mcp

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

designer-mcp 是什么?

该技能为 AI 代理(如 Claude Code、Cursor、Codex 等)提供了完整的 HyperFrames CLI 操作指南。它定义了一个结构化的开发循环,涵盖从项目脚手架搭建(init)、通过编目和添加数据块来查找动态效果、使用核心 API 编写合成、快速反馈(lint、check、snapshot)到最终预览和渲染(本地或云端)的全流程。该技能强制要求在编写自定义动态效果前先搜索目录,并详细说明了代理约定的关键细节,例如使用 `--json` 进行高效交互、理解目录搜索的不同层级(words 与 on-device)、以及通过 `feedback` 命令正确报告搜索遗漏。它支持多种渲染后端:本地、HeyGen 托管的云端、AWS Lambda 和 Google Cloud Run,并提供了每个后端的命令参考。此外,它还包含了强制性的创作者-编辑交叉引用,确保在处理变焦、音频编辑、关键帧和时间线操作之前,AI 代理会阅读相关的参考文档。该技能旨在提高使用 HyperFrames 工具生成视频内容的 AI 代理的效率和正确性,减少因幻觉或信息缺失导致的错误。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1999AZZAR/designer-mcp/tree/HEAD/skills/video/engine/hyperframes-cli

在你喜欢的 AI 中提问

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

文档

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 而非文本形式;对于相同或更好的正确性,它消耗更少的 token。请参阅 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. 验证输出: 确认文件存在且非空。读取渲染摘要的第二行(beginframe 与 screenshot、GPU、阶段时序)。Linux 上的 screenshot + software gpu 是慢路径。运行 ffprobe -v error -show_format -show_streams 并比较时长(如果简报设置了 fps)与根元素的 data-duration。

强制性创作者-编辑交叉引用

  • 在编写或诊断变焦、推近/拉远、重新构图、摄像机运动或任何关键帧运动之前,首先阅读 /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 根据含义进行排名(请参阅下面的离线层)。

  • 即使视频不是英文,也用英文查询。 两个层都为英文目录建立索引,因此使用其他语言的查询不会产生可搜索的词汇并返回空结果。用英文描述运动效果;屏幕上的文字保持在视频所需的任何语言。查询中没有可搜索的词汇 正是此意,而不是组件缺失,所以不要将其报告为目录缺口。

  • 阅读哪个层回答了问题;切勿从结果的出现来推断。 使用 --json 时,信封携带 query、tier(on-device 或 words)、tier_detail、dropped、unindexed、shown、total 和 results,以及当回答层产生时附带 top_score,和当请求某个层但无法运行时,或者搜索返回空而更好的层仍在等待某人同意时附带 warnings。words 层上出现较弱的结果是预期的;同样的结果出现在 on-device 层上则是一个 bug。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 层,该层需要同意的 33 MB 下载,因此在大多数代理运行中默认是关闭的——等待它意味着永远不会报告。层信息会随报告一起传递,因此词汇匹配失败与含义匹配失败的区别仍然可辨识,无需你自行判断遇到了哪一种。返回的是一个目录尚未拥有的运动效果列表,直接从安装计数中读取,而不是猜测,因此重要的措辞是你想要的效果,而不是你想象的项目名称。它不携带任何评级,也永远不会进入评级指标。

  • 提供离线层;切勿静默启用它。 一次性约 33 MB 下载(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 始终以零退出。根据其 payload 进行关卡判断:

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

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

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

  • JSON 路径将家目录替换为 $HOME;不要尝试逆转此替换。

  • 当托管云端项目接近或超过 200 MB 上传限制时,使用 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 --output out.mp4
最终本地交付npx hyperframes render --quality delivery --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 <project> --width 1920 --height 1080 --wait
自我管理的分布式 GCP 渲染npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait

技能归属是自动的——上面的示例不需要 --skill。由工作流搭建的项目(hyperframes init --skill=<workflow>)会将其所属技能记录在 hyperframes.json 中,并且以后的每次渲染(重新渲染、npm run render 和 --batch)都会通过匿名遥测继承它。仅当要标记一个非通过工作流创建的项目时,显式传递 --skill=<slug>(其首次渲染将持久化该技能)。

当用户想要托管的渲染而不需要本地 Chrome、FFmpeg 或 AWS 时,使用云端渲染。仅当 AWS 所有权是要求时,使用 Lambda。仅当 GCP 所有权是要求时,使用 Cloud Run。在运行任何云端路径之前,阅读相应的参考文档。

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

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

保持干净运行的反馈简洁。对于任何 bug 或摩擦,在提交之前捕获一份复现包;不要只发送症状摘要。包括可重新运行的命令(相对于项目目录——反馈会提交到公共频道,因此不要粘贴绝对路径、家目录前缀或用户/机器标识符)、预期行为与实际行为、确切的错误(同时剥离绝对路径)

Individual skills in this repo

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

1999AZZAR/designer-mcp

SOTA animation and physics heuristic guide using motion.dev

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

Use when building or editing a HyperFrames project that people open in Studio: 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`.

1999AZZAR/designer-mcp

Agent Media OS, the single skill for every media need in 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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

相关技能