【AI开源】codegraph 完整使用教程（2026最新版）

codegraph是目前最成熟的本地代码知识图谱引擎，专为解决AI编码代理"反复扫描文件、Token消耗爆炸、上下文混乱"的行业痛点而生。它预先将任意代码库构建为可交互的结构化知识图谱，让Claude Code、Gemini、Cursor等8+主流AI工具直接查询代码结构而非逐行扫描文件，平均节省60-90% Token消耗，同时大幅提升AI回答的准确性和响应速度，且所有操作100%在本地完成，代码永不泄露。

一、项目核心信息

• 项目地址：github.com/colbymchenry/codegraph
• 开发语言：TypeScript
• 核心定位：预索引代码知识图谱，为所有主流AI编码工具提供代码结构感知能力
• 三大核心功能：
• 自动知识图谱构建：将任意代码库转为可搜索、可问答的交互式知识图谱
• 极致成本优化：预索引机制消除AI对代码库的重复扫描，节省60-90% Token消耗
• 全平台兼容：原生支持Claude Code、Codex、Cursor、Gemini、OpenCode等8+主流编码代理
• 适用场景：AI编码代理增强、大型代码库维护、团队知识管理、开发者效率提升、遗留系统现代化

二、环境要求

• Node.js：18.17.0+ 版本（推荐20.x LTS，兼容性最佳）
• 包管理器：npm 9+ 或 pnpm 8+（pnpm速度更快，推荐使用）
• 支持的AI客户端：
  ✅ Claude Code（原生集成，体验最佳）
  ✅ Cursor 0.45+
  ✅ Google Gemini CLI
  ✅ GitHub Copilot（VS Code扩展）
  ✅ OpenCode
  ✅ DeepSeek-TUI
  ✅ Windsurf 1.5+
  ✅ JetBrains AI Assistant
• 支持的编程语言：TypeScript/JavaScript、Python、Java、C/C++、Rust、Go、C#、PHP
• 操作系统：Windows 10/11、macOS 12+、Linux(Ubuntu 22.04+)
• 硬件要求：8GB以上内存（推荐16GB），索引10万行代码约需1GB磁盘空间

三、安装方法（3种方案）

方案1：NPM全局安装（推荐所有用户）

# 使用pnpm安装（推荐）
pnpm add -g @codegraph/cli

# 使用npm安装
npm install -g @codegraph/cli

# 验证安装
codegraph –version

方案2：VS Code扩展一键安装

方案3：从源码编译（开发者/自定义修改）

git clone https://github.com/colbymchenry/codegraph.git
cd codegraph
pnpm install
pnpm build
pnpm link –global

四、初始配置与索引生成

1. 全局配置

首次使用前，配置你常用的大模型API密钥：

# 打开配置文件
codegraph config edit

在配置文件中添加你的API密钥：

# 默认模型（推荐Claude 3.5 Sonnet，知识图谱构建效果最佳）
defaultModel: "claude-3-5-sonnet-20240620"

# 支持的模型列表
models:
claude-3-5-sonnet:
apiKey: "your-anthropic-api-key"
gpt-4o:
apiKey: "your-openai-api-key"
gemini-1.5-pro:
apiKey: "your-google-api-key"
deepseek-v4:
apiKey: "your-deepseek-api-key"

2. 生成项目索引（核心步骤）

进入你的项目根目录，运行以下命令生成代码知识图谱：

# 生成当前项目的完整索引
codegraph index

# 只索引指定目录
codegraph index src/ include/

# 排除不需要的目录（推荐）
codegraph index –exclude node_modules/ build/ dist/ third_party/

# 强制重新生成所有索引
codegraph index –force

# 显示详细索引过程
codegraph index –verbose

索引时间参考：

• 小型项目(<1万行)：10-30秒
• 中型项目(1-10万行)：1-5分钟
• 大型项目(10-100万行)：5-30分钟
• 超大型项目(>100万行)：30分钟以上

五、核心功能使用

1. 与AI编码代理无缝集成

这是codegraph最强大的功能，集成后AI会自动使用知识图谱回答问题，无需任何额外操作。

Claude Code（原生集成，无需配置）

Claude Code会自动检测项目中的codegraph索引，当你询问关于代码库的问题时，它会优先查询知识图谱而不是扫描文件。

Cursor 集成

Gemini CLI 集成

# 生成Gemini配置文件
codegraph integrate gemini

# 启动带codegraph支持的Gemini
codegraph run gemini

其他AI客户端

# 通用集成命令，会生成对应客户端的配置
codegraph integrate [client-name]

# 支持的客户端：copilot, opencode, deepseek, windsurf, jetbrains

2. 命令行直接查询

你可以直接在终端中查询代码知识图谱，无需打开AI客户端：

# 查询函数的所有调用位置
codegraph query "find all calls to the init_uart function"

# 查询类的继承关系
codegraph query "show the inheritance tree of the GPIO_Driver class"

# 查询所有使用了某个库的文件
codegraph query "which files import the HAL library"

# 生成项目架构概述
codegraph query "describe the overall architecture of this project"

# 查找可能的Bug
codegraph query "find potential memory leaks in the codebase"

3. 交互式Web界面

启动Web界面，可视化探索代码知识图谱：

# 启动Web服务器（默认端口3000）
codegraph serve

# 指定端口
codegraph serve –port 8080

访问 http://localhost:3000 即可打开交互式界面，你可以：

• 查看项目的整体架构图
• 浏览所有类、函数和变量的详细信息
• 可视化函数调用链和数据流向
• 进行语义搜索和自然语言问答
• 导出图谱为图片或PDF文件

六、性能与成本优化效果

官方在多个不同规模的项目上进行了实测，结果如下：

平均效果：节省60-90% Token消耗，减少70%以上的工具调用次数，响应速度提升50-80%。

七、高级使用技巧

1. 增量索引与自动更新

# 只索引修改过的文件，大幅节省时间
codegraph index –incremental

# 自动监控文件变化，实时更新索引
codegraph watch

# 设置自动更新间隔（单位：分钟）
codegraph config set auto_update_interval 30

2. 多项目管理

# 列出所有已索引的项目
codegraph projects list

# 切换到另一个项目
codegraph projects switch my-embedded-project

# 导出项目索引，与团队共享
codegraph export stm32-driver-index.cg

# 导入团队共享的索引
codegraph import stm32-driver-index.cg

3. 零文件读取模式

对于高度敏感的代码库，可以开启零文件读取模式，让AI完全依赖索引回答问题，永远不会读取任何实际代码文件：

# 开启零文件读取模式
codegraph config set zero_file_read true

# 关闭零文件读取模式
codegraph config set zero_file_read false

4. 自定义索引规则

在项目根目录创建codegraph.config.json文件，自定义索引行为：

{
"include": ["src/**/*.c", "src/**/*.h", "drivers/**/*.c"],
"exclude": ["**/test/**", "**/examples/**", "**/build/**"],
"indexer": {
"c": {
"enableMacroExpansion": true,
"maxDepth": 10
}
}
}

八、常见问题与解决方案

九、重要注意事项