04 提交历史挖掘：从 commit 提炼演进脉络

这是《Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人》系列的第 4 篇。第 03 篇给仓库画了"画像"，这一篇开始挖最深的矿——提交历史。8,000 次提交不是一堆枯燥的记录，而是一部项目从 0 到 1 的编年史。我们要做的，是从这部编年史里还原出项目的演进脉络。

---

一、为什么提交历史是"金矿"

代码只告诉你"系统现在长什么样"，提交历史告诉你"系统是怎么一步步长成这样的"。这两者的差别，就是"快照"和"电影"的差别。

提交历史里埋着三类高价值知识：

知识类型	藏在哪	价值
演进脉络	提交时间线	项目从 0 到 1 的发展轨迹
决策动机	commit message、关联的 PR/issue	为什么这么设计
里程碑	重大提交、重构、架构变更	项目的关键转折点

但提交历史也有一个巨大的问题：噪音太多。8,000 次提交里，可能有 3,000 次是"fix bug"、“update”、"wip"这种无信息量的提交。挖掘的第一步，是过滤噪音，提取信号。

---

二、commit message 的语义提取

2.1 先看提交质量

# 查看最近 20 条提交的 message
git log --oneline -20

输出示例：

a1b2c3d fix: 修复登录页在 Safari 下的样式错乱
e4f5g6h feat: 新增模型导出功能
i7j8k9l update
m0n1o2p fix bug
q3r4s5t wip
u6v7w8x refactor: 重构 API 注册模块的状态管理
y9z0a1b docs: 补充模型汇聚模块的使用说明

一眼就能看出提交质量：有的提交有规范的前缀（feat: / fix: / refactor: / docs:），有的就是"update"、"wip"这种垃圾提交。

2.2 统计提交类型分布

如果团队用了 Conventional Commits 规范（feat: / fix: / refactor: 等前缀），可以统计类型分布：

# 统计各类型提交数量
git log --format="%s" | grep -oE '^(feat|fix|refactor|docs|chore|test|perf|style|build|ci|revert):' | sort | uniq -c | sort -rn

输出示例：

  2450 fix:
  1980 feat:
   890 refactor:
   420 docs:
   310 chore:
   180 test:
    90 perf:

这个分布告诉你：

• fix: 占比高 → 项目处于"修修补补"阶段，稳定性问题多
• refactor: 占比高 → 团队重视代码质量，重构频繁
• feat: 占比高 → 项目处于快速迭代期

2.3 提取"有信息量"的提交

对于没有规范前缀的仓库，用关键词过滤出高价值提交：

# 找出包含"重构/迁移/升级/架构"等关键词的提交
git log --oneline --grep="重构\|重构\|迁移\|升级\|架构\|redesign\|migrate\|upgrade\|rewrite"

# 找出包含"fix"且涉及核心文件的提交
git log --oneline --grep="fix" -- src/core/

判断提交信息量的标准：

• 高信息量：说明了"改了什么 + 为什么改"（如"重构 API 注册模块的状态管理，改用 Pinia 替代 Vuex"）
• 低信息量：只说"改了什么"甚至什么都没说（如"update"、“fix bug”）

---

三、演进脉络：从提交时间线还原项目发展轨迹

3.1 按时间线聚合提交

把提交按时间聚合，能看到项目的"呼吸节奏"：

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

# 按季度统计
git log --format="%ad" --date=format:"%Y-Q$(( (10#$(date -d @$(git log -1 --format=%ct) +%m) - 1) / 3 + 1 ))" 2>/dev/null || \
git log --format="%ad" --date=format:"%Y-%m" | sort | uniq -c

输出示例（按月）：

2021-03   45
2021-04   120
2021-05   180
2021-06   90
2021-07   60
...
2022-01   210
2022-06   320
2022-12   180
...
2023-03   400
2023-09   280
...
2025-01   60
2025-06   30

从时间线能读出什么：

• 启动期（2021-03~06）：提交量从 45 涨到 180，项目快速起步
• 平稳期（2021-07~12）：提交量回落，进入常规迭代
• 爆发期（2022-2023）：提交量高峰，可能是大版本迭代或团队扩张
• 衰退期（2025 后）：提交量骤降，项目进入维护模式

3.2 识别"提交密度"异常点

提交密度的突变往往对应重大事件：

# 找出单日提交数最多的 10 天
git log --format="%ad" --date=format:"%Y-%m-%d" | sort | uniq -c | sort -rn | head -10

输出示例：

  58  2022-06-15
  52  2022-06-16
  47  2023-03-20
  45  2022-06-14

单日 50+ 提交通常意味着：发布前冲刺、大规模重构、或架构迁移。这些日期就是"里程碑候选"。

3.3 用 git log --stat 看变更规模

# 查看某次提交的变更规模
git show --stat <commit-hash>

# 找出"大提交"（变更文件数多的提交）
git log --format="%h %ad %s" --date=short --name-only | awk '/^[0-9a-f]{7} /{if (count>0) print prev, count; prev=$0; count=0} /^[^0-9a-f]/{count++} END{if (count>0) print prev, count}' | sort -k2 -rn | head -20

**大提交（一次改 50+ 文件）**往往是：

