Appearance
CodeGraph：给 AI Agent 一张本地代码地图
最后更新：2026-08-11
一句话概括
CodeGraph 是一个预构建的代码知识图谱引擎——用 Tree-sitter 把整个代码库的符号、调用链、依赖关系提前索引到本地 SQLite，再通过 MCP 协议交给 Claude Code 等 AI Agent 直接查图，替代了 Agent 逐文件 grep → glob → Read 的笨重探索方式。
一、解决什么问题
Claude Code 在探索代码库时，默认做法是启动子代理（explore subagent），用 grep 搜文本、glob 查文件名、Read 打开文件，逐个拼凑出代码结构。每多一次工具调用就多消耗一轮 Token，且 Agent 看到的只是离散片段，缺少全局关联。
核心矛盾：Agent 需要"理解全局"才能高效干活，但默认工具只能"看局部"。
CodeGraph 的思路是：把"理解全局"这件事从 Agent 手里拿过来，提前做好。
| 维度 | 无 CodeGraph（默认） | 有 CodeGraph |
|---|---|---|
| 探索方式 | grep → glob → Read 逐文件扫 | 一次 codegraph_explore 查图 |
| 符号跳转 | Agent 自己猜文件名、翻 import | 直接走调用边和继承边 |
| 跨文件关系 | 靠 Agent 拼凑 | 图谱里天然连通 |
| 代码变更 | 不感知 | 文件监听 300ms 增量同步 |
| 数据在哪 | 无缓存 | 本地 SQLite，不出机器 |
二、架构：三层设计
| 层 | 职能 | 关键技术 |
|---|---|---|
| 提取层 | 解析 30+ 种语言的源码，提取符号和关系边 | Tree-sitter（Rust 内核），确定性解析 |
| 存储层 | 构建成结构化的 SQLite 图数据库 | FTS5 全文检索 + 符号表 + 关系边 |
| 接入层 | 以 MCP Server 形态暴露给 AI Agent | codegraph_explore 一条核心工具 |
关键：提取过程是确定性的 AST 解析，不走大模型推理，所以准确率高；存储和接入都不依赖云服务，100% 本地。
三、安装
3.1 安装 CodeGraph 本体
bash
# 方式一：一键安装脚本
# 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
# 方式二：npm
npx @colbymchenry/codegraph # 临时使用
npm i -g @colbymchenry/codegraph # 全局安装3.2 注册 MCP Server 到 AI 工具
bash
codegraph install该命令自动检测已安装的 AI 工具（Claude Code、Cursor、Codex、Gemini CLI 等），将 MCP Server 配置写入对应配置文件。
3.3 在项目中构建图谱
bash
cd your-project
codegraph init -i # -i 为交互式，可选 --auto 静默构建构建速度通常几秒到几分钟。完成后项目下生成 .codegraph/ 目录（建议加入 .gitignore）。
3.4 验证
bash
codegraph status
# 确认: 符号数 > 0，Backend 显示 native（非 wasm）四、与 Claude Code 协作的核心机制
4.1 协作全景
4.2 核心工具：codegraph_explore
默认只暴露这一个 MCP 工具，一次调用回答几乎所有结构性问题：
codegraph_explore("createOrder")
→ 返回:
- createOrder 的完整源码（按文件分组、带行号）
- 所有调用 createOrder 的位置
- createOrder 调用了哪些函数
- 受影响的上下游范围可以按需通过环境变量启用更多工具：
bash
export CODEGRAPH_MCP_TOOLS="explore,node,search,callers,callees,impact"| 工具 | 作用 |
|---|---|
codegraph_explore | 默认唯一暴露的核心工具，一次查所有 |
codegraph_node | 读取单个符号源码 + 调用者 |
codegraph_search | 按名称搜索符号 |
codegraph_callers | 查看谁调用了某符号 |
codegraph_callees | 查看某符号调用了谁 |
codegraph_impact | 修改某符号影响范围分析 |
codegraph_files | 文件结构浏览 |
4.3 实际效果对比
五、性能数据
基于 CodeGraph 官方在 7 个不同语言和规模的开源项目上的基准测试：
| 指标 | 改善幅度 |
|---|---|
| 工具调用次数 | ↓ 88% |
| 探索速度 | ↑ 53% |
| Token 消耗 | ↓ 62% |
| 总成本 | ↓ 44% |
项目越大（几百到几千文件），收益越明显。极小项目（< 50 文件）优势不大。
六、适合与不适合的场景
| 适合 | 为什么 |
|---|---|
| 大型代码库（> 200 文件） | grep/glob/Read 链的 Token 开销无法接受 |
| 频繁跨文件分析 | 调用链追踪、影响分析、重构前摸底 |
| 新人上手陌生项目 | 快速理解模块依赖和调用关系 |
| 框架项目（Web 路由、DI） | CodeGraph 的框架感知路由能理解 17 种框架模式 |
| 跨语言项目（iOS/RN） | 支持 Swift↔ObjC、JS→Native 桥接 |
| 不适合 | 为什么 |
|---|---|
| 极小项目（< 50 文件） | 图谱构建的成本超过用它省下的 Token |
| 频繁变动的 Monorepo | 增量同步仍有开销，且 Agent 自己在小范围内探索效率不差 |
| 运行时行为分析 | CodeGraph 是静态分析，不覆盖动态反射、DI 注入等 |
| 已有完善的 CLAUDE.md | 如果 CLAUDE.md 已经把关键符号关系写清楚了，不需要图谱 |
七、与 CLAUDE.md 的关系
很多人会问：既然有 CLAUDE.md，还需要 CodeGraph 吗？
| CLAUDE.md | CodeGraph |
|---|---|
| 人工写的"项目摘要" | 机器自动构建的"符号地图" |
| 适合 宏观信息（架构、约定、常用命令） | 适合 微观信息（谁调谁、继承链、import 链路） |
| 静态文档，容易过时 | 文件监听 300ms 后自动增量同步 |
| Claude Code 每次对话都读取 | Claude Code 按需查询（通过 MCP 工具） |
| 维护成本高（要人写、要人更新） | 零维护（自动同步） |
最佳实践：两者配合使用。
一句话：CLAUDE.md 画地图的图例**，CodeGraph 画地图的街道和交叉口。
八、常用命令速查
bash
# 安装与注册
codegraph install # 自动检测 AI 工具并配置 MCP
codegraph install --yes # 跳过交互确认
# 图谱管理
codegraph init -i # 在项目中构建图谱（交互式）
codegraph init --auto # 静默构建
codegraph status # 查看图谱状态（符号数、后端）
codegraph reset # 重置图谱，重新构建
# 手动查询（不通过 MCP，直接在终端用）
codegraph explore "createOrder" # 探索符号
codegraph search "order" # 搜索符号
codegraph callers "createOrder" # 查看调用者
codegraph callees "createOrder" # 查看被调者
codegraph impact "createOrder" # 影响分析
# 手动启动 MCP 服务
codegraph serve --mcp
# 环境变量
export CODEGRAPH_MCP_TOOLS="explore,node,search,callers,callees,impact"九、框架感知与跨语言桥接
CodeGraph 的两个独特能力：
9.1 框架感知路由
能理解 17 种 Web 框架的路由定义，把 URL 路径 → Handler 函数的关系编入图谱：
| 语言 | 框架 |
|---|---|
| Python | Django, Flask, FastAPI |
| Node.js | Express, NestJS |
| Go | Gin, Chi, Gorilla Mux |
| Rust | Axum, Actix, Rocket |
| PHP | Laravel, Drupal |
| Ruby | Rails |
| Java/Kotlin | Spring, Play |
9.2 跨语言桥接（iOS / React Native / Expo）
对于混合语言项目，CodeGraph 能连接跨语言调用链：
- Swift ↔ Objective-C 自动桥接
- React Native 旧桥接 / TurboModules
- Fabric / Paper 视图组件
- Expo Modules
- JS → Native 事件通道
生成的边带有 provenance: 'heuristic' 标记，表示这是推断边而非确定性解析。
十、故障排除
| 问题 | 方案 |
|---|---|
Backend 显示 wasm 而非 native | 安装 Node.js 原生依赖：npm rebuild 或重新全局安装 |
| 图谱符号数为 0 | 确认在项目根目录执行 codegraph init，且语言在支持列表中 |
| Claude Code 没调用 CodeGraph | codegraph status 确认图谱已构建 → 重启 Claude Code → 检查 MCP 配置 |
| 同步不及时 | 手动 codegraph init 重建，或等文件监听触发（~300ms 延迟） |
| Token 没明显减少 | 检查：项目太小？CLAUDE.md 太完善？Agent 没触发探索子代理？ |
十一、文件清单
项目目录/
├── .codegraph/ # CodeGraph 图谱数据（建议 .gitignore）
│ ├── codegraph.db # SQLite 主库（FTS5 + 符号 + 边）
│ ├── codegraph.db-shm # SQLite 共享内存
│ └── codegraph.db-wal # SQLite WAL 日志
└── .gitignore # 建议添加 .codegraph/MCP 配置位置（codegraph install 自动写入）：
Claude Code: ~/.claude/mcp.json 或 .claude/mcp.json
Cursor: ~/.cursor/mcp.json
Codex: ~/.codex/mcp.json一句话总结
CodeGraph 的本质是给 AI Agent 一张预制的城市地图——不用每次走路都靠眼睛找路标（grep/glob/Read），而是直接查地图（codegraph_explore）就知道每条街道通向哪里。
延伸阅读
- AI 编程工具总纲 —— 工具选型、四级演化、场景矩阵
- Claude Code 完整教程 —— 安装、命令、MCP、Agent/Skill 一站式手册
- Agent 与 Skill 深度解析 —— 概念辨析、决策树、协同模式