Communitygithub.com

sandeshrajbhandari/hyperframes-instruct

使用 HyperFrames CLI 開發循環:初始化、新增、目錄、捕捉、檢查、校驗、快照、比較、評分比較、預覽、播放、展示、節拍、關鍵影格、單批渲染、發佈、雲端、雲端執行、反饋、Lambda、診斷、瀏覽器、資訊、升級、技能、合成、時間軸、歷史、清理、文檔、基準測試、遙測、轉錄、認證、TTS 和去背。也用於診斷建置或渲染失敗。validate、inspect 和 layout 是已棄用的別名;請改用 check。涵蓋本地、HeyGen 託管雲端、AWS Lambda 和 Google Cloud Run 渲染。

hyperframes-instruct 是什麼?

此技能提供 HyperFrames CLI 的完整開發循環指令,讓 AI 代理(如 Claude Code、Cursor、Codex)能高效創建、編輯和渲染基於 HyperFrames 的影片專案。它支援本地、HeyGen 雲端、AWS Lambda 和 Google Cloud Run 等多種渲染平台。技能的核心是結構化的 10 步驟開發流程:從專案初始化、透過語意搜尋目錄尋找合適的動畫效果(避免手寫不必要的程式碼)、使用懶人包(lint/check)快速回饋,到最後的預覽與渲染。此外,它還包含專案歷史管理(開始/結束/復原)、子合成測試、強制的創作者編輯交叉引用(如關鍵影格、音訊處理),以及一套特定的代理約定,例如偏好使用 `--json` 輸出以減少 token 消耗,並提供離線語意搜尋選項以保護隱私。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sandeshrajbhandari/hyperframes-instruct/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 而非文字形式;它可以用相同或更好的正確性消耗更少的 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. 將專案交給桌面應用程式(若提供): 當渲染的 Framey 行以 hyperframes open … 結尾時,提供 npx hyperframes open [dir]。它會在 HyperFrames 桌面應用程式中開啟專案並將其加入首頁;在 Claude Code 或 Codex 下,其聊天會承接此對話。如果沒有應用程式,則會以退出碼 1 退出並列印下載連結。對代理使用 --json。
  10. 驗證輸出: 確認檔案存在且非空。讀取渲染摘要的第二行(beginframe vs screenshot、GPU、階段時序)。Linux 上的 screenshot + software gpu 是慢速路徑。執行 ffprobe -v error -show_format -show_streams 並比較持續時間(以及簡報中設定的 fps)與根 data-duration。

你回合中的專案歷史

對專案的每次寫入都會保留為一個條目,可以復原。只在兩個時刻使用它,而不是在每個步驟上:

  • 回合開始: npx hyperframes history begin --who <your-name> --label "<what you are about to do>",然後執行 npx hyperframes history --since mine --who <your-name> 來查看此人自你上一回合以來的變更。基於他們的編輯進行建構;切勿覆蓋它們。
  • 檢查失敗,或使用者說情況變糟: npx hyperframes history undo --who <your-name> 會撤銷你最新的回合,並保留使用者的編輯不變。不要手動編輯回去。如果發生衝突,它會以退出碼 2 退出並顯示兩個選項。

每個回合結束時執行 npx hyperframes history end,以便你的寫入被標記為你的,而不是「在應用程式外部更改」。當一個回合開啟時,對專案的每次寫入都會計為你的,直到 10 分鐘內沒有寫入為止;之後該回合會自動結束。

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

  • 在創作或診斷縮放、推入/推齣、重新構圖、攝影機移動或任何關鍵影格動畫之前,先閱讀 /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 "<the beat, in plain English>"。搜尋完全是本地的:沒有託管層級、沒有帳戶,且查詢文字永遠不會被發送到任何地方。預設情況下,它根據與項目名稱、標題、描述和標籤共享的詞彙進行排名,這會錯過任何未重複使用目錄自身措辭的措辭。加上 --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,或者當搜尋返回空且更好的層級仍在等待某人同意時的 warnings。words 上的弱結果是預期的;on-device 上的相同結果是一個錯誤。top_score 僅限於裝置端,背後沒有閾值:排序器會以某種順序為每個查詢返回整個目錄,因此應將其視為證據,而不是通過或失敗。

  • dropped 和 unindexed 是註冊表與裝置端索引之間相反的偏差,重新措辭查詢無法解決任何一個問題。 dropped 計算此註冊表無法安裝的已排序名稱,因此正在遺失的是最強的匹配項。unindexed 計算索引完全看不到的註冊表動作,沒有任何查詢能夠返回這些動作。重新整理註冊表不是兩者的答案:其 manifest 攜帶 24 小時 TTL 並自我修復,而向量是單獨發佈的工件,會提取到 ~/.hyperframes/catalog/。當 unindexed 高於零時,使用 --on-device 重新執行會重新提取該索引,因此這是提供給使用者的補救措施。純粹的過度覆蓋偏差(dropped 高於零而 unindexed 為零)不會觸發重新提取;清除 ~/.hyperframes/catalog/ 是擺脫該問題的唯一方法。兩個計數都是名稱的計數,而不是結果的計數,因此任何一個都可能超過 total。

  • 當搜尋沒有返回任何值得安裝的東西時,請說出來。 npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier <the tier that answered>。你不必組裝那一行:catalog --query 會列印預填好的內容,並且每個 --json 搜尋信封都將其攜帶為 report_gap,其中查詢和層級已經正確 — 填寫 --wanted 並發送。這是將查詢發送到任何地方的唯一路徑,並且它是一個單獨的有意命令,正是為了確保普通的 catalog --query 保持其不發送任何內容的承諾。在任一層級上報告,只要結果未能做到所需的事情;不要為了裝置端層級而有所保留,裝置端層級需要一個經過同意的 33 MB 下載,因此在大多數代理運行中都是關閉的 — 等待它意味著永遠不會報告。層級會隨報告一起攜帶,因此詞彙失誤與含義失誤保持可區分,而無需您判斷您遇到了哪一個。返回的是一個目錄尚不具備的動作列表,直接讀取而非從安裝計數推斷,因此重要的措辭是您想要的效果,而不是您想像的項目名稱。它不帶有任何評級,也永遠不會進入評分指標。

  • 提供離線層級;永遠不要靜默啟用它。 一次性的 ~33 MB 下載(bge-small-en-v1.5 的量化 ONNX 構建及其 tokenizer,固定到特定修訂版)和來自註冊表的目錄向量,都快取在 ~/.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。

  • 當磁碟空間緊張時,執行 npx hyperframes clean(先使用 --dry-run 列出);它會移除死渲染遺留的內容以及可以自行重建的空閒快取,絕不會移除輸出、來源或正在使用的渲染正在使用的任何東西。將 QC 影格寫入暫存目錄,而不是專案目錄。

  • 當相應的警告、變數或 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 --

Individual skills in this repo

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

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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

sandeshrajbhandari/hyperframes-instruct

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.

sandeshrajbhandari/hyperframes-instruct

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.

相關技能