hup-dev/promo-animation-skill

產品動畫

您正在為當前程式碼庫的產品製作一個完成的 MP4 動畫。此技能是一個確定性動畫引擎 + 方法論，而非固定格式 — 您可以根據使用者要求選擇合適的模式（聊天式示範、品牌介紹、數據揭露、工作流程導覽、前後對比等）。

每種模式都保持不變的要素：

• 真實的品牌資產從儲存庫擷取（SVG 標誌、設計 Token、字型）。
• Linear/Vercel/Stripe 級別的視覺精緻度（柔和陰影、真實排版、單一英雄時刻）。
• 確定性的 __setTime(t) 時間軸，讓 Playwright 每次渲染都能捕捉完美的影格。
• 具體、具名的內容，凡是動畫有陳述之處 — 不使用泛泛的「AI 節省成本」文案。

完整參考資料在 methodology.md — 在執行任何其他操作之前，請先閱讀它。其中包含視覺風格、時間設定、相機數學、ffmpeg 旗標以及初次嘗試最容易遇到的 10 個陷阱的具體細節。

輸出目標

預設：1920×1080 @ 30fps，H.264，可選音樂 + 1 秒結尾淡出。時長取決於模式：

• 品牌介紹 / 標誌揭示：5–8 秒
• 數據揭露：6–10 秒
• 產品宣傳（聊天式或其他）：15–22 秒
• 工作流程導覽：20–40 秒

如果使用者未指定，請與使用者確認時長和長寬比。除非他們要求社交/垂直格式，否則預設為 16:9 1920×1080。

當兩種鏡頭都有意義時（例如靜態相機 + 電影級相機），請同時輸出兩個版本。

前置檢查

在開始之前，請先確認環境可以執行此任務：

which ffmpeg && ffmpeg -version | head -1
which node && node --version
ls ~/Library/Caches/ms-playwright/ 2>/dev/null | head -3   # macOS playwright cache

如果 Playwright chromium 尚未快取，請執行 npx playwright install chromium。ffmpeg 是必需的。

建立工作目錄：

mkdir -p product-animation/frames
cd product-animation

四階段管線

在開始第四階段之前，請同時執行第一至三階段作為子代理（獨立工作）。

第一階段 — 品牌與資產探索（子代理）

啟動品牌提取器，並傳入 agents/01-brand-extractor.md 中的提示。向其傳遞：

• 程式碼庫根目錄路徑
• 關於產品功能的一些提示

它會回傳一個 JSON：真實的 SVG 標誌路徑、精確的十六進位色票、字型堆疊、英雄 UI 慣例（邊框半徑、內邊距、主要按鈕樣式）、產品名稱 + 標語。

將真實的文字標誌 SVG 複製到工作目錄中（例如 <product>-wordmark.svg）。使用內嵌的品牌資產，不要使用點陣圖。

第二階段 — 概念與腳本（子代理）

啟動腳本編寫器，並傳入 agents/02-script-writer.md 中的提示。向其傳遞第一階段的品牌摘要、產品功能以及使用者要求的動畫類型（宣傳、品牌介紹、數據揭露等）。

它會回傳：

• 為此產品選擇的動畫模式（例如 "chat-demo"、"stat-reveal"、"brand-intro"）
• 分鏡腳本，包含場景時間：開場 → 主要內容 → 結尾
• 每個場景中要展示的確切文字、數字/視覺元素

如果模式是 chat-demo，則 templates/chat-demo.html 範本是一個完整的可用起點 — 用腳本內容填入 CASES.BIGGEST 資料結構。對於其他模式，請使用 methodology.md § 2 中描述的動畫引擎從頭建立 HTML — 使用相同的 __setTime(t) 驅動器、相同的緩動工具包、相同的 Playwright 捕捉方式。

第三階段 — 內容研究（子代理）

啟動案例研究員，並傳入 agents/03-case-researcher.md 中的提示。向其傳遞產品領域和動畫模式。

其回傳內容取決於模式：

• 聊天示範 / 宣傳： 一個經典、具名、戲劇性的前後對比，附帶真實數據（該領域的 "Converse Chuck Taylor 時刻"）+ 3-4 個次要案例。
• 數據揭露： 一個產品能夠可信地擁有的重大公開指標，並附帶引用來源。
• 品牌介紹 / 標誌揭示： 公司的實際標題、真實客戶數量、真實的創業故事 — 任何可在螢幕上顯示且可驗證的資訊。
• 工作流程導覽： 最常見的真實使用者旅程，使用產品本身的名稱步驟。

凡是動畫有陳述之處，都必須是具體、具名且可驗證的。

第四階段 — 建構與渲染

將輸出合併到所選的 HTML 範本（或您從頭編寫的範本）中，使用 Playwright 渲染影格，並使用 ffmpeg 進行編碼。

建構階段

不同模式的建構方式略有不同。共同的流程：

1. 複製或編寫動畫 HTML。

   • 如果腳本編寫器選擇了 chat-demo，請將 templates/chat-demo.html 複製到工作目錄，並使用第二階段的腳本內容和第三階段的研究結果編輯 CASES.BIGGEST 資料物件。同時置換品牌 :root { --tokens }、標頭文字（"Atlas Trade"、"Intelligence"、徽章）、網址列、文字標誌 <img src> 以及標誌結尾的標語和行動呼籲按鈕。
   • 對於其他模式（品牌介紹、數據揭露、導覽、前後對比），請使用動畫引擎從頭編寫 HTML — methodology.md § 2 展示了確定性時間軸模式。重複使用 reference/design-rules.md 中的設計規則、reference/camera-modes.md 中的相機數學以及相同的 Playwright 渲染合約。

