CodeGraph - 给 AI 编码助手装上代码透视镜

少调用，少 Token，快理解。 CodeGraph 让 AI 编码助手从”逐文件扫描”进化到”一图尽览”。

📋 目录

AI 编码助手的困境
CodeGraph 是什么？
核心特性
工作原理
性能基准测试
支持的语言和框架
MCP 工具一览
快速开始
CLI 命令参考
CI/CD 集成：affected 命令
配置选项
与同类工具对比
总结

AI 编码助手的困境

当你让 Claude Code 或 Cursor 帮你理解一个代码库时，AI 助手通常会这样做：

AI: "让我看看这个项目..."
  → 启动 Explore 子代理
    → grep "functionName" (N 次)
    → Read 文件 A (几百行)
    → Read 文件 B (几百行)
    → grep "import" (N 次)
    → Read 文件 C...

结果: 一次简单的代码理解任务，可能产生 30-50 次工具调用，消耗 2 万+ tokens，花费 1-2 分钟。

问题不在于 AI 不够聪明，而在于它每次都要从零开始扫描。就像让一个侦探每次破案都要重新走访整个城市，而不是先看一张标注好线索的地图。

CodeGraph 是什么？

CodeGraph 是一个预索引的代码知识图谱工具，专为 AI 编码助手设计。它在后台用 tree-sitter 解析代码库，构建符号关系图（谁调用谁、谁继承谁、谁导入谁），存入本地 SQLite 数据库，然后通过 MCP 协议暴露给 AI 助手。

AI 助手 (Claude Code / Cursor / Codex)
    ↓ MCP 协议
CodeGraph MCP Server
    ↓
SQLite 知识图谱 (.codegraph/codegraph.db)
    ↑ 增量同步 (文件监听)
你的代码库

核心理念: 把”每次扫描”变成”一次索引、多次查询”。

核心特性

1. 智能上下文构建

一个工具调用，返回任务相关的所有入口点、符号关系和代码片段：

1 2	codegraph_context("用户登录流程") → 返回: AuthService.login()、SessionMiddleware、User 模型、相关路由

2. 全文搜索 (FTS5)

基于 SQLite FTS5 的符号搜索，毫秒级响应：

1 2	codegraph_search("authenticate") → 找到: AuthService.authenticate()、JWTAuthenticator、auth_middleware...

3. 影响分析

修改前先看影响范围：

1
2
3

codegraph_impact("User.save")
→ 影响链: User.save → AuthService.updateSession → APIHandler.respond
→ 涉及文件: user.ts, auth.ts, handler.ts

4. 始终保持新鲜

文件监听使用原生系统事件（macOS 的 FSEvents、Linux 的 inotify、Windows 的 ReadDirectoryChangesW），2 秒去抖后自动增量同步。改了代码，图谱自动更新。

5. 100% 本地运行

无外部服务、无 API Key、无网络依赖。所有数据存储在 .codegraph/codegraph.db。

工作原理

CodeGraph 的架构分为四个阶段：

阶段一：提取 (Extraction)

用 tree-sitter 将源码解析为 AST，通过语言特定的查询提取节点（函数、类、方法）和边（调用、导入、继承、实现）。

1	源码 → tree-sitter → AST → 语言查询 → 节点 + 边

阶段二：存储 (Storage)

所有符号和关系存入 SQLite 数据库，配合 FTS5 全文搜索索引。

阶段三：解析 (Resolution)

将引用解析为定义：函数调用 → 函数定义、import → 源文件、类继承关系、框架特定模式。

阶段四：自动同步 (Auto-Sync)

MCP Server 通过文件监听器监控项目文件变化，过滤只处理源码文件，2 秒去抖后增量更新图谱。

性能基准测试

CodeGraph 在 6 个真实项目上进行了基准测试，使用 Claude Opus 4.6（1M 上下文窗口）：

项目	使用 CodeGraph	不使用 CodeGraph	提升
VS Code (TypeScript)	3 次调用，17s	52 次调用，1m 37s	调用减少 94%，速度提升 82%
Excalidraw (TypeScript)	3 次调用，29s	47 次调用，1m 45s	调用减少 94%，速度提升 72%
Claude Code (Python+Rust)	3 次调用，39s	40 次调用，1m 8s	调用减少 93%，速度提升 43%
Claude Code (Java)	1 次调用，19s	26 次调用，1m 22s	调用减少 96%，速度提升 77%
Alamofire (Swift)	3 次调用，22s	32 次调用，1m 39s	调用减少 91%，速度提升 78%
Swift Compiler (Swift/C++)	6 次调用，35s	37 次调用，2m 8s	调用减少 84%，速度提升 73%

关键发现: 使用 CodeGraph 后，AI 助手从不需要回退到逐文件读取。最大的测试项目（Swift Compiler）包含 25,874 个文件、272,898 个节点，索引时间不到 4 分钟。

