第一部分 概述

CodeGraph 是一个为 AI 编码代理设计的语义代码智能工具，能够显著提升 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity 和 Kiro 等代理的代码理解和导航能力。它通过预索引的代码结构图，将符号关系、调用图和代码结构以 SQLite 数据库的形式存储在本地，使代理能够通过图形查询而非文件扫描来回答架构问题。

在实测中，CodeGraph 实现了约 16% 的成本节约、58% 的工具调用减少和 22% 的速度提升，整个过程完全在本地运行，不依赖外部服务。它支持 20 多种编程语言，包括自动识别框架路由、跨语言桥接等高级特性，能够为现代多语言项目提供完整的代码结构视图。

第二部分 核心性能优势

CodeGraph 最大的价值在于它如何改变 AI 代理通过代码库探索的方式。传统的代理在回答架构问题时，会启动 Explore 代理使用 grep、glob 和 Read 工具扫描文件，每次工具调用都消耗 tokens。CodeGraph 则为这些代理提供了一个预先构建的知识图谱，使它们能够直接查询符号关系、调用图和代码结构，而不是逐文件扫描。

基于 7 个真实开源代码库的基准测试结果非常显著：在 7 种不同语言的代码库中测试，代理回答架构问题时相比不使用 CodeGraph 的情况，平均实现了 16% 的成本节约、47% 的 tokens 减少、22% 的速度提升和 58% 的工具调用减少。

对于大规模项目如 VS Code（约 10,000 个 TypeScript 文件），CodeGraph 实现了 64% 的 tokens 减少和 81% 的工具调用减少。值得注意的是，它不仅在大型项目中表现出色，在中小型项目中同样有效。例如，Swift 项目 Alamofire（约 110 个文件）实现了 64% 的 tokens 减少和 58% 的工具调用减少，成本节省达到 40%。

这种性能提升的原理很直接：没有 CodeGraph 时，代理需要通过各种发现操作（grep/read/ls）找到正确的代码片段，然后才能回答问题。而有了 CodeGraph 的索引，代理可以直接获取相关信息，通常只需一次工具调用即可获得关联的源代码。

第三部分 关键功能特性

3.1 智能上下文构建与代码搜索

CodeGraph 的核心能力是在单次工具调用中返回入口点、相关符号和代码片段。这意味着回答"某功能如何工作"这类问题时，无需启动昂贵的探索代理。返回的相关源代码按文件分组，同时提供关系图和影响范围分析。这一特性让代理能够覆盖动态调度跳转，这是传统 grep 工具无法做到的 — 例如 JSX 重新渲染或接口到实现转换的场景。

在代码搜索方面，基于 FTS5 引擎的全文搜索功能允许在整个代码库中按名称快速查找代码，无需依赖文件名或手动扫描目录结构。在进行代码修改前，codegraph_impact 可以分析某个符号的完整影响半径 — 通过追踪调用者和被调用者，开发者可以清楚地知道修改某个方法会影响到哪些代码路径。

3.2 自动同步机制

文件监听机制使用原生操作系统事件（macOS 的 FSEvents、Linux 的 inotify、Windows 的 ReadDirectoryChangesW），配合防抖自动同步机制，确保代码图在编码过程中始终保持最新状态。整个过程无需任何配置，完全自动工作。

自动同步通过三层机制保证一致性：文件监听器在捕获变更后触发防抖同步（默认 2 秒静默窗口，可通过 CODEGRAPH_WATCH_DEBOUNCE_MS 调整）；同步进行期间涉及到的文件会在 MCP 工具响应中附带过期提示；MCP 服务器重新连接时会执行快速 (size, mtime) + 内容哈希的协调，确保离线期间的编辑被吸收。

3.3 跨语言桥接

这是 CodeGraph 区别于其他静态分析工具的重要特性。它支持 iOS/React Native/Expo 的多语言项目桥接，解决了静态解析在语言边界处的盲区。包括 Swift 与 Objective-C 互调、React Native Legacy Bridge、TurboModules、原生向 JS 的事件发射、Expo Modules、Fabric 视图组件以及 Legacy Paper 视图管理器等。

这些桥接关系通过带有 provenance:'heuristic' 标记和 metadata.synthesizedBy: 字段的边连接，代理可以清楚地看到跨语言调用是如何进入图谱的。

3.4 框架感知路由

CodeGraph 能够识别 Web 框架的路由文件，并发出通过 references 边链接到处理类或函数的 route 节点。这意味着查询视图或控制器的调用者时，会显示绑定它的 URL 模式。

