打造儲存庫 README
將儲存庫轉化為清晰可信的登陸頁面。所有主張、指令、徽章與連結都必須基於實際專案；視覺效果絕不能超越準確性。
選擇操作模式
- 當使用者僅要求回饋時，使用審計模式。進行檢查與報告；不要編輯或發布。
- 當使用者要求建立或改進 README 時，使用建構模式。編輯儲存庫並驗證結果。
- 僅在使用者要求提交、推送、開啟 Pull Request 或更新儲存庫設定時，使用發布模式。遵循儲存庫的一般 Git 工作流程。
1. 檢查真實專案
在起草之前，檢查：
- 現有的
README*、貢獻、安全、授權、變更日誌及部署文件。 - 套件清單、進入點、範例環境檔案、測試指令、螢幕截圖、標誌與公開 URL。
- Git 遠端、預設分支、釋出版本標籤、CI 工作流程及託管配置。
- 儲存庫層級的指示，例如
AGENTS.md或CONTRIBUTING.md。
從證據中推導出產品名稱、一句話的價值主張、目標受眾、支援的平台、安裝指令、執行指令及部署故事。如果無法驗證某項重要事實，則省略或清楚標記為計畫中。
2. 執行公開範圍與安全檢查
將 README 工作視為發布審查。在揭露細節之前：
- 搜尋追蹤的檔案與暫存變更中的 API 金鑰、私鑰、令牌、密碼、Cookie、內部主機名稱、私有 IP 與個人路徑。
- 絕不從本機配置、對話歷史、Shell 歷史或部署檔案中貼上機密。
- 連結至
.env.example；絕不重現.env中的值。 - 確認螢幕截圖、QR 碼、名稱與聯絡連結是故意公開的。
- 保留授權、商標、歸屬及第三方資產聲明。
若發布會暴露敏感資料，則停止並提出具體阻礙。
3. 在裝飾之前設計故事
按以下順序撰寫 README：
- 識別 — 名稱、標誌、簡潔承諾。
- 信任 — 少量真實徽章與實際產品視覺。
- 理解 — 它是做什麼的、為誰而做、及其關鍵差異。
- 嘗試 — 從複製到工作結果的最短路徑。
- 採用 — 配置、部署、架構、限制與支援。
- 參與 — 貢獻、安全、授權、贊助者與社群。
在重建 README 佈局或選擇徽章之前，先閱讀 references/readme-patterns.md。
4. 建立緊湊的品牌標頭
當專案擁有足夠資產時，使用以下順序：
- 帶有描述性替代文字與節制顯示大小的連結標誌。
- 專案名稱與一行價值主張。
- 四到八個有意義的徽章。
- 主要連結，例如線上示範、文件、問題追蹤器或下載。
- 可選的頁內導航（適用於較長的 README）。
- 一張強烈的英雄圖片、產品螢幕截圖或簡短示範。
優先使用儲存庫擁有的資產，位於穩定的 docs/、.github/ 或 assets/ 路徑下。在產生新標誌之前，先重複使用現有標誌。如果使用者要求新視覺效果，且可用的圖像生成技能存在，則使用它，然後針對儲存庫顯示進行最佳化。
不要使用虛假的構建徽章、佔位符指標、巨大的徽章牆、裝飾性計數器或專案未控制的外部連結資產。
5. 僅選擇有用的章節
一個緊湊的專案通常需要：
- 它是什麼以及為何存在。
- 基於實際實作的功能亮點。
- 附帶可複製且經測試指令的快速入門。
- 使用安全佔位符的配置。
- 螢幕截圖或示範（當視覺證據能實質幫助時）。
- 部署或生產注意事項（當專案可部署時）。
- 當存在相應檔案時，貢獻、安全、授權與致謝的連結。
僅在專案需要時才添加架構、API 參考、相容性、路線圖、常見問題與疑難排解。不要建立空的模板章節。
對於中文專案，先撰寫自然的中文，並保留技術識別符的原貌。僅在要求或儲存庫已維護英文版本時，才添加英文版本。
6. 在不干擾產品故事的情況下添加贊助
當使用者提供並授權贊助者圖片或 QR 碼時：
- 將其複製到穩定的儲存庫擁有資產路徑。
- 在 README 靠近底部處使用清晰的標題，例如
支持项目或贊助。 - 添加替代文字、合理的寬度，以及一句話說明贊助資金的用途。
- 除非明確要求，否則絕不更改、解碼或重新生成付款 QR 碼。
不要讓贊助的優先級超過快速入門、文件或安全資訊。
7. 將 README 驗證為可執行文件
在可行的情況下，執行專案的相關建構、測試、lint 或煙霧指令。然後執行捆綁的檢查器：
python3 craft-repository-readme/scripts/validate_readme.py \
--repo-root . \
--readme README.md
當相應元素為必要時，添加嚴格標誌：
python3 craft-repository-readme/scripts/validate_readme.py \
--repo-root . \
--readme README.md \
--require-logo --require-badges --require-hero --require-sponsor
同時手動驗證：
- 每個安裝與執行指令都與儲存庫相符。
- 相對圖片與文件連結能透過 GitHub 區分大小寫的路徑解析。
- 外部連結使用預期的正式網域。
- 標題錨點與目錄連結正常運作。
- 圖片具有描述性的替代文字與合理的尺寸。
- README 在桌面與窄螢幕上都能良好呈現。
- 沒有機密、佔位符、本機絕對路徑或未經驗證的主張殘留。
8. 謹慎發布
當發布在範圍內時：
- 審查
git diff並將不相關的變更排除在提交之外。 - 使用聚焦的訊息提交，並透過儲存庫的正常工作流程推送。
- 當分支保護或協作慣例要求時，優先使用 Pull Request。
- 僅在使用者要求變更儲存庫設定且值已驗證時，更新 GitHub 描述、首頁、主題與社交預覽。
- 發布後在 GitHub 上重新打開渲染後的 README，並檢查圖片、徽章、連結與行動佈局。
完成條件
- 首屏傳達了名稱、目的、信任信號與主要下一步行動。
- 所有突出的主張與指令都已針對儲存庫驗證。
- 標誌、英雄圖片、徽章與贊助內容是故意選用的，而非裝飾性的。
- 連結與本機資產能正確解析。
- 未暴露任何機密或私有的環境細節。
- 驗證通過，且要求的發布步驟已完成。