CodeGraph 完整使用文档

原创于 2026-08-12 10:26:42 发布 · 175 阅读

5 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

AI Agent

CodeGraph 完整使用文档

CodeGraph 是一个为 AI 编程助手预建“代码知识图谱”的本地工具。它不像传统 AI 助手那样在陌生代码库里反复 grep、find、read，而是提前把整个代码库解析成一张结构化地图，让 AI 直接查询图谱获取答案。

简单类比：无 CodeGraph 的 AI 像没有地图的路人，只能边走边问；接入 CodeGraph 后，AI 手持完整的项目地形图。

一、核心概述

1.1 它是什么？

CodeGraph 构建代码库的语义图谱——函数、类、导入、调用链——并通过 45 个 MCP 工具、VS Code 扩展和持久内存层暴露出来。它通过 tree-sitter 解析 37 种编程语言。

核心定位：它不是替代 AI 编程助手，而是给 AI 增加一层“代码地图”基础设施。

1.2 它解决什么问题？

AI 编程助手在理解代码时，通常需要反复进行文件搜索和读取（grep、ls、read），这会消耗大量时间、Token 和费用。

CodeGraph 的目标是改变这一点——通过预先建好的知识图谱，让 AI 助手一次调用就能获得精准的上下文。

1.3 支持的 AI 编程助手

CodeGraph 支持以下 AI 编程助手：

Claude Code
Cursor
Codex CLI
opencode
Hermes Agent
Gemini CLI
Antigravity IDE
Kiro
GitHub Copilot（VS Code、Copilot CLI、JetBrains IDEs）

1.4 支持的语言

支持 20+ 种编程语言：

TypeScript、JavaScript、ArkTS、Python、Go、Rust、Java、C#、VB.NET、PHP、Ruby、C、C++、CUDA、Objective-C、Metal、Swift、Kotlin、Scala、Dart、Lua、Luau、R、Nix、Erlang、CFML、COBOL、Solidity、Terraform/OpenTofu、Svelte、Vue、Astro、Liquid、Pascal/Delphi

二、安装与配置

2.1 安装 CLI

方式一：一键脚本安装（推荐，无需 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

方式二：通过 npm 安装（适用于已有 Node.js 环境）

npm i -g @colbymchenry/codegraph

注意：安装完成后，打开一个新终端再执行后续命令。

升级：任何时候执行 codegraph upgrade 即可升级到最新版本。

2.2 接入 AI 编程助手

在新终端中运行安装器，将 CodeGraph 连接到你使用的 AI 编程助手：

codegraph install

这个命令会自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro。

重要：这一步只连接你的 AI 编程助手——它不会索引你的代码。索引是下一步的事情。

非交互式安装（脚本/CI 环境）：

codegraph install --yes   # 自动检测并配置所有已安装的 agent

2.3 初始化项目索引

进入你的项目目录，构建知识图谱：

cd your-project
codegraph init

这一步会创建 .codegraph/ 目录并一次性构建完整的知识图谱。

2.4 自动同步——无需手动维护

自动同步默认启用。CodeGraph 通过原生文件系统事件（FSEvents/inotify/ReadDirectoryChangesW）监听文件变化，并在每次文件变更后自动增量更新图谱。

你不需要手动运行任何同步命令。图谱始终保持最新。

自动同步的三层保障：

文件监听器：捕获每个源文件的创建/修改/删除，在防抖窗口后触发重新索引（默认 2000ms，可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 调整）
陈旧标记横幅：在防抖窗口期间，MCP 工具响应如果引用了待同步的文件，会在响应前加上 ⚠️ 标记
连接时追赶：MCP 服务器（重）连接时，会快速对工作树进行 (size, mtime) + 内容哈希校对

2.5 手动配置（备选方案）

如果自动安装不适用，也可以手动配置：

npm install -g @colbymchenry/codegraph

在 ~/.claude.json 中添加 MCP 服务器配置：

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

在 ~/.claude/settings.json 中配置自动允许（可选）：

{
  "permissions": {
    "allow": ["mcp__codegraph__*"]
  }
}

2.6 卸载

一键移除 CodeGraph：

codegraph uninstall

这会从每个已配置的 agent 中移除 CodeGraph 的 MCP 服务器配置、指令和权限。项目索引文件（.codegraph/）不会被删除；如需删除，对每个项目执行 codegraph uninit。

三、核心功能

3.1 框架感知路由

CodeGraph 能识别 Web 框架的路由文件，并将 URL 模式与对应的处理函数关联起来。支持的框架包括：

框架	识别模式
Django	`path()`、`re_path()`、`url()`、`include()`
Flask	`@app.route()`、蓝图路由
FastAPI	`@app.get()`、`@router.post()` 等
Express	`app.get()`、`router.post()`
NestJS	`@Controller` + `@Get/@Post`、GraphQL `@Resolver`
Laravel	`Route::get()`、`Route::resource()`
Rails	`get '/x', to: 'users#index'`
Spring	`@GetMapping`、`@PostMapping`
React Router / SvelteKit	路由组件节点
Vue Router / Nuxt	`pages/` 文件路由
Astro	`src/pages/` 文件路由

