02 蒸馏目标定义：从仓库提炼什么、产出物清单

这是《Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人》系列的第 2 篇。第 01 篇讲了"为什么需要蒸馏"，这一篇回答紧接着的问题：到底要蒸馏什么？ 在跑任何 git 命令之前，先想清楚目标——否则你会被 8,000 次提交和 40 个模块淹没。

---

一、先想清楚：蒸馏不是"把仓库全读一遍"

很多人听到"仓库蒸馏"，第一反应是"把仓库里所有东西都整理一遍"。这是最大的误区。

一个维护了 5 年的仓库，包含：

• 8,000 次提交、40 个模块、20 万行代码
• 3,000 个 issue、2,000 个 PR
• 无数过期的注释和文档

你不可能、也不需要把所有这些都蒸馏。 蒸馏的本质是"有选择地提取"，而选择的前提是——明确目标。

这一篇的核心任务，就是帮你回答三个问题：

1. 从仓库中提炼什么？（蒸馏的 6 类内容）
2. 产出物有哪些、优先级怎么排？（8 类产出物清单）
3. 怎么根据团队需求确定蒸馏范围？（范围决策方法）

---

二、从仓库中提炼什么：6 类核心内容

仓库里的知识可以归纳为 6 大类。每一类对应一个"知识问题"，蒸馏就是回答这些问题：

#	内容类别	回答的知识问题	典型来源
1	架构	系统现在长什么样？模块怎么划分？	目录结构、依赖关系、import 图
2	演进	系统是怎么一步步长成这样的？	commit 时间线、里程碑、重构记录
3	模式	有哪些可复用的设计模式和最佳实践？	重复代码、惯用法、团队约定
4	决策	为什么这么设计？考虑过哪些方案？	commit message、PR 讨论、issue
5	API	对外暴露了什么接口？怎么用？	接口定义、类型声明、文档
6	技术债	哪些地方是"刻意留下的坑"？	TODO、FIXME、workaround、hack

2.1 架构：系统的"是什么"

架构蒸馏回答"系统现在长什么样"。这是最基础、也最容易被"文档"覆盖的一类——但正如第 01 篇所说，文档会过期，而从代码里蒸馏出来的架构是实时的。

蒸馏架构不是画一张漂亮的架构图，而是回答：

• 有哪些模块？模块之间的依赖关系是什么？
• 是分层架构、微服务、还是单体 + 模块化？
• 核心业务逻辑在哪？基础设施代码在哪？
• 哪些模块是"核心资产"，哪些是"历史包袱"？

2.2 演进：系统的"怎么来的"

演进蒸馏回答"系统是怎么一步步长成这样的"。这是文档永远无法提供的知识——因为文档只记录现状，不记录过程。

从 commit 时间线里，你能还原出：

• 项目从 0 到 1 的关键节点
• 几次重大重构的来龙去脉
• 架构从"简单"到"复杂"的演变路径
• 哪些模块是"后来加的"，哪些是"一开始就在的"

演进知识对新人尤其宝贵——它解释了"为什么代码长这样"，而不是让人对着现状瞎猜。

2.3 模式：系统的"可复用资产"

模式蒸馏回答"有哪些可以带走的东西"。这是蒸馏中复用价值最高的一类。

• 团队反复使用的设计模式（工厂、策略、观察者……）
• 项目特有的惯用法（错误处理方式、状态管理约定）
• 可复用的工具函数、公共组件
• 团队约定俗成的代码规范

模式蒸馏的产出是"模式库"——一份可以指导新代码怎么写、也可以让新人快速上手的资产。

2.4 决策：系统的"为什么"

决策蒸馏回答"为什么这么设计"。这是隐性知识密度最高的一类，也是蒸馏最有价值的部分。

一个"看起来不合理"的设计，背后往往有一个合理的历史原因：

• 当年为了赶上线，用了一个临时方案，后来一直没重构
• 某个第三方库有 bug，团队绕开了它，用了 workaround
• 业务需求变了，但代码没跟上，留下了"历史遗留"

