Community寫作與編輯github.com

tzwkb/repo-maintainer

Agent 技能 — GitHub 儲存庫清理、整併與維護。

repo-maintainer 是什麼?

此 AI Agent 技能提供一套系統化的工作流程,用於將零散的 GitHub 個人檔案轉變為乾淨、可維護且專業的儲存庫。它將清理過程分為六個階段:掃描與診斷、標準化基礎文件、處理過時儲存庫、合併相關儲存庫、重新命名儲存庫,以及程式碼層級重構。該技能支援 Claude Code、Cursor 等平台,並透過 GitHub API 執行操作。其核心原則是強制每個儲存庫都必須包含 LICENSE、README.md、.gitignore 和 GitHub 描述四項基礎文件。此外,它還包含嚴格的推送前安全掃描程序,用於檢測和處理洩漏的密鑰或密碼,並針對私人和公開儲存庫提供不同的處理規則。技能也詳細說明了處理大型本地重構、保留或取代 Git 歷史的各種情境與策略。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/repo-maintainer

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 的儲存庫之前,請先與使用者確認。

第六階段:程式碼層級重構

在遠端結構清理完畢後,重構儲存庫內部的程式碼:

  1. 統一術語 — 將硬編碼的品牌名稱替換為通用術語(GPTProcessor → LLMProcessor),同時保留實際的 API 模型 ID(gpt-4、gpt-5)。
  2. 檔案重新命名 — GitHub Contents API 沒有重新命名功能;建立新檔案並帶上更新後的內容,然後刪除舊檔案。
  3. 目錄重組 — 對於多風格專案,使用 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 (硬編碼預設值)

發現洩漏後的強制流程:

  1. 立即告知使用者哪個檔案的哪一行
  2. 替換為環境變數(os.getenv("API_KEY") 無預設值)
  3. 如果已 push 到 remote:告知使用者,獲得明確確認後刪庫重建(git history 無法透過 force push 徹底清除)
  4. 使用者撤銷對應服務商的 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 — 新的乾淨儲存庫 如果改寫幅度太大,本質上已經是一個新專案:

  1. 在 GitHub 上建立新的儲存庫(必須在建立請求中包含 description 或在建立後立即透過 PATCH 設定)
  2. 將本地程式碼推送到那裡
  3. 封存舊儲存庫,並在 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

相關技能