一天一个开源项目（第107篇）：CodeGraph - 给 AI 编码代理预建代码知识图谱，省 35% 费用减少 70% 工具调用

引言

“~35% cheaper · ~70% fewer tool calls · 100% local”

这是"一天一个开源项目"系列的第107篇文章。今天带你了解的项目是 CodeGraph。

先来一个场景：你用 Claude Code 问"AuthService 是怎么被调用的？"。没有任何辅助工具时，Claude 的做法是：先 glob 扫描目录，再多次 grep 搜索，再 read 打开若干文件，最后才给出答案。整个过程可能触发十几次工具调用，消耗数十万 tokens。

CodeGraph 的思路是把这件事前置：在你开始工作之前，它已经用 tree-sitter 把代码库解析成了一个语义图谱，存入本地 SQLite，然后通过 MCP 协议把 8 个查询工具暴露给 AI 代理。当代理需要理解代码时，一次 codegraph_context 调用就能拿到入口点、相关符号和代码片段，不需要再去翻文件。

9.6k Stars，588 Forks。跨 7 个真实开源项目的基准测试结果：平均节省 35% 费用、减少 70% 工具调用、加快 49% 速度。在 VS Code 这样的大型 TypeScript 仓库上，一次架构问答从 1.4M tokens 压缩到 393k tokens，成本从 $0.64 降至 $0.42。

你将学到什么

• CodeGraph 的四阶段工作流：提取 → 存储 → 解析 → 自动同步
• 8 个 MCP 工具的具体用途和调用场景
• 跨 7 个真实项目的基准测试数据详解：为什么大型项目收益更大？
• 19 种语言支持 + 13 个框架路由识别的实现思路
• 从安装到集成 Claude Code 的完整操作流程
• codegraph affected：如何用依赖追踪做智能 CI 测试选择

前置知识

• 使用过 Claude Code、Cursor 或类似 AI 编码工具
• 了解 MCP（Model Context Protocol）的基本概念
• 有 Node.js 使用经验

项目背景

项目简介

CodeGraph 是一个本地语义代码知识图谱工具，专为提升 AI 编码代理的效率而设计。它的核心洞察是：

AI 代理在处理代码任务时，大量 tokens 和时间消耗在"发现阶段"——扫描目录、搜索符号、读取文件——而不是真正的推理和生成。

CodeGraph 的解决方案是把发现阶段外包给一个预建索引，让 AI 代理在正式工作时能直接获得结构化的代码知识，而不是从零开始探索文件系统。

技术栈选择非常务实：tree-sitter 做 AST 解析（成熟、多语言、高性能），SQLite FTS5 做全文检索（零外部依赖、完全本地），原生 OS 文件事件做实时同步（FSEvents/inotify/ReadDirectoryChangesW）。

作者/团队介绍

• 主要作者：Colby McHenry（GitHub: colbymchenry）
• 仓库地址：colbymchenry/codegraph
• 发布渠道：npm 包 @colbymchenry/codegraph

项目数据

• ⭐ GitHub Stars: 9,600+
• 🍴 Forks: 588
• 📦 npm 包名: @colbymchenry/codegraph
• 🔧 运行环境: Node.js 20–24
• 💻 平台支持: Windows、macOS、Linux
• 📄 License: MIT
• 🌐 仓库: colbymchenry/codegraph

主要功能

核心作用

CodeGraph 在 AI 代理和代码库之间插入了一个预建索引层：

代码库（TypeScript / Python / Go / …）
↓ tree-sitter 解析
语义图谱（符号 + 关系 + 调用链）
↓ 存入 SQLite FTS5
本地知识库
↓ MCP 协议暴露
AI 编码代理（Claude Code / Cursor / Codex CLI / OpenCode）

没有 CodeGraph 的 AI 工作流：

用户问："AuthService 是怎么被调用的？"
→ AI: glob("src/**/*.ts") # 工具调用 1
→ AI: grep("AuthService") # 工具调用 2
→ AI: read("auth.service.ts") # 工具调用 3
→ AI: grep("import.*Auth") # 工具调用 4
→ AI: read("user.controller.ts") # 工具调用 5
→ AI: read("app.module.ts") # 工具调用 6
… 共 10–15 次工具调用，消耗大量 tokens

