一、什么是CodeGraph ？
CodeGraph 是一款专门为 AI 编程助手（Cursor / Claude Code / Copilot Agent）设计的代码索引与上下文检索工具。
它并不试图让 AI “理解代码语义”，而是致力于解决一个在实际开发中更迫切的问题——让 AI 在复杂项目中快速、准确地找到它需要的代码。
在真实的开发场景中，AI 最大的瓶颈往往不是不会写代码，而是：
-
找不到正确的文件（例如在 src/utils/ 下有实现，AI 却建议在 lib/ 下新建）；
-
找错函数或实现（同名函数多处存在，AI 选中了错误的那个）；
-
上下文过大导致 Token 爆炸（为了给 AI 足够信息，不得不贴入大量代码）；
-
跨文件关系无法识别（A 文件调用了 B 文件的类，AI 毫不知情）；
-
大型项目无法定位核心逻辑（几十万行代码，AI 只能浮于表面）
因此，AI 的真正瓶颈在于 缺少可靠的代码定位能力。
CodeGraph 的作用，就是提前对整个项目进行扫描与索引，构建一个结构化的代码检索系统，让 AI 在回答问题时能够先精准检索，再思考生成。
二、CodeGraph 的核心能力
CodeGraph 会在本地对项目进行深度分析，并构建以下关键索引结构：
-
文件索引（File Index） – 项目所有文件的层级路径。
-
函数索引（Function Index） – 每个函数的名称、参数、返回值、所在文件及行号。
-
类结构索引（Class Index） – 类的继承关系、属性和方法。
-
调用关系图（Call Graph） – 函数之间的调用链，帮助 AI 理解执行流。
-
依赖关系图（Dependency Graph） – 模块/文件间的依赖关系，避免循环引用和缺失。
通过这些预计算的结构化数据，AI 不再需要依赖 grep 或盲目搜索，而是可以直接基于索引进行精准定位，从而显著提升回答的准确性和效率。
三、安装 CodeGraph
CodeGraph 提供官方一键安装脚本，推荐使用该方式。
环境要求
-
macOS / Linux（Windows 可通过 WSL 支持）
-
无需额外依赖，安装包为独立二进制
安装
1、执行以下命令：
npm install -g @optave/codegraph
安装成功后，可以用下面的命令验证是否可用：
codegraph –version
如果输出类似：
3.15.0
则说明安装成功。
2、进入项目目录
cd D:\\qiqi\\lent-cf
3、初始化完成后构建索引执行：
codegraph build
这会生成完整的代码依赖关系图。
4、以后代码有变更，再次运行
codegraph build
就会增量更新，速度很快。
四、配置 PATH（必须）
🪟 Windows 配置方法
1️⃣ 查找 codegraph.cmd 所在目录
打开 命令提示符（CMD） 或 PowerShell，执行：
where codegraph
输出示例：
D:\\xxx\\xxxx\\node_global\\codegraph
D:\\xxx\\xxxx\\node_global\\codegraph.cmd
其中 D:\\xxx\\xxxx\\node_global 就是需要添加到 PATH 的目录（请根据你的实际输出替换）。
说明：如果通过 npm install -g @optave/codegraph 安装，默认路径为 %USERPROFILE%\\AppData\\Roaming\\npm；如果曾经修改过 npm 全局安装目录，路径可能不同。
2️⃣ 添加目录到 PATH
方法一：图形界面（推荐）
-
按 Win + X → 选择 “系统”；
-
点击左侧 “高级系统设置” → 点击 “环境变量”；
-
在 “用户变量” 区域找到 Path 变量，选中并点击 “编辑”；
-
点击 “新建”，粘贴上一步查到的目录（例如 D:\\APP\\nodejs\\node_global）；
-
依次点击 “确定” 保存所有窗口；
-
关闭所有 CMD 窗口，重新打开一个新的 CMD，验证。
方法二：命令行（管理员权限）
以管理员身份打开 CMD，执行：
setx PATH "%PATH%;D:\\xxx\\xxxx\\node_global"
（不加 /M 修改用户变量，重启终端后生效）
3️⃣ 验证
在新打开的 CMD 中执行：
codegraph –version
如果输出版本号（如 3.15.0），则配置成功。
🍎 macOS 配置方法
1️⃣ 查找 codegraph 所在目录
通常官方安装脚本会将二进制文件放入 ~/.local/bin/。你可以在终端中执行：
which codegraph
如果返回类似 /Users/你的用户名/.local/bin/codegraph，则说明安装在该目录。
2️⃣ 添加目录到 PATH
macOS 默认使用 zsh（从 Catalina 开始），配置文件为 ~/.zprofile；若使用 bash，则为 ~/.bash_profile。
在终端中执行以下命令（以 zsh 为例）：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
如果使用 bash：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
注意：如果你的 codegraph 在其他目录（例如通过 npm 安装于 /usr/local/bin），请将 $HOME/.local/bin 替换为实际路径。
3️⃣ 验证
在新终端窗口中执行：
codegraph –version
如果输出版本号，则配置成功。
五、配置 Cursor MCP（关键步骤）
CodeGraph 通过 MCP（Model Context Protocol） 与 Cursor 等编辑器集成，让 AI 能够自动调用项目索引。
配置文件位置
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "D:\\\\xxx\\\\xxxx\\\\node_global\\\\codegraph.cmd",
"args": ["mcp"]
}
}
}
配置完成后，重启 Cursor，CodeGraph 就会在后台为当前项目自动提供检索服务。
六、初始化项目
进入你的项目目录：
cd /项目路径
执行初始化命令：
codegraph init -i
其中 -i 表示交互式初始化，会引导你完成基本设置。你也可以直接使用 codegraph init 采用默认配置
七、初始化后生成了什么？
执行成功后，项目根目录下会新增：
-
.codegraph/ 目录 – 存放代码索引缓存和结构数据。
-
.cursor/rules/codegraph.mdc 文件 – 为 Cursor 提供的上下文规则，让 AI 自动引用 CodeGraph 检索结果。
八、增量更新机制
在日常开发中，代码频繁修改，CodeGraph 并不需要每次都全量重建索引。只需执行：
codegraph build
九、推荐使用流程
第一次接入项目：
codegraph init -i
日常开发（代码变更后）：
codegraph build
总结
十一、总结
CodeGraph 的核心价值可以概括为一句话：
它解决的是 AI 编程中的第一个关键瓶颈——代码定位。
-
❌ 过去：AI 找代码靠猜，grep 不稳定，上下文混乱，Token 消耗巨大。
-
✅ 现在：结构化索引 + 精准定位 + 低 Token 成本，AI 将精力真正用在逻辑生成上。
CodeGraph 并不会让 AI 变得更“聪明”，但它会让 AI 更“靠谱”。在大型项目中，这往往是决定 AI 辅助编程能否从“玩具”变成“生产力工具”的分水岭。
如果你也在为 AI 找不到代码而头疼，不妨试试 CodeGraph——只需几分钟配置，就能让你的编程助手拥有“全局视野”。
项目地址：https://github.com/colbymchenry/codegraph 反馈与讨论：欢迎在评论区分享你的使用体验，或提出改进建议。
