统一上下文图谱

lean-ctx 构建一个统一图谱，将代码、提交、测试、知识和问题连接起来--实现任务感知的上下文供给和深度影响分析。

节点类型

图谱包含 8 种节点类型，代表项目的不同方面：

📄 File

索引器追踪的源文件

🔣 Symbol

函数、类、类型和变量

📦 Module

逻辑分组（包、crate、模块）

📝 Commit

带消息和元数据的 Git 提交

🧪 Test

测试函数和测试文件

🏗️ CIRun

CI/CD 流水线运行和结果

🧠 Knowledge

来自 ctx_session 的项目知识

🎫 Issue

与代码关联的问题和工单

边类型

边表示节点之间的关系。lean-ctx 追踪 11 种边类型：

边类型	含义	示例
`Imports`	文件导入另一个文件	`A.ts → B.ts`
`Calls`	函数调用另一个函数	`fn_a → fn_b`
`Defines`	模块定义一个符号	`mod → fn`
`TestedBy`	文件被测试文件测试	`utils.rs → test_utils.rs`
`ChangedIn`	文件在提交中被修改	`file → commit`
`MentionedIn`	文件在知识事实中被提及	`file → knowledge`
`Affects`	问题影响一个文件	`issue → file`
`Breaks`	提交破坏了一个测试	`commit → test`

图谱丰富化

丰富化通过 Git、测试和知识数据扩展代码图谱--创建统一的项目视图。

Git 历史索引器

解析最近的 Git 提交（默认：最近 500 条），创建 Commit 节点和指向受影响文件的 ChangedIn 边。

测试索引器

通过命名约定（test_、_test、_spec）检测测试文件，并通过 TestedBy 边将其链接到源文件。

知识桥接

将通过 ctx_session 记录的项目知识事实与引用的文件通过 MentionedIn 边关联。

MCP 命令

ctx_graph enrich              # Enrich graph with git, tests, knowledge
ctx_graph build               # Index code structure
ctx_graph status              # Show node/edge counts

Community Detection (Louvain)

The Louvain algorithm clusters files into communities based on their dependency relationships. Files that frequently import each other or share transitive dependencies are grouped together, enabling smarter context preloading and relevance scoring for task-driven queries.

PageRank

Computes file importance scores based on the dependency graph structure. Files imported by many others (structural hubs) receive higher PageRank, which is used by Spectral Relevance and Boltzmann Allocation to prioritize high-impact files during context assembly.

上下文查询

使用基于图谱的上下文查询，为任何任务找到最相关的文件--利用结构、历史和语义连接。

使用方法

ctx_graph context "fix auth bug"       # Find relevant files for task
ctx_graph related src/auth.rs          # Connected files
ctx_graph impact src/auth.rs           # Blast radius analysis
ctx_graph symbol src/auth.rs::verify   # Symbol definition/usages

工作原理

从任务描述中提取关键词
将关键词与文件名和提交消息匹配
通过图谱边（导入、测试、知识）扩展结果
返回带有关系上下文的相关文件排名列表

交互式 HTML 导出

将您的依赖关系图导出为单个自包含的 HTML 文件。生成的文件完全离线运行--在任何浏览器中打开即可可视化探索您的代码库。无需服务器，无需依赖，只需一个 HTML 文件。

使用方法

# Export full graph (all nodes)
lean-ctx graph export-html --out graph.html

# Limit to 100 most-connected nodes
lean-ctx graph export-html --out graph.html --max-nodes 100

# Custom project root
lean-ctx graph export-html --out graph.html --root /path/to/project

交互功能

🔍 Search

输入任意文件路径子串即可即时高亮匹配节点

🖱️ Pan & Zoom

点击拖动平移，滚轮缩放。操作如同地图。

📋 Node Details

点击任意节点可在侧边栏查看其导入和依赖项

🔗 Reverse Deps

右键点击节点可高亮所有依赖它的文件（BFS 遍历）

🖼️ PNG Export

一键将当前画布视图下载为 PNG 图片

📡 Offline

无外部依赖。整个应用嵌入在一个 HTML 文件中。

提示

使用 --max-nodes 保持大型项目可视化的可读性（50–200 是推荐范围）
导出前先运行 graph build 确保索引是最新的
HTML 文件可安全分享给团队成员--它不包含源代码，只有文件路径和关系
右键高亮显示完整的反向依赖链，便于评估更改的影响范围

仪表盘 API

端点	描述
`/api/graph/stats`	节点和边的数量、数据库路径
`/api/graph/enrich`	触发完整图谱丰富化并返回统计信息