CodeGraph：给 AI 编程助手装上代码知识图谱，省 35% 费用、减少 70% 工具调用

Claude Code 理解你的代码库靠的是「探索」——启动子 Agent 用 grep、glob、Read 扫描文件，每一次工具调用都消耗 token。在 VS Code 级别的项目里回答一个架构问题，它可能调用 23 次工具，处理 140 万 token。

CodeGraph 的做法完全不同：提前把代码库构建成知识图谱，Agent 直接查询图谱，不需要逐个文件扫描。同一个问题，7 次工具调用，39 万 token。

结果：平均省 35% 费用，减少 59% token，减少 70% 工具调用，快 49%。

这篇文章涵盖什么

• CodeGraph 解决什么问题
• 性能基准测试数据
• 工作原理和技术架构
• 怎么安装使用
• 支持的语言和框架

核心问题：AI Agent 的「探索税」

当你在 Claude Code 里问「这个项目的认证流程是怎样的」，它会：

1. 启动 Explore 子 Agent
2. 子 Agent 用 find 扫目录结构
3. 用 grep 搜关键词
4. 用 Read 逐个读文件
5. 每一步都消耗 token 和时间

在大型项目里，这个过程可能需要 20-80 次工具调用。这就是「探索税」——Agent 花大量预算在找代码上，而不是理解和改代码。

CodeGraph 把这个过程前置了。它用 tree-sitter 解析源码，提取符号（函数、类、方法）和关系（调用、导入、继承），存进本地 SQLite 数据库。Agent 需要了解代码时，直接查数据库，一步到位。

基准测试：7 个真实项目

作者在 7 个开源项目上做了对比测试（Claude Opus 4.7，每个项目每个配置跑 4 次取中位数）：

项目	语言	费用节省	Token 减少	速度提升	工具调用减少
VS Code	TypeScript · ~10k 文件	35%	73%	41%	72%
Excalidraw	TypeScript · ~600 文件	47%	73%	60%	86%
Django	Python · ~2.7k 文件	34%	64%	59%	81%
Tokio	Rust · ~700 文件	52%	81%	63%	89%
OkHttp	Java · ~640 文件	17%	41%	36%	64%
Gin	Go · ~150 文件	22%	23%	34%	19%
Alamofire	Swift · ~100 文件	38%	59%	51%	77%

一个关键发现：项目越大，收益越明显。 VS Code 上工具调用从 23 次降到 7 次，Token 从 140 万降到 39 万。小项目（Gin ~150 文件）本身搜索就快，差距不大。

原理很直接：有 CodeGraph 时，Agent 用 codegraph_context 定位区域，一次 codegraph_explore 获取相关源码，然后直接回答——通常零文件读取。没有 CodeGraph 时，Agent（以及它启动的子 Agent）把大部分预算花在发现（find/ls/grep）上。

工作原理

                    ┌──────────────────────┐
                    │     Claude Code       │
                    │  "实现用户认证功能"     │
                    └──────────┬───────────┘
                               │
                ┌──────────────┼──────────────┐
                ▼                              ▼
         Explore Agent                  Explore Agent
                │                              │
                ▼                              ▼
    ┌──────────────────────────────────────────────┐
    │           CodeGraph MCP Server                │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐      │
    │  │  Search  │ │ Callers  │ │ Context  │      │
    │  │  "auth"  │ │"login()" │ │ for task │      │
    │  └────┬─────┘ └────┬─────┘ └────┬─────┘      │
    │       └─────────────┼────────────┘            │
    │                     ▼                         │
    │         ┌─────────────────────┐               │
    │         │  SQLite Graph DB    │               │
    │         │  · 387 symbols      │               │
    │         │  · 1,204 edges      │               │
    │         │  · Instant lookups  │               │
    │         └─────────────────────┘               │
    └──────────────────────────────────────────────┘

四个阶段：

1. 提取（Extraction）

