仓库维护者
系统化工作流,用于将碎片化的 GitHub 个人资料转化为整洁、可维护的专业仓库。
概述
分6个阶段执行清理。跳过不适用的阶段。始终在对破坏性操作(删除、重命名、合并)前获得用户确认。
核心原则(不可妥协)
每个仓库——无论新旧、活跃或已归档——都必须拥有以下四种基础文档。在所有四项都通过验证之前,请勿认为清理已完成。
| 文档 | 规则 | 原因 |
|---|---|---|
| LICENSE | 每个公开仓库都必须有一个许可证。默认 MIT,除非用户另有指定。 | 没有许可证,代码默认视为“保留所有权利”。任何人都不能合法使用它。 |
| README.md | 必须包含:项目名称、一句话描述、以及(如果适用)使用/安装说明。 | 这是每个访问者首先看到的内容。空的或缺失的 README 意味着项目已被放弃。 |
| .gitignore | 必须与主要语言匹配(Python/PHP/Node 等)。永远不要提交构建产物、缓存、环境文件或 IDE 配置。 | 防止意外泄露秘密,并保持差异可读。 |
| GitHub 描述 | description 字段绝不能为空。一句话,用简单的英文(或与仓库语言匹配)。 | 显示在搜索结果、个人资料置顶和社交卡片中。 |
如果某个仓库缺少这四项中的任何一项,修复它的优先级高于合并、重命名或重构。
阶段1:扫描与诊断
通过 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
阶段2:标准化基础文件
对于每个活跃仓库,确保存在最小的文件集:
| 文件 | 规则 |
|---|---|
LICENSE | 默认 MIT,除非用户另有指定 |
.gitignore | 匹配主要语言(Python/PHP/Node) |
README.md | 必须存在;如果只有占位符则重写 |
| GitHub 描述 | 通过 API 提供一句话摘要 |
通过 GitHub Contents API(PUT /repos/{owner}/{repo}/contents/{path})批量更新。
关键:PowerShell 的 here 字符串会损坏 Markdown 中的三重反引号代码块。 使用 Python 脚本进行批量 README 生成,以避免 ` 到 ``` 的转义失败。
阶段3:处理过时的仓库
决策树:
| 条件 | 操作 |
|---|---|
名称包含 outdated / deprecated / old | 归档或删除 |
| 被较新的仓库取代 | 归档 + 在 README 中添加后继链接 |
| 公开仓库历史包含泄露的秘密(API 密钥) | 删除(归档会保留完整历史) |
| 私有仓库包含密钥、密码、私有配置或个人数据 | 用户可忽略泄露规则;除非他们要求清理,否则视为可接受的私有状态 |
| 有用作为参考但不再维护 | 归档 |
已归档的仓库是只读的。要修改已归档仓库(重命名、更新 README),先取消归档(PATCH {"archived": false}),进行更改,然后重新归档。
阶段4:合并相关仓库
当2个或更多仓库是同一系统的变体(不同的后端、引擎、适配器)时:
选项A — 单体仓库(推荐)
创建一个新的干净仓库(无历史记录)。将每个变体放在 engines/{name}/ 子目录中。
project-suite/
├── main.py # 默认引擎
├── engines/
│ ├── babeldoc/
│ └── mineru/
└── README.md
保留每个引擎的入口点和配置。更新根目录 README 以解释切换方式。
选项B — Git 子模块 保持仓库独立。在父仓库中添加子模块。当历史记录保留比简洁性更重要时使用。
选项C — 保持独立 + 链接 不合并。在 README 中添加交叉链接。当变体已经显著分化时使用。
如果历史记录包含 secrets:始终创建一个新的干净仓库,并复制当前快照(通过 zip 下载 + 重新提交)。不要使用 git merge 或 git submodule,因为历史泄露会持续存在。
阶段5:重命名仓库
使用 PATCH API:处理 PATCH /repos/{owner}/{repo},参数为 {"name": "new-name"}。
指导原则:
- 全部小写,仅使用连字符
- 最多 3-4 个单词
- 删除冗余单词(
based-on、design-and-development) - 如果尚未添加,在已归档仓库名称后添加
outdated后缀
GitHub 会在一定时间内自动重定向旧 URL,但书签和脚本可能会失效。在重命名被加星标或被 fork 的仓库前,请与用户确认。
阶段6:代码级重构
在远程结构清理干净后,对仓库内的代码进行重构:
- 统一术语 — 将硬编码的品牌名称替换为通用术语(
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 (hardcoded default)
发现泄露后强制流程:
- 立即告知用户哪个文件哪一行
- 替换为环境变量(
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 或合并,解决冲突,然后 push |
本地是 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 上创建一个新仓库(必须在创建 body 中包含
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 可以忽略密钥泄露、密码、私有配置、个人数据以及其他敏感信息泄露规则。除非用户要求或仓库可能变为公开,否则不要仅因私有历史包含秘密而阻止推送、强制清理或建议删除。
- 公开仓库中的秘密历史:如果公开仓库曾经提交过 API 密钥,删除仓库是从 GitHub 清除历史的唯一方法。强制推送清理过的历史不能保证从 GitHub 的备份系统中删除。
- 包含秘密的已归档公开仓库:如果删除不可接受,至少将仓库从公开可见性中移除(设为私有),或者删除并重新创建干净代码的空仓库。
技术参考
编码陷阱(Windows)
PowerShell 默认对 stdout 使用 CP1252 编码,会损坏中文字符和 Markdown 代码块。始终重新配置:
import sys
sys.stdout.reconfigure(encoding='utf-8')
在 PowerShell 中使用包含反引号或三重反引号的 JSON body 调用 Invoke-RestMethod 时,优先使用 Python 脚本进行内容生成,以避免 JSON 序列化将 ``` 损坏为 `。
GitHub API 模式
创建仓库(永远不要省略 description):
api_call("POST", "/user/repos", {
"name": "repo-name",
"private": True,
"description": "One-sentence summary."
})
创建/更新文件:
import base64, json, urllib.request
payload = {
"message": "commit msg",
"content": base64.b64encode(content.encode('utf-8')).decode(),
"sha": existing_sha # required for updates
}
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