决策蒸馏把这些"为什么"从 commit、PR 讨论、issue 里挖出来，整理成决策记录（ADR）——让后人不再对着代码猜。

2.5 API：系统的"对外接口"

API 蒸馏回答"系统对外暴露了什么、怎么用"。这是消费频率最高的一类知识。

• 对外提供的接口/服务清单
• 每个接口的入参、出参、错误码
• 调用方式、鉴权方式、限流规则
• 版本演进（哪些接口废弃了、哪些是新加的）

API 知识是团队协作的基础——前端要调后端接口、新模块要复用老模块的能力，都依赖清晰的 API 认知。

2.6 技术债：系统的"坑在哪"

技术债蒸馏回答"哪些地方是刻意留下的坑"。这是最容易被忽视、却最救命的一类知识。

• TODO / FIXME / HACK / workaround 的分布
• 哪些"看起来该重构"的地方其实不能动（动了就崩）
• 哪些依赖是"必须锁版本"的（升级会炸）
• 哪些模块是"接手即地狱"的（需要特殊小心）

技术债知识让团队知道"哪里能碰、哪里不能碰"，避免新人（甚至老人）踩进历史遗留的坑。

---

三、产出物清单：8 类可交付资产

6 类内容蒸馏之后，落地为 8 类产出物。每一类都有明确的消费场景和格式：

#	产出物	对应内容	格式	消费场景
1	仓库画像	仓库结构、规模、元信息	Markdown / 表格	快速了解仓库全貌
2	演进报告	提交历史、里程碑、重构脉络	Markdown / 时间线	理解项目发展轨迹
3	架构文档	模块、依赖、架构模式	Markdown / 图	理解系统结构
4	知识摘要	README、注释、issue、PR 精华	Markdown	快速获取隐性知识
5	模式库	可复用设计模式、最佳实践	Markdown / 代码片段	指导新代码编写
6	决策记录	ADR：为什么这么设计	Markdown / ADR 模板	理解设计动机
7	知识图谱	实体、关系、依赖可视化	图 / JSON	全局视角看系统
8	工具链方案	git 命令 + AI 工具组合	Markdown / 脚本	可复用的蒸馏流程

3.1 优先级怎么排

8 类产出物不是都要做，也不是都要做到同样深度。优先级取决于团队当前最痛的问题：

团队痛点	优先产出物	原因
新人 onboarding 慢	仓库画像 + 架构文档 + 演进报告	先让新人"看懂"，再让新人"敢改"
核心成员离职风险	决策记录 + 知识摘要	把"脑子里的知识"抢救成文档
代码质量参差、重复造轮子	模式库	统一写法，减少重复
文档过期、没人信文档	架构文档 + API 清单	从代码蒸馏，实时准确
历史包袱多、不敢动	技术债清单 + 决策记录	知道哪些坑不能踩

一个判断原则：如果一份产出物做出来，团队里没人会去读、没人会去用，那它就不该做。蒸馏的产出物必须"有人消费"，否则就是自嗨。

---

四、如何根据团队需求确定蒸馏范围

蒸馏范围不是"仓库有多大"，而是"团队需要什么"。用三步法确定范围：

第一步：列出利益相关者

谁会用蒸馏产物？他们关心什么？

角色	关心的问题	需要的产出物
新人	系统怎么跑？模块怎么分工？	仓库画像、架构文档
维护者	哪里能改？哪里不能碰？	技术债清单、决策记录
架构师	架构是否合理？演进方向？	架构文档、演进报告
技术负责人	有哪些可复用资产？	模式库、API 清单
新项目团队	能不能复用这个仓库的能力？	模式库、API 清单、知识图谱

第二步：确定"蒸馏深度"

同一类产出物，可以做到不同深度：

L1 概览级：一页纸说清楚（适合快速了解）
L2 结构级：模块 + 依赖 + 关键路径（适合日常开发）
L3 细节级：逐模块深入 + 决策背景（适合核心资产）

建议：核心模块做到 L3，一般模块做到 L2，边缘模块 L1 即可。不要平均用力。

