06-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-文档蒸馏

06 文档蒸馏：从 issue、PR、README 提炼知识

这是《Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人》系列的第 6 篇。前几篇我们分析了仓库的"骨架"（结构、历史、架构），这一篇开始"蒸馏"——把散落在仓库各处的知识，提炼成结构化的文档。如果说代码是系统的"肉体"，那散落的文档、issue、PR、注释就是系统的"记忆"，而蒸馏就是把这些记忆整理成"传记"。

一、知识散落在哪：五大来源

仓库里的知识不是集中存放的，而是散落在五个地方：

关键认知：知识不是"没有"，而是"散落"。蒸馏的第一步，是把散落的知识收集起来；第二步，才是提炼成结构化文档。

二、收集：把散落的知识捞出来

2.1 README 与 docs/ 目录

# 列出所有文档
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*"

# 看 docs/ 目录结构
tree docs/ -L 2

# 统计文档规模
find . -name "*.md" -not -path "*/node_modules/*" | xargs wc -l | tail -1

收集时关注：

• README 是否过时（描述的功能是否还存在）
• docs/ 是否有清晰的目录结构
• 有没有"孤儿文档"（没人引用、没人维护）

2.2 issue：用 GitHub CLI 拉取

# 安装 GitHub CLI
brew install gh
gh auth login

# 拉取所有已关闭的 issue（含讨论）
gh issue list --state all --limit 500 --json number,title,body,labels,createdAt,closedAt

# 拉取带"决策"标签的 issue
gh issue list --label "decision" --state all --json number,title,body

# 拉取某个 issue 的完整讨论
gh issue view 123 --comments

2.3 PR：用 GitHub CLI 拉取

# 拉取所有已合并的 PR
gh pr list --state merged --limit 500 --json number,title,body,mergedAt

# 拉取某个 PR 的评审讨论
gh pr view 456 --comments

# 拉取 PR 关联的 commit
gh pr view 456 --json commits

PR 是知识富矿：一个 PR 的 body 往往写着"为什么这么改"，评审讨论里藏着"为什么不那么改"——这是决策记录（第 08 篇）的核心素材。

2.4 代码注释：用 grep 提取

# 提取 TODO / FIXME / HACK（技术债信号）
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.js" --include="*.vue"

# 提取"为什么"类注释（设计意图）
grep -rn "为什么\|why\|because\|注意\|NOTE" src/ --include="*.ts" | head -50

# 提取"不要"类注释（坑点提醒）
grep -rn "不要\|别\|don't\|never\|avoid" src/ --include="*.ts" | head -50

注释提取的价值：// 这里不能直接用 xxx，因为会触发 yyy 这种注释，是代码里最浓缩的知识——它记录了"踩过的坑"。

三、提炼：从散落信息到结构化知识

收集只是第一步，真正的蒸馏是提炼。提炼的核心方法是"三问"：

3.1 提炼三问

对每一条收集到的信息，问三个问题：

1. 它是什么？（事实：系统做了什么）
2. 它为什么存在？（动机：为什么这么做）
3. 它有什么坑？（经验：踩过什么雷）

把答案分别归入"事实 / 动机 / 经验"三类，就完成了从"信息"到"知识"的转化。

3.2 提炼示例

原始信息（散落在 issue #123 的讨论里）：

“之前用 Vuex 的时候，跨模块调用 store 特别痛苦，每次都要写一堆 getter。后来我们讨论了很久，决定迁移到 Pinia，因为它的 setup 风格写起来更直观，而且 TypeScript 支持更好。迁移的时候踩了个坑，Pinia 的 store 不能在 setup 外直接调用，会报错。”

提炼后（结构化知识）：

## 状态管理方案：Pinia

- **事实**：项目使用 Pinia 作为状态管理方案
- **动机**：Vuex 跨模块调用繁琐，Pinia 的 setup 风格更直观、TS 支持更好
- **经验**：Pinia store 不能在 setup 外直接调用，会报错
- **来源**：issue #123（2022-06 讨论）

3.3 用脚本辅助提炼

对于大量 issue/PR，可以写脚本批量提取关键信息：

#!/usr/bin/env python3
# scripts/extract_issues.py
# 用法: python extract_issues.py issues.json > knowledge.md
import json
import sys

