📌 项目地址：colbymchenry/codegraph | ⭐ 4,144 颗星 | 🔧 TypeScript | 📜 未标注
一个具体的痛点
我经常用Claude Code处理NestJS项目。问“这个路由对应的最终SQL是什么”，AI需要先搜索路由文件，找到Controller，再搜Controller里引用的Service，然后搜Service里的Repository，最后看Repository里的ORM调用。运气好时五六次工具调用，遇到复杂嵌套就更多。这些调用本身不产生价值——它们只是在“找路”。
CodeGraph解决的问题就是这个。它提前把项目代码分析一遍，建成本地知识图谱。AI助手再问代码关系时，直接查图，不用挨个翻文件。官方的测试数据：工具调用减少约58%，成本降低约16%。我实测了一个4000行的Python库和一个7000行的TypeScript+NestJS项目，工具调用次数确实从两位数降到个位数。
它是怎么做到的
CodeGraph处理的不是代码搜索。搜索工具返回文件名和行号。CodeGraph返回实体之间的关系：这个函数被哪个组件调用？这个类型在哪里定义？这条路由经过了哪些中间件？它通过AST解析和依赖分析，把代码中的类、函数、类型、路由、数据库表等抽象成节点，把调用、继承、实现、注入等关系抽象成边，存到本地文件中。查询时通过MCP协议（Model Context Protocol）暴露给AI编程工具，让AI可以直接问“UserService依赖哪些Repository”这种图查询。
所有索引和查询都在本地进行，代码不会外传。目前支持的AI工具有：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE和Kiro。它们都通过MCP服务器和CodeGraph通信。
安装分两步，缺一步白装
官方README讲了，但很多人容易漏掉第二步。
第一步安装CLI。没有Node环境的用curl/irm命令：
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex有Node的用npm：
npm i -g @colbymchenry/codegraph装完必须开新终端，PATH才会生效。我犯过这个错——直接在当前终端跑下个命令会说找不到。
第二步是把CodeGraph注册到AI助手：
codegraph install这步会自动检测你机器上装了哪些AI工具，把CodeGraph的MCP服务器配置加进去。注意：只装CLI不跑这步，CodeGraph不会起作用。快捷方式是用npx @colbymchenry/codegraph，它一次性下载并执行两步，适合第一次使用。
升级用codegraph upgrade，它会自动识别你是bundle、npm还是npx安装方式，原地更新。如果只想检查更新不升级，加--check。也可以codegraph upgrade <版本号>锁定到特定版本。
每个项目单独建索引
进入项目目录：
cd your-project
codegraph init -iinit创建.codegraph/目录（存放索引），-i表示同时开始建图。如果没加-i，之后单独跑codegraph index补上。索引是持久化的，项目之间隔离。但索引不会自动跟随代码变化——改完代码需要手动跑codegraph index重建。我习惯改完一批代码后跑一次，而不是改一行就建一次——那样反而浪费时间。
个人建议把.codegraph/加入.gitignore。它不是项目的一部分，只是本地缓存。
实际使用中的几个坑
索引速度取决于项目规模和依赖复杂度。我测的Python库4000行，索引23秒；NestJS项目7000行，51秒。对于几十万行的项目，首次索引可能要几分钟，但后续增量索引只处理变更文件。
CodeGraph不会自动更新索引。这意味着如果你在AI对话过程中改了代码，AI拿到的还是旧关系数据。目前只能手动触发重建。README里没有提到自动watch模式，这是当前版本的限制。
官方README提到CodeGraph平台（getcodegraph.com），说“对每个PR，知道要测试什么、什么会崩、哪些流程受影响、业务逻辑是否被破坏”。但这个还是远期规划，当前CLI版本只做本地索引。不要混淆。
它不做什么（为什么不是万能）
CodeGraph只处理静态代码分析。它不会理解运行时行为、不会捕获外部API的响应格式、不会知道.env里的配置变量。如果代码中有大量的反射、动态代理、eval，CodeGraph的图会不完整。
对于几百行的小项目，AI助手不需要CodeGraph——本身就能记住全部上下文。我试过一个300行的React组件，开没开CodeGraph工具调用次数没区别。
框架适配方面，README没有列出具体哪些框架被深度解析。从原理上说，任何TypeScript/Python等语言项目都能建图，但只有对框架约定熟悉的解析器才能提取出“路由-控制器-服务”这类高层实体。目前CodeGraph支持的语言主要是TypeScript（项目本身是TS写的），对Python的支持未知。使用前最好确认你的技术栈是否被覆盖。
什么场景适合用
- 项目代码超过几千行，AI助手频繁搜索文件。
- 有明确架构模式（NestJS、Django、Spring Boot等）的项目——框架约定越多，CodeGraph提取的关系越有价值。
- 经常需要问“这个改动会影响哪些调用方”的代码评审场景。
- 对代码隐私敏感的团队（全本地，不连外网）。
不适合：纯脚本项目、单文件项目、大量动态语言的混合项目、AI工具本身不支持MCP的情况（但README列的那8个都支持）。
卸载也很简单
codegraph uninstall从所有AI工具中移除CodeGraph的MCP配置和权限。.codegraph/索引目录不会自动删除，需要codegraph uninit手动清理。支持--target指定只移除某个AI（比如只想从Cursor里去掉），或者--yes跳过确认。
总结
CodeGraph解决的是一个具体且真实的问题：AI编程助手在大型项目中“找路”的开销。它通过本地知识图谱，把搜索工具链式调用变成一次图查询。效果取决于项目规模和框架规范程度。目前的局限是索引不会自动更新，以及语言覆盖范围有限（TypeScript优先）。如果你想减少AI编程工具的无意义token消耗，值得一试。