一句话引出项目价值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 服务通过 MCPModel 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 精确得多。为什么不用 LSPLSP 需要为每种语言启动一个独立的语言服务器进程资源开销大而且不是所有语言都有好的 LSP 实现。Tree-sitter 是纯 C 的解析器嵌入式运行支持 19 种语言启动速度快一个数量级。CodeGraph 从语法树中提取符号节点函数、类、接口、类型、变量引用边谁调用了谁、谁继承了谁、谁导入了谁路由节点Web 框架的 URL 模式到处理器的映射支持 14 个框架全文索引FTS5 全文搜索按名称即时查找这些数据全部存入 SQLite——一个嵌入式数据库零配置零外部依赖。MCP 协议代理的查询接口MCPModel Context Protocol是 Anthropic 定义的一个标准协议让 AI 代理能通过工具调用与外部服务交互。CodeGraph 暴露了两个核心 MCP 工具工具作用返回内容codegraph_context获取代码上下文入口点、相关符号、代码片段codegraph_explore深入探索特定区域源代码、调用者、被调用者codegraph_search全文搜索匹配的符号和文件代理的使用模式通常是先codegraph_context搞清楚这个问题涉及哪些模块再codegraph_explore深入看具体代码。两次调用就够了。框架感知路由这是 CodeGraph 一个很巧妙的设计。对于 Web 应用理解哪个 URL 对应哪个处理函数是常见需求。传统方式需要代理理解框架的路由约定CodeGraph 直接帮你建好了这个映射。支持 14 个框架框架识别的路由模式Djangopath(),re_path(),url(),include()Flaskapp.route(), blueprint routesFastAPIapp.get(...),router.post(...)Expressapp.get(...),router.post(...)NestJSControllerGet/Post, GraphQLLaravelRoute::get(),Route::resource()Railsget /x, to: users#indexSpringGetMapping,PostMappingGin / chir.GET(...),router.HandleFunc(...)Axum / actix.route(/x, get(handler))ASP.NET[HttpGet(/x)]Vaporapp.get(x, use: handler)React Router / SvelteKitRoute 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 Codeheadless 模式回答一个架构问题比较有无 CodeGraph 的差异。代码库语言文件数成本节省token 减少速度提升工具调用减少VS CodeTypeScript~10k35%73%41%72%ExcalidrawTypeScript~60047%73%60%86%DjangoPython~2.7k34%64%59%81%TokioRust~70052%81%63%89%OkHttpJava~64017%41%36%64%GinGo~15022%23%34%19%AlamofireSwift~10038%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/目录项目信息GitHubhttps://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 种
