03 仓库盘点：理解仓库结构与规模

这是《Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人》系列的第 3 篇。前两篇解决了"为什么蒸馏"和"蒸馏什么"，这一篇开始动手——先给仓库做一次全面盘点。就像医生看病先做体检，蒸馏仓库的第一步，是搞清楚这个仓库到底长什么样。

---

一、盘点要回答的四个问题

仓库盘点不是"随便看看"，它要为后续所有蒸馏步骤提供基础数据。盘点要回答四个问题：

问题	关注点	对应产出
仓库结构	目录怎么组织？有哪些模块？	目录树
语言与规模	用了哪些语言？多少行代码？	语言统计
依赖关系	依赖了哪些库？版本如何？	依赖清单
元信息	分支、tag、贡献者、提交量	仓库画像

这四个问题回答完，你就得到了一份"仓库画像"——后续的演进挖掘、架构分析、模式提炼，都建立在这份画像之上。

---

二、理解仓库结构：目录、语言、规模

2.1 目录结构：tree

先看目录长什么样。tree 命令能输出目录树，但大型仓库的完整目录树会非常长，所以通常限制深度：

# 只看 2 层目录结构
tree -L 2 -d

# 只看 3 层，排除 node_modules / .git 等
tree -L 3 -d -I "node_modules|.git|dist|build|__pycache__"

输出示例：

.
├── src/
│   ├── api/          # 接口层
│   ├── components/   # 组件层
│   ├── core/         # 核心业务
│   ├── utils/        # 工具函数
│   └── views/        # 页面层
├── tests/
├── docs/
├── scripts/
├── package.json
└── README.md

看目录树时关注什么：

• 顶层目录的划分逻辑（按层？按业务？按技术？）
• 哪些目录是"核心资产"（业务逻辑），哪些是"基础设施"（工具、配置）
• 有没有明显的"杂物目录"（什么都往里塞的 utils/、misc/）

2.2 语言与规模：cloc

cloc（Count Lines of Code）是统计代码行数的利器，能按语言分类统计：

# 安装（macOS）
brew install cloc
# 安装（Ubuntu）
sudo apt install cloc

# 统计代码量，排除依赖目录
cloc . --exclude-dir=node_modules,.git,dist,build

输出示例：

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
TypeScript                     128           3210           1890          12450
SCSS                            42            890            120           3200
JavaScript                      35            780            450           2100
HTML                            12            120             30            480
Markdown                        18            450              0            980
-------------------------------------------------------------------------------
SUM:                           235           5450           2490          19210
-------------------------------------------------------------------------------

cloc 数据告诉你的：

• 项目主体语言是什么（决定后续分析工具选型）
• 代码量级（几千行 vs 几十万行，蒸馏策略完全不同）
• 注释比例（注释多说明团队有写注释的习惯，是蒸馏的富矿）

2.3 依赖关系：包管理文件

看依赖清单，了解项目"站在哪些巨人肩膀上"：

# Node 项目
cat package.json | jq '.dependencies, .devDependencies'

# Python 项目
cat requirements.txt
# 或
cat pyproject.toml

# Java 项目
cat pom.xml | grep -A 100 "<dependencies>"

看依赖时关注什么：

• 依赖数量（依赖越多，技术债风险越高）
• 关键依赖的版本（是否过老？是否锁版本？）
• 有没有"奇怪"的依赖（一个简单项目却引了一堆重型库）

---

三、git 仓库元信息：分支、tag、贡献者、提交量

目录和代码是"静态"的，git 元信息是"动态"的——它记录了仓库的生命轨迹。

3.1 提交总量与时间跨度

# 总提交数
git rev-list --count HEAD

# 首次提交时间
git log --reverse --format="%ai" | head -1

# 最近提交时间
git log -1 --format="%ai"

# 按年份统计提交数
git log --format="%ad" --date=format:"%Y" | sort | uniq -c

输出示例：

总提交数: 8234
首次提交: 2021-03-12 09:24:11 +0800
最近提交: 2026-08-15 17:42:03 +0800

按年份统计:
 2021  412
 2022  1890
 2023  2560
 2024  2100
 2025  980
 2026  292

这个数据告诉你：项目 5 年历史、8,000+ 提交，2022-2023 是活跃期，2025 年后明显放缓——可能进入维护期。这对蒸馏策略有直接影响：维护期的仓库，蒸馏重点应该是"知识抢救"而非"新知识沉淀"。

3.2 分支与 tag

# 本地分支
git branch

# 远程分支
git branch -r

# 所有 tag（按时间排序）
git tag --sort=-creatordate

# 每个 tag 对应的提交
git for-each-ref --sort=creatordate --format='%(refname:short) %(creatordate:short)' refs/tags

看分支/tag 时关注什么：