tree-sitter 把源码解析成 AST，然后用语言特定的查询规则提取节点（函数、类、方法）和边（调用、导入、继承、实现）。

2. 存储（Storage）

所有数据存入本地 SQLite 数据库（.codegraph/codegraph.db），使用 FTS5 全文搜索。不发送任何数据到外部。

3. 解析（Resolution）

提取完成后，解析引用关系：函数调用 → 定义、导入 → 源文件、类继承、框架路由模式。

4. 自动同步（Auto-Sync）

MCP 服务器使用操作系统原生文件事件（macOS FSEvents、Linux inotify、Windows ReadDirectoryChangesW）监控项目变化，2 秒静默窗口防抖，只处理源文件，增量同步。你改代码，图谱自动更新。

安装使用

一行安装

不需要 Node.js，安装脚本自带运行时：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

如果有 Node.js：

npx @colbymchenry/codegraph

安装器会交互式引导你选择要配置的 Agent（自动检测已安装的 Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent），自动写入 MCP 配置和指令文件。

初始化项目

cd your-project
codegraph init -i

这一步构建项目知识图谱索引。完成后 .codegraph/ 目录出现在项目根目录。

重启 Agent

重启 Claude Code / Cursor / Codex 即可。Agent 检测到 .codegraph/ 目录会自动使用 CodeGraph 工具。

卸载

改主意了？一行命令从所有 Agent 中移除：

codegraph uninstall

CI 中的使用

codegraph affected 命令可以追踪依赖关系，找出哪些测试文件受变更影响：

git diff --name-only HEAD | codegraph affected --stdin --quiet | xargs npx vitest run

MCP 工具一览

CodeGraph 作为 MCP Server 暴露 8 个工具：

工具	用途
codegraph_search	按名称搜索符号
codegraph_context	为任务构建相关代码上下文
codegraph_callers	查找谁调用了某个函数
codegraph_callees	查找某个函数调用了谁
codegraph_impact	分析修改某个符号的影响范围
codegraph_node	获取单个符号的详细信息
codegraph_files	获取索引文件结构（比文件系统扫描快）
codegraph_status	检查索引健康状态和统计

主会话只使用轻量工具（search、callers、callees、impact），探索性任务交给 Explore 子 Agent 使用 codegraph_explore 和 codegraph_context。

框架感知路由

CodeGraph 不只理解代码结构，还理解 Web 框架的路由。它能识别路由文件，把 URL 模式链接到对应的处理函数。查询某个 Controller 的调用者时，会同时显示绑定了它的 URL 路径。

支持 14 个框架：Django、Flask、FastAPI、Express、NestJS、Laravel、Drupal、Rails、Spring、Gin/chi/gorilla、Axum/actix/Rocket、ASP.NET、Vapor、React Router/SvelteKit。

支持的语言

19 种语言全覆盖：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Lua/Luau、Pascal/Delphi。

零配置——自动根据文件扩展名识别语言，自动遵循 .gitignore 规则。

也可以作为库使用

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' 
});

cg.watch();   // 自动同步文件变化
cg.close();

技术细节

• TypeScript 编写，自包含 Node.js 运行时，无需编译
• tree-sitter 解析源码，语言特定查询提取符号和关系
• SQLite + WAL 模式 存储，并发读不阻塞写
• FTS5 全文搜索引擎
• 原生文件监控（FSEvents/inotify/ReadDirectoryChangesW）+ 2 秒防抖增量同步
• 零配置：遵循 .gitignore，跳过 >1MB 文件
• MIT 协议开源

适用场景

• 大型代码库：项目越大，探索税越重，CodeGraph 收益越明显
• 高频 AI 编程：每天用 Claude Code / Cursor 写代码，token 费用是实际开销
• 团队协作：新人用 AI Agent 理解陌生代码库，预索引大幅缩短理解时间
• CI/CD 集成：codegraph affected 精确运行受影响测试，跳过无关测试

---

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。