CodeGraph 项目介绍与使用指南

一、这是什么？

CodeGraph 是一个开源项目，旨在解决 AI 编程工具（如 Claude Code、Cursor、Codex 等）在分析中大型代码仓库时遇到的核心痛点：

痛点：当你在项目中问一个关于代码架构或调用流程的问题时，AI 会通过 grep和 read命令，反复扫描、读取大量相关文件来寻找答案。这个过程不仅耗时（十几分钟），而且会消耗巨量的 Token（单次查询可达六位数），导致 API 费用激增。

CodeGraph 的解决方案是：预先把你的整个代码库转换成一个本地的知识图谱数据库。当 AI 需要分析代码时，不再是“暴力搜索”所有文件，而是像“查字典”一样，直接在这个知识图谱中进行精准的图关系查询，一次性获取完整的调用链和符号关联。

简单来说，它让 AI 从“翻箱倒柜”变成了“按图索骥”。

基于官方测试（使用 Claude Opus 在 7 个真实开源项目上验证），使用 CodeGraph 后，平均可实现：

本质：这是一种上下文工程优化，通过为模型提供更精准、结构化的上下文（代码关系图），而非更大的上下文窗口，来显著提升其工作效率和准确性。

构建图谱：
- 解析：使用 tree-sitter解析源代码，准确识别出函数、类、方法、变量等符号。
- 关联：解析出符号之间的调用、导入、继承、实现等关系。
- 存储：将所有节点和关系存入本地的 SQLite 数据库（位于 .codegraph/codegraph.db），并建立全文搜索索引。
精准查询：AI 通过 **MCP (Model Context Protocol)** 协议与 CodeGraph 服务器通信，可以执行“查找此函数的所有调用者”、“找到这个 API 路由对应的处理函数”等精准查询。
与向量检索的区别：
- Cursor 自带索引 / 传统 RAG：基于语义相似度进行模糊匹配，找“最像的文本片段”。
- CodeGraph 图谱检索：基于代码的结构化关系进行精准查询，找“对象之间的调用和继承路径”。这在理解代码架构时优势明显。
其他特性：
- 支持广泛：覆盖 19+ 种编程语言，并能自动识别 13 种主流 Web 框架（如 Spring Boot, Django, Express, NestJS 等）中的路由映射。
- 完全本地：所有数据处理和存储均在本地完成，代码不会上传到任何外部服务器，安全性高。
- 自动同步：监听文件变更，增量更新索引，无需手动重建。

只需几步即可为你的项目启用 CodeGraph。

打开终端，执行以下命令（需 Node.js 18+）：

1	npx @colbymchenry/codegraph

这条命令会：

下载并安装 CodeGraph。
自动检测你系统上已安装的 AI 编程工具（如 Claude Code、Cursor、Codex CLI 等）。
自动为你配置好 MCP 连接。
- 对于 Claude Code：会在 ~/.claude.json中添加 MCP 服务器配置，并在 ~/.claude/CLAUDE.md中添加使用说明。
- 对于 Cursor：会在项目或全局的 .cursor/rules/目录下生成规则文件。

进入你需要分析的代码仓库根目录：

1 2	cd /path/to/your/project codegraph init -i # -i 选项表示立即构建初始索引

命令执行后，会在项目根目录下生成一个 .codegraph/文件夹，里面包含本地的图谱数据库。它会自动遵循你的 .gitignore文件规则。

重启你的 AI 编程工具（如 Claude Desktop、Cursor）。
像平常一样向 AI 提问关于代码的问题，例如：
- “/api/users这个接口是在哪里实现的？”
- “UserService类的 findById方法都被哪些地方调用了？”
- “这个登录模块的流程是怎么串起来的？”
AI 在回答时，会自动优先调用 CodeGraph 的工具来查询知识图谱，从而快速给出精准答案，不再需要几十轮的暴力文件搜索。你无需任何额外操作。

最佳适用场景：
- 中大型项目（文件数量上千）。
- 需要频繁进行代码探索、架构理解、影响分析、重构规划。
- 使用 Claude Code、Cursor 等工具且深感 Token 消耗昂贵的团队。
可能效果不明显的场景：小型或个人项目，代码量少，AI 本身就能快速遍历。
已知问题：
- 其解析能力依赖 tree-sitter，对于语法非常特殊或大量动态生成的代码，图谱覆盖可能会有遗漏。
- macOS 用户：请确保已安装 Xcode Command Line Tools (xcode-select --install)，否则会回退到低速的兼容模式，性能下降5-10倍。