• 有多少长期分支（develop、release、feature/*）——反映团队协作模式
• tag 的命名规律（v1.0.0？2024.01？）——反映发布节奏
• 有没有"僵尸分支"（很久没动的分支）——反映历史包袱

3.3 贡献者分析：git shortlog

git shortlog 是贡献者分析的利器：

# 按提交数排序的贡献者列表
git shortlog -sn

# 带邮箱的完整列表
git shortlog -sne

# 按时间范围统计（比如最近一年）
git shortlog -sn --since="1 year ago"

输出示例：

  3210  张三 <zhangsan@example.com>
  2450  李四 <lisi@example.com>
  1800  王五 <wangwu@example.com>
   774  赵六 <zhaoliu@example.com>

贡献者数据告诉你的：

• 核心贡献者是谁（提交量前 20% 的人，往往掌握最多隐性知识）
• 是"一人主导"还是"团队协作"（影响知识集中度）
• 结合离职风险，判断哪些人的知识最需要"抢救"

3.4 活跃度分析

# 最近 30 天活跃的贡献者
git shortlog -sn --since="30 days ago"

# 每个文件的修改次数（找出"热点文件"）
git log --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20

热点文件分析是仓库盘点的隐藏宝藏——修改次数最多的文件，往往是：

• 核心业务逻辑（高频变更 = 高风险 = 高价值）
• 或者"垃圾文件"（谁都在改，但谁都不清楚它干嘛的）

---

四、输出仓库画像

盘点完成后，把数据汇总成一份"仓库画像"。这是蒸馏流程的第一个正式产出物，也是后续所有步骤的输入。

4.1 仓库画像模板

# 仓库画像：xxx

## 基本信息
- 仓库地址：git@github.com:org/repo.git
- 创建时间：2021-03-12
- 最近提交：2026-08-15
- 历史跨度：5 年 5 个月

## 规模
- 总提交数：8,234
- 代码行数：19,210（TypeScript 12,450 / SCSS 3,200 / JS 2,100）
- 文件数：235
- 依赖数：128（dependencies 86 / devDependencies 42）

## 结构
- 顶层目录：src/（api、components、core、utils、views）、tests/、docs/、scripts/
- 核心模块：src/core/（业务逻辑）、src/components/（UI 组件）
- 杂物目录：src/utils/（疑似什么都往里塞）

## 协作
- 贡献者：12 人
- 核心贡献者：张三（3,210 提交）、李四（2,450 提交）
- 活跃度：2022-2023 高峰，2025 后放缓（进入维护期）

## 分支与发布
- 长期分支：main、develop、release/*
- 发布节奏：约每月 1 个 tag（v1.x.x）
- 僵尸分支：feature/old-refactor（2 年未动）

## 风险提示
- 核心知识集中在张三、李四两人（离职风险高）
- src/utils/ 疑似技术债聚集地
- 依赖版本偏老（部分依赖 3 年未升级）

## 蒸馏建议
- 优先蒸馏：决策记录（抢救核心贡献者知识）、架构文档（理清核心模块）
- 深度建议：src/core/ 做 L3 细节级，其余 L2 结构级

4.2 画像的用途

仓库画像不是"做完就扔"的文档，它是蒸馏流程的导航图：

• 给 04 演进挖掘：提交时间线、里程碑识别的基础
• 给 05 架构分析：模块划分、依赖关系的起点
• 给 06 文档蒸馏：知道哪些目录/文件是知识富矿
• 给 08 决策记录：核心贡献者名单 = 决策背景的采访对象
• 给 12 虚拟人化：画像本身就是虚拟人 memory 的第一份素材

---

五、盘点脚本：一键生成仓库画像

把上面的命令串成一个脚本，一键生成画像：

#!/bin/bash
# scripts/repo-inventory.sh
# 用法: ./repo-inventory.sh [仓库路径]

REPO_DIR="${1:-.}"
cd "$REPO_DIR"

echo "===== 仓库盘点报告 ====="
echo "生成时间: $(date '+%Y-%m-%d %H:%M:%S')"
echo ""

echo "--- 基本信息 ---"
echo "仓库路径: $(pwd)"
echo "总提交数: $(git rev-list --count HEAD 2>/dev/null || echo 'N/A')"
echo "首次提交: $(git log --reverse --format='%ai' 2>/dev/null | head -1)"
echo "最近提交: $(git log -1 --format='%ai' 2>/dev/null)"
echo "分支数: $(git branch -r 2>/dev/null | wc -l | tr -d ' ')"
echo "Tag 数: $(git tag 2>/dev/null | wc -l | tr -d ' ')"
echo ""

echo "--- 贡献者 Top 10 ---"
git shortlog -sn 2>/dev/null | head -10
echo ""

echo "--- 代码规模 ---"
if command -v cloc &> /dev/null; then
  cloc . --exclude-dir=node_modules,.git,dist,build --quiet
else
  echo "cloc 未安装，跳过代码统计（建议: brew install cloc）"
fi
echo ""

echo "--- 目录结构（2 层） ---"
if command -v tree &> /dev/null; then
  tree -L 2 -d -I "node_modules|.git|dist|build|__pycache__"
else
  echo "tree 未安装，跳过目录树（建议: brew install tree）"
fi
echo ""

echo "--- 热点文件 Top 10 ---"
git log --name-only --pretty=format: 2>/dev/null | sort | uniq -c | sort -rn | head -10

运行 ./repo-inventory.sh，一份基础画像就出来了。剩下的（依赖分析、风险判断、蒸馏建议）需要结合人工判断补充。

---

六、小结

这一篇的核心收获：

1. 四个维度盘点：结构（tree）、语言规模（cloc）、依赖（包管理文件）、元信息（git log/shortlog/branch/tag）。
2. git 元信息是金矿：提交量、时间跨度、贡献者分布、热点文件，直接反映仓库的健康度和知识分布。
3. 产出仓库画像：一份结构化的画像文档，是后续所有蒸馏步骤的导航图。
4. 脚本化：把盘点命令串成脚本，换一个仓库就能复用。

下一篇，我们深入 git 历史：[04 提交历史挖掘：从 commit 提炼演进脉络](04-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-提交历史挖掘.md)——从 8,000 次提交里，还原出项目从 0 到 1 的发展轨迹。

---

上一篇：[02 蒸馏目标定义：从仓库提炼什么、产出物清单](02-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-蒸馏目标定义.md)
下一篇：[04 提交历史挖掘：从 commit 提炼演进脉络](04-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-提交历史挖掘.md)