夜雨聆风CodeGraph：让 AI 编程助手理解你的代码库
项目介绍
CodeGraph 是一个本地优先的代码智能系统，它将源代码构建成语义知识图谱，从而加速 AI 辅助开发。通过预先索引代码结构、关系和语义到 SQLite 数据库中，CodeGraph 让 Claude Code 等 AI 助手能够查询图谱而不是重复扫描文件，显著降低了 LLM 探索的开销。
在实际测试中，CodeGraph 实现了约16% 更便宜的操作、47% 更少的 token和58% 更少的工具调用。
框架介绍
CodeGraph 采用多层管道架构，通过 tree-sitter 解析源代码，将符号和边存储在 SQLite 数据库中，并通过 MCP 协议向 AI 编程助手暴露知识图谱。
核心组件包括：
- •提取子系统：使用 web-tree-sitter 和 WASM 语法进行高保真 AST 解析
- •解析子系统：处理跨文件引用解析，包括导入解析、名称匹配和框架特定模式
- •存储子系统：基于 SQLite 的图数据库，支持 FTS5 全文搜索
- •查询子系统：提供调用者、被调用者、影响半径等图遍历查询
框架流程图
使用方法
安装
# 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
# 或使用 npm
npm i -g @colbymchenry/codegraph配置 AI 助手
codegraph install此命令会自动检测并配置已安装的 AI 助手（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro）。
初始化项目
cd your-project
codegraph init -i-i参数会在初始化后立即构建索引。
使用场景
1. 架构探索
当 AI 助手探索代码库时，CodeGraph 提供预索引的知识图谱，包含符号关系、调用图和代码结构，让助手能够即时查询图谱而不是扫描文件。
2. 影响分析
在修改代码前，使用codegraph_impact分析更改符号的影响范围，追踪调用者、被调用者和完整的影响半径。
3. 跨语言项目
支持 iOS/React Native/Expo 混合项目，连接 Swift ↔ ObjC 桥接、React Native legacy bridge + TurboModules + Fabric view components、native → JS event emitters 等跨语言流程。
4. 框架路由分析
识别 14 个 Web 框架的路由文件，将 URL 模式链接到其处理程序，包括 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring 等。
核心特点
| 特性 | 描述 |
|---|---|
| 智能上下文构建 | 一次工具调用返回入口点、相关符号和代码片段，无需昂贵的探索代理 |
| 全文搜索 | 通过 FTS5 在整个代码库中按名称查找代码 |
| 影响分析 | 在更改之前追踪调用者、被调用者和任何符号的完整影响半径 |
| 始终新鲜 | 文件监视器使用原生 OS 事件进行防抖自动同步 |
| 20+ 语言支持 | TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Objective-C、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal/Delphi |
| 框架感知路由 | 识别 Web 框架路由文件并将 URL 模式链接到处理程序 |
| 100% 本地 | 数据不离开机器，无 API 密钥，无外部服务，仅 SQLite 数据库 |
技术亮点
Tree-sitter 驱动
使用web-tree-sitter和 WASM 语法进行高保真 AST 解析，支持 22+ 种语言。
跨文件解析
处理复杂的跨文件关系，包括泛型类型、提升的方法和框架特定约定，如 Luarequire、RustRocket宏、SwiftFluent关系。
增量更新
仅重新索引更改的文件，通过后台同步保持索引新鲜度。
多操作系统兼容性
支持 Windows、macOS 和 Linux，通过CODEGRAPH_DIR环境变量专门处理 WSL/Windows 文件系统边界。
使用 Demo
MCP 工具使用
当 AI 助手通过 MCP 连接到 CodeGraph 时，可以使用以下工具：
| 工具 | 用途 |
|---|---|
codegraph_explore | 主要工具。在一个调用中返回相关符号、调用流程和"爆炸半径"影响的源代码 |
codegraph_search | 在整个代码库中执行语义和关键词搜索 |
codegraph_callers | 识别调用特定节点的所有函数/方法 |
codegraph_impact | 分析更改符号的"爆炸半径"，跟踪跨文件依赖关系 |
codegraph_node | 检索详细的节点元数据或读取整个源文件 |
codegraph_status | 报告索引新鲜度、CLI 版本和索引路径 |
编程式 API
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);
const impact = cg.getImpactRadius(results[0].node.id, 2);
cg.watch(); // 文件更改时自动同步
cg.close();总结
CodeGraph 通过将代码库转换为可查询的知识图谱，为 AI 编程助手提供了结构化的代码理解能力。它显著降低了 token 消耗和工具调用次数，同时保持了 100% 的本地隐私保护。支持 20+ 种编程语言和 14 个 Web 框架，使其成为现代开发工作流的强大工具。
GitHub 地址
https://github.com/colbymchenry/codegraph