2. 複製渲染腳本。 對於 chat-demo，使用 templates/render-chat-demo.js（525 影格，約 17.5 秒）或 render-chat-demo-zoom.js（585 影格，約 19.5 秒，電影級相機）。對於自訂模式，複製其中一個渲染腳本並更新 DURATION 常數 — 其餘部分保持不變即可。

3. 先在瀏覽器中驗證。 直接開啟 HTML — 動畫會自動循環播放。目測檢查每個場景。在瀏覽器中花 5 分鐘，可以為每次迭代節省 3 分鐘的渲染時間。

4. 快速渲染測試 — 在提交完整渲染之前，先在場景邊界處渲染 6–8 個關鍵影格。請參閱 scripts/smoke.js 了解模式。可在 30 秒內找出佈局重疊、字型後備、畫面外元素的問題。

渲染階段

在工作目錄中安裝 Playwright：

npm install [email protected] --no-save --no-audit --no-fund --silent

渲染影格：

node render-<pattern>.js          # 寫入 frames/f_*.png 檔案（大約每秒時長 x FPS 的影格數，共 3-5 個檔案）

使用 ffmpeg 進行編碼。將 -t 調整為動畫的時長，並將 afade=t=out:st=X 設定為在結束前 1 秒開始淡出：

ffmpeg -y -framerate 30 -i frames/f_%05d.png \
  -i /path/to/music.mp3 \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -preset medium -movflags +faststart \
  -c:a aac -b:a 192k -af "afade=t=out:st=<DURATION-1>:d=1.0" \
  -t <DURATION> -shortest animation.mp4

yuv420p 是 Slack/LinkedIn/Twitter 播放所必需的。+faststart 啟用串流播放。crf 18 接近視覺無損。

如果未提供音訊，請省略 -i music.mp3、-c:a aac -b:a 192k 和 -af 旗標。scripts/encode.sh 封裝了這些帶有合理預設值的設定。

品質檢查 — 在宣告完成前請先閱讀

通用（所有模式）：

• 使用真實的品牌文字標誌內嵌（SVG <img>，而非使用 Inter Tight 粗體樣式冒充的標誌）。
• 所有顏色均來自產品的色票 — 絕不使用自創的十六進位色碼。
• 動畫場景源自程式碼庫 — 其 UI、字型、文案風格應可辨識。
• 單一英雄時刻。一個數字、一個揭示、一個行動呼籲 — 而不是 12 個相互競爭的焦點。
• 任何滾動的數字都使用 tabular-nums（避免水平跳動）。
• 動畫有歸屬 — 沒有任何元素與另一個元素的淡出同時出現；尊重進場/出場時間視窗。
• 標誌在結尾處停留足夠長的時間（品牌結尾 ≥ 3 秒）。
• MP4 可在 QuickTime 中播放，完全符合目標解析度 × fps，檔案大小合理（通常 1–6 MB）。
• 使用 open <name>.mp4 為使用者開啟 MP4 檔案。

對於 chat-demo 模式，額外檢查（請參閱 reference/design-rules.md）：

• 英雄美元數字使用 JetBrains Mono / 粗細 800 / 至少 6 位數。
• 工具鏈約有 8 個環節，節奏約 3 秒 — 任何更短的時間都會顯得不真實。
• 使用者的對話氣泡在橫條清除後才出現，絕不同時出現。
• 思考氣泡在結果淡入之前向上滑出 — 兩者絕不同時不透明。
• 游標僅在輸入時出現，從不在佔位文字上出現。

在宣告完成前進行清理：

rm -rf frames frames-zoom node_modules package.json package-lock.json smoke_*.png

最終工作目錄應包含：HTML 檔案、渲染腳本、文字標誌 SVG 以及完成的 MP4 檔案。

檔案地圖

~/.claude/skills/promo-animation/
├── SKILL.md                  ← 您在這裡
├── methodology.md            ← 深度參考資料，請先閱讀 — 通用動畫引擎
├── agents/
│   ├── 01-brand-extractor.md   ← 第一階段子代理提示
│   ├── 02-script-writer.md     ← 第二階段子代理提示
│   └── 03-case-researcher.md   ← 第三階段子代理提示
├── templates/
│   ├── chat-demo.html              ← 標準聊天示範模式（可用範例）
│   ├── render-chat-demo.js         ← 靜態模式的 Playwright 渲染器
│   ├── render-chat-demo-zoom.js    ← 縮放模式的渲染器
│   └── atlas-wordmark.svg          ← 預設 SVG
├── scripts/
│   ├── smoke.js                ← 關鍵影格快速測試
│   └── encode.sh               ← ffmpeg 包裝腳本
└── reference/
    ├── design-rules.md         ← 濃縮的視覺規則
    ├── camera-modes.md         ← 靜態 vs 縮放決策
    └── timing-blueprint.md     ← 場景時間設定

如有疑問，請閱讀 templates/chat-demo.html — 它是一個完整的可用範例，您現在就可以渲染它（一個虛構的 "Atlas Trade" / Converse Chuck Taylor 重新分類場景）。它是聊天示範模式的標準參考，同時也是確定性動畫引擎的參考 — methodology.md 中的每個視覺規則、時間決策和陷阱都編碼在該檔案中。

對於其他動畫模式，您將從頭編寫 HTML — 但 methodology.md § 2 中的動畫引擎、§ 5 中的渲染合約以及 reference/design-rules.md 中的設計規則都將保持不變。