AI 助手理解代码库,从 grep 到图谱——CodeGraph 实战

你让 AI 助手理解一个陌生代码库，它第一件事是什么？搜关键词、找文件、逐个打开，像在黑暗中摸索。一个中等规模的项目，光"找到正确的文件"就要消耗十几轮工具调用。

CodeGraph 换了个思路：在本地把代码库解析成知识图谱存进 SQLite，AI 助手查一次就能拿到相关符号、调用路径和影响范围。官方在 7 个开源项目上的基准测试显示，工具调用减少 88%，Token 消耗减少 62%。

这篇文章记录我把 CodeGraph 接入运维告警分诊 Agent Demo（Go 后端 + React 前端）的完整过程：从安装索引、CLI 速览，到在 Claude Code 里通过 MCP 做 vibe coding 的实际效果。

一、为什么需要代码知识图谱

当前主流 AI 编程助手（Claude Code、Cursor、Codex 等）理解陌生代码的方式是"搜索-阅读-重建"循环：grep 搜关键词、glob 找文件、Read 逐个打开，然后在脑子里拼接调用关系。代码库一大，这套流程就很慢。更麻烦的是，grep 只能搜到字面匹配的符号名，动态分派、回调函数、React 组件的 props 传递全都跟踪不了。

CodeGraph 的解法

CodeGraph 用 tree-sitter 在本地解析代码，把每个符号（函数、类、方法、路由、组件）和它们之间的关系（调用、导入、继承、引用）提取出来，存成一个知识图谱。

AI 助手不再需要逐个打开文件去推断关系，图谱已经把这些连接建好了。

所有数据都在本地，隐私和安全没有顾虑。

二、架构拆解

CodeGraph 的架构可以用一句话概括：tree-sitter 解析代码 → SQLite 存储图谱 → MCP 暴露给 AI 代理 → 文件监听做增量同步。全部在本地完成，不调外部 API，不传代码到云端。

几个关键点：

• Rust 内核做重活：20 种语言的解析逻辑编译进 Rust 内核，遇到语法错误的文件自动回退到 WASM 版本。
• SQLite + FTS5 存储：整个图谱就是 .codegraph/ 目录下的一个 SQLite 文件，FTS5 提供符号名全文搜索。
• OS 原生事件做增量同步：macOS FSEvents / Linux inotify / Windows ReadDirectoryChangesW，300ms 防抖触发增量更新。代码改完，AI 助手查到的图谱就是最新的。

MCP 接口：一个主工具搞定大部分场景

CodeGraph 对外暴露的核心工具是 codegraph_explore。给它一个问题或一组符号名，它返回相关源码（带行号）、调用路径（包括动态分派跳转）、以及影响半径摘要。

为什么只暴露一个工具？官方的测量发现：一个精准的工具比一组细分工具效果更好，AI 助手不容易选错。所有信息都在一次调用中返回，避免了在多个工具之间来回试探。

除了 explore，底层还有 7 个细粒度工具（node/search/callers/callees/impact/files/status），默认不暴露，可通过 CODEGRAPH_MCP_TOOLS 环境变量按需启用。这些工具和后面的 CLI 命令一一对应，只是调用入口不同。一个小细节：文件数少于 500 的仓库会自动多开 search 和 node，因为小项目里只给一个 explore 反而导致成本上升。

相比项目 README / Markdown 文档

项目里写一份 README 或架构文档是标准做法。但作为 AI 助手的上下文来源，Markdown 有两个硬伤：写完就开始过时（代码改了文档没人同步），以及无法回答影响范围问题（"改这个函数影响谁"只能 grep 碰运气）。CodeGraph 自动同步 + 符号级影响分析，直接解决这两点。

CodeGraph 替代的是"给 AI 助手提供代码上下文"这个场景下的 Markdown 文档。面向人类阅读的架构设计文档、决策记录，仍然有存在价值。

三、实战：在运维 Agent Demo 上接入 CodeGraph

实战项目

用之前 Grafana AI SDK 文章里构建的运维告警分诊 Agent Demo 作为实战对象（读者可以按那篇文章的步骤搭一个同构项目）。项目结构：

incident-triage-assistant/├── main.go              # Go 后端 (317 行)├── go.mod / go.sum      # Go 依赖├── .env.example         # 环境变量模板├── README.md            # 项目说明└── web/                 # React 前端    ├── package.json    ├── vite.config.ts    └── src/        ├── App.tsx              # 主组件 (241 行)        ├── main.tsx             # 入口        ├── MarkdownRenderer.tsx # Markdown 渲染        └── markdown.css         # Markdown 样式

Go 后端用 Grafana AI SDK 构建了一个 ToolLoopAgent，配了两个运维工具：get_service_status（查服务健康状态）和 query_logs（搜服务日志）。React 前端用 Vercel AI SDK 的 useChat Hook 通过 SSE 对接后端。项目同时包含 Go 和 TypeScript 两种语言，正好检验 CodeGraph 的跨语言能力。

安装与索引

CodeGraph 当前版本 v1.5.0，三步走：

# 1. 全局安装npm i -g @colbymchenry/codegraph# 2. 在项目里初始化索引cd incident-triage-assistantcodegraph init# 3. 查看索引状态codegraph status

