Communitygithub.com

1999AZZAR/designer-mcp

使用 HyperFrames CLI 開發循環:init、add、catalog、capture、lint、check、snapshot、compare、grade-compare、preview、play、present、beats、keyframes、單一或批次渲染、publish、cloud、cloudrun、feedback、lambda、doctor、browser、info、upgrade、skills、compositions、timeline、docs、benchmark、telemetry、transcribe、auth、tts 和 remove-background。也可用於診斷建置或渲染失敗。validate、inspect 和 layout 為已棄用的別名;請改用 check。涵蓋本機、HeyGen 託管雲端、AWS Lambda 和 Google Cloud Run 渲染。

designer-mcp 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的技能,旨在透過 HyperFrames CLI 提供完整的影片創作、編輯與渲染工作流程。該技能的核心是引導代理遵循一個結構化的開發循環:從專案初始化(init)、素材管理(catalog、add)、編寫合成(composition)、快速回饋(lint、check)、預覽(preview)到最終渲染(render),涵蓋多種品質設定與部署目標(本機、HeyGen 雲端、AWS Lambda、Google Cloud Run)。它強調在手動編寫動畫之前,優先搜尋現有素材庫(catalog),並透過結構化的 JSON 輸出與快照(snapshot)來進行高效除錯與驗證。此技能支援 HeyGen Studio 的上下文編輯、批次渲染、子合成測試,並包含詳細的代理慣例,例如使用 `--on-device` 進行離線語意搜尋、透過 `feedback` 回報搜尋缺失,以及自動化歸因於創建專案的工作流程。

相容平台~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;它消耗較少的 tokens,但能達到相同或更好的正確性。請參閱 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 vs screenshot、GPU、階段時間)。screenshot + software gpu 在 Linux 上為慢速路徑。執行 ffprobe -v error -show_format -show_streams 並將持續時間(以及如果簡報有設定的 fps)與根目錄的 data-duration 進行比較。

強制性創作者編輯交叉引用

  • 在編寫或診斷縮放、切入/切出、重構圖、攝影機移動或任何關鍵幀動作之前,請先閱讀 /hyperframes-keyframes。
  • 在執行 hyperframes keyframes 之前,請先閱讀 /hyperframes-keyframes;該命令顯示動畫軌跡,且不診斷片段剪輯。
  • 對於剪輯、修剪、拼接、重新排序或來源時間編輯,請閱讀 /hyperframes-core 並使用其片段/時間軸合約。
  • 對於淡入/淡出、交叉淡入淡出、軌道增益、音量自動化、閃避、畫外音雕刻或對已放置音訊套用效果,請閱讀 /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 層級則是一個錯誤。top_score 僅限於 on-device 層級,並且其背後沒有閾值:排序器會為每個查詢返回整個目錄(按某種順序),因此請將其視為證據,而不是通過或失敗的標準。

  • dropped 和 unindexed 是註冊表與 on-device 索引之間的相反偏差,改寫查詢無法解決任何一個。 dropped 計算此註冊表無法安裝的已排序名稱,因此正在遺失的是最強的匹配項。unindexed 計算索引完全無法看到的註冊表動作,任何查詢都永遠無法返回它們。刷新註冊表不是這兩種情況的答案:其 manifest 帶有 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 總是退出並返回 0。根據其負載內容設定閘門:

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 "<具體結果或摩擦點>"

保持乾淨執行的回饋簡潔。對於任何錯誤或摩擦,請在提交前捕獲一個重現包;不要僅發送症狀摘要。包括可重新執行的命令(相對於專案目錄 — 回饋會提交到公共頻道,因此不要貼上絕對路徑、家目錄前綴或用戶/機器識別碼)、預期行為與實際行為、確切的錯誤訊息(也請去掉絕對路徑...)

(基於 [原文截斷] 進行翻譯)

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.

相關技能