reanimate 是做什麼的?
重建使用者指出的目標,使其動作與參考素材一致,並以逐幀比對證明,持續修正直到比對通過。最終交付項目為使用者專案中的程式碼,以及證據(數值與並排比較圖),絕不能是「看起來差不多」。
什麼是「完成」
根據使用者的說法選擇忠實度等級,並在第一則訊息中明確說明;這將決定你要驗證的內容。
| 等級 | 使用時機 | 必須匹配 | 可以不同 |
|---|---|---|---|
| 動作忠實 (預設) | 「複製這個動畫」、「讓我們的感覺像他們的」、「和 X 相同的主角但用我們的內容」 | 觸發時機、序列與順序、交錯延遲、每個步驟的時機 (±80 ms)、動畫曲線家族、相對於元素大小的移動方向與距離、版面比例 | 文案、顏色、字型、圖片、品牌細節 |
| 像素忠實 | 「完全匹配」、「像素完美」、「細節要符合」、「1:1」 | 以上所有項目加上字型、尺寸、顏色、間距、圓角、陰影、素材;平均影格差異 ≤ 2% | 使用者未要求更改的任何內容 |
| 混合 | 「複製 X 並加入 Y」、「像他們的一樣但使用我們的定價方案」 | 以其中一個等級複製的部分 | 新增的部分,你需描述並展示,但僅驗證其不破壞已複製的動作 |
使用者可以將目標縮小至某個區塊、某個元件、某個頁面,或影片的一段時間範圍(「前 3 秒」、「0:12 到 0:15」)。精確複製該範圍;不要引入頁面的其餘部分。
工作流程
以下所有內容皆位於使用者專案中的 .reanimate/<name>/ 目錄內(除非使用者希望提交證據,否則請將其加入 .gitignore)。保留每一輪的產出物;它們就是證據。
0. 範圍界定
在進行任何擷取之前,先在 .reanimate/<name>/spec.md 的最上方寫下三行內容:
- 目標:要複製的對象,盡可能精確地依照使用者的說法(URL + 選擇器 / 時間範圍 /「GIF 中的切換開關」)。
- 目的地:程式碼的去向與使用的技術棧(閱讀
package.json、現有元件以及正在使用的動畫函式庫;與其匹配,而非引入新的函式庫)。 - 忠實度:動作忠實、像素忠實或混合,若為混合則需列出新增項目。
從請求與 repo 中推斷你能得到的資訊。僅當兩種解讀方式會導致不同工作內容時(例如,某個頁面上有兩個可能的區塊都被稱為「主視覺」),才進行提問。當參考素材是需登入的頁面,或是你無法在此環境下載的 YouTube/Loom 連結時,請向使用者索取螢幕錄影,並在此期間繼續處理其他事項。
1. 設定
<skill> 指的是此 SKILL.md 所在的目錄。腳本需要 Bun;首次執行會下載 Playwright 的 Chromium 和一個靜態 ffmpeg(約 250 MB)。
bash <skill>/scripts/setup.sh # 安裝 playwright、ffmpeg、pixelmatch;顯示「ready」
所有腳本皆使用 bun <skill>/scripts/<name>.ts --help 執行。它們是確定性的,並遵守一個規則:使用相同的視口、選擇器裁切、觸發時機、持續時間與 fps 來擷取參考素材與克隆結果,否則比較的結果會是你的設定差異,而非你的工作成果。
2. 擷取參考素材
閱讀 references/capture.md 以取得適用於你的來源類型的操作指南。簡而言之:
- 網站:
capture.ts --url … --out ref --selector <section> --trigger load|scroll|hover|click|none --duration … --track "<moving elements>"。你會得到video.webm、frames/、inspect.json(宣告的動畫、關鍵影格、計算後樣式、字型、偵測到的函式庫)和track.json(每個追蹤元素在每個動畫影格的位置、尺寸、透明度、變形)。對於 CSS/WAAPI 動作,inspect.json通常包含精確的持續時間、延遲和動畫曲線:直接使用它們,這比自行估算要好。 - 影片或 GIF:
frames.ts --in file --out ref/frames --fps 10..30 --start … --end … --crop …。先使用--probe探測,然後檢視幾個影格以找出你要複製的元件的裁切範圍。 - Canvas、WebGL、WebGPU、3D(
inspect.json › canvases會顯示一個,或頁面使用了 three.js、Pixi、Babylon、Spline…):在擷取命令中加入--clock virtual --gl --assets,然後閱讀gl/summary.md(使用gl.ts summary <out>)。你會得到著色器原始碼、每個常數的 uniform、場景圖、渲染通道、紋理與模型,以及每個動畫化的 uniform 或物體屬性在gl-track.json中作為一個通道。虛擬時鐘使每個影格完全精確,每次擷取都相同,隨機粒子也不例外。閱讀references/webgl.md。 - Lottie / Rive / 原型匯出:檔案本身就是規格;直接讀取它,不要從像素重新推導。
然後建立帶有標籤的圖表並進行檢視:sheet.ts filmstrip --frames ref/frames --out ref/sheets。使用圖片檢視器閱讀每張圖表。這是使用者要求的逐幀檢查;不要跳過它或只取樣第一張圖表。
3. 撰寫動作規格
使用 references/analysis.md 中的範本填入 spec.md。每個元素、每個屬性一行:觸發時機、開始時間、持續時間、延遲或交錯延遲、起始值 → 結束值、動畫曲線、備註。優先依以下順序取得數值:inspect.json 的動畫與關鍵影格 → 對 track.json 或 canvas 的 gl-track.json --channel 使用 easing.ts → 讀取影格(第一個變化的影格、最後一個變化的影格、是否有 overshoot)。同時記錄動作依賴的靜態事實:元素尺寸與位置、z 順序、溢出裁剪、變形原點,以及像素忠實工作所需的字型、顏色、間距與素材。
這個規格是參考素材與克隆結果之間的契約。每一行都將成為步驟 5 中的一個檢查點。如果某一行帶有「?」,代表你尚未完成影格的閱讀。
4. 實作
在使用者的技術棧中實作,遵循 references/implementation.md(動畫曲線表、交錯延遲計算、滾動與懸停觸發、減少動畫)。保持 DOM 結構接近參考素材的角色結構,以便追蹤的選擇器有相對應的項目。對於混合工作,將新增項目放在明確分離的元件或區塊中,並在 spec.md 的「新增項目」部分提及。
為克隆結果提供與參考素材相同的擷取方式:一個路由或一個靜態頁面,能在參考視口大小下以相同觸發方式渲染該元件。開發伺服器即可(capture.ts --url http://localhost:5173/…);獨立的 HTML 檔案也行。
5. 驗證、修正、重複
使用與參考素材完全相同的命令來擷取克隆結果,僅更改 --url 和 --out clone-N,然後執行:
bun <skill>/scripts/compare.ts --ref ref/frames --clone clone-N/frames --out compare-N
bun <skill>/scripts/sheet.ts compare --ref ref/frames --clone clone-N/frames --diff compare-N/diff --out compare-N/sheets --every 2
bun <skill>/scripts/easing.ts --track clone-N/track.json --selector "<el>" --prop <translateY|opacity|…> --compare-track ref/track.json
對於 Canvas 工作,也需執行 gl.ts compare --ref ref --clone clone-N,它會檢查 Canvas 設定、繪製結構與每個動畫通道。
閱讀 references/verify.md 以了解如何解讀報告、每個忠實度等級的通過標準,以及每種失敗情況通常需要的修正方式。親自檢視每一輪的比較圖表;數字告訴你有些地方不對勁,而圖表告訴你是什麼地方不對勁。
持續迭代,直到每行規格都通過。每一輪:根據證據指向的最小變更來修改、重新擷取、重新比較。預期需要 2 到 5 輪。如果 5 輪後某一行仍然失敗,請停止並回報其數值與原因(缺少字型、使用者可能無法複製的著色器或模型、你近似處理的物理彈簧),不要悄悄降低門檻或刪除該行。
6. 報告
最終訊息必須能獨立呈現:
- 忠實度等級、複製了什麼、新增了什麼。
- 程式碼位置(檔案)以及如何觸發動畫。
- 最後一輪比較的簡短表格:時序誤差、平均不匹配度、每個關鍵元素的動畫曲線匹配度、通過/失敗。
- 最終比較圖表的路徑,若環境支援則嵌入為圖片。
- 殘餘偏差,每個偏差需附上數值與原因。
造成迭代浪費的常見陷阱
- 參考素材與克隆結果使用不同的視口或裁切:在修改程式碼之前先修正擷取設定。
- 僅根據第一幀和最後一幀來判斷:動畫曲線存在於中間影格;請閱讀圖表。
- 字型:不同的備用字型會改變每個影格的像素。對於像素忠實的工作,先載入相同的字型(來自
inspect.json的 fonts)再判斷不匹配度;對於動作忠實的工作,忽略文字像素並閱讀時序欄位。 - 參考素材在頁面載入後錄製,而克隆結果在冷啟動時擷取:使用
--wait-before,或使用--trigger none搭配--pre-js重新啟動動畫,使兩者都從靜止狀態開始。 - 滾動驅動的動作:它是滾動位置的函數,而非時間。使用相同的
--scroll-steps和--scroll-ms來擷取兩者,並按滾動位置(track 的scrollY)進行比較,而非按時間。 - JS 函式庫(GSAP、Framer Motion 的彈簧效果):
--playback-rate無法減慢它們。使用track.json和easing.ts(它會回報 overshoot 和「彈簧-like」)並根據 overshoot 和穩定時間來調整彈簧參數。 - 他人螢幕的影片會有游標、瀏覽器邊框和壓縮雜訊:將其裁切掉,並將
--pixel-threshold稍微調高(0.15),而不是追逐雜訊。 - Canvas 和 WebGL 在真實時鐘下擷取:軟體 GL 會掉幀,且隨機內容每次載入都不同,導致比較結果反映的是機器性能。請使用
--clock virtual和相同的--seed來擷取兩者。 - 從螢幕截圖重建著色器:追蹤結果已包含其原始碼與每個常數。在編寫 GLSL 之前,先閱讀
gl/shaders/和固定 uniforms。