albertirgi/replica

replica 是做什麼的？

重建使用者指向的內容，然後證明它。capture 將參考轉換為由實際量測事實組成的藍圖。你根據藍圖來建構。compare 從四個面向（佈局、樣式、像素、動畫）為你的建構打分數，並告訴你哪項修正能獲得最多分數。當 compare 回傳退出碼 0 時才算完成，而不是當你覺得建構看起來對了的時候。

<skill> 代表此 SKILL.md 所在的目錄。

規則

1. 測量，不要猜測。 所有尺寸、顏色、字型、間距、持續時間和緩動函數都從 blueprint.md、blueprint.json 或報告中取得。不要依賴你對於這類網站通常長怎樣的記憶。
2. 絕不操弄分數。 不要嵌入參考的螢幕截圖或影片畫格、不要 iframe 或代理參考、不要直接貼上其渲染後的 HTML、不要編輯 .replica/ 下的任何內容、也不要降低 --level 來通過。在使用者的技術棧中建立真正的 UI。
3. 使用專案的技術棧。 先讀取 package.json 和最近的現有元件。比照已使用的框架、樣式方法和動畫函式庫。只有當參考需要的功能是專案無法達到的時候，才新增依賴套件。
4. 依照報告順序修復，一次修復少數幾個。 最前面的項目通常會導致後面的項目出現問題：一次級聯修正就能移動數十個元素。在每批修正後重新執行 compare。絕不要累積十個推測性的修改。
5. 尊重所有權。 參考的字型、圖片、圖示和文字內容歸其所有者所有。在使用者擁有的地方，使用使用者自己的資產和文字內容。否則請詢問，或使用相同尺寸的佔位符，並標記 data-replica="placeholder"：compare 仍會檢查它們的盒子，但會將它們的像素排除在像素分數之外。在最終訊息中說明你重複使用了哪些參考資產。

0. 範圍

在你的第一條訊息中決定並說明以下項目：

• 目標：URL 或檔案，以及要複製的哪個部分：用於區塊或元件的 CSS 選擇器，或用於影片的時間範圍。

• 目的地：使用者專案中的檔案或路由，以及技術棧。

• 等級，這設定了 compare 對你的要求門檻：

  等級	使用者說的話	門檻（全部必須通過）
  structure	「佈局/感覺相同但用我們的品牌」、「像 X 但用我們的內容」	layout ≥ 90, motion ≥ 85
  faithful (預設)	「複製這個」、「重建」、「讓它看起來像」	layout ≥ 95, style ≥ 95, pixels ≥ 85, motion ≥ 90
  exact	「像素完美」、「1:1」、「完全一樣」	layout ≥ 98, style ≥ 98, pixels ≥ 97, motion ≥ 95

• 觸發條件：啟動動畫的事件（頁面載入、hover、點擊、滾動到視野中、滾動觸發）。這會變成 --action。

根據請求和儲存庫盡可能推斷。僅當兩種解讀會導致不同工作時才提問。

1. 設定（每台機器一次）

npm install --prefix <skill>/scripts
node <skill>/scripts/replica.mjs doctor

如果 doctor 回報沒有瀏覽器，請執行它列印的安裝指令。如果已安裝 Google Chrome，Replica 會將其用作備用方案。影片和 GIF 參考還需要在 PATH 中安裝 ffmpeg。

2. 擷取參考

將所有內容保留在使用者專案中的 .replica/<name>/ 目錄下，並將 .replica/ 加入 .gitignore。

node <skill>/scripts/replica.mjs capture <url|file.html|image|video> --out .replica/<name>/ref \
  --selector "<欲複製部分的 css>" --viewports 1440x900,390x844 --action load --motion 1500

• --selector：將擷取範圍限定在你正在複製的部分。擷取整個頁面會產生龐大的藍圖。
• --viewports：你將要發布的寬度。第一個是主要視口；動畫在那裡記錄。
• --action 和 --motion <ms>：僅當有待複製的動畫時使用。確保錄製時間足夠長以涵蓋所有動畫；如果結束時仍有動畫在移動，capture 會列印一條提示。
• --hide "<css>"：隱藏 cookie 橫幅、聊天視窗和開發者覆蓋層。這會同時套用在參考端和你建構的頁面上。

有關圖片、影片、需要登入的頁面、iframe、canvas 和深色模式的處理方法，請參閱 references/sources.md。

然後完整閱讀 ref/blueprint.md。用你的圖片檢視器查看 ref/<viewport>/shot.png 和 ref/motion/filmstrip.png。藍圖語法在 references/blueprint.md 中有說明。圖片和影片參考沒有藍圖，因此請根據螢幕截圖和影格來建構。

3. 建構

依以下順序進行：代碼記號 → 佈局骨架 → 排版 → 盒子和繪圖 → 媒體 → 響應式 → 動畫。

• 代碼記號：將藍圖的顏色、字體比例、圓角半徑、陰影和 CSS 變數以其實際數值放入專案的代碼記號系統（CSS 變數或 Tailwind 主題）。
• 佈局：重現每個輪廓線的 flex … / grid cols[…]、gap 和 pad 數值，以及容器的寬度。
• 排版：精確匹配字體系列、字重、大小/行高和字距。如果某個字體不可用或需要授權，請使用最接近的可用字體，並將其記錄為已知差異。
• 動畫：當藍圖中有「宣告的動畫」時，請精確複製其持續時間、延遲、緩動函數和關鍵影格。否則，請使用時間軸的開始時間、持續時間和緩動函數，或其彈簧參數。
• 提供服務：讓你的複製品可以透過一個 URL 或 HTML 檔案存取，該 URL 或檔案需呈現相同的狀態（開發伺服器的路由、Storybook 故事或靜態檔案）。如果其根元素需要與參考不同的選擇器，請將 --selector 傳遞給 compare。

每個技術棧（CSS、Tailwind、Framer Motion、GSAP）的註記在 references/building.md 中。

4. 比較、修正、重複

node <skill>/scripts/replica.mjs compare .replica/<name>/ref <clone url|file> [--selector "<clone root css>"]

它會建立 round-N/ 目錄，其中包含 report.md、issues.json、score.json 和 sheets/。退出碼 0 表示通過，1 表示尚未通過，2 表示發生錯誤。

1. 閱讀 round-N/report.md：先看分數表，然後看 Fix next。每個項目都會顯示修正它能獲得多少分數。
2. 查看 round-N/sheets/*.png：參考 | 你的 | 差異總覽、放大的熱點區域以及動畫條。
3. 修正最前面的 3-5 個項目，務必包含任何標記為 「Likely cause」 的項目。然後再次執行 compare。

• 如果報告顯示 ▼（分數下降），在嘗試其他操作之前，先復原你最後的更改。
• 如果連續兩輪的分數提升少於 1 點，請停止修補。重新閱讀失敗區域的藍圖，並檢查字體是否已載入，以及你是否比較了正確的選擇器、狀態和視口。
• 在 8 輪之後停止，並報告剩餘的問題及其原因。

references/fixing.md 涵蓋了每種發現的含義以及通常能解決問題的更改。

5. 交付

以如下格式結尾：

Replica · <目標> → <更改的檔案>
等級 <level> · 第 <N> 輪 · 分數 <overall> — 通過 | 尚未通過
layout <n> · style <n> · pixels <n> · motion <n>
已知差異：<每一項，並說明原因（需授權的字體、使用者的自有內容等）>
重複使用的參考資產：<列表，或無> · 佔位符：<列表，或無>
證據：.replica/<name>/round-<N>/report.md 以及 sheets/

如果未通過，請明確說明，並列出剩餘的主要發現。