AI 代码知识图谱 教程（一）| Codegraph（纯代码）

AI 代码知识图谱 教程（一）| Codegraph（纯代码）

• 一、你的日常痛点
• [二、纯代码场景为什么不需要 LLM](#二、纯代码场景为什么不需要 LLM)
• [三、Codegraph 是什么](#三、Codegraph 是什么)
• • 核心数据
  • 支持能力
• [四、Codegraph 实战教学](#四、Codegraph 实战教学)
• • [4.1 安装](#4.1 安装)
  • [4.2 注册到 AI 工具](#4.2 注册到 AI 工具)
  • [4.3 建索引](#4.3 建索引)
  • [4.4 MCP 工具速查](#4.4 MCP 工具速查)
  • [4.5 日常使用](#4.5 日常使用)
  • [4.6 卸载](#4.6 卸载)
  • [4.7 注意事项](#4.7 注意事项)
• 五、日常三个最高频场景
• • [场景 1：追踪调用链](#场景 1：追踪调用链)
  • [场景 2：改前影响分析](#场景 2：改前影响分析)
  • [场景 3：Code Review 查关键路径](#场景 3：Code Review 查关键路径)
• 六、其他值得关注的工具
• • GitNexus
  • Probe
  • Sense（luuuc/sense）
• 七、避坑清单
• [八、能不能和 Graphify 一起装？](#八、能不能和 Graphify 一起装？)
• 九、总结

本文是「AI 图谱系列」专栏一。如果你的项目没有架构文档、全是代码，这篇文章是写给你的。

---

一、你的日常痛点

• 接了一个旧项目，Controller → Service → Mapper 的调用链完全看不懂
• AI 每次回答一个问题翻了 50 个文件，token 烧得心疼
• 改一行代码，不知道会影响哪些模块，不敢改

纯代码项目的核心需求就三个：精准、实时、零成本。

---

二、纯代码场景为什么不需要 LLM

你的项目没有文档，架构设计全在代码里。这种情况下：

需求	Codegraph（编译器派）	Graphify（LLM 派）
追踪调用链	✅ 精准，AST 直接解析	✅ 能做，但没必要
零成本	✅ 永远免费	❌ 首建烧 token
实时同步	✅ 原生 OS 文件监听	⚠️ 依赖 Git hook
从不出错	✅ AST 确定性解析	❌ INFERRED 边可能不准确
理解"为什么这么设计"	❌ 不需要	✅ 但你没有文档给它读

结论：纯代码项目用 Graphify，就像给自行车装导航------功能是对的，但你根本用不上。

---

三、Codegraph 是什么

Codegraph 是编译器派知识图谱的代表，用 tree-sitter AST 像编译器一样解析代码结构。

核心数据

指标	数据（7 个真实项目实测）
成本降低	35%
Token 减少	59%
工具调用减少	70%
速度提升	49%

测试项目：VS Code（~10K 文件）、Django（~2.7K）、Excalidraw、Tokio、OkHttp、Gin、Alamofire。

支持能力

• 19+ 语言：Java、Python、Go、TypeScript、Rust、Kotlin、Swift 等
• 14 种 Web 框架路由识别 ：自动映射 URL → Handler（如 @GetMapping("/user") → UserController.getUser）
• 10 个 MCP 工具：覆盖搜索、调用链、影响分析、路径追踪、代码探索等

---

四、Codegraph 实战教学

开始之前先确认：你的项目超过 200 个文件吗？没超过就别往下看了，建图开销大于收益。

4.1 安装

方式一：一键安装（推荐，免配置环境）

# 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

一键脚本自动下载对应平台的二进制文件，无需手动安装 Node.js。

方式二：npm 安装（需 Node.js）

npx @colbymchenry/codegraph        # 零安装直接运行
npm i -g @colbymchenry/codegraph   # 全局安装

安装后验证：

codegraph --version

4.2 注册到 AI 工具

自动注册（推荐）：

codegraph install --yes

安装器会自动检测已安装的 AI 工具（Claude Code / Cursor / Codex / OpenCode 等），写入 MCP 配置，生成 CLAUDE.md 指令，一 条命令搞定。

指定平台注册：

codegraph install --target=cursor,claude --yes

非交互式（CI/CD 用）：

codegraph install --yes --location=local   # 项目本地配置
codegraph install --print-config claude     # 仅打印配置片段

手动注册（Claude Code）：

在 ~/.claude.json 中添加：

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

并在 ~/.claude/settings.json 添加权限：

{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_context",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_explore",
      "mcp__codegraph__codegraph_trace",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

重启 Claude Code 生效。

4.3 建索引

cd your-project
codegraph init -i        # 构建知识图谱索引

• 首次索引几分钟（视项目大小），产物落在 .codegraph/ 目录
• 之后文件变更会被 OS 原生文件监听（FSEvents / inotify）自动捕获并增量同步，零配置
• 也可手动触发增量：codegraph sync

4.4 MCP 工具速查

CodeGraph 通过 MCP 暴露 10 个工具，AI 直接调用：

重型工具（Explore 子代理使用，不建议主会话直接调用）：

工具	用途
codegraph_context	一次性返回任务相关的入口点 + 上下文（search + node + callers + callees）
codegraph_trace	追踪"X 是怎么调到 Y 的"，每跳函数体内联，跨动态分发
codegraph_explore	一次返回若干相关符号的完整源码 + 关系图（探索子代理主入口）

轻型工具（主会话可直接使用）：

工具	用途
codegraph_search	按符号名搜索代码库
codegraph_callers	查询谁调用了指定函数
codegraph_callees	查询指定函数调用了谁
codegraph_impact	分析修改某个符号的影响范围
codegraph_node	获取符号详情（含源码）
codegraph_files	查看索引的文件结构
codegraph_status	查看索引健康状态

4.5 日常使用

配好之后，大多数时候不需要手动敲命令------直接在对话里问，AI 自动调 MCP 工具查图。

手动查询举例：

codegraph query getUserById           # 搜索符号
codegraph context "添加用户权限校验"    # 为任务构建上下文
codegraph status                      # 查看索引状态
codegraph files                       # 查看文件结构

手动同步：

codegraph sync    # 代码改了但监听没触发时，手动增量同步

4.6 卸载

codegraph uninstall    # 从所有 AI 工具中移除 CodeGraph
codegraph uninit       # 删除当前项目的 .codegraph/ 索引
npm rm -g @colbymchenry/codegraph   # 卸载软件包

4.7 注意事项

• .codegraph/ 建议加入 .gitignore，不要提交到仓库
• 项目文件变更后图谱自动同步（OS 原生监听，增量同步），无需手动操作
• 支持 19+ 语言，14 种 Web 框架路由自动识别（Spring MVC、Express、Django 等）

---

五、日常三个最高频场景

场景 1：追踪调用链

你问：「getArticleById 被哪些 Controller 调用了？」

无 Codegraph：AI grep "getArticleById" → 返回 30 个文件 → 逐个 Read
有 Codegraph：AI 调 codegraph_callers → 直接返回调用者列表

场景 2：改前影响分析

你问：「我改了 UserService.updateUser，会影响哪些模块？」

无 Codegraph：手动全局搜索，靠人脑推断
有 Codegraph：AI 调 codegraph_impact → 列出所有直接和间接调用者

场景 3：Code Review 查关键路径

你看 PR 时发现改了一个底层工具方法。

无 Codegraph：不确定影响面，保守 Approve 或盲目担心
有 Codegraph：codegraph_impact 告诉你这个方法被 47 个地方调用，重点检查其中 3 个核心路径

---

六、其他值得关注的工具

GitNexus

架构先进（图数据库 + 社区检测），但 PolyForm NC 禁止商用，且有 28 个开放 bug（含 OOM）。不适合生产环境。

Probe

零索引即用（不需要预建图，实时解析），适合一次性代码分析。但不适合日常持续使用------因为没有预建索引，每次查询都需要重新解析代码。

Sense（luuuc/sense）

2026 年新项目，Go 编写，轻量。作者自测 benchmark 数据不错，但目前社区很小，生态远不如 Codegraph 成熟。感兴趣可以关注，但不建议作为主力工具。

---

七、避坑清单

坑	后果	解法
AST 抓不到反射/动态代理	运行时动态调用的方法链缺失	运行时行为用日志/测试补充
小项目硬上	建索引的时间 > 省下的 token	<200 文件别用
首次索引慢	大项目等几分钟	正常现象，之后增量更新很快
改了代码没自动同步	图谱过时	确认文件监听或手动 codegraph sync

---

八、能不能和 Graphify 一起装？

可以，推荐。

日常：Codegraph → 调用链追踪、影响分析、Code Review（零成本、实时）
阶段：Graphify → 架构审计、文档关联（烧 token 但深度更深）

两个工具各自独立目录，互不冲突。绝大多数时候 Codegraph 够了，偶尔想深入理解时再跑一次 Graphify。

---

九、总结

你的情况	选什么
纯代码项目（没文档）	Codegraph
有架构文档/ADR	看 专栏二：文档篇
做新人入职引导	看 专栏三：可视化篇

一句话：Codegraph 是查户口本的------精准、冰冷、从不出错。你的项目不需要"理解"，你只需要知道谁调了谁。