用 codegraph 把 token 消耗砍掉 50%

一个不对劲的账单

过去我们开发主要使用 Claude Code 按量付费。

随着团队里 AI 编程使用越来越频繁，token 消耗开始变成一个需要认真关注的问题。为了控制成本，我们在几个月前切换到了阿里云 token plan。

刚开始，我们并没有特别关注每个人的消耗差异，都是团队统一使用，整体看账单，只知道 token 在快速增长。

这个月为了更准确地了解实际使用情况，同时也想验证 codegraph 是否真的能够降低代码探索成本，我们给每个人分配了独立席位，开始观察不同使用习惯下的 token 消耗。

结果出现了一个有意思的现象：

15 天后，5 个席位里已经有 1 个额度耗尽，需要额外充值，另外两个也接近耗尽。

而唯一一个坚持每个新项目执行：

codegraph init -i

的人，恰好是目前消耗最低的那个。

这不是一次严格控制变量的实验。大家负责的任务不同，项目复杂度也不同，不能简单地说所有差异都来自 codegraph。

但这个结果足够引起我们的注意：

为什么同样使用 Claude Code，有的人 token 很快耗尽，而有的人可以节省一半以上？

进一步分析后，我们发现，真正消耗大量 token 的地方，并不是模型本身，而是 Claude Code 默认的代码探索方式。

这篇文章记录我们的一次实际测试：一个本地代码索引工具，为什么可能让 Claude Code 的 token 消耗降低 50% 以上。

烧 token 的真正原因不是模型，是 Read

很多人以为 token 贵是因为模型升级、上下文变长。这只是表层原因。真正吞掉 token 的是 Claude Code 的默认探索模式：Grep + Read 循环。

举个真实的例子。我问 Claude Code：

「pendingUrlNav 的 resolve 流程涉及哪些模块？怎么从 web 端调到 daemon 的？」

如果不干预，Claude Code 会这么干：

1. grep "pendingUrlNav" ------ 命中 KnowledgeBasePage.tsx
2. Read KnowledgeBasePage.tsx ------ 整个文件 800+ 行读进来
3. grep "resolveCanonicalPath" ------ 命中 knowledge.ts
4. Read knowledge.ts ------ 又是 500+ 行
5. grep "resolve" in routes/ ------ 命中 knowledge.ts:185
6. 再 Read 一次 routes 文件附近几行

每一次 Read 整文件，都把大量无关代码 塞进上下文。KnowledgeBasePage.tsx 里只有 resolveUrlFileNavigation 和那个 useEffect 跟我的问题有关，但 Claude Code 读进来的是整个组件------包括 import 列表、样式、其他十几个 hook、其他几十个 handler。

问题不在于"读得多"，问题在于读了不该读的。一个 800 行的文件里，跟问题相关的可能只有 30 行。但 Read 工具没有"只读相关部分"的能力------它只能整文件进。

codegraph 是什么：把代码变成可查询的结构

我不想花篇幅讲它的实现（tree-sitter 解析 AST → SQLite 存节点和边 → MCP server 提供查询接口）。从用户视角看，它就做了一件事：把"代码"从一堆文本文件，变成一个可以按符号、按调用关系查询的数据库。

装好之后，Claude Code 多了一组 codegraph_* 工具。同样的那个问题，用 codegraph 走一遍：

问题	工具	一次调用拿到什么
「pendingUrlNav 在哪定义？」	codegraph_search	文件路径 + 行号 + 签名
「这个流程涉及哪些模块？」	codegraph_context	入口符号 + 相关符号 + 关键源码片段
「几个相关函数的源码」	codegraph_explore	多个文件的相关符号片段，不是整文件
「A 怎么调到 B？」	codegraph_trace	完整调用链，含动态分发跳板

关键差别在 codegraph_explore：它返回的是符号级 的源码片段，不是文件级。一个 800 行的文件，如果跟你的问题有关的只有 resolveUrlFileNavigation 那 12 行，它就只返回那 12 行。

三步装好 codegraph

1. 安装 CLI

不需要预装 Node.js，一行命令拿下对应平台的二进制：

# 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

如果你已经装了 Node，也可以走 npm（任意版本通用）：

npx @colbymchenry/codegraph

2. 接入你的 agent

新开一个终端，跑安装器把 codegraph 接到你常用的 AI 编程工具上：

codegraph install

这一步会自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro 等主流 agent------把 CodeGraph MCP server 写进各自的配置。

两个容易踩的坑：

• 第 1 步装 CLI 不会自动接入 agent 。必须跑一次 codegraph install，agent 才知道 codegraph 存在。
• codegraph install 只接线，不索引代码。每个项目的图谱构建是下一步单独做的事。

3. 给每个项目初始化