实际跑了一遍：

Indexed 5 files49 nodes, 65 edges in 2.8s

codegraph status 看详细信息：

Index Statistics:  Files:     5  Nodes:     49  Edges:     65  DB Size:   0.23 MBNodes by Kind:  import          26  function         8  struct           6  file             5  constant         2  route            2Files by Language:  tsx              3  go               1  typescript       1

几个数据点：SQLite 数据库 0.23MB（.codegraph/ 目录含 WAL 和临时文件，总占 292KB）；tree-sitter 正确识别了 2 条 HTTP 路由（POST /api/chat 和 POST /api/triage）；26 个 import 节点说明跨文件引用关系都被提取了。

增量同步的速度也验证了。往 main.go 末尾加一行注释，跑 codegraph sync：

Modified: 1 — 28 nodes in 274ms

274ms 重新解析了一个 317 行的 Go 文件。文件保存后不用手动 sync，CodeGraph 的 daemon 会自动监听变更触发同步。

命令行查询

CodeGraph 的 CLI 子命令和 MCP 工具一一对应，适合需要手动验证或脚本集成的场景：

codegraph explore "<问题>"# 自然语言查询，最常用codegraph node <符号名>             # 查单个符号的源码 + 调用关系codegraph impact <符号名>           # 改动影响分析codegraph callers/callees <符号名>  # 查调用者/被调用者codegraph serve --mcp               # 启动 MCP 服务器模式

一个 grep 做不到的能力值得提一下：动态分派追踪。App.tsx 里通过 <MarkdownRenderer /> 渲染组件，grep 搜 MarkdownRenderer 只能找到 import 语句，搜不到 JSX 里的实际使用。CodeGraph 的 tree-sitter 从语法树里提取出了这条动态引用边，还能告诉你改这个组件会影响 App.tsx 中的 2 处调用。

不过日常开发中，更自然的方式是让 AI 代理通过 MCP 自动调用这些能力。下一节用 Claude Code 演示。

Agent 集成 MCP

以 Claude Code 为例，演示通过 MCP 在对话中直接调用 CodeGraph 的两个高频场景：改代码（影响分析）和读代码（理解陌生代码库）。

配置

有两种方式：

方式一：在项目根目录创建 .mcp.json（推荐，跟随项目走）：

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

方式二：跑 codegraph install，交互式选择要配置的 AI 代理（自动检测已安装的 Claude Code / Cursor / Codex / Gemini CLI 等）。这个命令做的事情和手动写 .mcp.json 一样，只是帮你自动写入。

Cursor 用户注意：Cursor 的 MCP 配置文件路径是 .cursor/mcp.json，格式和上面一样。codegraph install 会自动识别。

前置条件：在启动 AI 代理之前，确保项目已经跑过 codegraph init 建好索引。CodeGraph MCP 服务器启动后读的是 .codegraph/ 里的图谱数据，没有索引文件就没有内容可查。

验证连接

配好 .mcp.json 后重新启动 Claude Code，在会话里输入 /mcp 查看 MCP 服务器连接状态。看到 codegraph 显示 connected 就说明接通了。也可以跑 claude mcp list 查看已配置的 MCP 服务器。

实测：影响分析

对 Claude Code 说一个日常开发会问的问题（不需要提 CodeGraph，正常对话就行）：

我要给 QueryLogsInput 加一个 timeRange 字段，会影响哪些代码？

Claude Code 自动调用 codegraph_explore，返回结果：

Affected Symbols:1. QueryLogsInput (main.go:73)  — 直接修改，加字段2. queryLogs (main.go:88)       — 接收 QueryLogsInput，需要用新字段做过滤3. newAgent (main.go:121)       — 通过 TypedTool 泛型注册，JSON schema 自动更新No tests cover any of these symbols.

最后一句"No tests cover any of these symbols"是 CodeGraph 提供的测试覆盖信息。grep 搜不出这个，因为测试覆盖关系不是字面字符串匹配能发现的。

实测：理解陌生代码库

换一个场景：新人刚 clone 了项目，想快速搞懂后端的 Agent 是怎么工作的。同样不需要提 CodeGraph：

这个项目的后端 Agent 是怎么处理告警分诊的？从请求进来到结果返回，走一遍流程。

Claude Code 调用 codegraph_explore，直接拿到了完整的调用链路：

Request flow: POST /api/chat → newAgent() → ToolLoopAgent.Run()  → get_service_status (查服务健康)  → query_logs (搜日志)  → 模型推理生成分诊结论Key symbols:  main.go:274  main()           — 注册路由，启动 HTTP server  main.go:121  newAgent()       — 构建 Agent，注册两个工具  main.go:39   getServiceStatus — 调 Grafana API 查服务状态  main.go:88   queryLogs        — 调 Loki API 搜日志

一次调用拿到入口到出口的完整链路。如果靠 grep，得先搜 HandleFunc 或 mux.Handle 找路由入口，再 Read main.go 翻到处理函数，再从处理函数搜调用的下游函数，至少 4-5 轮工具调用才能拼出同样的链路。

好了，经过 Demo演示，想必大家对 CodeGraph 的作用和用法已经有所了解，如果你的项目已经大到 AI 助手找代码开始拖慢响应，它值得一试。