【Vibe Coding】CodeGraph 使用文档

CodeGraph 使用文档

CodeGraph 是一个为 AI 编程助手构建的语义代码知识图谱工具。它通过预先索引代码结构，让 AI 助手能够"理解"代码，而不是靠 grep 和逐文件阅读来猜测。在 7 个真实开源项目上的基准测试中，使用 CodeGraph 平均减少了 58%--71% 的工具调用 和 47%--57% 的令牌消耗。

一、快速开始

1. 安装 CLI

macOS / Linux：

bash 复制代码

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

Windows (PowerShell)：

powershell 复制代码

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

如果你已有 Node.js 环境，也可以用 npm 安装：

bash 复制代码

npm i -g @colbymchenry/codegraph

安装完成后，打开一个新终端 让 codegraph 命令生效。

2. 连接 AI 助手

bash 复制代码

codegraph install

这个命令会自动检测并配置你本地的 AI 编程助手，包括 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro 等，将 CodeGraph 的 MCP 服务器接入其中。

注意：这一步只是连接助手，还没有索引任何代码------索引是下一步的事。

3. 初始化项目

进入你的项目目录：

bash 复制代码

cd your-project
codegraph init -i

-i 参数表示在创建 .codegraph/ 目录的同时构建完整的代码图谱索引。如果省略 -i，可以稍后单独运行 codegraph index 来构建。

4. 自动同步

CodeGraph 默认开启了自动同步，它会通过操作系统原生文件事件（FSEvents/inotify/ReadDirectoryChangesW）监听项目变化，在每次文件修改后增量更新索引。索引永不陈旧，无需手动重新运行。

二、工作原理

当 AI 助手需要理解代码时，通常的做法是反复调用 grep、glob、Read 来搜索和阅读文件，这会消耗大量令牌和时间。

CodeGraph 预先用 tree-sitter 解析源代码，提取所有符号（函数、类、方法等）和它们之间的关系（调用、导入、继承、实现），存入本地的 SQLite 数据库 （.codegraph/codegraph.db），并支持 FTS5 全文搜索。AI 助手通过 MCP 协议直接查询这个图谱，一次调用就能获得精确的上下文。

复制代码

AI 助手提问 → CodeGraph MCP 服务器 → SQLite 知识图谱 → 返回精确上下文

三、核心工具

CodeGraph 提供了多组 MCP 工具，按使用场景分类如下：

场景一：搜索与定位

工具	用途	示例问题
`codegraph_search`	按名称查找符号	"找到 `UserService` 类在哪里定义"
`codegraph_explore`	一次调用获取多个相关符号的源码	"看看认证模块的几个关键函数"

场景二：理解关系与影响

工具	用途	示例问题
`codegraph_callers`	找出谁调用了某个函数/方法	"谁会调用 `validateToken()`？"
`codegraph_callees`	找出某个函数调用了谁	"`handleRequest()` 内部调用了哪些函数？"
`codegraph_impact`	变更影响范围分析（"爆炸半径"）	"如果我修改 `parseConfig()`，会影响哪些地方？"

场景三：上下文构建

工具	用途	示例问题
`codegraph_context`	一次性获取函数源码、依赖、调用者和测试	"给我修改 `buildGraph` 需要的全部上下文"
`codegraph_trace`	追踪从 A 到 B 的完整调用路径	"从 HTTP 请求到数据库的调用链是怎样的？"

场景四：高层分析

工具	用途	示例问题
`agentic_architecture_analysis`	分析整体架构和组件关系	"这个项目的整体架构是怎样的？"
`agentic_dependency_analysis`	依赖关系图谱与耦合度分析	"支付模块依赖哪些东西？"
`agentic_semantic_question`	跨多个区域的复杂语义问题	"错误处理在整个应用各层是如何工作的？"

工具命名在不同版本中可能略有差异，核心能力是一致的。

四、工作流模式

模式一：上手新项目

架构概览 ：让 AI 用 agentic_architecture_analysis 解释项目结构
找入口点 ：用 codegraph_search 找到关键入口函数
追踪流程 ：用 codegraph_trace 理解核心业务流程

模式二：重构前检查

影响分析 ：codegraph_impact 查看修改波及范围
依赖映射 ：codegraph_callers 确认所有调用方
上下文收集 ：codegraph_context 汇总全部相关信息

模式三：实现新功能

找模式：搜索类似功能的实现方式
收集上下文 ：codegraph_context 获取相关代码模式
检查集成点：确认新功能应该接入哪些现有接口

五、语言支持

CodeGraph 支持 20+ 种语言，全部使用相同的结构化提取和跨文件解析逻辑，无需针对每种语言单独配置：

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Objective-C、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal/Delphi 等。

此外还支持识别 14 种 Web 框架的路由定义，能将 URL 模式直接链接到对应的处理函数。

六、卸载

bash 复制代码

codegraph uninstall

这会从所有已配置的 AI 助手中移除 CodeGraph 的 MCP 服务器配置。项目中的 .codegraph/ 索引目录不会被自动删除------如需删除，请在项目目录下手动执行 codegraph uninit。

七、常见问题

问：AI 助手不主动使用 CodeGraph，还在手动 grep 怎么办？

明确指示它："请使用 codegraph 的 codegraph_search 工具，而不是逐文件 grep 阅读。"

问：改了代码但 CodeGraph 没更新？

CodeGraph 默认自动同步，如果感觉索引陈旧，可以确认是否启动了带 --watch 的模式，或手动运行 codegraph index -r 重建。