代码探索省 35% 成本、工具调用砍七成——CodeGraph 给 AI 编程代理装了张知识图谱
一句话引出项目价值：
AI 编程代理 70% 的 token 花在"找代码"而不是"写代码"。CodeGraph 把找代码这一步从实时扫描变成预索引查询，直接省掉三成成本。
读完本文你将了解：CodeGraph 的技术原理 | 架构设计 | 7 个真实代码库的基准测试数据 | 快速上手步骤
你有没有遇到过这种情况？
让 Claude Code 帮你改一个十万行项目的 bug。它先 spawn 一个 Explore 子代理，花 30 秒 grep 文件、glob 目录、读代码，烧掉 200k token，终于搞清楚了模块关系——然后才开始真正帮你改。
这不是 Claude Code 的问题，是所有 AI 编程代理的结构性浪费。代理在"发现阶段"消耗的 token 和时间，往往超过"推理和生成"阶段。代码越大，这个比例越离谱。
CodeGraph 的解法很直接：别让代理现场翻文件了，给它一张已经画好的代码地图。
CodeGraph 是什么？
CodeGraph 是一个本地优先的代码语义知识图谱工具，专门为 AI 编程代理（Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent）设计。它的工作方式是：
- 预索引：用 Tree-sitter 解析源码，提取符号、调用关系、类型信息，存入 SQLite 数据库
- MCP 服务：通过 MCP（Model Context Protocol）协议向代理暴露查询接口
- 即时查询：代理一个工具调用就能拿到入口点、相关符号和代码片段，不用再 spawn 探索子代理
核心指标：35% 成本节省 · 59% token 减少 · 49% 速度提升 · 70% 工具调用减少（7 个真实代码库中位数）。
支持 19+ 种编程语言，覆盖 14 个主流 Web 框架的路由识别，100% 本地运行——没有数据外泄，没有 API Key，没有外部服务依赖。
快速上手
安装
不需要 Node.js 环境也行，一条命令搞定：
# macOS / Linuxcurl-fsSLhttps://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安装器会自动检测你机器上装了哪些 AI 编程代理（Claude Code、Cursor、Codex CLI 等），然后帮你配置 MCP 服务器和权限。
初始化项目
cdyour-project codegraph init-i-i是交互模式，会问你要配置哪些代理。初始化完成后，CodeGraph 会：
- 用 Tree-sitter 解析你的代码库
- 提取所有符号（函数、类、变量、接口）
- 构建调用图和依赖关系
- 全文索引存入
.codegraph/目录下的 SQLite 数据库 - 配置文件监听，代码变更自动同步
使用
重启你的 AI 编程代理，然后正常问问题。代理会自动通过 MCP 接口查询 CodeGraph，而不是用 grep/find 扫描文件。
比如你问：“Excalidraw 怎么渲染和更新 canvas 元素？”
没有 CodeGraph：代理 spawn Explore 子代理 → grep/glob/Read 扫描 83 次工具调用 → 烧 3.2M token → 花 3 分 14 秒 → 花 $1.02
有 CodeGraph：代理调用codegraph_context查入口点 → 调用codegraph_explore读相关源码 → 12 次工具调用 → 烧 851k token → 花 1 分 17 秒 → 花 $0.54
省了 47% 成本，86% 工具调用，60% 时间。
技术原理
为什么预索引比实时扫描快这么多？
当 AI 代理探索代码库时，它做的是典型的"信息检索"任务：给定一个概念（比如"路由系统"），找到相关的文件、函数和调用链。
传统方式是实时搜索：grep 关键词 → 读文件 → 发现新线索 → 再 grep → 再读文件……这是一个深度优先的探索过程，每一步都要消耗 token 和工具调用。
CodeGraph 的方式是预计算：提前把所有符号关系建好索引，查询时直接返回结果。这把"探索"从 O(n) 的文件扫描变成了 O(1) 的数据库查询。
关键洞察：代码库的结构在两次提交之间是不变的。既然结构不变，为什么要每次问都重新扫描？预索引一次，查询无数次。
Tree-sitter：语义解析的核心
CodeGraph 用 Tree-sitter 做语法解析。Tree-sitter 是一个增量解析器，能生成具体的语法树（CST），比正则表达式和 grep 精确得多。
为什么不用 LSP？LSP 需要为每种语言启动一个独立的语言服务器进程，资源开销大，而且不是所有语言都有好的 LSP 实现。Tree-sitter 是纯 C 的解析器，嵌入式运行，支持 19+ 种语言，启动速度快一个数量级。
CodeGraph 从语法树中提取：
- 符号节点：函数、类、接口、类型、变量
- 引用边：谁调用了谁、谁继承了谁、谁导入了谁
- 路由节点：Web 框架的 URL 模式到处理器的映射（支持 14 个框架）
- 全文索引：FTS5 全文搜索，按名称即时查找
这些数据全部存入 SQLite——一个嵌入式数据库，零配置，零外部依赖。
MCP 协议：代理的"查询接口"
MCP（Model Context Protocol）是 Anthropic 定义的一个标准协议，让 AI 代理能通过工具调用与外部服务交互。
CodeGraph 暴露了两个核心 MCP 工具：
| 工具 | 作用 | 返回内容 |
|---|---|---|
codegraph_context | 获取代码上下文 | 入口点、相关符号、代码片段 |
codegraph_explore | 深入探索特定区域 | 源代码、调用者、被调用者 |
codegraph_search | 全文搜索 | 匹配的符号和文件 |
代理的使用模式通常是：先codegraph_context搞清楚"这个问题涉及哪些模块"，再codegraph_explore深入看具体代码。两次调用就够了。
框架感知路由
这是 CodeGraph 一个很巧妙的设计。对于 Web 应用，理解"哪个 URL 对应哪个处理函数"是常见需求。传统方式需要代理理解框架的路由约定，CodeGraph 直接帮你建好了这个映射。
支持 14 个框架：
| 框架 | 识别的路由模式 |
|---|---|
| Django | path(),re_path(),url(),include() |
| Flask | @app.route(), blueprint routes |
| FastAPI | @app.get(...),@router.post(...) |
| Express | app.get(...),router.post(...) |
| NestJS | @Controller+@Get/@Post, GraphQL |
| Laravel | Route::get(),Route::resource() |
| Rails | get '/x', to: 'users#index' |
| Spring | @GetMapping,@PostMapping |
| Gin / chi | r.GET(...),router.HandleFunc(...) |
| Axum / actix | .route("/x", get(handler)) |
| ASP.NET | [HttpGet("/x")] |
| Vapor | app.get("x", use: handler) |
| React Router / SvelteKit | Route component nodes |
这意味着代理问"这个 API 端点对应哪个函数"时，CodeGraph 能直接给出答案，不用代理自己去翻路由配置文件。
架构分析
整体模块
┌─────────────────────────────────────────────┐ │ CodeGraph │ │ │ │ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ │ │ Parser │ │ Indexer │ │ MCP Server │ │ │ │(Tree-sitter)│ │ (SQLite) │ │ (stdio) │ │ │ └────┬─────┘ └────┬─────┘ └──────┬──────┘ │ │ │ │ │ │ │ └──────┬───────┘ │ │ │ │ │ │ │ ┌──────┴──────┐ │ │ │ │ File Watcher│ │ │ │ │ (OS native) │ │ │ │ └──────────────┘ │ │ │ │ │ └───────────────────────────────────────┘ │ │ │ ┌─────────┴──────────┐ │ │ AI 编程代理 │ │ │ (Claude Code/Cursor)│ │ └─────────────────────┘Parser 层：Tree-sitter 解析器，支持 19+ 种语言。每种语言有独立的 grammar，解析后生成 CST（具体语法树），然后提取符号和引用关系。
Indexer 层：SQLite + FTS5。存储三类数据：
- 符号表（名称、类型、位置、所属模块）
- 边表（调用、继承、导入、引用关系）
- 全文索引（用于按名称搜索）
MCP Server 层：通过 stdio 协议暴露查询接口。代理通过 MCP 工具调用与 CodeGraph 交互。
File Watcher 层：使用操作系统原生事件（macOS 的 FSEvents、Linux 的 inotify、Windows 的 ReadDirectoryChangesW），带防抖的增量同步。代码变了，索引自动更新，不需要手动重新索引。
设计亮点
本地优先，零外部依赖：整个系统只用 SQLite，不需要启动额外的数据库服务。这对开发者来说意味着零运维成本——装上就能用。
自包含运行时：CodeGraph 把 Node.js 运行时打包在内，安装脚本会自动下载对应平台的构建产物。你不需要装 Node.js，不需要编译原生模块。
增量同步：File Watcher 不是每次变更都重建索引，而是只更新变更的文件。这保证了大型代码库的索引更新也是秒级的。
代理无关性：通过 MCP 标准协议，CodeGraph 不绑定任何特定的 AI 代理。Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent 都能用同一套索引。
不够好的地方
首次索引时间：对于超大型代码库（10 万+ 文件），首次索引可能需要几分钟。虽然有进度条，但对"想马上用"的场景不太友好。
语言覆盖的深度不均：TypeScript/Python 这些主流语言的支持很完善，但像 Lua、Pascal 这些小众语言的符号提取可能不如主流语言精确。
MCP 工具调用的提示工程：CodeGraph 需要在代理的配置文件（如CLAUDE.md）中注入使用指南，告诉代理"先用codegraph_context再用codegraph_explore"。如果代理不按这个模式来，效果会打折扣。
基准测试详解
CodeGraph 在 7 个真实开源代码库上做了严格的 A/B 测试，每个代码库跑 4 次取中位数。测试方法：让 Claude Code（headless 模式）回答一个架构问题，比较有无 CodeGraph 的差异。
| 代码库 | 语言 | 文件数 | 成本节省 | 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% |
规律很明显：代码库越大，CodeGraph 的收益越明显。VS Code 这种 10 万文件级别的项目，工具调用从 23 次降到 7 次。Gin 这种 150 文件的小项目，收益就小很多——因为原生搜索已经够快了。
这也解释了为什么 CodeGraph 的核心价值主张是"省 token"：在大项目上，代理 70% 的预算花在探索阶段，CodeGraph 把这个比例压到了 20% 以下。
优缺点总结
优点
效果立竿见影：装上就能用，不需要改代码、不需要配置额外服务。对大中型项目的 AI 辅助开发效率提升是实打实的。
真正的本地优先：SQLite 存储、文件监听、零网络请求。代码不出本机，对安全敏感的团队很友好。
代理无关：不绑定 Claude Code 或 Cursor，换了代理不用重新配置。MCP 标准协议保证了跨工具兼容性。
缺点
小项目收益有限：150 文件以下的项目，原生搜索已经够快，CodeGraph 的预索引反而增加了维护成本。
首次索引的冷启动：超大项目的首次索引需要等待，虽然增量更新很快，但第一次的体验不够即时。
谁应该立刻试试？
- 每天用 Claude Code / Cursor 在 1000+ 文件项目上工作的开发者
- 团队有安全要求、不能把代码发到云端的场景
- 经常让 AI 代理做跨模块重构、架构分析的重度用户
谁应该再等等？
- 项目本身很小（< 200 文件），原生搜索够用
- 主要使用不支持 MCP 的 AI 工具
- 不想在项目里多一个
.codegraph/目录
项目信息
- GitHub：https://github.com/colbymchenry/codegraph
- 语言：TypeScript
- 许可证：MIT
- 星标：19,537（今日 +2,456）
- 支持代理：Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent
- 支持语言：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua 等 19 种