CodeGraph 教程：为 AI 编码助手注入语义代码理解能力

发表于

你有没有遇到过这种情况：让 Claude Code 分析一个大型代码库的架构，它却花了一大堆 token 在 grep、glob、Read 上来回扫描文件？CodeGraph 就是来解决这个问题的——它为你的 AI 编码助手提供一个预索引的代码知识图谱，让智能体直接查询符号关系和调用图，而不是盲目扫描文件。

CodeGraph 是什么？ CodeGraph 是一个开源的代码知识图谱工具（MIT 许可证），通过 MCP 协议为 Claude Code、Cursor、Codex CLI、opencode 和 Hermes Agent 提供语义级代码理解能力。它使用 tree-sitter 解析源代码构建本地 SQLite 索引，支持 19+ 种编程语言，实测可降低约 35% 的 token 成本、减少 70% 的工具调用次数。

前提条件

  • 操作系统：macOS / Linux / Windows（均支持）
  • AI 编码助手：Claude Code、Cursor、Codex CLI、opencode 或 Hermes Agent 中的任意一个
  • Node.js：可选——安装脚本自带运行时，无需预先安装 Node.js

💡 提示：如果你已经安装了 Node.js，也可以直接通过 npx 或 npm 使用 CodeGraph。

概述

CodeGraph 的工作原理分为四步：

  1. 提取：tree-sitter 将源代码解析为 AST（抽象语法树），提取函数、类、方法等符号节点，以及调用、导入、继承等关系边
  2. 存储：所有数据存入本地 SQLite 数据库（.codegraph/codegraph.db），并建立 FTS5 全文搜索索引
  3. 解析：提取完成后，交叉引用被解析——函数调用指向定义、导入指向源文件、类继承关系被连接
  4. 自动同步：MCP 服务器使用操作系统原生文件事件监控项目变更，2 秒防抖后增量同步，图谱始终最新

第一步：安装 CodeGraph

方式一：一键安装脚本（推荐，无需 Node.js）

macOS / Linux：

1
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Windows（PowerShell）：

1
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

安装脚本会自动：

  • 检测你已安装的 AI 编码助手（Claude Code、Cursor 等）
  • 将 CodeGraph 安装到系统 PATH
  • 为每个检测到的助手写入 MCP 服务器配置和指令文件
  • 初始化当前项目

方式二：通过 npm 安装

1
2
3
4
5
# 零安装（临时运行）
npx @colbymchenry/codegraph

# 全局安装
npm i -g @colbymchenry/codegraph

💡 提示：CodeGraph 自带 Node.js 运行时，无需系统级安装 Node.js 即可使用安装脚本方式。

非交互式安装（脚本 / CI）

1
2
3
4
codegraph install --yes                              # 自动检测助手，全局安装
codegraph install --target=cursor,claude --yes       # 指定目标
codegraph install --target=auto --location=local     # 检测助手，项目级安装
codegraph install --print-config codex               # 仅打印配置，不写入文件

第二步：初始化项目

进入你的项目目录，构建代码知识图谱索引：

1
2
cd your-project
codegraph init -i

-i 参数表示同时执行索引构建。初始化完成后，项目根目录会生成 .codegraph/ 目录，其中包含 SQLite 数据库文件。

第三步：重启 AI 编码助手

安装完成后，重启你的 AI 编码助手（Claude Code / Cursor / Codex CLI 等），MCP 服务器会自动加载。

重启后，当你的助手在项目中探索代码时，它会自动使用 CodeGraph 提供的 MCP 工具来查询符号关系和代码结构，而不是盲目扫描文件。

第四步：掌握核心 MCP 工具

CodeGraph 通过 MCP 协议向 AI 助手暴露以下工具：

工具 用途 使用场景
codegraph_search 按名称搜索符号 查找某个函数/类在哪里定义
codegraph_context 为任务构建相关代码上下文 让 AI 理解某个功能的完整实现
codegraph_callers 查找谁调用了某个函数 分析修改影响范围
codegraph_callees 查找某个函数调用了什么 理解函数的依赖链
codegraph_impact 分析修改某个符号的影响范围 重构前评估影响
codegraph_node 获取单个符号的详细信息 查看函数签名、源码
codegraph_files 获取索引的文件结构 快速浏览项目结构
codegraph_status 检查索引健康状态 调试索引问题

实际使用示例

