让 AI 编程助手拥有”代码知识图谱”，节约Token成本
项目概览
解决什么问题？
当 Claude Code、Cursor 等 AI 编程助手探索一个代码库时，它们会启动探索代理（Explore Agent），通过 grep、glob、Read 等工具逐个扫描文件——每次工具调用都在消耗 token。
CodeGraph 的思路很直接：给 AI 代理一个预索引的代码知识图谱，包含符号关系、调用图和代码结构。代理可以直接查询图谱，而不是漫无目的地扫描文件。
一句话总结：把”翻书找答案”变成”查字典找答案”。
核心数据：效果有多显著？
作者在 6 个真实代码库上做了基准测试，对比使用和不使用 CodeGraph 的 Explore Agent 表现：
| 代码库 | 使用 CG | 不使用 CG | 改进 |
|---|---|---|---|
| VS Code (TS) | 3次调用, 17s | 52次调用, 1m37s | 94% 更少 · 82% 更快 |
| Excalidraw (TS) | 3次调用, 29s | 47次调用, 1m45s | 94% 更少 · 72% 更快 |
| Claude Code (Python+Rust) | 3次调用, 39s | 40次调用, 1m8s | 93% 更少 · 43% 更快 |
| Claude Code (Java) | 1次调用, 19s | 26次调用, 1m22s | 96% 更少 · 77% 更快 |
| Alamofire (Swift) | 3次调用, 22s | 32次调用, 1m39s | 91% 更少 · 78% 更快 |
| Swift Compiler (Swift/C++) | 6次调用, 35s | 37次调用, 2m8s | 84% 更少 · 73% 更快 |
关键发现
- 使用 CodeGraph 后，Agent 零次回退到读取文件——完全信任图谱结果
- 跨语言查询（Python+Rust）无缝工作
- Swift Compiler 项目（25,874 个文件，272,898 个节点）索引不到 4 分钟，复杂问题 35 秒回答完毕
技术架构
Claude Code / Cursor / Codex / OpenCode │ ▼ ┌─────────────────────────────────────┐ │ CodeGraph MCP Server │ │ ┌─────────┐ ┌─────────┐ ┌───────┐ │ │ │ Search │ │ Callers │ │Context│ │ │ └────┬────┘ └────┬────┘ └───┬───┘ │ │ └───────────┼──────────┘ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ SQLite Graph DB │ │ │ │ • 符号节点 │ │ │ │ • 关系边 │ │ │ │ • FTS5全文搜索 │ │ │ └──────────────────┘ │
- 提取（Extraction）：使用 tree-sitter 将源代码解析为 AST，通过语言特定查询提取节点（函数、类、方法）和边（调用、导入、继承、实现）
- 存储（Storage）：全部存入本地 SQLite 数据库（
.codegraph/codegraph.db），配备 FTS5 全文搜索 - 解析（Resolution）：函数调用→定义、导入→源文件、类继承、框架特定模式
- 自动同步（Auto-Sync）：MCP 服务器通过原生 OS 文件事件（FSEvents/inotify/ReadDirectoryChangesW）监听项目，2 秒防抖，增量更新
核心功能
| 功能 | 说明 |
|---|---|
| 智能上下文构建 | 一次调用返回入口点、相关符号和代码片段 |
| 全文搜索 | 基于 FTS5，跨整个代码库即时查找符号 |
| 影响分析 | 追踪调用者、被调用者，以及更改任何符号的影响范围 |
| 实时同步 | 文件变化自动更新图谱，零配置 |
| 19+ 语言支持 | TS/JS/Python/Go/Rust/Java/C#/PHP/Ruby/C/C++/Swift/Kotlin/Dart/Svelte/Vue/Liquid/Pascal |
| 框架感知路由 | 识别 13 种 Web 框架的路由文件，将 URL 模式链接到处理器 |
| 100% 本地 | 数据不出本机，无 API Key，无外部服务，仅 SQLite |
支持的 Web 框架
MCP 工具集
作为 MCP 服务器运行时，CodeGraph 暴露以下工具给 AI 代理：
| 工具 | 用途 |
|---|---|
codegraph_search |
按名称查找符号 |
codegraph_context |
为任务构建相关代码上下文 |
codegraph_callers |
查找谁调用了某个函数 |
codegraph_callees |
查找某个函数调用了什么 |
codegraph_impact |
分析更改符号的影响范围 |
codegraph_node |
获取单个符号的详细信息 |
codegraph_files |
获取索引的文件结构 |
codegraph_status |
检查索引健康状态和统计信息 |
快速上手
一行安装
npx @colbymchenry/codegraph交互式安装器会自动检测已安装的代理（Claude Code / Cursor / Codex CLI / OpenCode），并自动配置 MCP 服务器。
初始化项目
cd your-project
codegraph init -i构建项目的知识图谱索引。
非交互式安装（CI/脚本）
codegraph install --yes # 自动检测代理，全局安装
codegraph install --target=cursor,claude --yes # 指定目标
codegraph install --target=auto --location=local # 项目级安装代码库集成
import CodeGraph from '@colbymchenry/codegraph';
const cg = await CodeGraph.init('/path/to/project');
await cg.indexAll({
onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});
const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', {
maxNodes: 20,
includeCode: true,
format: 'markdown'
});
const impact = cg.getImpactRadius(results[0].node.id, 2);
cg.watch(); // 文件变化自动同步
cg.unwatch(); // 停止监听
cg.close();实用功能：codegraph affected
追踪变更文件的传递依赖，找出受影响的测试文件：
# 直接传入文件
codegraph affected src/utils.ts src/api.ts
# 从 git diff 管道输入
git diff --name-only | codegraph affected --stdin
# 自定义测试文件模式
codegraph affected src/auth.ts --filter "e2e/*"CI Hook 示例
#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fi项目亮点总结
- 性能提升显著：工具调用减少 92%，速度提升 71%（平均值）
- 零数据外泄：纯本地 SQLite，无 API 调用，适合企业级安全要求
- 多语言覆盖：19 种编程语言 + 13 种 Web 框架感知
- 即插即用：一行命令安装，自动配置 Claude Code / Cursor / Codex / OpenCode
- 增量同步：基于 OS 原生文件事件，编码过程中图谱始终保持最新
- 影响分析：改代码前一键查看影响范围，降低回归风险
适用场景
- 大型代码库中快速定位代码逻辑
- AI 编程助手（Claude Code / Cursor）的 token 优化
- 代码审查前的影响范围分析
- CI/CD 中精准测试（只跑受影响的测试）
- 跨语言项目的代码追踪
