git-repo-doctor 是做什么的？
对臃肿的 Git 仓库进行只读诊断，并生成安全的清理建议。
何时使用此技能
.git目录膨胀到数 GB。objects/pack/tmp_pack_*或objects/??/tmp_obj_*文件大量堆积。git count-objects -v显示大量garbage计数或数十万个松散对象。gc.auto=0，或 gc / repack / fetch 频繁被中断。- 编辑器或编码代理（Codex、Claude Code、Cursor、IDE 索引器）在扫描仓库时崩溃或 OOM。
- 用户希望安全地缩小、清理、修剪、垃圾回收或回收仓库空间。
如何运行
单个零依赖 Python 3 脚本。严格为只读。
# 诊断当前目录所在的仓库：
python3 scripts/git_repo_doctor.py
# 指向特定的 git 目录，包括已更名/禁用的目录：
python3 scripts/git_repo_doctor.py --git-dir /path/to/.git.disabled-xyz
# 机器可读输出（作为代理时解析此输出）：
python3 scripts/git_repo_doctor.py --json
# 跳过远程可达性探测（离线或网络缓慢时）：
python3 scripts/git_repo_doctor.py --no-remote
返回内容
- 大小分解 — 明确垃圾 / 松散对象 / 包文件 / 可达历史 / 不可达估计 / 磁盘余量。
- 健康问题 —
gc.auto=0、过时的gc.log、工作树等于$HOME、Syncthing 同步.git、松散对象泛滥、残留临时文件。 - 一项建议，包括以下之一：
- 路径 A（可达历史很小）：创建安全网 bundle，验证可恢复，然后进行分层、延迟删除。
- 路径 B（历史较大）：就地执行
git maintenance+gc/repack；如果磁盘空间紧张，先删除垃圾文件。 - filter-repo / BFG 提示：当可达历史中存在巨大 blob 时。
- 可直接粘贴、支持回滚的清理计划，包含明确的回滚点。脚本会打印命令，但不会执行其中任何一条。
代理应如何使用输出
- 运行脚本，然后向用户总结大小分解、健康问题和推荐的路径。
- 展示打印的计划，但不要自动执行任何命令。清理不可逆；每个破坏性步骤都必须由人类确认。
- 始终确认
$GITDIR的值，确保已创建并验证 bundle，并在用户确定之前保留 bundle。
安全契约
此工具从不运行 gc、prune、repack、rm、reflog expire 或任何修改命令。它执行的唯一操作是只读的 git 查询和文件系统统计，且全部带有超时保护。每个破坏性动作仅作为打印计划中的文本存在，供人类审查和运行。
决策逻辑（摘要）
| 条件 | 推荐做法 |
|---|---|
| 可达历史 < 1 GiB 且小于总大小的 10% | 路径 A：bundle + 分层删除/重建 |
| 可达历史较大，空闲空间充足 | 路径 B：就地 git maintenance + gc/repack |
| 可达历史较大，磁盘空间紧张 | 先删除垃圾文件，再 repack |
| 打包对象很少但包文件巨大 | 巨大 blob 提示（运行 git-sizer，考虑 git-filter-repo） |
完整文档和示例报告请参见 README.md。