支持的语言和框架

19+ 编程语言

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

13 个框架的路由识别

框架类型	支持的框架
Python	Django、Flask、FastAPI
Node.js	Express
PHP	Laravel
Ruby	Rails
Go	Gin、chi、gorilla/mux
Rust	Axum、actix、Rocket
C#	ASP.NET
Swift	Vapor
前端	React Router、SvelteKit

框架路由识别意味着 CodeGraph 能将 URL 模式链接到处理函数，帮助 AI 理解请求流转。

MCP 工具一览

CodeGraph 通过 MCP 协议暴露 8 个工具：

工具	功能	典型场景
`codegraph_search`	按名称搜索符号	“找到 authenticate 函数在哪”
`codegraph_context`	构建任务相关上下文	“理解用户登录流程”
`codegraph_callers`	查找谁调用了某个函数	“谁在用 User.save()”
`codegraph_callees`	查找某个函数调用了什么	“login() 调用了哪些方法”
`codegraph_impact`	分析修改影响范围	“改 User 模型会影响什么”
`codegraph_node`	获取符号详细信息	“show me authenticate 的签名”
`codegraph_files`	获取文件结构	“src/ 下有哪些文件”
`codegraph_status`	检查索引状态	“索引建好了吗”

常用工具链

理解代码库：

1	codegraph_context("支付流程") → 读取相关入口和代码

重构前评估：

1	codegraph_search("UserService") → codegraph_callers("UserService") → codegraph_impact("UserService")

调试回归：

1	codegraph_callers("handlePayment") → 发现意外调用 → codegraph_impact 扩大范围

快速开始

一键安装

1	npx @colbymchenry/codegraph

交互式安装器会自动检测已安装的 AI 助手，提示配置作用域（全局或项目级），写入 MCP 服务器配置和指令文件。

非交互式安装（CI 环境）

1	npx @colbymchenry/codegraph --yes --target claude --location project

手动安装

# 全局安装
npm install -g @colbymchenry/codegraph

# 在项目中初始化
codegraph init

# 添加到 Claude Code 配置
claude mcp add codegraph -- codegraph serve --mcp

验证安装

1 2	codegraph status # 应该显示索引统计信息

CLI 命令参考

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

CI/CD 集成：affected 命令

codegraph affected 是一个强大的 CI 工具，它通过传递性导入依赖追踪，找出哪些测试文件会受到源码变更的影响：

# 基本用法
codegraph affected src/auth/login.ts src/auth/session.ts

# 从 git diff 管道输入
git diff --name-only | codegraph affected --stdin

# 自定义过滤
codegraph affected --filter "src/**/*.ts" --filter "!**/*.test.ts"

# JSON 输出（适合 CI 解析）
codegraph affected --json

实际应用场景: 在 CI 中只运行受影响的测试，大幅减少测试时间。

配置选项

配置文件位于 .codegraph/config.json：

{
  "languages": [],
  "exclude": ["node_modules/**", ".git/**", "dist/**"],
  "frameworks": [],
  "maxFileSize": 1048576,
  "extractDocstrings": true,
  "trackCallSites": true
}

选项	说明	默认值
`languages`	要索引的语言（空=自动检测）	`[]`
`exclude`	要排除的 glob 模式	`["node_modules/**"]`
`frameworks`	框架提示，用于更好的路由解析	`[]`
`maxFileSize`	跳过超过此大小的文件	1MB
`extractDocstrings`	提取文档字符串	`true`
`trackCallSites`	跟踪调用位置	`true`

与同类工具对比

特性	CodeGraph	传统 grep/rg	IDE 语言服务
符号关系图	✅ 完整调用图	❌ 只有文本匹配	⚠️ 部分支持
跨语言支持	✅ 19 种语言	✅ 通用文本	⚠️ 语言特定
AI 集成	✅ 原生 MCP	❌ 需手动包装	❌ 无标准协议
增量更新	✅ 文件监听自动	❌ 每次重新扫描	✅ 增量
影响分析	✅ 传递性追踪	❌ 不支持	⚠️ 有限
外部依赖	无	无	需要运行时
数据存储	本地 SQLite	无	内存/索引文件

总结

CodeGraph 解决了 AI 编码助手的一个根本性问题：代码理解的效率。通过预构建知识图谱，它让 AI 助手从”逐文件扫描”进化到”一图尽览”：

90%+ 工具调用减少 — 从 30-50 次降到 1-6 次
70-80% 响应加速 — 从 1-2 分钟降到 17-39 秒
100% 本地 — 无外部依赖，数据不出本机
即装即用 — 一个 npx 命令完成安装

如果你经常使用 AI 编码助手处理中大型代码库，CodeGraph 值得一试。它不是让 AI 更聪明，而是让 AI 更快地变聪明。

🔗 GitHub 仓库 | npm 包