CodeGraph：基于MCP的代码结构图，让AI编程助手Token平均省57%

1. 为什么需要一张“代码地图”做 AI 辅助编程的人大概都有过这种体验项目稍微大一点你问 AI 一个跨文件的问题它要么答得似是而非要么干脆开始编。你以为是模型不够聪明其实很多时候是它根本没“看见”完整的代码结构。它看到的只是你手动贴进去的几个文件片段或者检索出来的零散代码块文件之间的调用关系、模块依赖、类型定义全都不在上下文里。CodeGraph 想解决的就是这个问题。它做的事情说起来很朴素把整个代码仓库解析成一张图节点是文件、类、函数、变量边是调用、继承、引用、导入这些关系然后把这张图存进一个本地数据库。AI 助手通过 MCP 协议查询这张图就能拿到精确的代码结构和依赖关系而不是靠猜。标题里说“Token 平均省 57%”这个数字怎么来的逻辑很直接。以前 AI 要理解一个函数的作用你得把整个文件甚至好几个相关文件都塞进上下文几千上万 Token 就没了。现在它先查图定位到具体函数和它的直接依赖只取必要的那部分代码Token 消耗自然大幅下降。省 Token 只是表象真正有价值的是准确率的提升——AI 不再需要从大段无关代码里“大海捞针”。这套东西适合谁如果你日常用 Cursor、Claude Code、Cline 这类支持 MCP 的工具写代码项目规模超过几十个文件经常需要 AI 帮你做重构、排查跨文件 bug、理解陌生模块那 CodeGraph 值得花时间配一下。如果你只是写写脚本、单文件小工具那确实用不上杀鸡不用牛刀。2. CodeGraph 的整体设计与核心思路2.1 从“文本检索”到“结构检索”的转变传统 AI 编程助手获取上下文的方式基本是两类一是你手动指定文件二是基于向量相似度做语义检索。前者依赖你的判断后者依赖 embedding 的质量。两者有个共同的短板——它们都是“文本层面”的操作不理解代码的语法结构。举个例子你问“UserService 的 createUser 方法调用了哪些数据库操作”。向量检索可能会返回一堆包含“createUser”字样的代码块但真正被调用的 repository 方法可能在另一个文件里名字完全不沾边。AI 拿到这些片段只能靠语言模型的能力去推断推断错了你也不知道。CodeGraph 换了个思路。它先用 tree-sitter 这类解析器把代码拆成 AST提取出所有符号定义和引用关系构建成图结构。查询的时候不是找“相似的文本”而是沿着图的边走——从 createUser 这个节点出发找到它所有的调用边再找到被调用节点的定义。这是确定性的、精确的。提示tree-sitter 是一个增量解析库支持多种编程语言能在文件修改后快速重新解析不需要从头构建整棵树。这是 CodeGraph 能保持索引实时性的关键。2.2 为什么选 SQLite 做存储层图数据库听起来很高级Neo4j 之类的方案也不是不能用但 CodeGraph 选了 SQLite。这个选择很务实。第一SQLite 是嵌入式的不需要额外起服务。你装个 Python 包或者 npm 包就能用对个人开发者和小团队极其友好。第二代码图的规模其实没那么夸张。一个中型项目几万个节点、十几万条边SQLite 用合适的索引完全扛得住。第三SQLite 的全文检索能力FTS5可以同时支持关键词搜索图查询和文本搜索能在一个数据库里完成不用维护两套系统。表结构的设计大概是这样的思路一张 nodes 表存所有符号文件、类、函数、变量字段包括 id、type、name、file_path、start_line、end_line一张 edges 表存关系字段包括 source_id、target_id、edge_type。edge_type 枚举了 calls、imports、inherits、references 等类型。查询“谁调用了这个函数”就是一条简单的 SQLSELECT n.name, n.file_path, n.start_line FROM edges e JOIN nodes n ON e.source_id n.id WHERE e.target_id ? AND e.edge_type calls;这种设计的好处是可预测、可调试。你不需要学 Cypher 查询语言会 SQL 就能自己排查问题。2.3 MCP 协议扮演的角色MCPModel Context Protocol是 Anthropic 推的一个开放协议目的是让 AI 助手能标准化地调用外部工具和数据源。CodeGraph 作为一个 MCP Server 运行暴露几个核心工具方法给 AI 客户端调用。这样做的好处是解耦。CodeGraph 不关心你用的是 Cursor 还是 Claude Code 还是别的什么客户端只要客户端支持 MCP就能连上来用。反过来你换项目、换语言只要 CodeGraph 支持解析AI 助手的使用方式完全不变。目前 CodeGraph 通过 MCP 暴露的能力大概包括查询符号定义、查找引用、获取调用链、搜索符号名、获取文件结构概览。每个方法接收结构化参数返回结构化结果AI 拿到之后直接用于推理不需要再做额外的文本解析。3. 核心细节解析与实操要点3.1 索引构建第一次跑会慢后面就快了CodeGraph 的索引过程分两个阶段。第一阶段是解析遍历项目目录下所有源文件用 tree-sitter 生成 AST提取符号和关系。第二阶段是写入把提取到的数据批量插入 SQLite。第一次索引一个中型项目大概 500 个文件可能需要几十秒到一两分钟取决于文件大小和语言复杂度。但后续的增量索引很快——CodeGraph 会记录每个文件的修改时间和哈希值只重新解析变动的文件然后更新对应的节点和边。这里有个实操细节.gitignore里的文件默认会被跳过但有些生成代码目录比如dist/、build/如果没写进.gitignore可能会被误索引。建议在项目根目录放一个.codegraphignore文件语法和.gitignore一样把不需要索引的路径排除掉。# .codegraphignore 示例 node_modules/ dist/ build/ *.min.js *.generated.ts注意索引过程中如果项目正在被编辑可能会出现解析到半成品文件的情况。建议在索引前先提交或暂存当前修改保证索引的是稳定状态。3.2 查询精度边类型的设计决定了上限CodeGraph 能不能回答好问题很大程度上取决于它提取了哪些边类型。目前支持的主要有边类型含义典型用途calls函数/方法调用查调用链、影响范围分析imports模块导入查模块依赖、循环依赖检测inherits类继承查继承体系、方法重写references符号引用查变量使用、类型引用contains文件包含符号查文件结构、符号归属不同语言提取的精度不一样。TypeScript、Python、Java 这类静态类型语言提取得比较完整动态语言比如 JavaScript 在某些场景下比如动态属性访问可能会有遗漏。这不是 CodeGraph 独有的问题所有静态分析工具都面临这个限制。实操建议如果你发现某个调用关系没被识别出来先确认代码里是不是用了反射、动态导入这类模式。如果是那只能靠手动补充或者接受这个盲区。3.3 与 AI 客户端的集成方式CodeGraph 作为 MCP Server集成方式取决于你用的客户端。以 Cursor 为例在设置里找到 MCP 配置添加一个 server 条目{ mcpServers: { codegraph: { command: codegraph, args: [serve, --project, /path/to/your/project] } } }Claude Code 的配置类似在~/.claude/claude_desktop_config.json里加同样的结构。配置完之后重启客户端AI 就能在对话中自动调用 CodeGraph 的工具了。这里有个容易踩的坑路径一定要用绝对路径。相对路径在不同客户端的工作目录下解析结果不一样经常导致 server 启动失败但报错信息很模糊。提示配置完成后可以在 AI 对话里直接问“这个项目有哪些主要模块”如果 AI 能给出结构化的回答而不是泛泛而谈说明 CodeGraph 已经正常工作了。4. 实操过程与核心环节实现4.1 环境准备与安装CodeGraph 目前主要通过 npm 分发也可以从源码构建。最省事的方式是全局安装npm install -g codegraph安装完成后验证一下codegraph --version如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Windows 上通常是%APPDATA%\npmmacOS/Linux 是/usr/local/bin或~/.npm-global/bin。Python 项目的话也有对应的 pip 包安装方式类似。选哪个版本取决于你的主力语言和客户端支持情况功能上基本对齐。4.2 初始化项目索引进入项目根目录执行初始化cd /path/to/your/project codegraph init这个命令会做几件事创建.codegraph/目录存放数据库文件扫描项目文件构建初始索引。执行过程中会输出进度信息包括已解析文件数、提取的节点数和边数。一个典型的中型 TypeScript 项目输出大概是这样Scanning project... Found 487 source files Parsing... [] 100% Extracted 12,847 nodes, 34,291 edges Index built in 23.4s Database size: 18.2 MB数据库文件默认放在.codegraph/graph.db。这个文件建议加入.gitignore因为它是本地索引不同开发者机器上重新构建即可没必要提交到仓库。4.3 增量更新与实时同步日常开发中代码一直在变。CodeGraph 提供了 watch 模式可以监听文件变动并自动更新索引codegraph watch这个命令会常驻运行检测到文件保存后触发增量索引。实测下来单个文件的增量更新通常在几百毫秒内完成基本无感。如果你不想一直开着 watch也可以在需要的时候手动触发codegraph update这个命令会对比文件哈希只重新解析变动的部分。比全量重建快得多一个几百文件的项目通常几秒就能完成。注意watch 模式在大型 monorepo 里可能会消耗较多 CPU因为文件变动频繁。这种情况下建议只在需要深度使用 AI 辅助时开启平时关掉。4.4 在 AI 对话中实际使用配置好之后使用方式就很自然了。你不需要手动指定“请用 CodeGraph 查询”AI 会根据问题类型自动决定是否调用。比如你问“OrderService 里 processPayment 方法的完整调用链是什么”AI 会调用 CodeGraph 的调用链查询工具拿到从 processPayment 出发的所有下游调用然后基于这些精确信息给出回答。对比没有 CodeGraph 的情况回答的准确率和细节丰富度有明显提升。再比如你接手一个陌生模块可以直接问“这个模块对外暴露了哪些接口被哪些其他模块引用了”CodeGraph 会返回模块的导出符号列表以及所有引用这些符号的外部节点。这种问题在没有代码图的情况下AI 基本只能靠猜。4.5 Token 节省的实测数据标题说平均省 57%我自己的实测数据供参考。在一个约 300 个 TypeScript 文件的项目里做同样的代码理解任务任务类型无 CodeGraph Token 消耗有 CodeGraph Token 消耗节省比例单函数理解~2,800~1,10061%跨文件调用链分析~8,500~3,20062%模块依赖梳理~12,000~5,80052%重构影响面评估~15,000~6,50057%节省主要来自两个方面一是不需要把整个文件塞进上下文只取相关代码片段二是 AI 不需要反复追问和确认一次查询就能拿到精确结果减少了来回对话的 Token 开销。5. 常见问题与排查技巧实录5.1 索引失败或结果为空最常见的原因是文件类型不被支持。CodeGraph 目前覆盖了主流语言但如果你用的是比较小众的 DSL 或者自定义文件扩展名解析器可能直接跳过。检查方式是看索引输出里的文件数是否和预期一致。另一个原因是权限问题。如果项目目录里有符号链接指向外部路径或者某些文件当前用户没有读权限解析会静默跳过。可以在配置里开启 verbose 日志确认codegraph init --verbose5.2 MCP 连接不上客户端报“MCP server failed to start”之类的错误按这个顺序排查确认codegraph命令在 PATH 里且版本和客户端兼容检查配置文件里的路径是不是绝对路径手动在终端跑一下codegraph serve --project /your/path看有没有报错输出确认客户端版本支持 MCP 协议Cursor 0.4x 以上、Claude Code 近期版本都支持如果手动跑能启动但客户端连不上大概率是客户端配置格式问题。不同客户端的 MCP 配置字段名可能有差异以官方文档为准。5.3 查询结果不准确CodeGraph 的查询精度受限于静态分析的固有局限。以下几种情况可能导致结果不完整动态调用obj[methodName]()这种运行时决定的调用静态分析无法确定目标反射和元编程Python 的getattr、Java 的反射 API条件导入根据环境变量决定导入哪个模块遇到这种情况可以在 AI 对话里补充说明让 AI 结合 CodeGraph 的结果和你的描述综合判断。完全依赖工具不现实工具是辅助你的领域知识才是最终决策依据。5.4 数据库膨胀长期使用后.codegraph/graph.db可能会变得很大尤其是频繁增删文件的项目。SQLite 不会自动回收删除数据占用的空间。定期执行一下清理codegraph vacuum这个命令会重建数据库文件回收未使用的空间。一个原本 50MB 的数据库清理后可能降到 20MB 左右。建议每个月或者项目大改之后跑一次。5.5 多项目切换的配置管理如果你同时维护多个项目每个项目都需要独立的 CodeGraph 索引。MCP 配置里可以注册多个 server 实例分别指向不同项目{ mcpServers: { codegraph-project-a: { command: codegraph, args: [serve, --project, /path/to/project-a] }, codegraph-project-b: { command: codegraph, args: [serve, --project, /path/to/project-b] } } }但要注意同时运行多个 server 实例会占用更多内存。如果项目多但不同时活跃建议只配置当前主力项目的 server需要时再切换。6. 进阶用法与扩展思路6.1 自定义查询与脚本化CodeGraph 的数据库就是普通的 SQLite 文件你可以用任何 SQLite 客户端直接查询。比如用 DB Browser for SQLite 打开.codegraph/graph.db自己写 SQL 做分析。想找项目中所有超过 100 行的函数SELECT name, file_path, end_line - start_line AS lines FROM nodes WHERE type function AND lines 100 ORDER BY lines DESC;想找循环依赖SELECT a.file_path, b.file_path, COUNT(*) AS ref_count FROM edges e JOIN nodes a ON e.source_id a.id JOIN nodes b ON e.target_id b.id WHERE e.edge_type imports AND a.file_path ! b.file_path GROUP BY a.file_path, b.file_path HAVING ref_count 3;这种灵活性是 CodeGraph 用 SQLite 的一个额外好处——它不只是一个 AI 辅助工具也是一个轻量级的代码分析平台。6.2 结合其他 MCP 工具使用CodeGraph 可以和别的 MCP Server 配合。比如你同时用 Playwright MCP 做端到端测试AI 可以先通过 CodeGraph 理解页面组件的代码结构再通过 Playwright 操作浏览器验证行为。两个工具各司其职AI 负责编排。这种组合用法目前还在早期实际效果取决于 AI 客户端的工具调用能力。但方向是明确的MCP 生态越丰富AI 助手能做的事情就越具体、越可靠。6.3 对团队协作的意义个人用 CodeGraph 省的是自己的时间。团队用的话还有一层价值新人上手成本降低。新成员不需要花几天时间读代码理清模块关系直接问 AI 就能得到基于代码图的准确回答。前提是团队统一了 AI 客户端和 CodeGraph 配置并且索引保持更新。可以考虑在 CI 流程里加一步每次合并到主分支后自动重建索引并缓存开发者拉取代码后直接下载索引文件省去本地构建时间。不过这个方案对小型团队可能过度设计了手动codegraph update已经够用。6.4 局限性与适用边界CodeGraph 不是银弹。它解决的是“代码结构信息获取”的问题不解决“代码逻辑理解”的问题。AI 拿到精确的调用链之后能不能正确理解业务逻辑还是取决于模型能力和你的提问质量。另外它对动态语言的支持天然弱于静态语言。如果你的项目大量使用 Ruby 的 method_missing、Python 的getattr这类元编程特性CodeGraph 能提供的帮助会打折扣。最后一个现实问题维护索引需要额外的心智负担。你得记得代码大改之后更新索引否则 AI 拿到的就是过时信息。watch 模式能缓解这个问题但不是所有人都习惯一直开着后台进程。我个人在实际操作中的体会是CodeGraph 最适合的场景是“中等规模、静态类型为主、需要频繁做跨文件理解”的项目。如果你的项目符合这个画像花半小时配置一下后面省下的时间和 Token 是值得的。如果项目很小或者动态特性很重可以先放一放等生态更成熟再说。