CodeGraph

CodeGraph – 开源代码知识图谱工具，加速代码理解和分析

CodeGraph：赋能AI编码代理的智能代码导航系统

在日益复杂的软件开发环境中，AI编码代理正逐渐成为开发者不可或缺的助手。然而，传统的文件搜索方式往往效率低下，难以满足AI代理对代码精准定位的需求。CodeGraph应运而生，它是一款专为AI编码代理设计的、预先构建的代码知识图谱工具，旨在革新AI代理的代码理解与交互方式。

CodeGraph的核心在于其强大的代码解析与图谱构建能力。它借助tree-sitter技术，能够深入解析代码库，提取出符号关系、调用链以及代码的整体结构。这些信息被高效地存储在本地的SQLite数据库中，形成一个即时可查的知识图谱。AI代理可以通过对这个图谱进行查询，精准地找到目标代码，从而彻底摆脱了grep、glob或简单的文件读取等低效搜索模式。

经过在7个真实开源项目上的严格基准测试，CodeGraph展现出了惊人的效率提升。它平均能够降低35%的API调用成本，减少59%的Token消耗，节省49%的执行时间，并且工具调用次数锐减70%。尤为重要的是，CodeGraph全程在本地运行，无需任何外部API密钥，完美保障了用户代码的隐私安全。

CodeGraph的主要功能亮点纷呈，极大地增强了AI代理的代码处理能力：

预索引代码知识图谱：通过tree-sitter将代码转化为抽象语法树（AST），精确提取函数、类、方法等核心节点，并建立它们之间的调用、导入、继承等关系，构建一个可供即时检索的SQLite图谱。
智能上下文构建：一次工具调用即可高效获取代码的入口点、相关符号及其代码片段，避免了AI代理进行耗时且昂贵的逐文件扫描式探索。
全文符号搜索：基于FTS5技术，实现跨代码库的符号名称的秒级搜索，极速定位您所需的目标代码。
影响半径分析：能够精准追踪任意符号的调用者、被调用者以及其完整的影响范围，在进行代码修改前，能够全面评估潜在的波及面。
框架感知路由：自动识别14种主流Web框架的路由文件，将URL模式与对应的处理器函数或类进行精确关联。
实时自动同步：利用原生操作系统文件（如FSEvents、inotify、ReadDirectoryChangesW），实时项目文件的变动，并在短暂的2秒防抖后，自动进行增量图谱同步。
变更影响测试追踪：通过codegraph affected命令，可以追踪变更文件的传递性依赖，精准识别受影响的测试文件，为CI流水线提供有力支持。
零配置即开即用：自动识别文件扩展名以确定编程语言，并能智能遵循.gitignore规则，无需用户进行任何手动配置文件设置。

使用CodeGraph的过程简洁高效：

安装CodeGraph：在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。已安装Node.js的用户也可直接使用npx @colbymchenry/codegraph。
选择集成代理：安装器会自动检测您已安装的AI代理（如Claude Code、Cursor、Codex CLI、opencode、Hermes Agent），并通过交互式提示选择您要配置的代理，并自动完成MCP配置的写入。
重启AI代理：完成安装后，请重启您选择的AI代理，以确保MCP服务器配置生效。
初始化项目索引：进入您的项目目录，执行codegraph init -i命令，即可构建该项目的知识图谱索引。同时，该命令还会自动配置项目级别的代理规则文件（例如.cursor/rules/codegraph.mdc）。
开始使用：当项目目录现.codegraph/文件夹时，AI代理将自动调用CodeGraph工具进行代码查询与探索。您也可以通过CLI执行codegraph query <关键词>、codegraph callers <符号名>等命令进行手动查询。

CodeGraph的核心优势在于其卓越的价值和安全性：

显著降低使用成本：在VS Code、Excalidraw、Django、Tokio、OkHttp、Gin、Alamofire等7个大型开源项目上的测试表明，CodeGraph平均可节省35%的API成本、59%的Token消耗、49%的执行时间以及70%的工具调用次数。其效果在大规模代码库中尤为突出。
100%本地隐私安全：所有数据均存储于本地SQLite数据库，无需联网，不依赖API密钥，绝不上传任何用户数据，全面保障您的代码隐私。
跨平台自包含运行：提供适用于Windows（x64/arm64）、macOS（x64/arm64）和Linux（x64/arm64）的构建包，自带Node运行时，无需本地编译或额外安装Node.js。
19+语言全覆盖：全面支持TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Lua、Luau等主流及小众编程语言。
深度框架集成：原生支持Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、React Router、SvelteKit等14种框架的路由语法，实现URL与处理器函数的精确匹配。
无缝Agent集成：通过MCP协议与主流AI编码代理无缝对接，安装器可自动完成配置，无需手动编辑复杂的JSON配置文件。

CodeGraph的项目地址位于其GitHub仓库：https://github.com/colbymchenry/codegraph

CodeGraph的应用场景广泛，能够极大地提升开发效率和代码质量：

架构问题快速解答：当您向AI代理提出“扩展宿主进程如何与主进程通信？”这类架构层面的问题时，CodeGraph能让代理直接定位到相关源码，无需进行大范围的文件扫描。
代码审查与影响分析：在修改核心函数之前，利用codegraph_impact分析潜在的变更影响范围，有效规避引入回归性错误。
新人上手与代码熟悉：新加入团队的成员可以通过自然语言向AI代理提问，快速掌握项目结构、模块依赖以及关键业务逻辑。
精准测试定位：在CI流水线中，结合git diff和codegraph affected，仅执行受代码变更影响的测试文件，显著缩短构建周期。
跨文件重构辅助：在重构公共API时，利用callers/callees功能追踪全库的引用点，确保所有调用处都能得到及时更新。