09-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-知识图谱构建

09 知识图谱构建：连接知识节点

这是《Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人》系列的第 9 篇。前几篇我们蒸馏出了各种"碎片"：仓库画像、演进报告、架构文档、知识摘要、模式库、决策记录。这一篇把这些碎片织成一张网——知识图谱。碎片是"点"，图谱是"网"，而虚拟人需要的正是这张网。

一、为什么需要知识图谱

前几篇的产出物是"文档"，文档的问题是割裂：

• 架构文档里提到"状态管理用 Pinia"，但没说为什么
• 决策记录里说"用 Pinia 因为 TS 支持好"，但没说影响哪些模块
• 模式库里说"统一请求封装"，但没说在哪些模块被使用

这些信息单独看都对，连起来才完整。知识图谱就是把它们连起来：

[ADR-001: 用 Pinia] --决策影响--> [src/stores/ 模块]
        |
        +--理由--> [TypeScript 支持好]
        |
        +--关联--> [issue #123]

[统一请求封装模式] --被使用于--> [src/api/ 模块]
        |
        +--关联--> [ADR-003: 错误处理规范]

图谱的价值：从"查文档"变成"查关系"。问"为什么用 Pinia"，图谱能给出完整链路：决策 → 理由 → 影响范围 → 相关 issue。

二、知识节点定义：实体、概念、决策、模式

2.1 节点类型

知识图谱的节点（Node）是"知识单元"，分为四类：

2.2 节点定义规范

每个节点有统一的属性：

{
  "id": "entity:src/stores",
  "type": "entity",
  "name": "src/stores/",
  "description": "全局状态管理模块",
  "source": "架构文档",
  "created": "2022-06"
}

节点 ID 规范：类型:名称，如 entity:src/stores、concept:状态管理、decision:ADR-001、pattern:统一请求封装。

2.3 从产出物提取节点

前几篇的产出物是节点的来源：

三、关系建模：依赖、引用、演进、决策

3.1 关系类型

节点之间的边（Edge）是"关系"，分为四类：

3.2 关系定义规范

{
  "source": "entity:src/views",
  "relation": "depends_on",
  "target": "entity:src/api",
  "description": "页面层调用接口层",
  "source_doc": "架构文档"
}

关系类型枚举：

• depends_on（依赖）
• references（引用）
• evolved_from（演进）
• decides / affected_by（决策）
• implements（实现）
• related_to（关联）

3.3 关系建模示例

把前几篇的知识连起来：

{
  "nodes": [
    { "id": "entity:src/stores", "type": "entity", "name": "src/stores/" },
    { "id": "concept:状态管理", "type": "concept", "name": "状态管理" },
    { "id": "decision:ADR-001", "type": "decision", "name": "用 Pinia 替代 Vuex" },
    { "id": "pattern:store-factory", "type": "pattern", "name": "Store 工厂" }
  ],
  "edges": [
    { "source": "entity:src/stores", "relation": "implements", "target": "concept:状态管理" },
    { "source": "decision:ADR-001", "relation": "decides", "target": "entity:src/stores" },
    { "source": "pattern:store-factory", "relation": "implements", "target": "entity:src/stores" },
    { "source": "decision:ADR-001", "relation": "related_to", "target": "pattern:store-factory" }
  ]
}

四、图谱构建工具

4.1 轻量方案：JSON + 可视化

对于中小型仓库，用 JSON 存图谱 + 可视化工具展示：

# 安装可视化工具（如 vis-network / cytoscape）
npm install vis-network

# 或用 Python 的 networkx 生成图
pip install networkx matplotlib

Python 生成图谱可视化：

#!/usr/bin/env python3
# scripts/build_graph.py
import json
import networkx as nx
import matplotlib.pyplot as plt

def build_graph(data):
    G = nx.DiGraph()
    for node in data["nodes"]:
        G.add_node(node["id"], label=node["name"], type=node["type"])
    for edge in data["edges"]:
        G.add_edge(edge["source"], edge["target"], relation=edge["relation"])
    return G

def visualize(G, output="graph.png"):
    pos = nx.spring_layout(G, seed=42)
    plt.figure(figsize=(16, 12))
    nx.draw(G, pos, with_labels=True, node_size=2000,
            node_color="lightblue", font_size=8, arrows=True)
    labels = nx.get_edge_attributes(G, "relation")
    nx.draw_networkx_edge_labels(G, pos, edge_labels=labels, font_size=6)
    plt.savefig(output, dpi=150, bbox_inches="tight")
    print(f"图谱已保存: {output}")

if __name__ == "__main__":
    with open("knowledge-graph.json") as f:
        data = json.load(f)
    G = build_graph(data)
    print(f"节点数: {G.number_of_nodes()}, 边数: {G.number_of_edges()}")
    visualize(G)

4.2 专业方案：Neo4j 图数据库

对于大型仓库，用图数据库存储和查询：

// 创建节点
CREATE (stores:Entity {name: 'src/stores/', type: 'entity'})
CREATE (pinia:Decision {name: 'ADR-001', title: '用 Pinia 替代 Vuex'})
CREATE (state:Concept {name: '状态管理', type: 'concept'})

// 创建关系
CREATE (pinia)-[:DECIDES]->(stores)
CREATE (stores)-[:IMPLEMENTS]->(state)

// 查询：状态管理相关的所有知识
MATCH (n)-[r]-(m)
WHERE n.name = '状态管理' OR m.name = '状态管理'
RETURN n, r, m

4.3 查询示例：回答"为什么用 Pinia"

// 从决策出发，查理由和影响范围
MATCH (d:Decision {name: 'ADR-001'})-[r]-(n)
RETURN d.name, type(r), n.name, n.type

输出：

ADR-001  DECIDES  src/stores/  entity
ADR-001  RELATED_TO  store-factory  pattern
ADR-001  REFERENCES  issue#123  entity

五、输出知识图谱

5.1 图谱交付物

知识图谱的交付物包括：

knowledge-graph/
├── knowledge-graph.json   # 图谱数据（节点+边）
├── graph.png              # 可视化图
├── node-index.md          # 节点索引
└── query-examples.md      # 常用查询示例

5.2 节点索引

# 知识图谱节点索引

## 实体（Entity）
| ID | 名称 | 说明 |
|----|------|------|
| entity:src/stores | src/stores/ | 全局状态管理模块 |
| entity:src/api | src/api/ | 接口层 |
| entity:src/core | src/core/ | 核心业务逻辑 |

## 概念（Concept）
| ID | 名称 | 说明 |
|----|------|------|
| concept:状态管理 | 状态管理 | 全局状态管理方案 |
| concept:分层架构 | 分层架构 | UI→业务→数据 |

## 决策（Decision）
| ID | 名称 | 状态 |
|----|------|------|
| decision:ADR-001 | 用 Pinia 替代 Vuex | 已接受 |

## 模式（Pattern）
| ID | 名称 | 分类 |
|----|------|------|
| pattern:store-factory | Store 工厂 | 状态层 |
| pattern:unified-request | 统一请求封装 | 请求层 |

5.3 图谱的用途

知识图谱是蒸馏流程的知识网络：

• 给 10 工具链：图谱是工具链的"知识底座"，查询接口基于图谱
• 给 12 虚拟人化：图谱是虚拟人 memory 的"关系层"，让虚拟人能"联想"知识
• 给 13 落地：虚拟人回答问题时，通过图谱做知识关联检索

六、小结

这一篇的核心收获：

1. 节点定义：实体、概念、决策、模式四类节点，统一 ID 规范。
2. 关系建模：依赖、引用、演进、决策四类关系，把碎片连成网。
3. 构建工具：轻量方案（JSON + networkx 可视化）和专业方案（Neo4j 图数据库）。
4. 输出知识图谱：图谱数据 + 可视化 + 节点索引 + 查询示例，是虚拟人的"关系层"。

下一篇，我们搭建蒸馏的流水线：[10 蒸馏工具链：自动化蒸馏流水线](10-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-蒸馏工具链.md)——把前几篇的手工操作，固化成可重复执行的自动化流水线。

上一篇：[08 决策记录生成：用 ADR 固化架构决策](08-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-决策记录生成.md)
下一篇：[10 蒸馏工具链：自动化蒸馏流水线](10-Git 仓库蒸馏术：从代码仓库到 OpenClaw 虚拟人-蒸馏工具链.md)