第四部分 技术原理

CodeGraph 的工作流程分为四个阶段：

1. 提取 — 使用 tree-sitter 解析源代码生成抽象语法树（AST）。语言特定的查询提取节点（函数、类、方法）和边（调用、导入、继承、实现）。

2. 存储 — 所有内容存储在本地 SQLite 数据库（.codegraph/codegraph.db）中，并启用 FTS5 全文搜索。

3. 解析 — 提取完成后进行引用解析，包括函数调用到定义、导入到源文件、类继承以及框架特定模式的解析。

4. 自动同步 — MCP 服务器使用原生 OS 文件事件监听项目。更改被防抖后（默认 2 秒静默窗口），过滤为仅源文件，然后增量同步。

┌───────────────────────────────────────────────────────────────────┐
│                            AI 代理                                │
│   "How does a request reach the database?"                        │
│       直接调用 CodeGraph 工具 — 无需 Explore 子代理               │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                       │
│       explore · search · callers · callees · impact · node        │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite 知识图谱                             │
│          symbols · edges · files · FTS5 全文搜索                  │
└───────────────────────────────────────────────────────────────────┘

CodeGraph 采用零配置设计，语言支持根据文件扩展名自动识别。默认排除依赖/构建/缓存目录（node_modules、vendor、dist、build、target 等）、.gitignore 中的内容以及超过 1 MB 的大文件。如需自定义排除，添加到 .gitignore；如需将默认排除的目录重新纳入索引，使用否定语法 !vendor/。

第五部分 快速开始与安装

5.1 安装 CLI

CodeGraph 不需要 Node.js 环境，它自带运行时。对于 macOS 和 Linux 系统：

bash
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Windows 用户（PowerShell）：

powershell
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

如已安装 Node.js，也可以使用 npm：

bash
npm i -g @colbymchenry/codegraph

5.2 连接代理与初始化项目

在新终端中运行安装器连接 CodeGraph 到你使用的代理：

bash
codegraph install

这个命令会自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro 等代理。安装 CLI 本身并不会连接代理，运行 codegraph install 才是实际的连接步骤。

然后进入项目目录初始化：

bash
cd your-project
codegraph init -i

-i 参数表示在初始化的同时建立索引。一次全局的 codegraph install 适用于每个你打开的项目，无需每个项目重新运行安装器。当项目目录中存在 .codegraph/ 时，代理会自动使用 CodeGraph 工具。

安装脚本还提供非交互选项用于脚本和 CI 环境：

bash
codegraph install --yes                              # 自动检测代理，全局安装
codegraph install --target=cursor,claude --yes       # 显式指定目标列表
codegraph install --target=auto --location=local     # 检测到的代理，项目本地安装
codegraph install --print-config codex               # 仅打印配置片段，不写文件

卸载也同样简单，一条命令从所有代理中移除：

bash
codegraph uninstall

第六部分 CLI 命令参考

CodeGraph 提供了一套完整的命令行工具，覆盖从安装配置到索引管理的各个环节。

6.1 完整命令列表

bash
codegraph                         # 运行交互式安装器
codegraph install                 # 运行安装器（显式调用）
codegraph uninstall               # 从代理中移除 CodeGraph（安装的逆操作）
codegraph init [path]             # 在项目中初始化（--index 同时建立索引）
codegraph uninit [path]           # 从项目中移除 CodeGraph（--force 跳过确认）
codegraph index [path]            # 全量索引（--force 重新索引，--quiet 减少输出）
codegraph sync [path]             # 增量更新
codegraph status [path]           # 显示统计信息
codegraph query <search>          # 搜索符号（--kind, --limit, --json）
codegraph files [path]            # 显示文件结构（--format, --filter, --max-depth, --json）
codegraph callers <symbol>        # 查找调用某函数/方法的代码（--limit, --json）
codegraph callees <symbol>        # 查找某函数/方法调用的代码（--limit, --json）
codegraph impact <symbol>         # 分析修改某符号会影响的代码（--depth, --json）
codegraph affected [files...]     # 查找受变更影响的测试文件
codegraph serve --mcp             # 启动 MCP 服务器
codegraph upgrade [version]       # 更新到最新版本（--check, --force）

6.2 affected 命令详解

codegraph affected 命令通过追踪导入依赖关系，找出哪些测试文件会受到源文件变更的影响。这在 CI/CD 流程中非常有用，可以只运行相关的测试而不是全量测试。

bash
codegraph affected src/utils.ts src/api.ts         # 直接传递文件参数
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道输入
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件匹配模式