def extract(issue):
    """从 issue 中提取结构化知识"""
    return {
        "id": issue.get("number"),
        "title": issue.get("title"),
        "labels": [l.get("name") for l in issue.get("labels", [])],
        "created": issue.get("createdAt"),
        "closed": issue.get("closedAt"),
        "body": issue.get("body", "")[:500],  # 截断长文本
    }

def main():
    issues = json.load(sys.stdin)
    for issue in issues:
        e = extract(issue)
        print(f"## #{e['id']} {e['title']}")
        print(f"- 标签: {', '.join(e['labels']) or '无'}")
        print(f"- 创建: {e['created']} / 关闭: {e['closed']}")
        print(f"- 摘要: {e['body'][:200]}...")
        print()

if __name__ == "__main__":
    main()

# 使用：gh 拉取 JSON 后管道给脚本
gh issue list --state all --json number,title,body,labels,createdAt,closedAt | python scripts/extract_issues.py

四、文档分类与整理

提炼出的知识需要分类归档，才能被后续步骤复用。推荐按"知识类型"分类：

4.1 知识分类体系

4.2 整理目录结构

knowledge/
├── 01-定位/
│   └── 项目简介.md
├── 02-使用/
│   ├── 快速上手.md
│   └── 配置说明.md
├── 03-设计/
│   ├── 架构设计.md
│   └── 状态管理方案.md
├── 04-演进/
│   └── 演进报告.md
└── 05-经验/
    ├── 坑点清单.md
    └── 最佳实践.md

4.3 建立知识索引

分类后，用一份索引文件把知识串起来：

# 知识索引

## 核心知识
- [项目简介](01-定位/项目简介.md) — 项目定位与价值
- [架构设计](03-设计/架构设计.md) — 系统架构与模块边界

## 高频问题
- [状态管理方案](03-设计/状态管理方案.md) — 为什么用 Pinia
- [坑点清单](05-经验/坑点清单.md) — 常见坑与规避

## 演进脉络
- [演进报告](04-演进/演进报告.md) — 项目发展时间线

五、输出知识摘要

蒸馏的最终产出是"知识摘要"——一份浓缩了仓库核心知识的文档。

5.1 知识摘要模板

# 知识摘要：xxx

## 项目定位
一句话说明项目是什么、解决什么问题。

## 核心概念
- 概念1：定义 + 为什么重要
- 概念2：定义 + 为什么重要

## 关键决策
| 决策 | 背景 | 选择 | 原因 |
|------|------|------|------|
| 状态管理 | Vuex 跨模块繁琐 | Pinia | 直观、TS 支持好 |

## 常见坑点
- 坑1：现象 + 原因 + 规避方法
- 坑2：现象 + 原因 + 规避方法

## 最佳实践
- 实践1：适用场景 + 做法
- 实践2：适用场景 + 做法

## 知识来源
- issue #123（状态管理讨论）
- PR #456（架构重构）
- README（项目定位）

5.2 知识摘要的用途

知识摘要是蒸馏流程的知识中枢：

• 给 07 模式提炼：最佳实践是模式提炼的素材
• 给 08 决策记录：关键决策表是决策记录的基础
• 给 09 知识图谱：核心概念是图谱的节点
• 给 12 虚拟人化：知识摘要是虚拟人 memory 的"知识库"部分

六、小结

这一篇的核心收获：

1. 五大来源：README、docs/、issue、PR、代码注释，知识散落各处。
2. 收集：用 gh CLI 拉取 issue/PR，用 grep 提取注释，用 find 盘点文档。
3. 提炼三问：它是什么 / 为什么存在 / 有什么坑，把信息转化为知识。
4. 分类整理：按定位/使用/设计/演进/经验五类归档，建立知识索引。
5. 输出知识摘要：一份浓缩核心知识的文档，是后续蒸馏的知识中枢。

下一篇，我们提炼代码里的智慧：[07 代码模式提炼：从实现中抽象通用模式](07-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-代码模式提炼.md)——从重复的代码实现里，抽象出可复用的模式。

上一篇：[05 代码结构分析：模块、依赖、架构识别](05-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-代码结构分析.md)
下一篇：[07 代码模式提炼：从实现中抽象通用模式](07-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-代码模式提炼.md)