河内机器人 30K Star 神器，给 Claude Code 装上代码地图，Token 中位数省 65 倍
项目：CodeGraph（colbymchenry/codegraph） GitHub 约30K⭐，基于 Tree-sitter，通过 MCP（Model Context Protocol） 接入 Claude Code
一、痛点：Claude Code 默认模式疯狂烧 Token
默认情况下 Claude Code 是“盲探模式”：
你让它修复支付回调 bug，它会反复执行 grep、read 读取一堆文件：
grep 匹配 payment，读取12个文件
找到 OrderService，顺着 import 继续读8个文件
改完测试报错，发现漏了继承基类
直接读取整个 service 目录几十份源码
问题：
每次新开会话，全部重新扫描一遍代码库；
大量无关源码塞进上下文，Token 爆炸；
AI 容易丢失依赖、继承关系，产生幻觉，改错代码；
仓库越大，这个问题越严重，大型项目单次会话十几万 token。
本质：AI 没有项目地图，只能像陌生人逛街，挨个房间推门查看。
二、CodeGraph 是什么
CodeGraph 会本地静态解析代码库，构建代码知识图谱：
节点：类、函数、接口、变量、模块符号；
边：调用关系、继承、导入、依赖；
底层：Tree-sitter AST 解析；
存储：本地 SQLite，代码不上传到任何云端；
接入方式：MCP Server，作为 Skill 注册给 Claude Code。
接入之后 Claude Code 的行为彻底改变：
不再无脑 grep/read 扫一堆文件。先查本地代码图谱：
直接查到：这个函数被谁调用、继承自哪个基类、改动影响范围；
只把最小必要的代码片段送入 LLM 上下文；
文件改动自动增量更新图谱，不用每次全量重建。
Benchmark（6个真实开源仓库，VS Code / Django / Gin 等）
Token 中位数减少 65倍，最高场景达到 376倍；
工具调用次数中位数下降约 71%；
代码探索耗时缩短约 77%；
评估指标：代码修改正确性、是否遗漏依赖、影响范围识别准确率。
不是简单压缩文本，是从“全量读文件”变成“查询结构化代码关系”。LLM拿到的是精简符号摘要，只有必要时才读取少量完整源码。
三、核心原理拆解
AST 静态建图（Tree-sitter）支持多语言：TS/JS、Python、Go、Rust、Java、C/C++、Swift 等。解析代码语法树，提取符号与调用关系，存入本地数据库。
增量更新图谱文件保存 / git commit 触发增量索引；只重新解析改动文件，大仓库不会每次全量扫描。
MCP 协议对接 Claude CodeMCP 让 Claude Code 可以调用本地工具。CodeGraph 对外暴露能力：
查询函数调用者/被调用者
查询类继承链
改动影响范围分析（blast radius）
符号定位，快速找到定义位置
上下文裁剪策略图谱返回结构化摘要（几十～几百 token）描述依赖关系；只有模型确认必须看源码时，才读取少量目标文件，避免一次性喂整个仓库。
四、三步安装
1. 安装 CodeGraph
npm install -g @colbymchenry/codegraph
2. MCP 接入 Claude Code
codegraph install
自动写入 Claude Code 的 MCP 配置，注册这个工具，重启 Claude Code。
3. 项目初始化建图
cd your-project codegraph init
首次运行会全量扫描，生成 .codegraph/ 本地索引目录。后续文件修改自动增量更新。
验证：在 Claude Code 里提问“这个函数有哪些调用方”，它会调用 codegraph 的工具而不是执行 grep。
五、适用场景 & 优势
✅ 大型单体仓库、多模块项目（收益最大） ✅ 重构、接口修改、Bug 定位、影响范围评估 ✅ 担心代码泄露，需要本地不把源码外传的私有项目 ✅ 长期高频使用 Claude Code，Token 账单很高
额外收益：降低幻觉AI 不再漏看父类、间接调用、跨模块依赖；修改代码时更容易识别改动会影响哪些测试、哪些下游逻辑。
六、局限（文章重点提醒，不要神话）
动态代码分析弱Tree-sitter 是静态AST。动态反射、运行时动态注册、动态导入无法在静态图谱捕获，这部分依然需要 AI 读取源码。
首次建图耗时十万行以上大仓库，第一次
codegraph init需要时间，取决于代码量。后续增量更新很快。小项目收益有限几百行的小仓库，本身token消耗就很低，省不了多少，提升更多是AI理解准确性。
多语言混合项目部分小众语言 Tree-sitter 解析器质量一般，图谱信息会不全。
图谱会过期风险极端场景下文件修改后增量索引失败，图谱和真实代码不一致，AI会基于旧地图推理，产生错误。可手动执行
codegraph reindex重建。
七、同类工具横向对比（文章附带）
| 工具 | 核心思路 | 特点 |
|---|---|---|
| CodeGraph（colbymchenry） | Tree-sitter + MCP，本地图谱 | 增量更新，多语言，30k⭐，本文主角 |
| code-review-graph | Tree-sitter，代码审查专用 | 主打PR评审，token大约省6.8倍 |
| ctxgraph-code | AST知识图谱，SQLite | 对比graphify，进一步降低token |
| Graphify | 代码+文档知识库 | 支持PDF/Markdown，部分场景最高几百倍token节省 |
八、实操验证方法（确认是否真在生效）
打开 Claude Code 的
/insights，查看工具调用记录；正常生效：大量
codegraph_xxx调用，read/grep大幅减少；未生效：依然疯狂调用 read/grep，说明 MCP 没加载成功；
Token 对比：同一个问题，对比接入前后
/insights的 token 消耗。
九、结论
Claude Code 最大的 token 浪费不是写代码，而是反复探索、读取大量无关源码。CodeGraph 用本地静态代码图谱，把“盲搜”变成“地图导航”。
大型项目：Token 中位数下降65倍，同时减少幻觉；
核心前提：静态代码能被 Tree-sitter 解析；动态代码场景依然有短板；
隐私友好：全部在本地完成，源码不会上传第三方。