用CodeGraph减少70%工具调用
当我第一次看到 Claude Code 在回答一个关于我 18 万行后端代码的问题时，连一个文件都没有读取，我以为它产生了幻觉。我问它某个特定的计费 webhook 在哪里被验证。通常，这个问题需要我花费四到五次工具调用——用 grep 搜索处理器，用 glob 查找路由文件，两次 Read 来追踪调用链，可能还需要第三次来确认。而这一次，它一次性给出了答案：确切的函数、文件名、三个调用者以及导入路径。零次 Read 调用。一次对本地图谱的查询就够了。
这个图谱就是 CodeGraph。在四个真实仓库中使用一周后，它将我的代理工具调用次数减少了中位数 70%，token 消耗降低了 59%，响应时间缩短了 49%——这些都是作者公布的亮眼数据，我起初持怀疑态度，但最终基本上被说服了。这个项目在 一周内获得了超过 14,000 个 GitHub star，并在 2026 年 5 月底飙升至 GitHub Trending 第 2 名。下面来看看它实际做了什么，在哪些方面真正有用，以及它在哪个方面悄悄让你付出更多代价。
1、编码代理在真正工作之前就烧掉大量 Token
如果你曾经盯着 Claude Code 或 Cursor 会话，纳闷为什么一个"简单"的问题花了你 1 美元，那么答案几乎总是出现在"发现阶段"。在代理编辑一行代码之前，它必须先弄清楚代码在哪里。它会启动一系列探索步骤：用 grep 搜索符号，用 glob 查找文件名，读取整个文件到上下文中，仅仅是为了追踪一条调用链。每一次工具调用都会返回内容，填满上下文窗口。在大型或不熟悉的仓库中，这种探索开销可能在任何实质性变更发生之前就占据了整个会话成本的大部分。
更残酷的是，这项工作是可重复的。代理在每个新会话中都会重新发现相同的结构，因为结构存在于文件系统中，而文件系统并不能以代理所需的方式被查询。Anthropic 自己在 Claude Code 中关于有效上下文使用的工程指南恰恰强调了这一点：最小化不必要的文件读取，策略性地选择进入上下文窗口的内容。CodeGraph 的核心理念是：发现阶段是可以预先计算的。一次解析代码，存储关系，然后让代理查询图谱而不是扫描目录树。2026 年主导的"上下文工程"讨论已经围绕这个想法进行了数月；CodeGraph 只是发布了一个开发者真正会去 star 的版本。
值得具体说明一下浪费的规模。当 Claude Code 在一个不熟悉的仓库上启动探索步骤时，一个简单的"X 在哪里处理"的问题通常会扩散成一次符号 grep、一次文件名 glob，以及两到三次 Read 调用——每次都会把整个文件（往往是数百行不必要的代码）倒入上下文窗口。在大型仓库会话中，这种发现开销可能在代理提出任何编辑建议之前就消耗掉总 token 的相当大一部分。而且由于这些信息不会持久化，下一次会话又要支付同样的代价。你所厌恶的 token 账单，不成比例地花费在代理一遍又一遍地重新学习你的代码库结构上。
2、CodeGraph 究竟是什么
CodeGraph 是一个开源的、本地的代码知识图谱，由 Colby McHenry 构建，他自称是一名专注于 AI 工具开发的软件工程师。其架构朴素得令人耳目一新。它使用 tree-sitter 解析你的代码库，提取符号、调用图、导入链和 Web 路由，并将所有内容写入存储在仓库中 .codegraph/ 文件夹下的 SQLite 数据库。然后，它通过三个接口向编码代理暴露这个结构化图谱：Model Context Protocol（MCP）服务器、CLI 和 TypeScript 库。
让它变得有趣而不仅仅是另一个 RAG 包装器的关键在于它所索引的内容。它不存储代码块的模糊嵌入。它存储的是显式的边——这个函数调用了那个函数，这个模块导入了那个模块，这个路由映射到那个处理器。当代理询问"什么调用了 validate_webhook"时，CodeGraph 返回的是实际的调用者，而不是五个看起来统计相似的片段。而且所有这些都不需要 API 密钥，也不需要外部服务。正如 README 中所说："没有数据离开你的机器。不需要 API 密钥，不需要外部服务——只是一个在 .codegraph/ 中的 SQLite 数据库。"对于那些担心专有源代码接触第三方索引服务的公司来说，这一设计决策本身就是全部的卖点。
它目前宣称与八种代理集成：Claude Code、Codex CLI、Cursor、OpenCode、Gemini CLI、Google 的 Antigravity IDE、Kiro 和 Hermes Agent。这种广度很重要——它被定位为你目前使用的任何代理之下的基础设施，而不是任何代理的竞争对手。
3、数据与测量方法
McHenry 的基准测试方法论简单明了，易于理解。每个任务运行两次：一次使用基线代理（使用 grep/glob/Read 进行发现），一次使用相同的代理但由 CodeGraph 的预索引图谱支持。比较隔离了发现阶段，这正是节约应该（也确实）出现的地方。在 七个真实代码库 中，中位数结果是 token 减少 59%，响应速度提升 49%，工具调用减少 70%。
他还在最新的技术栈上重新运行了测试套件——CodeGraph v0.9.7 搭配 Claude Opus 4.8，验证日期为 2026 年 5 月 28 日（Opus 4.8 发布当天）。这些数字更加温和，值得称赞的是，他仍然公开了它们：
+--------------------+----------------------+--------------------------------+
| Metric | Median (7 codebases) | v0.9.7 + Opus 4.8 (2026-05-28) |
+--------------------+----------------------+--------------------------------+
| Token reduction | 59% fewer | 51% fewer |
| Tool-call reduction| 70% fewer | 57% fewer |
| Speed | 49% faster | 16% faster |
| Cost | (not headlined) | 18% cheaper |
+--------------------+----------------------+--------------------------------+
"七个仓库的中位数"与"最新模型在单次验证上的表现"之间的差距，正是你想看到的诚实纹理。70% 的工具调用减少是那种能卖 README 的数字；57% 的减少（在新模型上）则是那种经得起现实检验的数字。两者都很可观。成本降低（18%）落后于 token 减少（51%）的原因值得理解：CodeGraph 用大量廉价的发现 token 换取了更少但更密集的图谱查询 token，所以原始 token 数量的下降速度快于美元数字的下降速度。你仍然赢了——只是不像 token 图表所暗示的那么戏剧性。
4、在真实会话中的表现
使用模式几乎千篇一律。代理首先调用 codegraph_context 来映射代码库的相关区域——即它关心的区域的结构概览。然后调用一次 codegraph_explore 来拉取它所需特定符号的实际源代码。然后就结束了。在最好的情况下，代理以零文件读取回答结构性问题，因为所需的一切都来自两次图谱查询，而不是一连串的 grep 和 Read。
除了这两个，图谱还支持整个仓库的符号搜索、影响分析（如果我更改这个符号会破坏什么）、调用图遍历和导入链追踪。影响分析工具是我最常使用的。问"重命名这个函数之前有什么依赖于它"过去是一个需要几分钟的探索工作；而有了图谱，这只是返回直接影响范围的单次查询。在我最大的仓库中，一个之前触发九次工具调用和三次完整文件读取的问题，简化为两次图谱查询和一段话的回答。
第二个例子让差异变得切实可感。我让代理追踪一个请求如何从 HTTP 路由流到数据库层——这种跨领域的问题通常会让代理依次读取路由文件、控制器、服务和仓库类，至少需要四次完整的 Read 调用。有了图谱，代理直接沿着调用链走：路由到处理器到服务到查询，以一条连接路径的形式返回，附带相关的签名，并且只为那个我随后要求修改的函数拉取实际的源代码。行为上的转变微妙但一致——代理不再把探索当作"读完附近所有内容然后碰运气"，而是开始把它当作"向索引提一个精确的问题"。这就是整个关键所在，也是工具调用减少（中位数 70%）甚至超过 token 减少（59%）的原因：代理不仅读得更少，而且决策更快。
5、真正的优势，以及它悄悄输掉的地方
这是营销文案所掩盖的问题，作者至少做了脚注：在小型仓库上，投资回报率可能为负。 当代码库文件很少时，发现阶段已经足够便宜——代理可以通过 grep 和 Read 以几乎零成本完成理解——因此构建和查询图谱的开销无法得到回报。用 CodeGraph 自己的话说，在较小的仓库上，成本收益"可能更窄，有时甚至是负面的"。节约效果随代码库规模和结构复杂性而增长。如果你的项目只有几千行代码，你是在增加机器来解决一个你没有的问题。
第二个真正的限制是"过时性"。这是主导 Hacker News 讨论和 GitHub issue 追踪器的批评。预索引图谱本质上是一个快照。当代码发生变化时，图谱会不同步，信任过时边的代理可能会自信地指向一个已经不存在的调用者。CodeGraph 的答案是重新索引——增量更新和监视模式是目前正在积极讨论的方向——但过时性是整个预索引方法固有的问题。正是在这一点上，主要替代方案 Serena 采取了相反的路线。
Serena 是一个成熟的基于 LSP 的 MCP 服务器，它查询实时的语言服务器而不是静态索引。这使得它始终是最新的——没有过时问题——但它依赖于每种语言运行一个语言服务器，设置和操作起来更重。取舍很清楚：CodeGraph 提供快速、廉价、结构精确但可能过时的答案；Serena 提供始终最新的答案，但代价是更多的活动部件。基于嵌入的 RAG 是第三种选择，它回避了这两个问题但失去了结构精确性——它检索看起来相似的代码，而不是实际连接的代码，这对于导航来说是错误的失败模式。而大家起步时用的基线方案——纯 grep/Read——始终最新、零设置，但 token 消耗最高。
6、究竟应该使用哪种方案？
如果你在 大型单体仓库或不完全了解的遗留代码库 上工作，CodeGraph 是最强选择——过时风险可以通过 CI 中的重新索引来管理，而且在每个探索密集型会话上的 token 节约正是其 59% token 减少数字真正落地的地方。如果你的首要任务是 绝不对当前代码出错——你经常重构，一条过时的边可能是危险的——那么 Serena 基于 LSP 的实时查询尽管设置较重，却是更安全的选择，因为没有索引会漂移。如果你主要做 语义化的"找像这样的代码"搜索 而不是结构化导航，嵌入 RAG 仍然有一席之地，但对于调用者/被调用者问题，图谱每次都能胜出。如果你在 小型或快速变动的项目 上工作，正确的答案就是什么都不用：纯 grep/Read 始终最新、零设置，在小型仓库上已经足够便宜，任何索引都是你无法回收的开销。
7、为什么它现在爆发了
时机并非偶然。CodeGraph 赶上了 2026 年 5 月更广泛的 GitHub 趋势，其中主导主题不是更大的模型，而是更便宜、设备端、支持代理的基础设施——内存层、代码索引器、本地运行时。在当周的 trending 数据中，旨在减少代理会话期间 token 消耗的项目与完全在设备端运行的工具一起聚集在顶部。CodeGraph 本身在 24 小时内增加了 2,434 个 star，于 5 月 23 日登上 GitHub Trending 第 2 名，并在 第一个大周内突破了 14,000 个 star。5 月 28 日 Claude Opus 4.8 的发布——其动态工作流特性可以将数百个子代理分配到一个问题中——更加剧了这一点：更多的并行代理意味着更多的并行发现，而这正意味着发现税与你所兴奋的特性成比例增长。一个能够降低这种税的工具，恰好在这个税变得更大的时刻出现了。
8、五分钟快速上手
安装真的一行命令就够了。在 macOS 或 Linux 上：
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
在 Windows 上通过 PowerShell：
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
或者完全跳过安装程序，通过 npm 运行，适用于任何环境：
# 零安装，直接运行
npx @colbymchenry/codegraph
# 或全局安装
npm i -g @colbymchenry/codegraph
然后，你将它指向一个仓库，让它将索引构建到 .codegraph/ 中，并向你的代理注册 MCP 服务器。一旦 Claude Code 或 Cursor 看到 codegraph_* 工具，它们会自动优先使用图谱查询而不是文件扫描——你不需要提示它们这样做。大型仓库的首次索引需要一些时间，因为 tree-sitter 必须解析所有内容一次；此后的每次会话都会享受节约的成果。将 .codegraph/ 添加到你的 .gitignore（除非你想提交索引），并在你的工作流（或 CI）中规划一个重新索引步骤，这样图谱就不会落后于你的代码。
9、结束语
CodeGraph 是迄今为止最清晰的信号，表明 2026 年代理工具的发展方向：从中心模型做所有事情，转向由专门组件组成的外围层——内存、代码索引、运行时、安全——这些组件使模型更便宜、更锐利。工具调用减少 70% 的标题在大型仓库上是真实的，在小型仓库上则表现一般；过时问题是真实存在的，且在设计上无法完全解决；小型仓库上 ROI 为负的警告是作者没有隐藏而是公之于众的，值得称赞。
如果你每天都在大型代码库上使用代理，并且你的 token 账单已经开始让你感到刺痛，那么这五分钟的安装是值得的——索引在一到两次会话内就能收回成本。如果你在小型项目或结构每小时都在变动的项目上工作，跳过它；机器成本超过了问题本身。无论如何，一个单个工程师的本地优先 SQLite 图谱能让 Claude Code 在回答结构性问题时读取零个文件，这一事实告诉我们：发现阶段从来就不应该花费我们一直在支付的代价。
原文链接: I Gave Claude Code a Map of My Repo — CodeGraph Killed 70% of Its Tool Calls
汇智网翻译整理，转载请标明出处