Law的数字世界

核心能力一览#

它是怎么”画地图”的#

整个流程就四步:

1. 提取 — 用 Tree-sitter 把源码解析成 AST(抽象语法树),提取出函数、类、调用关系
2. 存储 — 全部塞进 .codegraph/codegraph.db 这个 SQLite 文件
3. 解析 — 把”函数调用 → 函数定义”、“import → 源文件”这些关系连起来
4. 自动同步 — 监听你本地的文件改动,用 Windows 的 ReadDirectoryChangesW 系统 API 实时增量更新

TIP

这就像你给老板做汇报前先画了张组织架构图。下次他问”研发归谁管”,你不用翻 50 个微信群,直接指着图说”归 Tony”。

适用场景#

• 接手别人留下的老项目,想让 AI 一两句话讲清架构
• 在大型代码库(几千到几万文件)里让 Claude Code 跑得更快
• 想让 AI 改代码前先做影响分析,避免改 A 炸 B
• 本地、离线敏感代码,不想让任何东西离开你的电脑
• 单纯就是嫌 token 烧得太多,想省点钱

同类工具横评#

CodeGraph 不是唯一一个干这事的。我把市面上几个主流方案拉出来对比一下:

怎么选?一张决策图给你

• 你只用 Claude Code/Cursor/Codex,想立刻见效 → 选 CodeGraph,装完就能用,benchmark 数据最硬
• 你需要 IDE 级精度,愿意忍受多语言 LSP 的折腾 → 选 Serena
• 你只用 Aider,不打算换工具 → 直接用它内置的 RepoMap,别折腾
• 你的需求是”找语义相似的代码”,不是”找精确符号” → 选 claude-context 走 Embedding 路线
• 你要给自己的 LLM 应用做 RAG,不只是给 AI 助手用 → 看 CocoIndex Code

泼一盆冷水

CodeGraph 不是万能药,它解决的是”探索阶段”的开销,不是”写代码本身”的开销。

几个前提条件先想清楚:

1. 你的项目得够大,至少 100 个文件以上,小项目用它纯属杀鸡用牛刀
2. 你用的得是 Claude Code、Cursor、Codex 或 opencode 这四个工具之一
3. 你的项目语言得在它支持的 19 种里(主流的都有,但 Elixir、Haskell 这种小众的还不行)
4. 第一次索引大项目要等几分钟,Swift 编译器 25,000 多文件用了 4 分钟——后续都是增量,不会再花这个时间

如果你的项目只有十几个文件,或者你不用上面几个 AI 助手,装它没意义。

工具组合清单#

第一步:一句话让 Claude Code 装好#

Windows 小白最爽的姿势——打开 Claude Code,直接丢一句:

1
帮我安装一下:https://github.com/colbymchenry/codegraph,安装完后检查一下是否安装完成

它会自己干完这些事:

• WebFetch / gh repo view 拉下 README,搞清楚怎么装
• node -v && npm -v 检查 Node 版本(没装的话它会提示你去 nodejs.org 下 LTS,要求 18+)
• npm install -g @colbymchenry/codegraph 全局装好 CLI
• codegraph install --target=claude --location=global --yes 非交互式把 MCP server 配进 Claude Code
• codegraph status 验证安装结果

整个过程一两分钟,你只要盯着看就行。装完它会给你列一张”安装结果”小表:

正常情况下你会看到:

TIP

如果你不用 Claude Code,只要把上面那句话发给 Cursor、Codex CLI、opencode 里任意一个 AI 助手,流程都一样。手动派的可以自己跑:

1
npx @colbymchenry/codegraph

它会以交互方式问你 4 个问题(给谁配、要不要加 PATH、全局还是项目、要不要自动授权),全选 Yes 即可。

第二步:重启你的 AI 客户端#

这一步很多人会忘——MCP 服务器配置只在客户端启动时加载一次。

把 Claude Code(或者 Cursor)整个关掉,再重新打开。重启完打开命令行确认:

1
claude mcp list

应该能看到 codegraph 出现在列表里,状态 connected。

第三步:在你的项目里初始化索引#

打开你想用 CodeGraph 的项目目录:

1
cd D:\your-project
2
codegraph init -i

这一步是真正的”画地图”。终端会显示进度条,告诉你解析了多少文件、提取了多少符号。

小项目几秒钟,中型项目几十秒,大型项目(VS Code 那种)几分钟。

跑完后你会发现项目根目录多了个 .codegraph/ 文件夹,里面有个 codegraph.db——这就是你的本地代码地图。

TIP

建议把 .codegraph/ 加进 .gitignore,别提交进仓库。每个人本地索引一份就好,文件可能上百 MB。

第四步:验证一切就绪#

跑两个命令检查健康度:

1
codegraph status

应该会输出:

1
Backend: native           ← 这一行要是 native,说明跑在快速通道
2
Files indexed: 1,234
3
Nodes: 12,345
4
Edges: 23,456
5
Last sync: 2 seconds ago

WARNING

如果 Backend: 显示的是 wasm,意味着 better-sqlite3 没编译成功,跑的是 WebAssembly 版本——慢 5-10 倍。

解决方法:装 Visual Studio Build Tools,然后:

1
npm rebuild better-sqlite3
2
# 或者强制装一遍
3
npm install better-sqlite3 --save

装 VS Build Tools 的下载地址:visualstudio.microsoft.com/visual-cpp-build-tools

安装时勾选”使用 C++ 的桌面开发”。

再随便搜个符号:

1
codegraph query "login"

应该能看到一堆相关函数、类被列出来。

第五步:让 Claude Code 真正用上它#

打开你的项目,启动 Claude Code,问一句:

1
帮我解释一下明暗模式(dark/light)切换的整个实现流程

观察工具调用栏——如果你看到 mcp__codegraph__codegraph_explore 这种字样跳出来,而不是密集的 Grep、Read,就说明它已经在用 CodeGraph 了。

实测对比

我用 Mizuki(Astro 静态博客)测了一下:

• 不用 CodeGraph:34 次工具调用,1 分 18 秒,83k token
• 用 CodeGraph:3 次调用,19 秒,39k token

一次任务省一半 token——按 Claude Sonnet 现在的价格,大项目一个月省几十刀很轻松。

进阶技巧:8 个核心 MCP 工具速查#

主会话里 AI 可以直接用这些”轻量级”工具:

注意:codegraph_explore 和 codegraph_context 只能由 Explore 子代理调用,主会话里直接用会把上下文撑爆——这是官方文档里强调的反模式。

老项目迁移的实战姿势#

这套组合拳特别适合接手老代码做迁移。我的建议流程:

1. 先索引 — codegraph init -i 把整个老项目画进图里
2. 让 AI 画架构图 — “用 codegraph_explore 帮我梳理这个项目的核心模块和它们的关系”
3. 挑入口 — 让 AI 用 codegraph_callers 找出最关键的几个被调用次数最多的函数
4. 改之前先 impact — 改任何关键文件前,先 codegraph_impact 看影响半径,避免连环爆炸
5. 改完同步 — CodeGraph 会自动监听文件变化,改完两秒就同步到图里,不用手动重建

TIP

还有一个被忽视的杀手锏命令:

1
git diff --name-only | codegraph affected --stdin --quiet

它会根据你 Git diff 出来的改动文件,反向追踪所有受影响的测试文件。CI 流水线里塞这一行,只跑相关测试,流水线时间能砍掉 60% 以上。