OpenGHz/open-source-project-polish

開源專案打磨

目標

將一個現有的專案資料夾，透過改善對外文件、社群文件、儲存庫元資料以及 Git/GitHub 設定，轉變為高品質的開源儲存庫，同時保留原始原始碼不變。

嚴格邊界

• 除非使用者明確要求，否則不得修改原始產品/原始碼、生成的邏輯、測試、筆記本、資源檔案或執行時行為。
• 允許的更改僅限於專案層面的元資料和文件，例如：README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT、SECURITY、CHANGELOG、SUPPORT、CITATION、issue/PR 範本、版本發行說明、徽章、.gitignore、.gitattributes、.editorconfig 以及 GitHub 工作流程/文件框架。
• 切勿在 README 或公開文件中包含使用者特定的本地機器路徑，例如 /home/<user>/...、/Users/<user>/...、磁碟代號路徑、個人工作區名稱、下載資料夾或機器特定的絕對專案路徑。應使用相對路徑、$HOME、<repo> 或佔位符替代。
• 若專案中無授權條款，且使用者未指定偏好，預設採用 MIT 授權。
• 對於沒有 Git 遠端儲存庫的資料夾，預設自動進行公開的 GitHub 發布。若無法明確判斷目標擁有者/名稱，則先進行確認，然後在金鑰檢查通過後建立公開的遠端儲存庫並推送僅限文件的變更。
• 如果網路/GitHub 指令執行失敗，在宣告遠端操作受阻之前，應使用配置的本地代理重試一次。
• 盡可能保留現有的文件與社群檔案；以增量方式進行改善，而非替換有用的內容。

需要釐清的輸入資訊

僅詢問會對不可逆轉或公開行為產生重大影響的資訊：

1. 目標範圍：工作區專案路徑，或者如果已明確則為當前資料夾。
2. 公開身份：在建立任何遠端儲存庫之前，若無法從資料夾和已驗證的 GitHub 帳戶推斷，則需要 GitHub 擁有者/儲存庫名稱。
3. 授權條款覆寫：如果已有授權條款則沿用；否則預設使用 MIT，除非使用者要求其他授權。
4. 專案定位：一句話的價值主張、目標用戶以及成熟度（如果無法從程式碼/文件中推斷）。
5. 原始碼編輯：假設不允許；在觸及元資料/文件以外的任何內容之前，務必先詢問。

步驟

1. 審查專案狀態

• 檢查資料夾結構、現有 README/文件、套件清單、建置檔案、範例、授權檔案和 Git 狀態。
• 檢查是否存在 .git 目錄以及是否配置了任何遠端儲存庫。
• 在建立任何遠端儲存庫或推送之前，識別可能包含金鑰的檔案：.env、憑證、令牌、大型二進位檔案、資料集、私人筆記、本地日誌以及機器特定的路徑。
• 總結現有優勢、缺少的開源必備元素，以及任何需要使用者輸入的不確定之處。

2. 規劃非程式碼的新增項目

建立一個簡潔的計劃，僅涵蓋允許的文件和元資料工作：

• 以 create-readme 技能為基礎，改進 README 的結構、語調和 GitHub 風格 Markdown。
• 預設生成雙語 README：在主（英文）README 完成後，產生中文版本並儲存為 README.zh-CN.md，並在兩者之間交叉連結。直接撰寫中文版本；對於篇幅長或術語密集的文件，才保留使用 baoyu-translate 技能來確保術語一致性。
• 社群健康檔案：預設使用 MIT 授權、貢獻指南、行為準則、安全政策、支援指南、變更日誌、引用資訊、治理規範、問題範本、PR 範本。
• 儲存庫衛生：.gitignore、.gitattributes、.editorconfig、文件索引、範例索引、徽章、專案描述、主題、資金/贊助元資料（如適用）。
• Git/GitHub 設定：若無 Git 則初始化，若無遠端則建立公開遠端、設定預設分支，並在安全檢查後推送僅限文件的變更。

3. 改進 README

使用 create-readme 技能來建立或更新 README。確保 README 簡潔、有吸引力且實用：

• 清晰的專案名稱、標語和簡短的價值主張。
• 僅在徽章真實且易於維護時才使用。
• 盡可能附帶經過驗證的快速入門指令。
• 指令必須能從儲存庫根目錄複製貼上使用，且不得包含當前用戶的絕對本地路徑；應優先使用 ./script.sh、$HOME/...、/path/to/... 或 <repo>/... 等範例。
• 包含安裝、使用、配置、範例、專案結構、故障排除以及專用文件的連結。
• 請勿在 README 中重複完整版 LICENSE、CONTRIBUTING、CHANGELOG 或 SECURITY 的內容；應連結到這些文件。
• 保留現有的專案特定知識和範例。

在英文 README.md 定稿後，預設生成中文翻譯：

