Repository Maintainer
系統化工作流程,用於將零散的 GitHub 個人檔案轉變為乾淨、可維護且專業的儲存庫。
總覽
分六個階段執行清理。可跳過不適用的階段。所有破壞性操作(刪除、重新命名、合併)都必須取得使用者確認。
核心原則(不可妥協)
每個儲存庫——新的或舊的、活躍的或封存的——都必須具備以下四份基礎文件。在確認這四份文件都到位之前,不要認為清理工作已完成。
| 文件 | 規則 | 原因 |
|---|---|---|
| LICENSE | 每個公開儲存庫都必須有 LICENSE。除非使用者指定,否則預設使用 MIT。 | 沒有授權,程式碼預設為「版權所有,保留所有權利」。沒有人可以合法使用它。 |
| README.md | 必須存在,至少包含:專案名稱、一句話描述,以及適用時的使用/安裝說明。 | 這是每位訪客看到的第一個東西。空的或缺少的 README 表示該專案已被棄置。 |
| .gitignore | 必須與主要程式語言(Python/PHP/Node 等)匹配。永遠不要提交建置工件、快取、環境變數檔案或 IDE 設定。 | 防止意外洩漏機密,並保持 diff 的可讀性。 |
| GitHub 描述 | description 欄位永遠不能為空。一句話,使用簡單明瞭的英文(或與儲存庫語言相符)。 | 會出現在搜尋結果、個人檔案置頂和社交卡片中。 |
如果某個儲存庫缺少上述四項中的任何一項,優先修復它,而不是進行合併、重新命名或重構。
第一階段:掃描與診斷
透過 GitHub API 取得完整的儲存庫清單:
curl -sH "Authorization: Bearer TOKEN" \
"https://api.github.com/user/repos?per_page=100&affiliation=owner"
檢查每個儲存庫:
- 缺少
LICENSE、.gitignore、README.md - 空的
description欄位 - 命名不一致(大小寫混合、名稱過長)
- 明顯的重複或系列(例如:
project、project-v2、project-mineru) - 名稱中包含
outdated、deprecated、old、test
第二階段:標準化基礎文件
對於每個活躍的儲存庫,確保存在最小的文件集:
| 文件 | 規則 |
|---|---|
LICENSE | 除非使用者指定,否則預設使用 MIT |
.gitignore | 與主要程式語言(Python/PHP/Node)匹配 |
README.md | 必須存在;如果只有佔位符內容則重新撰寫 |
| GitHub 描述 | 透過 API 設定一句話摘要 |
透過 GitHub Contents API 進行批量更新 (PUT /repos/{owner}/{repo}/contents/{path})。
關鍵提醒:PowerShell here-strings 會損壞 Markdown 中的三重反引號程式碼區塊。 請使用 Python 腳本進行批量 README 生成,以避免 ` → ``` 跳脫失敗。
第三階段:處理過時儲存庫
決策樹:
| 條件 | 動作 |
|---|---|
名稱包含 outdated / deprecated / old | 封存或刪除 |
| 已被較新的儲存庫取代 | 封存 + 在 README 中加入後繼者連結 |
| 公開儲存庫的歷史記錄包含洩漏的機密(API 金鑰) | 刪除(封存會保留完整歷史記錄) |
| 私有儲存庫包含金鑰、密碼、私有設定或個人資料 | 使用者可以忽略洩漏規則;將其視為可接受的私有狀態,除非他們要求清理 |
| 有參考價值但已不再維護 | 封存 |
封存後的儲存庫是唯讀的。要修改封存後的儲存庫(重新命名、更新 README),請先取消封存(PATCH {"archived": false}),進行修改,然後重新封存。
第四階段:合併相關儲存庫
當 2 個以上的儲存庫是同一系統的不同變體(不同的後端、引擎、介面卡)時:
選項 A — 單一儲存庫(推薦)
建立一個新的乾淨儲存庫(無歷史記錄)。將每個變體放在 engines/{name}/ 子目錄中。
project-suite/
├── main.py # 預設引擎
├── engines/
│ ├── babeldoc/
│ └── mineru/
└── README.md
保留每個引擎的進入點和設定。更新根目錄 README 以說明切換方式。
選項 B — Git 子模組 保持儲存庫獨立。在父儲存庫中加入子模組。當歷史記錄的保存比簡潔性更重要時使用。
選項 C — 保持獨立 + 連結 不合併。在 README 中加入交叉連結。當變體之間分歧很大時使用。
如果歷史記錄包含機密:始終建立一個新的乾淨儲存庫,並複製目前的快照(透過下載 zip 並重新提交)。不要使用 git merge 或 git submodule,因為歷史記錄中的洩漏會持續存在。
第五階段:重新命名儲存庫
使用 PATCH API:PATCH /repos/{owner}/{repo},並帶上 {"name": "new-name"}。
指導原則:
- 全部小寫,僅使用連字號
- 最多 3-4 個單字
- 移除冗詞(
based-on、design-and-development) - 對於已封存的儲存庫,如果名稱中尚未包含,則加上
outdated後綴
GitHub 會在一段時間內自動重新導向舊 URL,但書籤和腳本可能會失效。在重新命名已加星號或已 fork 的儲存庫之前,請先與使用者確認。
第六階段:程式碼層級重構
在遠端結構清理完畢後,重構儲存庫內部的程式碼:
- 統一術語 — 將硬編碼的品牌名稱替換為通用術語(
GPTProcessor→LLMProcessor),同時保留實際的 API 模型 ID(gpt-4、gpt-5)。 - 檔案重新命名 — GitHub Contents API 沒有重新命名功能;建立新檔案並帶上更新後的內容,然後刪除舊檔案。
- 目錄重組 — 對於多風格專案,使用
engines/、variants/或core/+adapters/的模式。
將大型本地重構推送到遠端
當使用者下載程式碼到本地、進行大量修改(檔案重新命名、變數重新命名、結構性改寫),然後需要推送回遠端儲存庫時。
推送前機密掃描(強制)
推送前必須先掃描 secret 洩漏,有任何發現立即報告,禁止繼續 push。
私有儲存庫例外: 如果目標儲存庫確認為 private,可以無視 key、密碼、私有配置、個人信息以及其他敏感信息洩漏規則。掃描可以作為提醒,但命中不阻斷 push、不要求刪庫重建、不要求替換為環境變量,除非用戶明確要求清理或計劃改成 public。
掃描模式(兩道都要跑——只跑 token 正則會漏掉明文密碼):
① 高熵 token / API key:
grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
--include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
--include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
--exclude-dir=".git" .
② 明文密碼 / 憑證 helper(token 正則抓不到;實戰曾漏掉 askpass.sh 裡一行 echo "<sudo密碼>",隨 init commit 推上了 GitHub):
git ls-files -z | xargs -0 grep -nIE "password|passwd|密碼|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
| grep -vE "\.md:|getenv|getpass|placeholder|example"
# 並人工核對孤立的 askpass.sh / *_secret* / .pgpass / .npmrc 類文件——它們整文件就是憑證
公開儲存庫任一道命中即按下方強制流程處理。私有儲存庫命中只需提醒使用者,不作為阻斷條件。注意掃的是 git ls-files(已跟蹤集),.gitignore 擋掉的不算洩漏,但已 commit 的檔案即使現在 gitignore 也仍在歷史裡。
報告格式:
[LEAK] scripts/eval.py:15 — sk-xxxx (硬編碼 fallback)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (硬編碼預設值)
發現洩漏後的強制流程:
- 立即告知使用者哪個檔案的哪一行
- 替換為環境變數(
os.getenv("API_KEY")無預設值) - 如果已 push 到 remote:告知使用者,獲得明確確認後刪庫重建(git history 無法透過 force push 徹底清除)
- 使用者撤銷對應服務商的 key
推送前檢查清單
推送前必須執行:
git status
確認無以下情況:
- Untracked files — 未跟蹤的新檔案(常見遺漏:docs/, scripts/, config 模板)
- Changes not staged — 修改未 add
- Changes to be committed 中包含不應上傳的檔案(金鑰、個人資料、臨時腳本)
未確認前,禁止直接 push。
決策樹
| 情況 | 建議動作 |
|---|---|
本地儲存庫沒有 .git(下載的 zip / 複製的檔案) | 請參閱情境 A 以下說明 |
本地是 git clone 且帶有歷史記錄,遠端未變更 | 正常的 git add → commit → push |
本地是 git clone,遠端有新的提交 | git pull --rebase 或合併,解決衝突,然後推送 |
本地是 git clone,變更是大量重新命名 + 改寫 | 請參閱情境 B 以下說明 |
| 想要保留遠端歷史記錄但取代所有程式碼 | 請參閱情境 C 以下說明 |
情境 A:本地沒有 Git 歷史記錄
最常見的情況是使用者下載了 zip,進行了大量編輯,然後想要同步回來。
選項 A1 — 強制推送(個人 / 獨自專案)
# 在本地專案資料夾中
git init
git add .
git commit -m "refactor: major rewrite"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force
⚠️ 會銷毀遠端歷史記錄。僅在使用者確認遠端歷史記錄可拋棄時使用。
選項 A2 — 保留遠端歷史記錄(推薦用於有價值的儲存庫)
git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./your-local-project/
cd your-local-project
git add .
git commit -m "refactor: major rewrite"
git push
此方法會保留所有先前的提交,並將重構作為一個新的單一提交附加。
選項 A3 — 新的乾淨儲存庫 如果改寫幅度太大,本質上已經是一個新專案:
- 在 GitHub 上建立新的儲存庫(必須在建立請求中包含
description或在建立後立即透過 PATCH 設定) - 將本地程式碼推送到那裡
- 封存舊儲存庫,並在 README 中加入後繼者連結
情境 B:在已複製的儲存庫中進行大量重新命名 + 改寫
關鍵規則:永遠不要在同一個提交中混合檔案重新命名和內容變更。 Git 會將其視為「刪除舊檔案 + 建立新檔案」,並失去歷史記錄連結。
逐步提交策略:
# 步驟 1:僅重新命名
git mv old_module.py new_module.py
git mv old_utils/ new_utils/
git commit -m "refactor: rename modules"
# 步驟 2:變數/類別重新命名
git add .
git commit -m "refactor: rename variables and classes"
# 步驟 3:邏輯變更
git add .
git commit -m "feat: update core logic"
如果使用者已經在工作目錄中混合了所有內容:
# 暫存目前的變更,分段重播
git stash push -m "mixed refactor"
# 僅恢復重新命名(使用 git mv 或手動 mv + git add)
git mv old_file new_file
git commit -m "refactor: rename files"
# 恢復內容變更
git stash pop
# 解決任何衝突,然後提交
情境 C:取代所有程式碼但保留歷史記錄
當使用者想要從頭開始新程式碼,但保留星號 / issues / URL 時很有用。
git checkout --orphan fresh-start
git rm -rf .
# 將新的本地程式碼複製到這裡
git add .
git commit -m "init: clean rewrite"
git branch -D main
git branch -m main
git push -u origin main --force
檢查重新命名偵測
推送後,驗證 Git 是否正確追蹤了重新命名:
git log --follow -- new_file.py
如果歷史記錄中斷(顯示檔案是全新的),則表示重新命名和內容變更被一起提交了。
安全性與合規性
- GitHub token:需要 PAT 時在 agent 記憶裡找(不在此寫具體路徑/帳號/值)。絕不要把 token 值寫進任何會被 push 的檔案(含本 skill、README、設定)——含 token 的內容一旦 push 即被 GitHub secret-scanning 吊銷。
- Token 衛生:批量操作後,指示使用者立即在
https://github.com/settings/tokens撤銷該 PAT。 - 私有儲存庫例外:如果儲存庫是私有的,agent 可以忽略金鑰洩漏、密碼、私有設定、個人資料和其他敏感資訊洩漏規則。不要僅僅因為私有歷史記錄包含機密而阻止 push、強制清理或建議刪除,除非使用者要求或該儲存庫可能變成公開。
- 公開的機密歷史記錄:如果公開儲存庫曾經提交過 API 金鑰,刪除該儲存庫是從 GitHub 清除歷史記錄的唯一方法。強制推送已清理的歷史記錄並不能保證從 GitHub 的備份系統中移除。
- 包含機密的已封存公開儲存庫:如果無法接受刪除,至少將該儲存庫從公開可見中移除(設為私有),或刪除並以乾淨的程式碼重新建立一個空的儲存庫。
技術參考
編碼陷阱(Windows)
PowerShell 的標準輸出預設使用 CP1252,這會破壞中文字元和 Markdown 程式碼區塊。始終重新設定:
import sys
sys.stdout.reconfigure(encoding='utf-8')
當在 PowerShell 中使用 Invoke-RestMethod 並帶有包含反引號或三重反引號的 JSON 主體時,建議使用 Python 腳本進行內容生成,以避免 JSON 序列化將 ``` 破壞成 `。
GitHub API 模式
建立儲存庫(永遠不要省略 description):
api_call("POST", "/user/repos", {
"name": "repo-name",
"private": True,
"description": "一句話摘要。"
})
建立/更新檔案:
import base64, json, urllib.request
payload = {
"message": "commit msg",
"content": base64.b64encode(content.encode('utf-8')).decode(),
"sha": existing_sha # 更新時需要
}
req = urllib.request.Request(
f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
method="PUT",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {token}", ...}
)
封存/取消封存:
api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})
重新命名儲存庫:
api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "new-name"})
刪除儲存庫:
api_call("DELETE", f"/repos/{owner}/{repo}")
無需複製的批量下載
下載儲存庫快照為 zip 檔案,以避免在不穩定的網路上進行緩慢的 git clone:
curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip
捆綁資源
scripts/repo_analyzer.py— 掃描使用者的 GitHub 儲存庫並生成清理建議scripts/bulk_file_updater.py— 透過 GitHub API 批量建立/更新 LICENSE、.gitignore、README