CodeGraph：为 AI 代理构建代码知识图谱
# 1.1 简介
CodeGraph 是一个预索引的代码知识图谱工具，专为 AI 编程代理设计。它能够自动同步代码变更，为 Claude Code、Cursor、Codex、Gemini、OpenCode、Hermes Agent 等 AI 代理提供精准的代码上下文。
当 AI 代理需要理解代码时，传统方式是逐个文件搜索、读取、分析，耗时且消耗大量 Token。CodeGraph 则预先构建了整个代码库的符号、调用边和依赖关系图谱，让代理通过一次查询就能获取精确的代码上下文，大幅减少工具调用次数和响应时间。
核心价值：
| 指标 | 效果 |
|---|---|
| 工具调用 | 减少 40%-81% |
| 响应时间 | 加速 11%-33% |
| 文件读取 | 接近零 |
| Token 消耗 | 减少 23%-64% |
# 1.2 优势
# 外科手术式的上下文
一次工具调用返回入口点、相关符号和代码片段，无需逐文件探索。传统方式下，代理需要使用 grep、glob、Read 等工具一个文件接一个文件地搜索，然后手动重建调用路径和依赖关系。CodeGraph 则直接提供精确的代码上下文。
# 全文搜索
基于 FTS5 的即时全文搜索，支持按名称查找代码，快速定位目标。
# 影响分析
在修改代码前，可以追踪调用者和被调用者，了解任何符号的完整影响半径，避免意外破坏。
# 自动同步
文件监视器使用原生 OS 事件（FSEvents/inotify/ReadDirectoryChangesW），配合防抖自动同步机制。当代理编辑代码或你手动添加、修改、删除文件时，图谱自动更新，无需手动重新索引。
# 支持 20+ 语言
包括：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Scala、Dart、Lua、R、Nix、Erlang、Solidity、Terraform、Svelte、Vue、Astro 等。
# 框架感知路由
识别 17 种 Web 框架的路由文件，自动链接 URL 模式到对应的处理函数：
- JavaScript: Express、Fastify、Hono、Next.js App Router
- Python: Django、Flask、FastAPI
- Java: Spring Boot
- Go: Gin、Echo、Fiber
- Ruby: Rails
- PHP: Laravel
- Rust: Axum、Actix
- C#: ASP.NET Core
- Kotlin: Ktor
# 混合平台桥接
支持 iOS 与 React Native/Expo 的跨语言流追踪：
- Swift ↔ Objective-C 桥接
- React Native 传统桥接 + TurboModules + Fabric 视图组件
- Native → JS 事件发射器
- Expo Modules
# 100% 本地运行
数据不离开本地机器，无需 API 密钥，不依赖外部服务，仅使用 SQLite 数据库。
# 1.3 安装和配置
# 安装方式
方式一：一键安装（推荐）
无需安装 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
2
3
4
5
方式二：npm 安装
如果已安装 Node.js：
npm i -g @colbymchenry/codegraph
安装后打开新终端，确保 codegraph 命令可用。
# 配置 AI 代理
运行安装器，自动检测并配置你使用的 AI 代理：
codegraph install
该命令会自动配置 Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro 等，将 CodeGraph 的 MCP 服务器接入每个代理。
# 项目初始化
在项目目录下初始化索引：
cd your-project
codegraph init
2
该命令创建 .codegraph/ 目录并构建完整图谱，一步完成。
# 验证状态
codegraph status
查看索引状态，如果有待同步的文件，会显示 ### Pending sync: 部分。
# 卸载
移除所有代理的配置：
codegraph uninstall
移除特定项目的索引：
cd your-project
codegraph uninit
2
# 1.4 常用命令
| 命令 | 说明 |
|---|---|
codegraph install | 配置 AI 代理，连接 MCP 服务器 |
codegraph init | 在项目中创建索引 |
codegraph sync | 手动同步代码变更 |
codegraph status | 查看索引状态 |
codegraph serve --mcp | 启动 MCP 服务器 |
codegraph upgrade | 升级到最新版本 |
codegraph upgrade --check | 检查是否有新版本 |
codegraph uninstall | 从所有代理移除配置 |
codegraph uninit | 移除项目索引 |
# 自动同步机制
CodeGraph 通过三层机制确保索引始终同步：
文件监视器 + 防抖同步：原生文件监视器捕获所有源文件的创建/修改/删除事件，防抖窗口（默认 2 秒）后触发重新索引，大量编辑合并为单次同步。
文件过期标记：在防抖窗口内，MCP 工具响应会标记待处理文件，提示代理直接读取最新内容，避免返回过期数据。
连接时同步：当 MCP 服务器（重新）连接时，会执行快速（大小 + 修改时间）+ 内容哈希校验，确保在没有运行 MCP 服务器期间所做的更改也能被吸收。
环境变量配置：
# 防抖窗口（毫秒），默认 2000，范围 [100, 60000]
export CODEGRAPH_WATCH_DEBOUNCE_MS=2000
# 禁用守护进程
export CODEGRAPH_NO_DAEMON=1
2
3
4
5
# 2 总结和建议
# 2.1 核心价值
CodeGraph 的核心价值在于精准上下文和速度提升：
| 优势 | 说明 |
|---|---|
| 减少工具调用 | 平均减少 58%，大型代码库可达 81% |
| 加速响应 | 平均快 22%，最高 33% |
| 零文件读取 | 接近零文件读取，直接返回相关代码 |
| 降低 Token 消耗 | 平均减少 40%，大型项目节省更明显 |
| 降低成本 | 大型代码库、高频使用时可节省可观费用 |
性能实测数据（Claude Opus 4.8，中位数）：
| 代码库 | 语言 | 文件数 | 工具调用减少 | 速度提升 | Token 减少 |
|---|---|---|---|---|---|
| VS Code | TypeScript | ~10k | 81% | 11% | 64% |
| Django | Python | ~3k | 77% | 13% | 60% |
| Tokio | Rust | ~790 | 57% | 18% | 38% |
| OkHttp | Java | ~645 | 50% | 31% | 54% |
| Alamofire | Swift | ~110 | 58% | 33% | 64% |
# 2.2 适用场景
强烈推荐：
- 大型代码库：文件数超过 500，依赖关系复杂
- 频繁 AI 编程：每天大量使用 Claude Code、Cursor 等代理
- 跨语言项目：React Native + Native、全栈项目
- 代码审查与重构：需要理解调用链和影响范围
可以考虑：
- 中型项目：100-500 文件，可提升效率但收益有限
- 框架开发：利用路由识别功能追踪 API 处理链
不太需要：
- 小型项目：<100 文件，传统搜索已足够高效
- 单语言简单项目：依赖关系简单，手动搜索成本不高
# 2.3 注意事项
安装注意：
- 安装脚本会将
codegraph添加到 PATH，但不会改变当前 shell，需要打开新终端 - macOS 可能需要允许运行未签名应用
使用注意：
- 首次索引大型代码库可能需要几分钟
- 自动同步有短暂延迟（防抖窗口），紧急情况可用
codegraph sync手动触发 - 确保项目根目录运行
codegraph init
性能注意：
- Token 和成本节省与代码库规模相关，小型项目收益有限
- 实测数据显示大型项目节省显著，小型项目可能持平
安全注意：
- 100% 本地运行，数据不会上传
- 无需 API 密钥，不依赖外部服务
- SQLite 数据库存储在
.codegraph/目录