引言

“~35% cheaper · ~70% fewer tool calls · 100% local”

这是"一天一个开源项目"系列的第107篇文章。今天带你了解的项目是 CodeGraph。

先来一个场景：你用 Claude Code 问"AuthService 是怎么被调用的？"。没有任何辅助工具时，Claude 的做法是：先 glob 扫描目录，再多次 grep 搜索，再 read 打开若干文件，最后才给出答案。整个过程可能触发十几次工具调用，消耗数十万 tokens。

CodeGraph 的思路是把这件事前置：在你开始工作之前，它已经用 tree-sitter 把代码库解析成了一个语义图谱，存入本地 SQLite，然后通过 MCP 协议把 8 个查询工具暴露给 AI 代理。当代理需要理解代码时，一次 codegraph_context 调用就能拿到入口点、相关符号和代码片段，不需要再去翻文件。

9.6k Stars，588 Forks。跨 7 个真实开源项目的基准测试结果：平均节省 35% 费用、减少 70% 工具调用、加快 49% 速度。在 VS Code 这样的大型 TypeScript 仓库上，一次架构问答从 1.4M tokens 压缩到 393k tokens，成本从 $0.64 降至 $0.42。

你将学到什么

• CodeGraph 的四阶段工作流：提取 → 存储 → 解析 → 自动同步
• 8 个 MCP 工具的具体用途和调用场景
• 跨 7 个真实项目的基准测试数据详解：为什么大型项目收益更大？
• 19 种语言支持 + 13 个框架路由识别的实现思路
• 从安装到集成 Claude Code 的完整操作流程
• codegraph affected：如何用依赖追踪做智能 CI 测试选择

前置知识

• 使用过 Claude Code、Cursor 或类似 AI 编码工具
• 了解 MCP（Model Context Protocol）的基本概念
• 有 Node.js 使用经验

---

项目背景

项目简介

CodeGraph 是一个本地语义代码知识图谱工具，专为提升 AI 编码代理的效率而设计。它的核心洞察是：

AI 代理在处理代码任务时，大量 tokens 和时间消耗在"发现阶段"——扫描目录、搜索符号、读取文件——而不是真正的推理和生成。

CodeGraph 的解决方案是把发现阶段外包给一个预建索引，让 AI 代理在正式工作时能直接获得结构化的代码知识，而不是从零开始探索文件系统。

技术栈选择非常务实：tree-sitter 做 AST 解析（成熟、多语言、高性能），SQLite FTS5 做全文检索（零外部依赖、完全本地），原生 OS 文件事件做实时同步（FSEvents/inotify/ReadDirectoryChangesW）。

作者/团队介绍

• 主要作者：Colby McHenry（GitHub: colbymchenry）
• 仓库地址：colbymchenry/codegraph
• 发布渠道：npm 包 @colbymchenry/codegraph

项目数据

• ⭐ GitHub Stars: 9,600+
• 🍴 Forks: 588
• 📦 npm 包名: @colbymchenry/codegraph
• 🔧 运行环境: Node.js 20–24
• 💻 平台支持: Windows、macOS、Linux
• 📄 License: MIT
• 🌐 仓库: colbymchenry/codegraph

---

主要功能

核心作用

CodeGraph 在 AI 代理和代码库之间插入了一个预建索引层：

代码库（TypeScript / Python / Go / ...）
        ↓ tree-sitter 解析
  语义图谱（符号 + 关系 + 调用链）
        ↓ 存入 SQLite FTS5
  本地知识库
        ↓ MCP 协议暴露
  AI 编码代理（Claude Code / Cursor / Codex CLI / OpenCode）

没有 CodeGraph 的 AI 工作流：

用户问："AuthService 是怎么被调用的？"
→ AI: glob("src/**/*.ts")     # 工具调用 1
→ AI: grep("AuthService")     # 工具调用 2
→ AI: read("auth.service.ts") # 工具调用 3
→ AI: grep("import.*Auth")    # 工具调用 4
→ AI: read("user.controller.ts")  # 工具调用 5
→ AI: read("app.module.ts")   # 工具调用 6
... 共 10–15 次工具调用，消耗大量 tokens