bash
#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

第七部分 MCP 配置与工具详解

7.1 MCP 工具列表

当作为 MCP 服务器运行时，CodeGraph 向代理暴露了一组专用工具：

7.2 手动 MCP 配置

如果需要手动配置 MCP 服务器（而不是使用 codegraph install），可以按以下步骤操作。首先全局安装：

bash
npm install -g @colbymchenry/codegraph

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

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

json
{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_explore",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

7.3 代理工具指导机制

CodeGraph 的 MCP 服务器在 initialize 响应中自动向代理传递使用指导，无需管理单独的说明文件。指导内容包括：

• 将 CodeGraph 视为已构建的索引，用 grep/read 循环只是重复已完成的工作
• 将返回的源代码视为已读取的内容
• 根据意图选择合适的工具：explore 用于大多数问题、search 仅定位符号、callers/callees 用于调用流程、impact 用于修改前分析
• 检查编辑后的过期提示
• 如果 .codegraph/ 不存在，主动提议运行 codegraph init -i

第八部分 支持的平台与语言

CodeGraph 为所有桌面操作系统提供自包含构建（包括捆绑的 Node 运行时），支持 Intel/AMD (x64) 和 ARM (arm64) 架构，Windows、macOS 和 Linux 均可运行。

8.1 支持的编程语言

8.2 跨文件覆盖率

影响范围和变更影响查询的质量取决于底层依赖图的完整性，因此 CodeGraph 对覆盖率进行了实际测量而非单纯声明。覆盖率定义为"具有至少一个已解析跨文件依赖的符号承载源文件的百分比"。

第九部分 高级用法：库嵌入

CodeGraph 可以直接嵌入到应用程序中。npm 包导出了编程 API，允许在自己的进程中使用 CodeGraph 类，适合嵌入到 Electron 主进程等场景。

9.1 编程接口

typescript
import CodeGraph from '@colbymchenry/codegraph';
// CommonJS 也支持：
//   const { CodeGraph } = require('@colbymchenry/codegraph');

const cg = await CodeGraph.init('/path/to/project');
// 或者打开已存在的索引：
//   const cg = await CodeGraph.open('/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 context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // 文件变更时自动同步
cg.unwatch(); // 停止监听
cg.close();

对于需要直接驱动图谱的调用者，同一入口点还导出了底层组件：DatabaseConnection、QueryBuilder、getDatabasePath、initGrammars / loadGrammarsForLanguages 和 FileLock。

9.2 嵌入要求

使用库嵌入模式需要注意以下几点：

• 必须从 npm 安装（npm i @colbymchenry/codegraph），以便获取匹配的平台包（内含编译好的库及其依赖）
• API 运行在你的运行时上，需要 Node 22.5+ 以使用内置的 node:sqlite（Electron 需要其捆绑的 Node 版本为 22.5+）
• TypeScript 类型随包提供，需要保持 @types/node 可用并设置 skipLibCheck: true

第十部分 常见问题排查

"CodeGraph not initialized" — 首先在项目目录运行 codegraph init。

索引速度慢 — 检查 node_modules 等大目录是否被排除，使用 --quiet 减少输出开销。

MCP 报告 database is locked — 当前版本不应该遇到这个问题，因为 CodeGraph 捆绑了自己的 Node 运行时，并使用 Node 内置的 WAL 模式 SQLite，并发读操作不会阻塞写入。如果仍然遇到，可能需要重新安装最新版本，或检查项目是否位于网络共享/WSL2 /mnt 上 — 这些场景下 WAL 可能无法启用。

MCP 服务器未连接 — 确保项目已初始化/索引，验证 MCP 配置中的路径，并检查 codegraph serve --mcp 是否可以从命令行正常运行。

缺失符号 — MCP 服务器在保存时会自动同步，等待几秒钟。如果需要，可以手动运行 codegraph sync。检查文件的语言是否被支持，以及是否位于 .gitignore 或默认排除的目录中。

在 Windows 和 WSL 之间共享检出 — 不要让两边都指向同一个 .codegraph/ 目录，因为后台服务锁和 SQLite 索引与写入它们的操作系统绑定，跨 WSL2/Windows 文件系统边界的 SQLite 锁定不可靠。通过设置 CODEGRAPH_DIR 环境变量让每边使用各自的索引目录（如 CODEGRAPH_DIR=.codegraph-win），CodeGraph 在索引和监听时会跳过相邻的 .codegraph-* 目录，两边互不干扰。

本文内容来源于 CodeGraph GitHub 仓库