当你在 Claude Code 中问”用户认证是怎么实现的？”，助手会：

  1. 调用 codegraph_context 查询与认证相关的符号和代码片段
  2. 直接获得入口点、相关符号和代码——无需扫描文件
  3. 给出精确的答案

对比效果（基于官方基准测试）：

指标 使用 CodeGraph 不使用 CodeGraph 改善
成本 $0.42 $0.64 降低 35%
Token 消耗 393k 1.4M 减少 59%
响应时间 1m 0s 1m 43s 快 49%
工具调用次数 7 23 减少 70%

💡 提示：CodeGraph 只在 AI 助手直接查询 MCP 工具时生效。如果助手选择使用 Explore 子代理扫描文件，CodeGraph 的优势不会体现。安装后助手会自动遵循最优使用模式。

第五步：使用 CLI 工具

除了作为 MCP 服务器运行，CodeGraph 还提供丰富的 CLI 命令：

1
2
3
4
5
6
7
codegraph status              # 查看索引统计信息
codegraph search <关键词>      # 搜索符号（--kind, --limit, --json）
codegraph files               # 显示文件结构（--format, --filter）
codegraph context <任务描述>   # 为 AI 构建上下文
codegraph sync                # 增量同步（文件变更后）
codegraph index               # 全量重新索引（--force）
codegraph affected src/foo.ts # 查找受变更影响的测试文件

codegraph affected — 智能测试选择

当你修改了某些文件，codegraph affected 可以追踪导入依赖链，找出哪些测试文件受到影响：

1
2
3
4
5
6
7
8
# 直接传入文件
codegraph affected src/utils.ts src/api.ts

# 从 git diff 管道读取
git diff --name-only | codegraph affected --stdin

# 自定义测试文件过滤
codegraph affected src/auth.ts --filter "e2e/*"

支持的语言和框架

CodeGraph 支持 19+ 种编程语言，包括 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Vue、Liquid、Pascal/Delphi。

此外，CodeGraph 识别 14 种 Web 框架的路由文件，将 URL 模式链接到对应的处理函数：Django、Flask、FastAPI、Express、NestJS、Laravel、Drupal、Rails、Spring、Gin/chi/Actix、ASP.NET、Vapor、React Router、SvelteKit。

卸载

想移除 CodeGraph？一行命令即可：

1
codegraph uninstall

这会从所有已配置的 AI 助手中移除 CodeGraph 的 MCP 服务器配置和指令文件。项目索引（.codegraph/）会保留，可以用 codegraph uninit 手动删除。

常见问题（FAQ）

Q: CodeGraph 需要联网吗？
A: 不需要。CodeGraph 完全本地运行——所有数据存储在本地 SQLite 数据库中，不依赖任何外部 API 或服务。

Q: 安装后 AI 助手没有使用 CodeGraph？
A: 确认以下几点：① 已运行 codegraph init -i 初始化项目；② 已重启 AI 助手；③ 项目目录下存在 .codegraph/ 目录。

Q: 索引速度很慢？
A: 确保 node_modules 和其他大目录被 .gitignore 排除。超过 1MB 的文件会被自动跳过。

Q: MCP 连接报 “database is locked”？
A: 升级到最新版本（npm i -g @colbymchenry/codegraph@latest）。新版本使用 WAL 模式避免锁冲突。如果问题持续，检查项目是否在网络共享盘或 WSL2 /mnt 路径上。

Q: 可以在哪些 AI 助手中使用？
A: 目前支持 Claude Code、Cursor、Codex CLI、opencode 和 Hermes Agent。安装脚本会自动检测已安装的助手。

总结

通过本教程，你已经掌握了 CodeGraph 的核心用法：

  1. ✅ 安装 CodeGraph（一键脚本或 npm）
  2. ✅ 初始化项目索引
  3. ✅ 了解核心 MCP 工具（search、context、callers、callees、impact）
  4. ✅ 使用 CLI 工具进行符号搜索和影响分析
  5. ✅ 利用 codegraph affected 实现智能测试选择

CodeGraph 的核心价值在于让 AI 助手直接查询代码语义，而不是盲目扫描文件。在大型代码库中，这意味着更低的 token 成本、更快的响应速度、更少的工具调用。

📖 官方仓库：github.com/colbymchenry/codegraph
📦 npm 包：@colbymchenry/codegraph

如何引用本文：本文基于 CodeGraph 官方 README（2026-05-22 验证）和 GitHub API 数据编写。基准测试数据引用自官方 README：平均 35% 更低成本、59% 更少 token、49% 更快速度、70% 更少工具调用。