• 架构级重构
• 依赖升级（改了所有 import）
• 代码格式化（全量 prettier）
• 目录重组

这些提交是演进脉络的关键节点。

---

四、关键里程碑、重大重构、架构变更识别

4.1 里程碑识别方法

结合前面几步，用"三重信号"识别里程碑：

信号	判断方法	示例
提交密度突变	单日/单周提交数异常高	发布冲刺、重构周
大提交	一次变更 50+ 文件	架构迁移、依赖升级
语义关键词	message 含"重构/迁移/升级/架构"	技术栈切换、模块拆分

把三重信号交叉验证，就能圈出项目的关键节点。

4.2 用 git log -S 找"行为变更"

git log -S（pickaxe）能找出"某个字符串出现/消失"的提交——这是定位功能变更的利器：

# 找出"Vuex"被移除的提交（技术栈切换）
git log --oneline -S "Vuex"

# 找出"createStore"首次出现的提交
git log --oneline -S "createStore" --reverse | head -1

# 找出某个函数被删除的提交
git log --oneline -S "handleWeirdCase" --all

pickaxe 的价值：它不依赖 commit message，直接从代码内容变化里找信号。即使提交 message 是"update"，只要它删除了 Vuex，-S "Vuex" 就能把它揪出来。

4.3 用 git log --follow 追踪文件演进

# 追踪某个文件的完整历史（含重命名）
git log --follow --oneline -- src/core/model-service.js

# 看这个文件被改了多少次
git log --follow --oneline -- src/core/model-service.js | wc -l

文件演进追踪的价值：一个核心文件从"创建 → 频繁修改 → 稳定"，它的修改历史就是一段微型的架构演进史。

---

五、输出演进报告

挖掘完成后，把发现整理成"演进报告"。这是蒸馏流程的第二个正式产出物。

5.1 演进报告模板

# 演进报告：xxx

## 项目生命周期
- 启动：2021-03（45 提交/月）
- 快速成长期：2021-04 ~ 2021-06（提交量 3 倍增长）
- 平稳迭代期：2021-07 ~ 2021-12
- 爆发期：2022-2023（月均 250+ 提交）
- 维护期：2025 至今（月均 <50 提交）

## 关键里程碑

### M1: 项目启动（2021-03）
- 事件：创建仓库，搭建基础脚手架
- 证据：首批 45 个提交集中在脚手架搭建
- 影响：奠定项目技术栈（Vue 3 + Vite + Element Plus）

### M2: 首次架构调整（2021-06）
- 事件：从"单文件"重构为"模块化目录"
- 证据：2021-06-15 单日 58 提交，src/ 目录重组
- 影响：确立 src/api、src/components、src/core 分层

### M3: 技术栈迁移（2022-06）
- 事件：Vuex → Pinia 状态管理迁移
- 证据：git log -S "Vuex" 显示 2022-06 集中移除
- 影响：状态管理统一，性能提升

### M4: 核心模块重构（2023-03）
- 事件：API 注册模块重构
- 证据：2023-03-20 单日 47 提交，重构提交密集
- 影响：模块可维护性大幅提升

## 重大重构清单
| 时间 | 重构内容 | 涉及范围 | 动机 |
|------|---------|---------|------|
| 2021-06 | 目录模块化 | 全仓库 | 可维护性 |
| 2022-06 | Vuex→Pinia | 全局状态 | 性能/生态 |
| 2023-03 | API 模块重构 | src/api | 可维护性 |

## 架构变更时间线
2021-03 单体脚手架
  → 2021-06 模块化分层
  → 2022-06 状态管理统一
  → 2023-03 核心模块重构
  → 2024-01 引入微前端（待确认）

## 风险与待确认
- 2024-01 疑似引入微前端，但 commit message 无记录，需查 PR/issue 确认
- 2025 年后提交骤降，需确认是"稳定"还是"停滞"

5.2 演进报告的用途

演进报告是蒸馏流程的时间轴骨架：

• 给 05 架构分析：知道架构"现在长这样"之前经历了什么
• 给 06 文档蒸馏：知道哪些时间段的 issue/PR 讨论最有价值
• 给 08 决策记录：里程碑 = 决策背景的锚点
• 给 12 虚拟人化：演进报告是虚拟人 memory 的"时间线"部分

---

六、小结

这一篇的核心收获：

1. 过滤噪音：commit message 语义提取，用类型统计和关键词过滤筛出高价值提交。
2. 还原脉络：按时间线聚合提交，从提交密度突变识别项目生命周期阶段。
3. 识别里程碑：用"提交密度 + 大提交 + 语义关键词"三重信号，加上 git log -S pickaxe 定位行为变更。
4. 输出演进报告：一份带时间线、里程碑、重构清单的演进报告，是后续蒸馏的骨架。

下一篇，我们转向代码本身：[05 代码结构分析：模块、依赖、架构识别](05-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-代码结构分析.md)——从静态代码里识别出系统的架构模式。

---

上一篇：[03 仓库盘点：理解仓库结构与规模](03-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-仓库盘点.md)
下一篇：[05 代码结构分析：模块、依赖、架构识别](05-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-代码结构分析.md)