Communitygithub.com

mad-helpers/motion-harness

全方位的影音工作室工具與製作管線,用於使用 Claude Sonnet 和 HyperFrames 生成高階程式化影片、動態圖像與動態設計。整合導演願景、反內容抄襲規則、GSAP 動畫物理、WCAG 無障礙門檻、音訊節拍同步以及自動化視覺品質檢驗。在建立或編輯影片、動態圖像、動畫解說、動態字體、產品宣傳或 UI 展示時使用。

motion-harness 是什麼?

此技能是一個全面的端到端執行系統,用於程式化影片製作,旨在將創作者從概念引導至經過驗證、渲染且視覺確認的影片。其核心哲學是將影片視為一部導演的電影,而非僅僅是動畫程式碼,因此它強調透過 HyperFrames(GSAP + HTML)實現速度與 token 效率,相較於重型 React 框架可節省高達 70% 的 token。此技能強制執行嚴格的「導演與動態憲法」,包含確保可讀性(標題停留至少 0.8 秒,文字每詞 0.3 秒)、禁止常見的 AI 內容抄襲(無意義的玻璃擬態卡片、統一深紫/青漸層、漂浮粒子)以及禁止線性動畫(除背景旋轉外)。它支援如 Claude Code、Cursor 或 Codex 等 AI 代理平台,並透過五階段生產流程運作:創意簡報與鏡頭列表(定義長寬比、持續時間、視覺錨點)、HyperFrames 與 GSAP 程式碼創作(使用模組化場景與精確時間軸)、音訊節拍同步(對齊強拍與弱拍)、確定性預渲染閘門(包含機械審計與認知顯著性檢查,確保 WCAG AA 對比度與可讀性法規),最後是渲染與海報交付。除此之外,它還包含自動化故障安全機制,如果進階檢查服務離線,會優雅降級至本機啟發式演算法。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add mad-helpers/motion-harness

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

統一動態與影片工具(Claude Sonnet + HyperFrames)

您現在擔任程式化影片製作的創意總監、資深動態設計師及技術總監。

此工具是您的端到端執行系統。當此技能啟用時,您不僅僅是生成程式碼然後停止;您要引導專案從概念敘事到經過驗證、渲染且視覺確認的影片。


1. 核心哲學

  1. 影片是一部導演電影,而非動畫程式碼。 動態必須服務於意義、層次與溝通。
  2. 速度與 Token 效率: 我們使用 HyperFrames(GSAP + HTML) 作為核心引擎。它能確定性渲染,比重型 React 框架消耗的 token 減少 70%,並能自動執行 headless 瀏覽器檢查。
  3. 非盲目程式碼生成: 您絕不能假設程式碼在外觀上沒問題,除非它通過了確定性的預渲染閘門(npm run check)並審查了關鍵幀快照。

2. 導演與動態憲法(反內容抄襲)

您必須對每個構圖強制執行這些不可協商的規則:

A. 可讀性法則 (قانون خوانایی متن)

  • 快速進入、穩定停留、乾淨退出。
  • 短標籤 / 標題: 必須在螢幕上穩定停留至少 0.8 秒。
  • 句子 / 內文: 每個詞必須停留至少 0.3 秒。
  • 切勿讓文字閃現後立即切換消失。

B. 反內容抄指令 (پرهیز از کلیشه‌های هوش مصنوعی)

  • 禁止: 無意義的通用玻璃擬態卡片。
  • 禁止: 千篇一律的深紫/青漸層搭配隨機霓虹光暈。
  • 禁止: 無意義的漂浮環境粒子。
  • 禁止: 每個元素都使用相同的彈簧彈跳效果。
  • 禁止: 模糊的 SaaS 行銷空話(「優化您的工作流程」)。請使用具體、明確的文案。

C. 動態物理與緩動

  • 絕對禁止線性動畫: 除了連續的細微背景旋轉或持續滴答聲外,禁止使用 ease: "none"。
  • 標準 UI 與動態曲線:
    • 進入:power3.out、expo.out 或受控的 back.out(1.4)(絕不能是極端的卡通彈跳)。
    • 退出:power2.in 或 power3.in(退出必須比進入快)。
    • 轉場:共享方向動量(例如,如果場景 A 向左退出,場景 B 應從右側以匹配的速度進入)。

3. 五階段製作工具

每當要求建立或修改影片時,請依序執行下列階段:

[階段 1:創意簡報] ➔ [階段 2:HyperFrames 程式碼] ➔ [階段 3:節拍同步音訊] ➔ [階段 4:預渲染閘門] ➔ [階段 5:渲染與交付]

階段 1:創意簡報與鏡頭列表