3.2 跨语言桥接

对于 iOS / React Native / Expo 混合代码库，CodeGraph 能桥接跨语言调用：

Swift ↔ Objective-C：@objc 自动桥接规则
React Native 桥接：Legacy Bridge + TurboModules + Fabric 视图组件
Expo Modules：requireNativeModule() 与原生模块的 DSL 解析
Fabric 视图组件：TS Codegen 规范 → 原生实现类的桥接

3.3 MCP 工具集

CodeGraph 通过 MCP 协议提供 45 个工具。最核心的工具是 codegraph_explore：

codegraph_explore 一次调用即可返回入口点、相关符号、调用路径和代码片段——无需慢速的文件逐个探索。

3.4 核心能力

能力	说明
语义搜索	按含义和意图查找代码
结构搜索	遍历调用图和数据流
影响分析	追踪任何符号的调用者、被调用者和完整影响范围
全文搜索	基于 FTS5 的快速代码搜索
LLM 合成	生成人类可读的回答

四、使用方法

4.1 CLI 命令行查询

不需要启动 AI 编程助手，直接在终端查询：

# 搜索符号
codegraph query <symbol>

# 探索代码结构
codegraph explore "<task>"

# 查看节点信息
codegraph node <symbol-or-file>

# 查看文件树
codegraph files --format tree

4.2 在 AI 编程助手中使用

安装并初始化后，CodeGraph 会自动配置好 MCP 服务器。之后你在 AI 编程助手中提问时，AI 会自动查询图谱。

典型提问方式：

问题类型	示例
定义查询	“`heap_insert` 方法在哪里定义的？”
关系查询	“谁调用了 `AuthService.login`？”
流程查询	“登录功能的数据流是怎样的？”
影响分析	“修改 `useAuth` 这个 Hook 会影响哪些地方？”
架构问题	“请求是如何到达数据库的？”

4.3 查看同步状态

codegraph status

如果有待同步的文件，会显示 ### Pending sync: 部分，列出文件及其编辑时长。

五、前端开发场景

在前端开发场景下，CodeGraph 能深度理解现代前端框架的复杂模式。

5.1 React 项目

支持 TypeScript JSX (.tsx) 解析
追踪组件、Hooks 及 RTK Query 的数据流
识别 React Router 路由配置

实战案例：一个 React+TypeScript 项目（约 80 个文件），同样改一个路由守卫，没用 CodeGraph 前 AI 调了 12 次文件，用了之后只调了 2 次。

5.2 Vue 项目

索引 Vue 组件（.vue 文件）
支持 Pinia 的 Options 和 Setup 两种 Store 形式
追踪 Vuex 的 dispatch 和 commit 调用
识别 Vue Router / Nuxt 的 pages/ 文件路由

5.3 跨语言混合项目

对于 React Native 项目，CodeGraph 能桥接 JS 与原生代码的调用链：

JS 文件调用 React Native 桥接的原生模块
JSX 组件委托给原生视图管理器
调用路径跨越语言边界，而不是停在那里

六、性能数据

CodeGraph 在 7 个真实世界开源代码库（涵盖 7 种语言）上进行了对比测试：

6.1 综合数据

指标	提升幅度
工具调用	平均减少 88%
处理速度	平均加快 53%
Token 消耗	平均减少 62%
成本	平均降低 44%
文件读取	降至 0 次

6.2 具体仓库实测

仓库	有 CodeGraph	无 CodeGraph
VS Code	17s / 3 次调用	52 次调用
中型项目	平均 45 次调用	显著更多

星火甄选系统（基于 RuoYi-Vue 二次开发，~1,300 个源文件）：工具调用次数减少 69%。

七、高级配置

7.1 MCP 服务器配置选项

参数	默认值	说明
`--workspace <path>`	当前目录	要索引的目录（可重复，用于多项目）
`--exclude <dir>`	—	跳过的目录（可重复）
`--max-files <n>`	5000	最大索引文件数
`--graph-only`	off	跳过向量嵌入生成，仅构建图谱，索引速度提升 10-50 倍
`--profile <name>`	all	过滤暴露的 MCP 工具集

7.2 GitHub Action — PR 自动审查

在 CI 中自动生成代码图谱分析评论：

# .github/workflows/codegraph-pr.yml
- name: CodeGraph PR Analysis
  run: |
    codegraph-server --graph-only \
      --run-tool codegraph_pr_context \
      --tool-args '{"baseBranch":"main","format":"markdown"}'

输出内容包括：影响范围、测试缺口、过时文档、建议的审查人。