• 英文 README.md 的頂部必須包含一個語言切換行，例如 English | [简体中文](README.zh-CN.md)。即使中文檔案仍在同一工作階段中生成，也要加入此行——該連結指向的是工作流程完成後將存在的路徑。
• 根據 README.md 生成 README.zh-CN.md。對於一般的 README（主要是簡短散文加上必須保持不變的程式碼/指令），建議直接撰寫中文版本；僅當 README 篇幅較長或術語密集，且需要 baoyu-translate 技能的 analyze/translate/review 流程與共享詞彙表時，才呼叫該技能。
• 中文的 README.zh-CN.md 在頂部也包含鏡像切換行，例如 [English](README.md) | 简体中文。
• 保持所有程式碼區塊、指令、路徑、連結、徽章和佔位符不變；僅翻譯散文部分。
• 僅在使用者明確選擇退出時，才跳過生成中文版本。如果專案本身主要以中文撰寫，則將 README.md 視為中文版本，翻譯為 README.en.md，並在每個檔案頂部放置相應的切換行。

4. 新增社群檔案

僅在這些檔案有助於讓專案看起來完整且值得信賴時，才新增或更新它們：

• LICENSE：如果已有則沿用；否則預設添加 MIT 授權，並在適當位置填入偵測到的當前年份和擁有者/專案名稱。
• CONTRIBUTING.md：開發環境設定、分支/提交慣例（如果可以推斷）、測試期望、Issue/PR 流程。
• CODE_OF_CONDUCT.md：除非使用者有其他政策，否則使用標準的簡潔貢獻者公約風格。
• SECURITY.md：支援的版本、負責任的揭露管道佔位符、漏洞回報期望。
• CHANGELOG.md：初始化為 Unreleased 和當前的公開基準版本；不要編造發行歷史。
• SUPPORT.md：提出問題、回報錯誤和請求功能的地方。
• .github/ISSUE_TEMPLATE/* 和 .github/PULL_REQUEST_TEMPLATE.md：針對該專案量身定做的實用表單/檢查清單。
• CITATION.cff：僅適用於研究/學術/科學專案，或當有作者元資料可用時。

5. 儲存庫衛生

• 根據偵測到的語言/工具建立或完善 .gitignore，不要排除可能是原始碼產物的檔案。
• 在有用時新增 .gitattributes 以進行文字標準化和常見的二進位模式處理。
• 新增 .editorconfig，並使用與儲存庫風格相符的保守空白預設值。
• 除非已知或驗證過建置/測試指令，否則不要新增 CI 工作流程；如果新增，請保持精簡且不具侵入性。

6. Git 與遠端儲存庫處理

對於沒有 Git 的資料夾：

1. 在驗證資料夾路徑後，為目標資料夾初始化一個儲存庫。
2. 僅暫存此工作流程建立或更改的元資料/文件檔案。
3. 在準備發布時，使用專注於文件的提交訊息進行提交。

對於沒有遠端儲存庫的 Git 儲存庫：

1. 儘可能從 gh 認證推斷 GitHub 擁有者，並從資料夾推斷儲存庫名稱；僅在不確定時才詢問。
2. 在建立遠端儲存庫之前，檢查 gh 是否已認證。
3. 預設建立一個公開的 GitHub 儲存庫。
4. 新增 origin、設定預設分支，並在審查暫存變更並確認不包含金鑰後進行推送。

推薦的 GitHub CLI 流程，可根據專案調整：

git status --short
git remote -v
gh auth status
gh repo create OWNER/REPO --public --source=. --remote=origin --push

如果網路指令失敗，使用以下指令重試一次：

export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890

7. 品質檢查

在最終確定之前：

• 重新打開已更改的 Markdown 片段，檢查標題、連結、程式碼圍欄以及可複製貼上的指令縮排。
• 在最終確定之前，搜尋 README 和公開文件中的本地機器路徑，包括 /home/、/Users/、磁碟代號路徑、個人工作區名稱以及從當前環境複製的絕對路徑。
• 確認未經明確批准，未修改任何原始碼檔案。
• 確認所有指向本地檔案的連結都指向實際存在的檔案。
• 如果生成了中文 README，請確認 README.zh-CN.md 存在、兩個檔案中的語言切換連結都能正常解析，並且程式碼/指令/路徑與英文版本完全相同。
• 如果可以，執行輕量級格式化或 Markdown 檢查；除非使用者同意，否則不要為此工作流程安裝重量級依賴。
• 顯示 git diff --stat 並總結已更改的檔案。
• 如果已建立遠端儲存庫，請報告其 URL、可視性、預設分支以及是否推送了任何內容。

決策點

• 現有 README 很完善：保留結構並補充缺失的部分，而不是重寫。
• 沒有經過驗證的安裝/測試指令：包含明確標記的佔位符或「尚未記錄」的備註，而不是編造指令。
• 授權條款未知：除非使用者要求不同的授權，否則預設添加 MIT。
• 可能存在金鑰或私人資料：停止遠端儲存庫的建立/推送，並報告有風險的路徑。
• 沒有 gh CLI 或未認證：提供確切的指令讓使用者執行，但仍完成本地文件打磨，並在安全的情況下準備一個僅限文件的提交。
• 單一儲存庫多專案 (Monorepo)：僅在套件邊界明確時，建立或更新根目錄的社群檔案和每個套件的 README 檔案。

完成摘要

結束時應包含：

• 已新增/更新的檔案。
• 有意不觸碰的內容，特別是原始碼。
• 已執行的驗證。
• 遠端儲存庫狀態（如適用）。
• 建議的後續步驟，例如啟用 CI、新增範例、建立第一個發行版本或建立專案主題。