有 CodeGraph 的 AI 工作流：

用户问："AuthService 是怎么被调用的？"
→ AI: codegraph_callers("AuthService")   # 工具调用 1
→ 返回：所有调用者列表 + 调用位置 + 代码片段
→ AI 直接回答，无需再读文件

快速开始

一键安装（推荐）：

# 运行交互式安装器，自动检测已安装的 AI 代理并配置
npx @colbymchenry/codegraph

# 在项目中初始化（-i 表示交互式）
cd your-project
codegraph init -i

非交互式安装（CI 环境）：

# 自动检测所有已安装代理，全局安装
codegraph install --yes

# 指定目标代理
codegraph install --target=cursor,claude --yes

# 项目级别安装
codegraph install --target=auto --location=local

手动配置 Claude Code：

npm install -g @colbymchenry/codegraph

然后将以下内容加入 ~/.claude.json（或项目级 .claude.json）：

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

验证安装：

codegraph status          # 查看索引状态和统计
codegraph query "UserService"  # 测试符号搜索

8 个 MCP 工具详解

这是 CodeGraph 暴露给 AI 代理的完整工具集：

工具	用途	典型调用场景
codegraph_search	按名称搜索符号	“找所有叫 authenticate 的函数”
codegraph_context	为任务构建代码上下文	“理解登录流程需要哪些代码”
codegraph_callers	找调用某函数的所有地方	“谁调用了 AuthService?”
codegraph_callees	找某函数调用了哪些函数	“processPayment 内部调了什么?”
codegraph_impact	分析修改的影响半径	“改这个函数会影响哪些模块?”
codegraph_node	获取特定符号的详细信息	“给我 UserController 的完整签名”
codegraph_files	获取已索引的文件结构	“项目整体结构是什么?”
codegraph_status	检查索引健康状态和统计	“索引了多少符号?最后同步时间?”

codegraph_context 是其中最重要的工具——它不只返回搜索结果，而是为给定任务智能构建一个包含入口点、相关符号、代码片段的综合上下文包：

# 命令行等价操作
codegraph context "修复用户登录 bug"
# → 自动找到 login 相关函数、调用链、相关文件，打包成 AI 可直接消费的上下文

项目优势

对比维度	CodeGraph	原生 AI 代理（无辅助）	其他代码索引工具
工具调用次数	~70% 更少	高（每次任务重新扫描）	部分减少
Token 消耗	~59% 更少	高	部分减少
数据隐私	100% 本地	取决于代理	多数需要上传
实时同步	原生 OS 文件事件	不适用	通常轮询或手动
语言支持	19+ 种	取决于代理能力	通常 3–5 种
框架路由识别	13 个框架	无	罕见
安装复杂度	一条 npx 命令	不适用	通常需要服务端

---

项目详细剖析

一、四阶段工作流

阶段 1：提取（Extraction）

tree-sitter 把源文件解析为 AST，从中提取：

• 符号：函数、类、方法、接口、变量定义
• 关系：函数调用、模块导入、类继承、接口实现

tree-sitter 的优势在于它是容错 AST 解析器——即使代码有语法错误也能解析出部分结构，这对处理正在编写中的代码非常重要。

阶段 2：存储（Storage）

所有数据落入本地 SQLite，使用 FTS5（Full-Text Search 5）扩展提供全文检索能力：

-- 符号表（简化示意）
CREATE VIRTUAL TABLE symbols USING fts5(
  name,          -- 符号名称
  kind,          -- function/class/method/...
  file_path,     -- 所在文件
  line_start,    -- 起始行
  signature,     -- 函数签名
  docstring,     -- 文档注释
  code_snippet   -- 代码片段
);

