CodeGraph:让 AI 编程助手告别“大海捞针”

🤔 痛点：AI 助手看代码像“盲人摸象”

想象一下：你让一个助手去陌生的大仓库找一个零件。没有地图，没有目录，只能：

翻遍每个箱子 → 打开看看 → 不是这个 → 继续翻...

AI 编程助手（Claude Code、Cursor 等）探索代码库就是这样：

• grep 搜字符串 → 找到一堆文件
• find 找文件名 → 再搜
• Read 打开看 → 不对，继续搜
• 来回折腾 50 次工具调用，消耗一堆 token，可能才找到关键代码

结果：大部分 token 花在“找路”上，真正分析代码的精力反而不多。

💡 解决方案：提前画一张“代码地图”

CodeGraph 实现思路——先把整个代码库解析成一张地图：

┌─────────────────────────────────────────────────────────┐│                    你的代码库                            ││                                                         ││   getUser() ←─── 调用 ────→  login()                   ││       ↓                         ↓                       ││   返回 User  ←─── 依赖 ────→  Database.query()          ││                                                         │└─────────────────────────────────────────────────────────┘                           ↓               tree-sitter 解析 + SQLite 存储                           ↓┌─────────────────────────────────────────────────────────┐│                  CodeGraph 知识图谱                     ││  • 谁是调用者？谁被调用？                                ││  • 改这个函数会影响谁？                                  ││  • 路由 /api/login 对应哪个控制器？                      │└─────────────────────────────────────────────────────────┘

AI 助手不再是“翻箱子”，而是在图上精确导航：

问：“这个函数被谁调用了？”答：codegraph_callers → 3 个调用者，都在这里

📊 效果有多好？

官方在 7 个真实项目上测试（VS Code、Django、Tokio 等），平均：

一个具体例子：Alamofire（Swift 网络库）

问题：「从 Session.request() 到网络请求，数据怎么流下去的？」

代理从“翻十几个文件拼线索”变成“在图上游走 3 步就抓到完整的 9 步调用链”。

极限测试：Swift 编译器

• 25,874 个文件、272,898 个符号节点
• 索引时间：不到 4 分钟
• 之后回答跨模块诊断问题：6 次 explore、35 秒、零文件读取

🚀 5 分钟上手

1️⃣ 安装（30 秒）

npx @colbymchenry/codegraph

交互式安装程序会自动检测你电脑上的 AI 工具（Claude Code / Cursor / Codex），并配置好 MCP 服务器。

2️⃣ 初始化项目索引

cd 你的项目目录codegraph init -i

这会在项目里创建 .codegraph/ 文件夹，并开始构建索引。

首次索引时间：小项目几秒，VS Code 级别（4000 个 TS 文件）约 4 分钟。之后文件改动了会自动增量更新。

3️⃣ 重启 AI 助手

让 MCP 服务器加载生效，就可以用了。

🛠️ AI 助手多了哪些能力？

安装后，AI 助手获得 9 个新工具：

💡 使用原则

✅ 查符号名 → codegraph_search（别用 grep）✅ 查调用关系 → codegraph_callers/callees（别在文件里人肉翻）✅ 改代码前 → codegraph_impact（看影响面）✅ 探索陌生模块 → codegraph_explore

🔧 常用命令速查

CI 集成示例：找出受影响的测试

# 从 git 变更找出需要跑的测试git diff --name-only HEAD | codegraph affected --stdin# 然后只跑这些测试npx vitest run $(git diff --name-only HEAD | codegraph affected --stdin --quiet)

🔒 100% 本地，隐私安全

• 没有 API key
• 没有外部服务
• 数据全存在本地的 SQLite 数据库
• 敏感项目直接用，不用担心代码外传

⚠️ 踩坑提醒

📚 支持的场景

语言（19+ 种）

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Lua 等

Web 框架路由识别

Django、Flask、FastAPI、Express、NestJS、Rails、Spring、Gin 等 —— 自动识别路由与控制器/处理函数的对应关系

AI 助手

Claude Code、Cursor、Codex CLI、OpenCode、Hermes

🎯 总结

CodeGraph 做的事：把代码库预先解析成知识图谱，让 AI 助手直接在图上游走，而不是 grep 盲搜。

适合谁：

• 用 AI 编程助手处理大型代码库的人
• 关心 token 成本的人
• 需要隐私安全（代码不出去）的项目

下一步：

1. 在你的项目里跑 npx @colbymchenry/codegraph
2. 初始化索引
3. 问问 AI：「帮我看看这个函数被谁调用了」
4. 你也可以自定义一些comands 或者agents 使用
5. 在 AGENTS.md 设计好指南,以引导LLM调用
   
   

仓库：github.com/colbymchenry/codegraph