有 CodeGraph 的 AI 工作流：

用户问："AuthService 是怎么被调用的？"
→ AI: codegraph_callers("AuthService") # 工具调用 1
→ 返回：所有调用者列表 + 调用位置 + 代码片段
→ AI 直接回答，无需再读文件

快速开始

一键安装（推荐）：

# 运行交互式安装器，自动检测已安装的 AI 代理并配置
npx @colbymchenry/codegraph

# 在项目中初始化（-i 表示交互式）
cd your-project
codegraph init -i

非交互式安装（CI 环境）：

# 自动检测所有已安装代理，全局安装
codegraph install –yes

# 指定目标代理
codegraph install –target=cursor,claude –yes

# 项目级别安装
codegraph install –target=auto –location=local

手动配置 Claude Code：

npm install -g @colbymchenry/codegraph

然后将以下内容加入 ~/.claude.json（或项目级 .claude.json）：

{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "–mcp"]
}
}
}

验证安装：

codegraph status # 查看索引状态和统计
codegraph query "UserService" # 测试符号搜索

8 个 MCP 工具详解

这是 CodeGraph 暴露给 AI 代理的完整工具集：

codegraph_context 是其中最重要的工具——它不只返回搜索结果，而是为给定任务智能构建一个包含入口点、相关符号、代码片段的综合上下文包：

# 命令行等价操作
codegraph context "修复用户登录 bug"
# → 自动找到 login 相关函数、调用链、相关文件，打包成 AI 可直接消费的上下文

项目优势

项目详细剖析

一、四阶段工作流

阶段 1：提取（Extraction）

tree-sitter 把源文件解析为 AST，从中提取：

• 符号：函数、类、方法、接口、变量定义
• 关系：函数调用、模块导入、类继承、接口实现

tree-sitter 的优势在于它是容错 AST 解析器——即使代码有语法错误也能解析出部分结构，这对处理正在编写中的代码非常重要。

阶段 2：存储（Storage）

所有数据落入本地 SQLite，使用 FTS5（Full-Text Search 5）扩展提供全文检索能力：

— 符号表（简化示意）
CREATE VIRTUAL TABLE symbols USING fts5(
name, — 符号名称
kind, — function/class/method/…
file_path, — 所在文件
line_start, — 起始行
signature, — 函数签名
docstring, — 文档注释
code_snippet — 代码片段
);

— 关系表
CREATE TABLE edges (
from_id INTEGER, — 调用方符号 ID
to_id INTEGER, — 被调用符号 ID
kind TEXT, — calls/imports/inherits/implements
file TEXT,
line INTEGER
);

阶段 3：解析（Resolution）

这是最关键的一步：把抽象的"调用了某个名字"解析为具体的"调用了哪个文件里的哪个定义"。

源代码: import { AuthService } from './auth.service'
…
this.authService.login(user)
↓ 解析
图谱边: UserController.login → AuthService.login (calls)
UserController → AuthService (imports)

阶段 4：自动同步（Auto-Sync）

使用原生 OS 文件事件（不是轮询！）监听变化：

• macOS: FSEvents
• Linux: inotify
• Windows: ReadDirectoryChangesW

有 2 秒防抖：避免文件快速连续变化时触发大量重建，等变化稳定后再做增量更新。

二、基准测试数据解读

官方测试条件：Claude Code（headless，Opus 4.7）回答架构问题，每组测试对同一问题跑 4 次取中位数，跨 7 个真实开源仓库。

项目 语言 规模 节省费用 减少 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%
──────────────────────────────────────────────────────────────────────
平均 35% 59% 49% 70%

几个值得关注的规律：

结论：仓库越大、依赖关系越复杂、语言类型系统越丰富，CodeGraph 的收益越大。对于日常使用 Claude Code 处理大型项目的用户，这个工具的 ROI 非常明显。

三、19 种语言 + 13 个框架路由识别

语言支持（通过 tree-sitter grammar）：

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Scala

