---
title: "SemanticCodeGraph"
type: concept
tags: ["code-intelligence", "semantic-graph", "LSP", "symbol-index", "navigation"]
sources: ["lsp-index-engineer.md"]
last_updated: 2026-04-29
---

## Definition
语义代码图谱（Semantic Code Graph）是以**节点**（文件/模块/符号）和**边**（语义关系）表示代码结构统一语义抽象的数据结构。相比纯文本搜索和 AST 解析，语义图谱能够表达代码的深层语义关系（调用链、继承关系、类型层次），为代码导航、重构分析和可视化提供结构化数据基础。

## Core Mechanism

### Node Schema
```typescript
interface GraphNode {
  id: string;        // "file:src/foo.ts" or "sym:AppController#method"
  kind: 'file' | 'module' | 'class' | 'function' | 'variable' | 'type';
  file?: string;     // Parent file path
  range?: Range;     // LSP Range for symbol location
  detail?: string;  // Type signature or brief description
}
```

### Edge Schema
```typescript
interface GraphEdge {
  id: string;        // "edge:uuid"
  source: string;    // Node ID
  target: string;   // Node ID
  type: 'contains' | 'imports' | 'extends' | 'implements' | 'calls' | 'references';
  weight?: number;  // Importance/frequency weight
}
```

### Consistency Invariants
- **每个符号有且仅有一个定义节点**
- **所有边必须引用有效节点 ID**
- **文件节点必须先于其包含的符号节点存在**
- **Import 边必须解析到实际文件/模块节点**
- **Reference 边必须指向定义节点**

## Graph Construction Pipeline
1. **收集文件**：通过 glob 扫描所有源文件
2. **创建文件节点**：为每个文件创建 `file:` 节点
3. **提取符号**：通过 LSP `textDocument/documentSymbol` 提取符号
4. **添加符号节点**：为每个符号创建 `sym:` 节点
5. **添加 Contains 边**：文件节点 → 符号节点
6. **解析引用**：通过 LSP `textDocument/references` 解析引用关系
7. **添加语义边**：imports / calls / references / extends / implements

## Connections
- [[SemanticCodeGraph]] ← built_by ← [[GraphDaemon]]
- [[SemanticCodeGraph]] ← uses ← [[LSPOrchestrator]]
- [[SemanticCodeGraph]] ← persisted_as ← [[nav.index.jsonl]]
- [[SemanticCodeGraph]] ← indexed_via ← [[LSIF]]