-- 关系表
CREATE TABLE edges (
  from_id  INTEGER,  -- 调用方符号 ID
  to_id    INTEGER,  -- 被调用符号 ID
  kind     TEXT,     -- calls/imports/inherits/implements
  file     TEXT,
  line     INTEGER
);

阶段 3：解析（Resolution）

这是最关键的一步：把抽象的"调用了某个名字"解析为具体的"调用了哪个文件里的哪个定义"。

源代码: import { AuthService } from './auth.service'
         ...
         this.authService.login(user)
        ↓ 解析
图谱边: UserController.login → AuthService.login (calls)
         UserController → AuthService (imports)

阶段 4：自动同步（Auto-Sync）

使用原生 OS 文件事件（不是轮询！）监听变化：

• macOS: FSEvents
• Linux: inotify
• Windows: ReadDirectoryChangesW

有 2 秒防抖：避免文件快速连续变化时触发大量重建，等变化稳定后再做增量更新。

---

二、基准测试数据解读

官方测试条件：Claude Code（headless，Opus 4.7）回答架构问题，每组测试对同一问题跑 4 次取中位数，跨 7 个真实开源仓库。

项目           语言         规模         节省费用  减少 Token  加快速度  减少工具调用
──────────────────────────────────────────────────────────────────────
VS Code        TypeScript   ~10k 文件    35%       73%         41%       72%
Excalidraw     TypeScript   ~600 文件    47%       73%         60%       86%
Django         Python       ~2.7k 文件   34%       64%         59%       81%
Tokio          Rust         ~700 文件    52%       81%         63%       89%
OkHttp         Java         ~640 文件    17%       41%         36%       64%
Gin            Go           ~150 文件    22%       23%         34%       19%
Alamofire      Swift        ~100 文件    38%       59%         51%       77%
──────────────────────────────────────────────────────────────────────
平均                                     35%       59%         49%       70%

几个值得关注的规律：

1. Tokio（Rust，700 文件）收益最大（81% token 减少，89% 工具调用减少）：Rust 的类型系统复杂，AI 代理原本需要大量文件探索才能理解 trait 实现和泛型关系，CodeGraph 把这些关系预建好后效果显著。

2. Gin（Go，150 文件）收益最小（23% token 减少，19% 工具调用减少）：小型 Go 项目文件结构简单，AI 代理原本就可以高效浏览，CodeGraph 的边际价值较低。

3. VS Code 的绝对数字最震撼：同一个问题，无 CodeGraph 时消耗 1.4M tokens（$0.64），有 CodeGraph 时只消耗 393k tokens（$0.42）。单次任务节省 $0.22。

结论：仓库越大、依赖关系越复杂、语言类型系统越丰富，CodeGraph 的收益越大。对于日常使用 Claude Code 处理大型项目的用户，这个工具的 ROI 非常明显。

---

三、19 种语言 + 13 个框架路由识别

语言支持（通过 tree-sitter grammar）：

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Scala

框架路由识别是 CodeGraph 的一个差异化功能——它不只识别符号，还能理解 URL 路由和它背后的处理函数之间的映射：

# Django
urlpatterns = [
    path('users/<int:pk>/', UserDetailView.as_view()),
]
# → codegraph 知道 GET /users/{id}/ 对应 UserDetailView

# FastAPI
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    ...
# → codegraph 知道 GET /items/{id} 对应 read_item()

支持的 13 个框架：Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin/chi/gorilla/mux、Axum/actix/Rocket、ASP.NET、Vapor、React Router/SvelteKit。

这意味着 AI 代理可以直接问"/api/users/:id 的处理逻辑在哪里？"，CodeGraph 能给出精准答案，而不需要代理去扫描路由配置文件。

---

四、codegraph affected——智能 CI 测试选择

这是 CodeGraph 里一个被低估的功能：通过追踪导入依赖关系，找出受变更影响的测试文件。

# CI 场景：只运行受本次变更影响的测试
git diff --name-only | codegraph affected --stdin

# 手动指定变更文件
codegraph affected src/auth.ts