框架路由识别是 CodeGraph 的一个差异化功能——它不只识别符号，还能理解 URL 路由和它背后的处理函数之间的映射：

# Django
urlpatterns = [
path('users/<int:pk>/', UserDetailView.as_view()),
]
# → codegraph 知道 GET /users/{id}/ 对应 UserDetailView

# FastAPI
@app.get("/items/{item_id}")
async def read_item(item_id: int):
...
# → codegraph 知道 GET /items/{id} 对应 read_item()

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

这意味着 AI 代理可以直接问"/api/users/:id 的处理逻辑在哪里？"，CodeGraph 能给出精准答案，而不需要代理去扫描路由配置文件。

四、codegraph affected——智能 CI 测试选择

这是 CodeGraph 里一个被低估的功能：通过追踪导入依赖关系，找出受变更影响的测试文件。

# CI 场景：只运行受本次变更影响的测试
git diff –name-only | codegraph affected –stdin

# 手动指定变更文件
codegraph affected src/auth.ts

# 配合过滤器（只查 e2e 测试）
codegraph affected src/auth.ts –filter "e2e/*"

工作原理：

变更了 src/auth.ts
↓ CodeGraph 查依赖图
找到直接导入 auth.ts 的: user.service.ts, auth.controller.ts
找到间接导入 auth.ts 的: app.module.ts, integration.test.ts
↓ 过滤只保留测试文件
受影响的测试: auth.spec.ts, user.service.spec.ts, integration.test.ts
↓ 输出
[这些文件] ← 只跑这些测试，而不是全量测试套件

对大型项目来说，这能把 CI 测试时间从几十分钟压缩到几分钟。

五、配置和性能注意事项

项目配置文件（.codegraph/config.json）：

{
"version": 1,
"languages": ["typescript", "javascript"],
"exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
"maxFileSize": 1048576,
"extractDocstrings": true,
"trackCallSites": true
}

SQLite 后端选择：

CodeGraph 内置两个 SQLite 后端：

• native better-sqlite3（默认，推荐）：高性能，支持并发读写
• WASM fallback：兼容性更好，但比 native 慢 5–10 倍，并发操作可能报 database is locked

如果遇到性能问题或锁定错误：

# 重建 native 模块
npm rebuild better-sqlite3

# 查看当前使用的后端
codegraph status

CLI 完整参考

codegraph # 运行交互式安装器
codegraph init [path] # 在项目中初始化
codegraph uninit [path] # 从项目移除 CodeGraph
codegraph index [path] # 全量索引（–force 强制重建）
codegraph sync [path] # 增量更新
codegraph status [path] # 显示统计信息
codegraph query <search> # 搜索符号
codegraph files [path] # 显示文件结构
codegraph context <task> # 为 AI 任务构建上下文
codegraph affected [files] # 找受影响的测试文件
codegraph serve –mcp # 启动 MCP 服务器

Library API 用法（在自己的工具中嵌入 CodeGraph）：

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

// 构建 AI 上下文
const context = await cg.buildContext('fix login bug', {
maxNodes: 20,
includeCode: true
});

// 影响半径分析（深度 2）
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch(); // 启动文件监听自动同步
cg.close(); // 清理资源

项目地址与资源

官方资源

• 🌟 GitHub: https://github.com/colbymchenry/codegraph
• 📦 npm: @colbymchenry/codegraph
• ⚡ 快速安装: npx @colbymchenry/codegraph

适用人群

• Claude Code / Cursor 重度用户：在大型项目上使用 AI 编码，希望降低成本、加快响应速度
• 大型 TypeScript/Rust/Python 项目开发者：代码库规模大，AI 代理的文件扫描开销显著
• CI/CD 工程师：用 codegraph affected 做智能测试选择，减少不必要的全量测试
• 工具链开发者：通过 Library API 在自己的工具中嵌入代码语义分析能力

总结与展望

核心要点回顾

一句话评价

CodeGraph 做了一件看似简单但极其务实的事：把 AI 代理每次都要重做的代码发现工作，变成一个可以持续复用的本地索引——这不是功能的叠加，而是工作流架构的优化。

欢迎来我的个人主页找到更多有用的知识和有趣的产品