第三步：明确"不做"什么

蒸馏范围要明确边界，防止无限膨胀：

• ❌ 不蒸馏"所有" commit（只蒸馏有信息量的）
• ❌ 不蒸馏"所有" issue（只蒸馏有决策价值的）
• ❌ 不蒸馏"所有"代码（只蒸馏有复用价值的）
• ❌ 不蒸馏"所有"历史（只蒸馏对当前有意义的）

蒸馏是减法，不是加法。 做减法的标准是：这份知识"现在或可预见的未来"会不会被用到？用不到，就不蒸馏。

---

五、产出物驱动的大纲设计

这个系列的 14 篇大纲，就是"产出物驱动"设计的——每一章对应一个可交付产出：

01 为什么需要仓库蒸馏        → 认知（为什么做）
02 蒸馏目标定义              → 产出规划（做什么）  ← 本篇
03 仓库盘点                  → 仓库画像（产出物 1）
04 提交历史挖掘              → 演进报告（产出物 2）
05 代码结构分析              → 架构文档（产出物 3）
06 文档蒸馏                  → 知识摘要（产出物 4）
07 代码模式提炼              → 模式库（产出物 5）
08 决策记录生成              → 决策记录（产出物 6）
09 知识图谱构建              → 知识图谱（产出物 7）
10 蒸馏工具链                → 工具链方案（产出物 8）
11 OpenClaw 虚拟人机制       → 认知（虚拟人是什么）
12 蒸馏产物 → 虚拟人         → 虚拟人雏形（memory + skills）
13 虚拟人落地                → 可用的仓库专家
14 实战案例与总结            → 全套模板

这种"产出物驱动"的设计有一个好处：每章结束，你手里都多了一个能用的东西，而不是"又学了一堆概念"。跟着系列走完，你自然就攒齐了 8 类产出物 + 1 个虚拟人 + 1 套模板。

5.1 一个可复用的蒸馏目标模板

在开始蒸馏前，建议先写一份"蒸馏目标声明"，作为整个流程的锚点：

# 蒸馏目标声明

## 仓库
- 名称：xxx
- 规模：xx 万行 / xx 模块 / xx 年历史

## 利益相关者
- 主要消费者：新人 / 维护者 / 架构师 / 技术负责人
- 他们最痛的问题：xxx

## 蒸馏范围
- 内容类别（6 类中选）：架构、演进、模式、决策、API、技术债
- 深度：核心模块 L3 / 一般模块 L2 / 边缘模块 L1

## 产出物清单（8 类中选）
- [ ] 仓库画像（优先级：高）
- [ ] 演进报告（优先级：中）
- [ ] 架构文档（优先级：高）
- [ ] 知识摘要（优先级：中）
- [ ] 模式库（优先级：中）
- [ ] 决策记录（优先级：高）
- [ ] 知识图谱（优先级：低）
- [ ] 工具链方案（优先级：中）

## 明确不做
- 不蒸馏：xxx（理由：xxx）

## 验收标准
- 蒸馏完成后，团队能回答哪些问题？
- 虚拟人上线后，能回答哪些问题？

这份声明写清楚后，后面 03~10 篇的每一步都有了"该做什么、做到什么程度"的依据。

---

六、小结

这一篇的核心就三句话：

1. 蒸馏是减法：从 6 类内容（架构/演进/模式/决策/API/技术债）中，只选团队需要的。
2. 产出物驱动：8 类产出物按优先级排，每份产出物必须"有人消费"。
3. 范围要明确：用"利益相关者 → 深度 → 不做清单"三步法，防止蒸馏无限膨胀。

下一篇，我们开始动手：[03 仓库盘点：理解仓库结构与规模](03-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-仓库盘点.md)——用 git log、git shortlog、cloc、tree 等命令，先给仓库画一张"画像"。

---

上一篇：[01 为什么需要仓库蒸馏](01-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-为什么需要仓库蒸馏.md)
下一篇：[03 仓库盘点：理解仓库结构与规模](03-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-仓库盘点.md)