让 AI 编程助手停止瞎翻文件

一、先说痛点：你的 AI 助手每天都在做无用功

用过 Claude Code、Cursor、Codex 这类 AI 编程工具的人都见过这个场景：

你问它"登录逻辑在哪个文件"，它开始表演——grep 一把、glob 一把、再 Read 五六个文件，翻完才回答。一个简单问题，几十次工具调用，几万 token 烧掉，最后还可能漏掉跨文件的调用关系。

问题出在哪？AI 助手理解代码靠"翻"，而不是靠"查"。

CodeGraph 要解决的就是这件事：先把整个代码库解析成一张知识图谱存到本地，之后 AI 助手直接查图，一次调用拿到答案。

官方在 7 个真实开源项目（VS Code、Django、Tokio、OkHttp 等）上做的基准测试显示：使用 CodeGraph 后，AI 工具调用次数平均减少 88%，耗时减少 53%，token 消耗减少 62%，成本降低 44%。

二、CodeGraph 是什么

CodeGraph 是一个开源（MIT 协议）的本地代码知识图谱工具，工作原理一句话讲完：

用 tree-sitter 解析代码 AST，把函数、类、调用关系、导入关系、路由全部抽出来，存进项目目录下的本地 SQLite 数据库，再通过 MCP 协议暴露给 AI 编程助手查询。

三个关键特性：

1. 100% 本地运行。 图谱就在项目根目录的 .codegraph/ 文件夹里，没有 API Key，不上传代码，对公司项目和隐私敏感场景友好。

2. 自动保持新鲜。 通过操作系统原生文件监听，保存文件后约 300 毫秒内增量更新图谱，不用手动重建。

3. 支持 34 种语言。 TypeScript、JavaScript、Python、Go、Java、PHP、C#、Rust、Vue、Svelte 等主流语言全覆盖，其中 20 种由 Rust 原生内核解析，速度是早期 WASM 方案的 3 倍以上。

三、安装：三条命令的事

Windows（PowerShell）：

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

macOS / Linux：

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

已有 Node.js 的话也可以用 npm：

npm i -g @colbymchenry/codegraph

安装器自带运行时，不需要预先装 Node。装完记得开一个新终端再执行后续命令。

一个小提醒：如果你之前用 npm 装过旧版，安装器会警告 PATH 上存在另一个副本。用 where.exe codegraph 查一下，两个版本一致可以不管，不一致建议卸掉 npm 那份（npm rm -g @colbymchenry/codegraph），避免以后升级时改的和跑的不是同一个。

四、上手三步走

# 第 1 步：把 CodeGraph 接入你的 AI 工具
# 自动检测本机已装的 Claude Code / Cursor / Codex / Gemini CLI 等并写入 MCP 配置
codegraph install --yes

# 第 2 步：进项目目录建索引（每个项目执行一次，路径换成你自己的）
cd D:\projects\your-project
codegraph init

# 第 3 步：没有了，日常写代码即可，图谱自动同步

init 之后用 codegraph status 可以看到索引规模，输出大致长这样：

Files: 300+    Nodes: 7,000+    Edges: 20,000+    DB Size: ~30 MB
Nodes by Kind: function / method / class / route / import ...

一个中型项目通常是数百个文件、数千个符号、上万条关系边，索引只需要几秒到几十秒。它会自动识别框架路由，自动遵守 .gitignore，并且自动把 .codegraph/ 加进 .gitignore，不会污染你的 git 仓库。

五、日常查询命令速查

以下是各命令的典型输出示例。

| 命令 | 作用 |
|---|---|
| codegraph status | 查看索引状态和统计 |
| codegraph query <名字> | 全文搜索符号，秒回定位到文件和行号 |
| codegraph callers <符号> | 谁调用了它 |
| codegraph callees <符号> | 它调用了谁 |
| codegraph impact <符号> | 改动它会影响哪些符号和文件 |
| codegraph explore <词> | 一次拿全：相关源码原文 + 调用路径 + 影响半径 |
| codegraph node <符号> | 单个符号的源码 + 调用链 |
| codegraph context <任务描述> | 按自然语言任务自动组装代码上下文 |
| codegraph files | 从索引输出项目文件结构树 |
| codegraph affected <文件> | 找出改动波及的测试文件（适合 CI） |
| codegraph sync / index | 手动增量同步 / 全量重建 |
| codegraph uninit | 删除当前项目的图谱 |

几个实用的例子。

重构前先看影响面——想知道改 refreshSession 会炸到谁：

$ codegraph impact refreshSession

Impact of changing "refreshSession" — 4 affected symbols:

src/handler.js
  function  handleLogin:3
  function  handleLogout:10

追调用链：

$ codegraph node useAuth

**Trail**
Calls →   verifyToken (src/auth.js:8)
Called by ← handleLogin (src/handler.js:3)

一句话拿上下文：codegraph explore handleLogin 直接返回带行号的完整源码原文，输出里明确写着"这是磁盘上的逐字节原文，不是摘要"——对 AI 和人来说都省了一轮 Read。

六、在 AI 工具里怎么用

codegraph install 做了两件事：写入各 AI 工具的 MCP server 配置，同时往 CLAUDE.md、AGENTS.md 等指令文件里插入一段使用指引。

之后在 Cursor 或 Claude Code 里直接用人话提问：

• "handleLogin 的完整调用链是什么？"
• "改这个函数签名会影响哪些文件？"
• "这个项目登录功能涉及哪些模块？"

助手会自动调用 codegraph_explore 这个 MCP 工具查图谱，通常 1 到 4 次调用就能给出结构化答案，而不是 grep 半天。

七、两个进阶玩法

1. 接入 CI 流水线。 codegraph affected src/auth.js --json 可以输出受改动影响的测试文件列表，让流水线只跑该跑的测试。

2. Claude Code 提示钩子。 CodeGraph 内置了 UserPromptSubmit 钩子支持（codegraph prompt-hook），配置后每次向 Claude 提问都会自动注入相关的图谱上下文，结构类问题不用再手动触发。

八、使用建议与避坑

适合用的场景： 大型代码库、monorepo、接手别人的老项目、频繁让 AI 做跨模块改动。项目小到 ls 一屏看完的，收益不大，别为了装而装。

三个坑：

1. 图谱会过期。 大重构之后重跑 codegraph index 重建，图谱是导航仪不是真理，源码和编译器说了算。
2. 上下文残留更高。 官方承认它返回密集的源码原文，长会话结束时上下文里残留的检索内容比普通模式多约 80%，小窗口模型要留意。
3. 重复安装会打架。 npm 版和独立安装版并存时，实际运行的是 PATH 靠前的那份，升级前先 where.exe codegraph 确认。

写在最后

CodeGraph 的本质，是给 AI 编程助手发了一张代码地图。以前它靠翻箱倒柜重建对项目的理解，现在直接查图。

工具是本地开源的，安装一分钟，索引几秒钟，不满意 codegraph uninit 一秒还原。如果你每天都在让 AI 助手在大项目里找代码，值得一试。

---

*项目地址：github.com/colbymchenry/codegraph*
*适用版本：CodeGraph v1.6.2 · 文中路径、项目信息与输出数字均为示例*