# 配合过滤器（只查 e2e 测试）
codegraph affected src/auth.ts --filter "e2e/*"

工作原理：

变更了 src/auth.ts
  ↓ CodeGraph 查依赖图
  找到直接导入 auth.ts 的: user.service.ts, auth.controller.ts
  找到间接导入 auth.ts 的: app.module.ts, integration.test.ts
  ↓ 过滤只保留测试文件
  受影响的测试: auth.spec.ts, user.service.spec.ts, integration.test.ts
  ↓ 输出
  [这些文件] ← 只跑这些测试，而不是全量测试套件

对大型项目来说，这能把 CI 测试时间从几十分钟压缩到几分钟。

---

五、配置和性能注意事项

项目配置文件（.codegraph/config.json）：

{
  "version": 1,
  "languages": ["typescript", "javascript"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true
}

SQLite 后端选择：

CodeGraph 内置两个 SQLite 后端：

• native better-sqlite3（默认，推荐）：高性能，支持并发读写
• WASM fallback：兼容性更好，但比 native 慢 5–10 倍，并发操作可能报 database is locked

如果遇到性能问题或锁定错误：

# 重建 native 模块
npm rebuild better-sqlite3

# 查看当前使用的后端
codegraph status

---

CLI 完整参考

codegraph                        # 运行交互式安装器
codegraph init [path]            # 在项目中初始化
codegraph uninit [path]          # 从项目移除 CodeGraph
codegraph index [path]           # 全量索引（--force 强制重建）
codegraph sync [path]            # 增量更新
codegraph status [path]          # 显示统计信息
codegraph query <search>         # 搜索符号
codegraph files [path]           # 显示文件结构
codegraph context <task>         # 为 AI 任务构建上下文
codegraph affected [files]       # 找受影响的测试文件
codegraph serve --mcp            # 启动 MCP 服务器

Library API 用法（在自己的工具中嵌入 CodeGraph）：

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');

// 全量索引（支持进度回调）
await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

// 搜索符号
const results = cg.searchNodes('UserService');

// 查调用链
const callers = cg.getCallers(results[0].node.id);

// 构建 AI 上下文
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20,
  includeCode: true
});

// 影响半径分析（深度 2）
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // 启动文件监听自动同步
cg.close();   // 清理资源

---

项目地址与资源

官方资源

• 🌟 GitHub: https://github.com/colbymchenry/codegraph
• 📦 npm: @colbymchenry/codegraph
• ⚡ 快速安装: npx @colbymchenry/codegraph

适用人群

• Claude Code / Cursor 重度用户：在大型项目上使用 AI 编码，希望降低成本、加快响应速度
• 大型 TypeScript/Rust/Python 项目开发者：代码库规模大，AI 代理的文件扫描开销显著
• CI/CD 工程师：用 codegraph affected 做智能测试选择，减少不必要的全量测试
• 工具链开发者：通过 Library API 在自己的工具中嵌入代码语义分析能力

---

总结与展望

核心要点回顾

1. 核心价值：在 AI 代理和代码库之间插入预建语义索引，平均节省 35% 费用、减少 70% 工具调用、加快 49% 速度
2. 技术选型：tree-sitter（AST 解析）+ SQLite FTS5（全文检索）+ 原生 OS 文件事件（实时同步），零外部服务依赖
3. 8 个 MCP 工具：codegraph_context 最核心，一次调用返回任务所需的完整代码上下文
4. 19 种语言 + 13 个框架路由识别，覆盖主流开发栈
5. codegraph affected：依赖追踪驱动的智能测试选择，CI 加速利器
6. 规模越大收益越大：Tokio（Rust，700 文件）达到 89% 工具调用减少；小型 Go 项目约 19%

一句话评价

CodeGraph 做了一件看似简单但极其务实的事：把 AI 代理每次都要重做的代码发现工作，变成一个可以持续复用的本地索引——这不是功能的叠加，而是工作流架构的优化。

---

欢迎来我的个人主页找到更多有用的知识和有趣的产品