Community写作与编辑github.com

tzwkb/repo-maintainer

Agent技能——GitHub仓库清理、整合与维护。

repo-maintainer 是什么?

这是一个系统化的GitHub仓库维护技能,旨在帮助开发者将碎片化的GitHub个人资料转化为整洁、可维护的专业仓库。该技能定义了六个明确的清理阶段,从扫描诊断、标准化基础文件(LICENSE、README.md、.gitignore、GitHub描述),到处理过时仓库、合并相关仓库、重命名仓库,以及代码级重构。它提供了详细的决策树和自动化操作指南,包括使用GitHub API进行批量文件更新、仓库归档、重命名和删除等操作。该技能特别强调安全合规,在推送本地修改前强制进行密钥扫描,并提供了在公共仓库泄露机密时的处理流程。支持所有主流GitHub工作流,包括本地无历史下载、克隆后大规模重构、以及完全替换代码但保留历史等场景。

兼容平台~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 的新对话。

文档

仓库维护者

系统化工作流,用于将碎片化的 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:代码级重构

在远程结构清理干净后,对仓库内的代码进行重构:

  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 (hardcoded default)

发现泄露后强制流程:

  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 或合并,解决冲突,然后 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 — 新的干净仓库 如果重写如此彻底,以至于它本质上是一个新项目:

  1. 在 GitHub 上创建一个新仓库(必须在创建 body 中包含 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 可以忽略密钥泄露、密码、私有配置、个人数据以及其他敏感信息泄露规则。除非用户要求或仓库可能变为公开,否则不要仅因私有历史包含秘密而阻止推送、强制清理或建议删除。
  • 公开仓库中的秘密历史:如果公开仓库曾经提交过 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

相关技能