cd your-project
codegraph init

这一步才真正把当前项目解析成符号图谱。每个项目都要单独 init 一次，之后文件改动会通过 watcher 增量同步，不用重复 init。

实测：同一个问题，两条路径

我在项目（200 个 TypeScript 文件）上跑了同一个问题，分两次会话：

指标	Grep/Read 路径	codegraph 路径
Input token	69.4k	23.2k
Cache read	423.6k	194.2k
工具调用次数	6-8 次	5 次
单会话成本	$0.60	$0.27
节省	---	66% input / 55% 成本

需要诚实说明：codegraph 路径其实走了一次弯路------codegraph_context 用自然语言提问时，它把 "resolve" 匹配到了不相关的 agent binary 解析函数，agent 不得不补一次 codegraph_search 才找到正确符号。即便如此，token 消耗仍然只有 Grep/Read 路径的三分之一。

这背后的账很好算：一次错的 codegraph 查询代价是几千 token（返回几个不相关符号的签名），一次错的 Grep 代价是几百 token（匹配行），但为了补救这次 Grep 而触发的整文件 Read，代价是几万 token。整文件 Read 才是真正的 token 黑洞。

团队 5 席位的对比

回到开头的账单。按 1398 元/席、25 万 credits/席算，5 个席位总共投入近 7000 元、125 万 credits。

如果全团队都按 codegraph 路径走，按 50% 节省算，每月能省下相当于 2.5 个席位的额度------也就是近 3500 元、62.5 万 credits。

ROI 显而易见。这不是"用了新工具提高了效率"那种难以量化的收益，是直接从账单里能看到的数字。

怎么养成习惯

讲真，codegraph 不是装上就自动省 token 的。Claude Code 默认还是优先用 Grep/Read，需要在项目的 CLAUDE.md 里写死规则强制使用。我自己项目里的 CLAUDE.md 有这么一段：

## CodeGraph

| 问题 | 工具 |
|---|---|
| "X 在哪定义？" | codegraph_search |
| "什么调用 Y？" | codegraph_callers |
| "X 怎么到达 Y？" | codegraph_trace |
| "这个任务需要哪些上下文？" | codegraph_context |

更重要的是写反模式 ------告诉 Claude Code 不要做什么：

• 不要 codegraph_search + codegraph_node 链式调用（用 codegraph_context 一次搞定）
• 不要循环 codegraph_node 查多个符号（用 codegraph_explore 一次拿完）
• 不要用 grep 验证 codegraph 的结果（AST 解析已经权威，grep 反而更慢更不准）
• 不要把探索委派给 sub-agent（sub-agent 重复 codegraph 已做的工作）

这些规则的存在本身就说明：不写死，Claude Code 会按默认 Grep/Read 模式跑，token 照样烧。

边界：什么时候 codegraph 不省

实事求是地讲几个不适用场景：

1. 项目太小（<50 个文件）------Grep 就够了，codegraph 的索引 overhead 反而拖慢
2. 查字符串内容（log 文本、注释、配置值）------codegraph 是 AST 索引，不索引字符串内容，这种场景必须用 Grep
3. 代码刚改完还没重新索引------codegraph 有 ~1 秒的索引延迟，刚改的代码要等同步，或者直接 Read
4. 非主语言的大段配置/资源文件------YAML、JSON、Markdown 这些 codegraph 不解析

我的经验是，这些场景加起来大概占 20% 的探索需求。剩下 80% 的"代码理解类"问题，codegraph 都能省。

写在最后

AI 编程工具的 token 经济学，目前被严重低估了。大家关注模型能力、上下文窗口、agent 框架，但很少有人认真谈每一次工具调用的 token 成本。

AI 编程进入第二阶段以后，真正昂贵的已经不是模型，而是上下文。

当 Agent 一次次 Read 整个仓库时，我们买单的其实不是 Claude，而是低效的代码探索方式。

codegraph 的价值，不是让模型更聪明，而是让模型少走弯路。

今天节省的是 token，未来节省的，会是每一个 Agent 在大型代码库里的搜索成本。

---

关于我们

筑照云（GitHub: github.com/zhuzhaoyun）开源了两款产品：

• OpenSpec ------ 企业级智能长文档生成与审查平台。AI 驱动的专业文档自动生成与合规审查工具，通用架构，不限行业。
• Molio ------ 知识管理与创作工具。本地知识库 + AI 写作 + 多平台发布一站式桌面应用，支持类 Obsidian 的知识管理、Claude Code/Codex 等 AI runtime 集成、以及 doocs/md 排版和多平台发布。本文中的 token 实测数据全部来自 Molio 项目日常开发。

欢迎在 GitHub 关注我们，也欢迎在 issue 区交流 codegraph 的使用心得。