引言“~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 Stars588 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 编码工具了解 MCPModel Context Protocol的基本概念有 Node.js 使用经验项目背景项目简介CodeGraph 是一个本地语义代码知识图谱工具专为提升 AI 编码代理的效率而设计。它的核心洞察是AI 代理在处理代码任务时大量 tokens 和时间消耗在发现阶段——扫描目录、搜索符号、读取文件——而不是真正的推理和生成。CodeGraph 的解决方案是把发现阶段外包给一个预建索引让 AI 代理在正式工作时能直接获得结构化的代码知识而不是从零开始探索文件系统。技术栈选择非常务实tree-sitter 做 AST 解析成熟、多语言、高性能SQLite FTS5 做全文检索零外部依赖、完全本地原生 OS 文件事件做实时同步FSEvents/inotify/ReadDirectoryChangesW。作者/团队介绍主要作者Colby McHenryGitHub: 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 表示交互式cdyour-project codegraph init-i非交互式安装CI 环境# 自动检测所有已安装代理全局安装codegraphinstall--yes# 指定目标代理codegraphinstall--targetcursor,claude--yes# 项目级别安装codegraphinstall--targetauto--locationlocal手动配置 Claude Codenpminstall-gcolbymchenry/codegraph然后将以下内容加入~/.claude.json或项目级.claude.json{mcpServers:{codegraph:{type:stdio,command:codegraph,args:[serve,--mcp]}}}验证安装codegraph status# 查看索引状态和统计codegraph queryUserService# 测试符号搜索8 个 MCP 工具详解这是 CodeGraph 暴露给 AI 代理的完整工具集工具用途典型调用场景codegraph_search按名称搜索符号“找所有叫 authenticate 的函数”codegraph_context为任务构建代码上下文“理解登录流程需要哪些代码”codegraph_callers找调用某函数的所有地方“谁调用了 AuthService?”codegraph_callees找某函数调用了哪些函数“processPayment 内部调了什么?”codegraph_impact分析修改的影响半径“改这个函数会影响哪些模块?”codegraph_node获取特定符号的详细信息“给我 UserController 的完整签名”codegraph_files获取已索引的文件结构“项目整体结构是什么?”codegraph_status检查索引健康状态和统计“索引了多少符号?最后同步时间?”codegraph_context是其中最重要的工具——它不只返回搜索结果而是为给定任务智能构建一个包含入口点、相关符号、代码片段的综合上下文包# 命令行等价操作codegraph context修复用户登录 bug# → 自动找到 login 相关函数、调用链、相关文件打包成 AI 可直接消费的上下文项目优势对比维度CodeGraph原生 AI 代理无辅助其他代码索引工具工具调用次数~70% 更少高每次任务重新扫描部分减少Token 消耗~59% 更少高部分减少数据隐私100% 本地取决于代理多数需要上传实时同步原生 OS 文件事件不适用通常轮询或手动语言支持19 种取决于代理能力通常 3–5 种框架路由识别13 个框架无罕见安装复杂度一条 npx 命令不适用通常需要服务端项目详细剖析一、四阶段工作流阶段 1提取Extractiontree-sitter 把源文件解析为 AST从中提取符号函数、类、方法、接口、变量定义关系函数调用、模块导入、类继承、接口实现tree-sitter 的优势在于它是容错 AST 解析器——即使代码有语法错误也能解析出部分结构这对处理正在编写中的代码非常重要。阶段 2存储Storage所有数据落入本地 SQLite使用 FTS5Full-Text Search 5扩展提供全文检索能力-- 符号表简化示意CREATEVIRTUALTABLEsymbolsUSINGfts5(name,-- 符号名称kind,-- function/class/method/...file_path,-- 所在文件line_start,-- 起始行signature,-- 函数签名docstring,-- 文档注释code_snippet-- 代码片段);-- 关系表CREATETABLEedges(from_idINTEGER,-- 调用方符号 IDto_idINTEGER,-- 被调用符号 IDkindTEXT,-- calls/imports/inherits/implementsfileTEXT,lineINTEGER);阶段 3解析Resolution这是最关键的一步把抽象的调用了某个名字解析为具体的调用了哪个文件里的哪个定义。源代码: import { AuthService } from ./auth.service ... this.authService.login(user) ↓ 解析 图谱边: UserController.login → AuthService.login (calls) UserController → AuthService (imports)阶段 4自动同步Auto-Sync使用原生 OS 文件事件不是轮询监听变化macOS:FSEventsLinux:inotifyWindows:ReadDirectoryChangesW有2 秒防抖避免文件快速连续变化时触发大量重建等变化稳定后再做增量更新。二、基准测试数据解读官方测试条件Claude CodeheadlessOpus 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%几个值得关注的规律TokioRust700 文件收益最大81% token 减少89% 工具调用减少Rust 的类型系统复杂AI 代理原本需要大量文件探索才能理解 trait 实现和泛型关系CodeGraph 把这些关系预建好后效果显著。GinGo150 文件收益最小23% token 减少19% 工具调用减少小型 Go 项目文件结构简单AI 代理原本就可以高效浏览CodeGraph 的边际价值较低。VS Code 的绝对数字最震撼同一个问题无 CodeGraph 时消耗 1.4M tokens$0.64有 CodeGraph 时只消耗 393k tokens$0.42。单次任务节省 $0.22。结论仓库越大、依赖关系越复杂、语言类型系统越丰富CodeGraph 的收益越大。对于日常使用 Claude Code 处理大型项目的用户这个工具的 ROI 非常明显。三、19 种语言 13 个框架路由识别语言支持通过 tree-sitter grammarTypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C、Swift、Kotlin、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Scala框架路由识别是 CodeGraph 的一个差异化功能——它不只识别符号还能理解 URL 路由和它背后的处理函数之间的映射# Djangourlpatterns[path(users/int:pk/,UserDetailView.as_view()),]# → codegraph 知道 GET /users/{id}/ 对应 UserDetailView# FastAPIapp.get(/items/{item_id})asyncdefread_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 场景只运行受本次变更影响的测试gitdiff--name-only|codegraph affected--stdin# 手动指定变更文件codegraph affected src/auth.ts# 配合过滤器只查 e2e 测试codegraph affected src/auth.ts--filtere2e/*工作原理变更了 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 后端nativebetter-sqlite3默认推荐高性能支持并发读写WASM fallback兼容性更好但比 native 慢 5–10 倍并发操作可能报database is locked如果遇到性能问题或锁定错误# 重建 native 模块npmrebuild better-sqlite3# 查看当前使用的后端codegraph statusCLI 完整参考codegraph# 运行交互式安装器codegraph init[path]# 在项目中初始化codegraph uninit[path]# 从项目移除 CodeGraphcodegraph index[path]# 全量索引--force 强制重建codegraphsync[path]# 增量更新codegraph status[path]# 显示统计信息codegraph querysearch# 搜索符号codegraph files[path]# 显示文件结构codegraph contexttask# 为 AI 任务构建上下文codegraph affected[files]# 找受影响的测试文件codegraph serve--mcp# 启动 MCP 服务器Library API 用法在自己的工具中嵌入 CodeGraphimportCodeGraphfromcolbymchenry/codegraph;constcgawaitCodeGraph.init(/path/to/project);// 全量索引支持进度回调awaitcg.indexAll({onProgress:(p)console.log(${p.phase}:${p.current}/${p.total})});// 搜索符号constresultscg.searchNodes(UserService);// 查调用链constcallerscg.getCallers(results[0].node.id);// 构建 AI 上下文constcontextawaitcg.buildContext(fix login bug,{maxNodes:20,includeCode:true});// 影响半径分析深度 2constimpactcg.getImpactRadius(results[0].node.id,2);cg.watch();// 启动文件监听自动同步cg.close();// 清理资源项目地址与资源官方资源GitHub: https://github.com/colbymchenry/codegraphnpm: colbymchenry/codegraph⚡快速安装:npx colbymchenry/codegraph适用人群Claude Code / Cursor 重度用户在大型项目上使用 AI 编码希望降低成本、加快响应速度大型 TypeScript/Rust/Python 项目开发者代码库规模大AI 代理的文件扫描开销显著CI/CD 工程师用codegraph affected做智能测试选择减少不必要的全量测试工具链开发者通过 Library API 在自己的工具中嵌入代码语义分析能力总结与展望核心要点回顾核心价值在 AI 代理和代码库之间插入预建语义索引平均节省 35% 费用、减少 70% 工具调用、加快 49% 速度技术选型tree-sitterAST 解析 SQLite FTS5全文检索 原生 OS 文件事件实时同步零外部服务依赖8 个 MCP 工具codegraph_context最核心一次调用返回任务所需的完整代码上下文19 种语言 13 个框架路由识别覆盖主流开发栈codegraph affected依赖追踪驱动的智能测试选择CI 加速利器规模越大收益越大TokioRust700 文件达到 89% 工具调用减少小型 Go 项目约 19%一句话评价CodeGraph 做了一件看似简单但极其务实的事把 AI 代理每次都要重做的代码发现工作变成一个可以持续复用的本地索引——这不是功能的叠加而是工作流架构的优化。欢迎来我的个人主页找到更多有用的知识和有趣的产品