在用 Cursor、Claude Code 开发大型代码库时，普遍存在一个问题：AI 会不停读取文件、全局检索代码。

这个过程不仅消耗大量 Token，而且效率极低。复杂项目的调用链、依赖关系、路由逻辑，AI 很难一次性梳理清楚，修改代码后也无法预判会影响哪些业务。

而 CodeGraph 可以给本地项目构建代码知识图谱，替代 AI 盲目扫代码的行为，从根本上提升 AI 辅助编码效率。

一、CodeGraph 是什么

CodeGraph 是一款基于 TypeScript 开发的开源工具，核心能力是本地代码知识图谱构建与 MCP 服务。

工具基于 tree-sitter 做静态代码解析，自动扫描项目内的类、函数、变量、接口、路由等核心代码元素，自动梳理函数调用关系、模块依赖、路由流转逻辑，生成结构化、可查询的代码图谱。

CodeGraph 支持 MCP 协议，可直接对接 Cursor、Claude Code 等主流 AI 编程工具。所有解析和索引操作均在本地完成，不上传任何代码数据，无需第三方 API 密钥，个人开发和企业私有化项目都可以直接用。

官方实测数据：可减少 94% 的 AI 工具调用次数，代码探索效率提升 77%，大幅降低 AI 开发的 Token 开销。

二、核心作用与核心特性

（一）核心作用

1. 提升 AI 编码效率：杜绝 AI 反复读文件、全局检索的低效操作。AI 可直接读取结构化图谱数据，精准掌握项目架构、调用链和依赖关系，专注编码逻辑。
2. 快速读懂陌生代码库：自动解析项目结构、函数调用链路、类依赖、接口路由。大幅降低接手新项目、老旧项目的学习成本。
3. 精准评估代码改动风险：代码修改后，快速定位所有受影响的文件、业务逻辑、测试用例，提前规避隐性 Bug，适配日常开发、代码评审、自动化测试场景。
4. 快速定位接口问题：自动识别主流 Web 框架路由，完整还原前端请求到数据层的全调用链路，快速排查接口 404、请求报错、逻辑异常等问题。

（二）核心特性

1. 兼容绝大多数技术栈：原生支持 JS/TS、Python、Go、Java、Rust、C/C++ 等 20 余种编程语言，适配 Spring、Django、Gin、Express、NestJS 等 14 种主流 Web 框架。
2. 自动实时更新索引：无需手动配置解析规则，自动识别代码文件类型。依托系统文件监听，代码修改后 2 秒内更新索引，保证图谱数据实时最新。
3. 本地数据安全可控：所有索引数据以 SQLite 数据库形式存放在项目 .codegraph 隐藏目录，无外网请求、无数据上传，完全满足企业私有化部署安全规范。
4. 全设备架构适配：支持 x64、ARM64 架构，桌面设备、服务器、国产 ARM 设备均可运行。客户端内置运行环境，无需提前配置依赖。

三、使用教程

CodeGraph 提供三种安装方式，适配不同开发环境。没有 Node.js 环境，直接用一键客户端安装即可。

方式一：一键客户端安装（推荐）

内置 Node.js 运行环境，零依赖、零配置，安装后自动写入系统环境变量。

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

安装完成后，执行如下命令验证是否安装成功：

codegraph -v

方式二：NPM 安装（已有 Node.js 18+）

适合前端、全栈开发者，支持全局安装和临时运行。

全局安装（长期使用）：

npm install -g @colbymchenry/codegraph

临时运行（无需安装）：

npx @colbymchenry/codegraph

方式三：CI 静默安装（自动化流水线专用）

# 自动识别AI代理，全局静默安装
codegraph install --yes

# 指定对接 Cursor、Claude Code
codegraph install --target=cursor,claude --yes

# 仅当前项目本地部署，不全局生效
codegraph install --target=auto --locatinotallow=local

补充：手动配置 AI 代理

自动安装适配失败时，可手动配置 MCP 服务。

Claude Code：编辑全局配置 ~/.claude.json 或项目配置 .claude.json，写入以下内容：

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

Cursor：执行 codegraph install 自动生成规则文件，重启 Cursor 即可生效。

四、项目实战

步骤1：进入项目根目录

cd /你的项目根目录

步骤2：初始化代码图谱

v0.9.8 及以上版本，初始化命令会自动构建代码索引，无需额外配置。

# 交互式初始化，展示构建进度（推荐）
codegraph init -i

# 静默快速初始化
codegraph init

执行完毕后，项目根目录会生成 .codegraph 隐藏文件夹，存放索引数据库与配置，不要手动修改或删除。

步骤3：验证索引状态

codegraph status

状态说明：

• 文件数、节点数、边数：代表当前索引覆盖的代码文件、代码符号、依赖关系总量
• Backend 为 native：正常高性能模式；为 wasm：性能降级，需要修复本地环境

步骤4：高频实用 CLI 命令

# 检索项目内指定函数、类、变量
codegraph query UserService --limit 10

# 查看目标函数的所有调用位置
codegraph callers createOrder

# 查看目标函数内部调用的所有方法
codegraph callees createOrder

# 评估指定文件修改的影响范围
codegraph affected src/utils.ts src/api.ts

# 结合 Git，评估本次提交的改动影响
git diff --name-only | codegraph affected --stdin

# 手动启动 MCP 服务，对接 AI 工具
codegraph serve --mcp

# 移除当前项目索引
codegraph uninit

步骤5：对接 AI 代理使用

1. 完成项目索引构建与 AI 工具 MCP 配置；
2. 重启 Cursor、Claude Code 等工具；
3. 正常使用 AI 编码、查架构、改代码、排错，工具会自动调用 CodeGraph 结构化数据，无需重复扫描文件。

五、典型使用场景

场景1：快速接手大型陌生代码库

拿到不熟悉的大型项目，执行 init 构建全局图谱，搭配 query、callers 命令快速梳理项目入口、业务链路、模块依赖，短时间吃透整体架构，效率远高于逐文件读代码。

场景2：规避代码改动风险

修改公共方法、核心接口、底层代码前，用 affected 命令查看全量关联代码，明确改动影响范围，避免改一处崩多处的隐性问题，提升迭代稳定性。

场景3：快速排查接口故障

后端接口出现 404、报错、逻辑异常时，依托路由解析能力，还原完整调用链路，快速定位问题出在路由层、业务层还是数据层。

场景4：优化 CI 自动化测试

流水线接入 CodeGraph，通过 affected 筛选本次改动对应的测试用例，跳过无关测试，省去全量测试的耗时，提升 CI 构建效率。

六、总结

CodeGraph 解决了 AI 开发大型代码库的核心痛点：重复检索、Token 浪费、架构梳理困难、改动风险不可控。

日常 AI 辅助编码、新项目接手、代码风险管控、自动化流程优化，都可以通过 CodeGraph 提升开发与排错效率，是适配 AI 编程流程的实用工具。

文章来自：51CTO