CodeGraph：给AI编码助手装个离线知识图谱，减少80%的token浪费

最近在 GitHub Trending 上看到一个项目叫 CodeGraph，两天涨了 1.6 万星。作为一个被 AI 编码助手 token 账单支配过的后端，我第一反应是——这东西能帮我省多少钱？

先交代背景。我团队用 Claude Code 和 Cursor 写代码，有个痛点：AI 每次要理解项目结构，都得反复读取文件、调用工具。一个中等规模的 TypeScript 项目（200+ 文件），光让 AI 理解依赖关系就能烧掉几千 token，而且它经常重复读同一个文件。

CodeGraph 的做法很直接：在 AI 提问之前，先把代码库的依赖关系、类型定义、函数调用链全部索引好，存成一个离线知识图谱。 AI 需要时直接查图，而不是从头扫描文件。

它到底做了什么？

简单说，CodeGraph 解析你的代码库，提取三类信息：

• 模块依赖：哪个文件引用了哪个文件
• 类型定义：接口、类型别名、类的继承关系
• 函数调用：函数 A 调用了函数 B

然后把这些信息存成 JSON 或 SQLite 格式的图谱文件。AI 编码助手（Claude Code、Codex、Cursor、OpenCode）通过一个 MCP 服务器（Model Context Protocol）读取这个图谱，避免重复扫描。

看一个实际例子。假设你有这样的 TypeScript 代码：

// user-service.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

export function createUser(data: Partial<User>): User {
  // ...
}

// order-service.ts
import { User, createUser } from './user-service';

export function placeOrder(userData: Partial<User>) {
  const user = createUser(userData);
  // ...
}

CodeGraph 会生成这样的图谱节点：

{
  "nodes": [
    {
      "id": "user-service.ts",
      "type": "file",
      "exports": ["User", "createUser"]
    },
    {
      "id": "User",
      "type": "interface",
      "file": "user-service.ts",
      "properties": ["id", "name", "email"]
    },
    {
      "id": "order-service.ts",
      "type": "file",
      "imports": ["User", "createUser"]
    }
  ],
  "edges": [
    { "from": "order-service.ts", "to": "user-service.ts", "type": "import" },
    { "from": "placeOrder", "to": "createUser", "type": "calls" }
  ]
}

当 AI 助手需要理解 placeOrder 函数时，它直接查询图谱就知道它调用了 createUser，而 createUser 定义在 user-service.ts 中，并且依赖 User 接口。不需要打开任何文件。

和同类方案的对比

目前市面上处理代码上下文的方式主要有几种：

1. 传统做法：AI 自己扫描
Claude Code 默认会读取文件列表，然后根据需要逐个打开文件。对于大型项目，它可能打开 30-50 个文件才能理解一个函数调用链。每次打开文件都消耗 token，而且经常重复。

2. 代码索引工具（如 ripgrep + tree-sitter）
这些工具能快速搜索代码，但每次查询都需要重新解析。它们没有持久化的图谱结构，AI 每次问“这个函数被谁调用了”都得跑一次搜索。

3. CodeGraph 的做法
一次索引，多次查询。图谱文件只有几十 KB 到几百 KB，加载到 AI 上下文中几乎不占 token。而且查询是 O(1) 的——直接通过 ID 查找节点和边。

我做了个简单测试：在一个 150 个文件的 NestJS 项目中，让 Claude Code 理解 AuthService.login 方法的调用链。

数据说明：CodeGraph 在 Token 消耗上节省了约 80%，工具调用减少了 83%。注意，这个测试是在我本机跑的，项目结构比较规整，实际效果可能因项目复杂度而异。

适用场景与局限

什么时候值得用？

• 项目规模在 50 个文件以上，AI 经常需要跨文件理解
• 你使用 Claude Code 或 Codex 这类支持 MCP 的助手
• 团队成员频繁修改代码，需要持续更新图谱
• 对 token 成本敏感（比如用 API 按量付费）

什么时候别用？

• 小项目（少于 20 个文件），AI 自己扫描足够快
• 纯脚本或单文件项目，没有复杂的依赖关系
• 项目使用动态导入或反射（比如 NestJS 的模块注册），图谱可能不完整
• 代码库频繁变更（每小时改几十个文件），重新索引的成本可能超过收益

一个坑： CodeGraph 目前只支持 TypeScript/JavaScript。如果你的项目混用 Python、Go 或 Rust，它只能索引 TS/JS 部分。项目文档说未来会支持更多语言，但当前版本（v0.1.0）只有 TS 解析器。

快速上手

安装很简单，用 npm 全局装：

npm install -g @codegraph/cli

然后在项目根目录运行：

codegraph index --format sqlite --output ./codegraph.db

这会生成一个 SQLite 文件。接着启动 MCP 服务器：

codegraph serve --db ./codegraph.db

最后在 Claude Code 的配置文件中添加 MCP 服务器地址。以 Claude Code 为例，在 ~/.claude/config.json 中：

{
  "mcpServers": [
    {
      "name": "codegraph",
      "url": "http://localhost:3000/mcp"
    }
  ]
}

之后 Claude Code 就会自动使用 CodeGraph 的图谱来回答代码相关问题。

我的看法

CodeGraph 解决了一个真实痛点：AI 编码助手在大型项目中浪费大量 token 去理解上下文。它的思路类似于“预计算”——把 AI 需要频繁查询的信息提前算好存起来。

但这不是银弹。首先，它只支持 TypeScript，限制了适用范围。其次，对于动态语言特性（比如装饰器、元编程），静态分析很难覆盖全。最后，图谱需要维护——代码改了，图谱得重新索引。

不过对于 TypeScript 项目，尤其是后端 Node.js 项目，它的价值很明显。我准备在自己维护的一个 300 文件的项目里跑一段时间，看看实际能省多少 token。

如果你也在被 AI 助手的 token 账单困扰，值得花 10 分钟试试 CodeGraph。至少，它比我之前手动粘贴文件给 AI 问“这个函数在哪定义”要优雅得多。

本文基于 CodeGraph v0.1.0，测试环境为 macOS 14.4 + Node.js 20.11。