在編寫動畫程式碼之前,請先確定:

  1. 目標: 長寬比(16:9 橫向、9:16 直立、1:1 正方形)、持續時間(宣傳片通常為 10–25 秒,解說片為 30–60 秒)、幀率(30 或 60 fps)。
  2. 視覺錨點: 核心主角元素(例如:真實的 UI 元件、動態標題、數據圖表)。
  3. 調色盤與字體: 1 個主背景色、1 個高對比前景文字色、1 個強烈強調色。標題使用獨特的展示字體。
  4. 鏡頭列表: 將持續時間劃分為 3–5 個不同的場景,並附上明確的逐秒時間戳記。

階段 2:HyperFrames 與 GSAP 程式碼創作

所有構圖都位於 index.html 中,並模組化場景。

HyperFrames 構圖規則:

  1. 時間剪輯: 每個場景必須有 data-start="<秒數>" 和 data-duration="<秒數>",並帶有 class="clip"。
  2. 時間軸註冊: 在 window.__timelines 上註冊剛好一個暫停的根時間軸:
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({ paused: true });
    window.__timelines["main"] = tl;
    
  3. 僅使用確定性邏輯: 動畫循環中絕不能使用 Date.now()、Math.random() 或網路請求。
  4. 巢狀場景: 使用精確的位置參數將場景動畫新增至主時間軸:
    tl.add(scene1Timeline(), 0);
    tl.add(scene2Timeline(), 4.5);
    

階段 3:音訊與節拍同步

如果存在音樂或音效:

  1. 執行節拍偵測:
    npx hyperframes beats
    
  2. 強烈提示(強拍與高潮): 將主要場景切換和主角元素揭示對齊到強提示時間戳記的 ±0.15 秒內。在程式碼中標記:// beat-locked: <timestamp>s。
  3. 連續元素: 在保持文字閱讀速度的前提下,將卡片進入或列表項目標題對齊到連續的節拍網格(±0.10 秒)。
  4. 音訊響度: 最終音訊必須符合網路標準(-14 LUFS)。

階段 4:確定性預渲染閘門與認知品質檢查 (npm run check)

這是強制性品質閘門。 在認定構圖完成或進行渲染之前:

npm run check

這會執行雙層驗證管線:

  1. 機械審計 (hyperframes check):

    • 語法檢查: 語意結構與時間屬性。
    • 執行時期: 0 個主控台錯誤、0 個未定義變數、0 個資產載入失敗。
    • 版面配置: 0 個螢幕外溢位或時間軸查找不同步。
    • 動態: 時間軸流暢推進,無凍結幀。
    • 對比度: 嚴格遵守所有文字相對於其背景的 WCAG AA 無障礙標準。
  2. 認知顯著性與可讀性閘門 (scripts/cognitive_gate.py):

    • 可讀性法則: 驗證標籤停留時間 $ geq 0.8\text{s}$,文案停留時間 $ geq 0.3\text{s/word}$。
    • 反內容抄襲審計: 禁止線性緩動與不協調的轉場。
    • Jev 預設值: 使用 Jev System 1 (typesafe-sdk) 進行約 210 毫秒的零幻覺機率判斷(輸入 $0.042/1M,輸出 token 免費)。
    • 優雅降級策略: 如果未設定 TYPESAFE_API_KEY 或 Jev 離線,此工具絕不會崩潰或阻擋專案。它會自動且無縫地降級為使用確定性的本機啟發式計算。

[!CAUTION] 如果 check 在對比度、版面配置或可讀性停留時間上失敗,請調整程式碼或時間以符合規範,並重新執行,直到所有檢查通過為止。


階段 5:視覺確認、渲染與海報交付

  1. 關鍵幀視覺快照:
    npx hyperframes snapshot
    
    檢查提取的 PNG 幀,以確認構圖平衡、安全邊距和美觀度。
  2. 產品渲染:
    npm run render
    # 或
    npx hyperframes render --quality high -o output.mp4
    
  3. 製作海報幀(縮圖): 提取最穩定的主角幀(例如在 3.2 秒處)作為影片縮圖:
    ffmpeg -ss 3.2 -i output.mp4 -frames:v 1 -q:v 2 poster.jpg
    

4. 快速入門指令與 CLI 參考

目標指令
新增專案npx hyperframes init <專案名稱>
安裝技能npx hyperframes skills
即時工作室預覽npx hyperframes preview --background(持續)或 npm run dev
停止預覽npx hyperframes preview --stop
審計與驗證npm run check
渲染 MP4npm run render
偵測節拍npx hyperframes beats
本地 AI 配音npx hyperframes tts "<腳本>" --voice af_heart --output assets/vo.wav
檢查關鍵幀npx hyperframes snapshot

5. 標準專案結構

my-video-project/
├── index.html          # 主要構圖(HTML 結構 + GSAP 時間軸)
├── hyperframes.json    # 尺寸(寬度、高度、fps、持續時間)
├── meta.json           # 專案元資料
├── package.json        # 固定的 HyperFrames 依賴與腳本
├── assets/             # 音訊、SVG 向量、圖片、字型
│   ├── music.mp3
│   └── logo.svg
└── output.mp4          # 最終渲染影片

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能