onovich/RepoCover

RepoCover 是做什麼的？

建立一個儲存庫專屬的社群預覽圖，並確保在縮圖尺寸下仍清晰可讀。偏好確定性、可編輯的構圖，而非通用的自動生成橫幅。

產品不變量

• 產出精確的 1280×640 點陣圖，通常為 PNG，且檔案大小小於 1,000,000 位元組。
• 在點陣圖旁保留一份可編輯的原始檔，通常為 SVG。
• 所有可見的宣稱、指標、螢幕截圖與證明，皆以儲存庫的證據為基礎。
• 保留儲存庫的識別性，而非強加統一的風格。
• 在亮色與暗色背景上驗證完整尺寸以及 320×160 的縮圖效果。
• 將圖片建立與 GitHub 上傳視為不同的授權邊界。
• 不得暗示與 GitHub 有關聯或獲得其背書。

載入正確的參考資料

每張封面都需讀取以下兩個檔案：

• references/common-quality.md：通用構圖與拒絕條件。
• references/design-ledger-template.md：證據、設計與驗證記錄。

然後僅讀取適用的路線：

• 當存在螢幕截圖、執行時期畫面、標誌、插圖、SVG、精靈圖、紋理或其他有意義的視覺素材時，請讀取 references/source-material.md。
• 當沒有可用的螢幕截圖、執行時期畫面、品牌標誌或儲存庫自有的主要視覺素材時，請讀取 references/cold-start.md。
• 當要重新整理現有封面、比較候選方案或產生批次版本時，請讀取 references/version-regression.md。

不要只因某個路線存在就載入不相關的路線。references/design-recipes.md 僅作為較舊提示的相容性索引。

工作流程

1. 檢查並界定證據範圍

讀取適用的 AGENTS.md 檔案、README、套件中繼資料、有意義的原始碼路徑、視覺素材以及任何現有的社群預覽圖。辨識以下項目：

• 儲存庫名稱與主要使用者任務；
• 一個具體的價值陳述；
• 最多三個證明點；
• 最強的產品證據；
• 已建立的視覺識別與應排除的次要事實；
• 證據模式：remote-static、local-static、build-tested 或 runtime-tested。

絕不能暗示當僅檢查靜態證據時，就已執行了建置、執行時期、場景或測試。如果 GitHub 的圖片要求可能已變更，請根據官方 GitHub 文件進行驗證。

對於遠端儲存庫，請使用可用的公開或已認證的 GitHub 證據來檢查其 README、目錄結構、清單檔案、有意義的原始碼檔案、目前的預覽圖以及最強的視覺素材。將輸出保留在一個持久的、使用者可見的目錄中，並記錄來源 URL 與宣稱邊界。如果無法存取任何執行時期或具代表性的介面，請陳述此限制，而不是假裝遠端證據等同於可運作的本機預覽。可預覽的本機專案（尤其是具有現有介面的網頁專案）通常能提供最豐富的視覺證據。

2. 撰寫分類帳並選擇路線

在開始繪圖之前，使用隨附的範本建立一份設計分類帳。至少記錄以下項目：

• 承諾、證明、排除事項；
• 證據模式與宣稱邊界；
• 素材診斷或冷啟動語意骨架；
• 選擇的生產與解讀路線；
• 素材、素材角色、版面配置與線條的決策；
• 輸出版本、驗證結果與推廣決策（如適用）。

選擇能保留識別性的最小生產路線：

• 程式碼原生 SVG（推薦）： 開發者工具、圖表、圖表、標誌、函式庫及推斷出的視覺系統。
• 螢幕截圖或來源混合： 僅在診斷後，自包含的來源素材仍是最清晰的證明時使用。
• 插圖混合： 僅在插圖是儲存庫識別性的核心時使用；產生不含重要文字的素材，並在 SVG 中覆蓋確切的文字。

不要為了模仿既有的向量系統而呼叫圖片生成。

3. 建置並版本化管理可編輯的原始檔

除非儲存庫有明確的素材慣例或使用者指定了其他目錄，否則預設路徑為 docs/social-preview.svg 與 docs/social-preview.png。

• 使用 1280 640 的 viewBox 與全畫布背景。
• 將基本內容保留在大約 72 像素的外部安全區域內。
• 將文案、產品證明、說明文字與簽名區分為不重疊的區域。
• 除非儲存庫提供了適當的授權字型，否則使用系統字型。
• 嵌入本機證據，或使用確定性的 SVG 基本元素來重現；避免外部執行時期依賴。
• 將圖表、螢幕截圖、重複標記與波形裁剪至其所屬區域。
• 除非明確要求替換，否則保留現有封面並建立一個版本化的副本。

4. 以機械方式渲染與驗證

當 Sharp 可用時，使用隨附的腳本進行渲染：

node <skill-directory>/scripts/render_svg.mjs <source.svg> <output.png>

僅在範圍內需要取代已命名的輸出時，才使用 --force。在 Codex Desktop 中，載入工作區依賴項，並使用傳回的 Node 可執行檔與套件路徑（透過 NODE_PATH）；未經許可不得安裝任何依賴項。

驗證 PNG 與 SVG：

python <skill-directory>/scripts/validate_preview.py <output.png> --svg <source.svg>

建立標準的縮圖檢查表：

node <skill-directory>/scripts/create_review_sheet.mjs <preview.png> <review.png>

在 Windows 舊版字碼頁上，請為讀取 UTF-8 來源的工具設定 PYTHONUTF8=1。

5. 以視覺方式驗證

以完整尺寸檢查點陣圖，並檢查產生的檢查表。確認：

• 儲存庫名稱與價值陳述在 320×160 時仍可讀；
• 產品證明顯而易見且在技術上忠實呈現；
• 文字、標記、裁切、面板與裝飾元素沒有碰撞或卡掉；
• 構圖在亮色與暗色背景上皆可行；
• 每個可見元素都對應到承諾或證明；
• 設計通過每個適用的路線特定否決條件。

從左到右、從上到下掃描，一次修正一個指定的缺陷，重新渲染，並重新執行驗證。不要將已知的缺陷移交出去。

對於批次處理，請建立一份聯絡表，並在推廣候選方案之前檢查是否有意外的共用範本偏移。

6. 僅在要求時才上傳

建立素材並不代表授權更改 GitHub 設定。當明確要求上傳時，請開啟：

https://github.com/<owner>/<repo>/settings

使用 Social preview → Edit → Upload an image… 並遵循現行的 UI 確認政策。上傳後，請擷取公開的儲存庫頁面，並驗證 og:image 是否解析為新的 1280×640 圖片。不要僅憑設定頁面的縮圖就回報成功。

交接

顯示最終圖片並回報：

• 可編輯原始檔路徑；
• 點陣圖路徑、格式、尺寸與位元組大小；
• 一句話的設計理由；
• 驗證與版本推廣狀態；
• 上傳狀態：未要求、待處理或已公開驗證。

不要將專案範圍的輸出僅留在暫存目錄或模型擁有的目錄中。