CodeGraph 详细调研报告

调研时间：2026-07-21
来源：GitHub 仓库、官方文档站、博客园第三方评测

一、CodeGraph 是什么

CodeGraph 是一个本地优先的代码智能工具（local-first code-intelligence tool）。它用 tree-sitter 解析你的代码库，将所有符号、关系和文件存入本地 SQLite 数据库，形成一个可查询的知识图谱，通过 MCP（Model Context Protocol）、CLI 和 TypeScript 库对外暴露。

它的核心使命：让 AI 编程助手不必逐文件扫描就能回答代码结构问题。

• 仓库：colbymchenry/codegraph
• 官网：https://colbymchenry.github.io/codegraph/
• GitHub 星数：61,130（截至 2026-07-21）
• 创建时间：2026-01-18
• 语言：C / TypeScript（自包含 Node.js 运行时）
• 许可证：MIT
• 主要受支持代理：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro

口号：Understand any codebase as a graph（以图谱理解任何代码库）

二、解决什么问题

AI Agent 的「探索税」

当 AI 编程助手（如 Claude Code）回答"这个项目的认证流程是怎样的"时，传统流程是：

1. 启动 Explore 子 Agent
2. 用 find 扫描目录结构
3. 用 grep 搜索关键词
4. 用 Read 逐个读取文件
5. 每一步都消耗 token 和时间

在大型项目中，这个过程可能需要 20-80 次工具调用。Agent 把大部分预算花在"找代码"而非"理解和改代码"上。

CodeGraph 的做法：提前将代码库构建为知识图谱。Agent 直接查询数据库，一次调用即可获得答案——通常零文件读取。

实测收益（7 个真实项目基准测试，Claude Opus 4.7，每组 4 次取中位数）

平均值：省 35% 费用、减少 59% token、减少 70% 工具调用、快 49%。

关键规律：项目越大，收益越明显。VS Code 上工具调用从 23 次降到 7 次，Token 从 140 万降到 39 万。

三、工作原理（四阶段流水线）

files → Extraction (tree-sitter) → DB (nodes/edges/files)
            ↓
      Resolution (imports, name-matching, framework patterns)
            ↓
      Graph queries (callers, callees, impact)
            ↓
      Context building (markdown / JSON for AI consumption)

1. 提取（Extraction）

tree-sitter 将源码解析为 AST，语言特定的查询规则提取节点和边。繁重的解析在主线程外运行。

2. 存储（Storage）

所有数据存入本地 SQLite 数据库（.codegraph/codegraph.db），使用 FTS5 全文搜索，WAL 模式（并发读不阻塞写）。使用 Node 内置的 node:sqlite。数据不离开你的机器。

3. 解析（Resolution）

• 函数调用 → 定义
• 导入 → 源文件
• 类继承
• 框架特定模式（如路由）
• 动态分派边界（回调、观察者、React 重渲染、JSX 子组件）由合成器桥接，使执行流端到端连通

4. 自动同步（Auto-Sync）

MCP 服务器使用操作系统原生文件事件监控代码变化： - macOS: FSEvents - Linux: inotify - Windows: ReadDirectoryChangesW

变更经过 2 秒静默窗口防抖，只处理源文件，增量同步。你改代码，图谱自动更新，无需配置。

四、知识图谱结构

节点类型（Node Kinds）

file、module、class、struct、interface、trait、protocol、function、method、property、field、variable、constant、enum、enum_member、type_alias、namespace、parameter、import、export、route、component

边类型（Edge Kinds）

contains、calls、imports、exports、extends、implements、references、type_of、returns、instantiates、overrides、decorates

溯源（Provenance）

大多数边直接来自 AST。少数动态分派边界由合成生成，标记为 provenance: 'heuristic'，在 explore 和节点轨迹中内联展示，Agent 可看到连接的确切来源。

五、MCP 工具体系

CodeGraph 作为 MCP Server 运行（codegraph serve --mcp），由代理自动启动，无需手动运行。

默认暴露的核心工具

codegraph_explore —— 唯一默认暴露的工具。它是 Read 等价物： - 输入自然语言问题或一组符号/文件名 - 返回相关符号的逐行带行号源码（按文件分组，与 Read 工具相同的格式） - 同时返回符号间的调用路径（包括 grep 无法追踪的动态分派跳转：回调、React 重渲染、JSX 子组件） - 以及影响范围总结（blast radius） - 一次调用通常就能回答整个问题

设计哲学：暴露一个强大的工具胜过暴露一堆窄工具——更少的误选，Agent 用它回答问题和编辑代码都更有效。

7 个附加工具（默认不列出，但功能完整）

启用附加工具：设置环境变量 CODEGRAPH_MCP_TOOLS=explore,node,search,callers

六、安装与上手（3 步）

第 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

已有 Node.js 的用户：

npm i -g @colbymchenry/codegraph

# 或一行下载并运行

npx @colbymchenry/codegraph

安装器会将 codegraph 加入 PATH，但当前 shell 不会刷新，需打开新终端。

第 2 步：连接你的 AI 代理

codegraph install

交互式引导： - 自动检测已安装的代理（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro） - 为每个选中的代理写入 MCP 服务器配置 - 为支持指令文件的代理（CLAUDE.md / AGENTS.md / GEMINI.md）写入一段 CodeGraph 指令 - 为 Claude Code 设置自动允许权限

注意：此步骤只连接代理，不索引代码。

非交互式（CI/脚本）：

codegraph install --yes                              # 自动检测，全局安装
codegraph install --target=cursor,claude --yes       # 指定目标
codegraph install --target=auto --location=local     # 项目本地

第 3 步：初始化每个项目

cd your-project
codegraph init

一行命令创建 .codegraph/ 目录并构建完整图谱。之后文件监视器自动保持图谱最新。只需为每个项目运行一次。

完毕。重启 AI 代理后，Agent 检测到 .codegraph/ 会自动使用 CodeGraph 工具。

手动配置方式（Claude Code 示例）

~/.claude.json：

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

~/.claude/settings.json（自动允许所有 CodeGraph 工具）：

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

七、CLI 命令完整列表

codegraph                         # 交互式安装器
codegraph install                 # 运行安装器（显式）
codegraph uninstall               # 从所有代理移除 CodeGraph
codegraph init [path]             # 初始化项目 + 构建图谱（一步到位）
codegraph uninit [path]           # 从项目移除 CodeGraph（--force 跳过确认）
codegraph index [path]            # 从零全量重建（--force --quiet --verbose）
codegraph sync [path]             # 增量更新（--quiet）
codegraph status [path]           # 查看统计（--json）
codegraph unlock [path]           # 移除阻碍索引的陈旧锁文件
codegraph query <search>          # 搜索符号（--kind --limit --json）
codegraph explore <query>         # 一次获取相关符号源码+调用路径
codegraph node <symbol|file>      # 单个符号源码+调用者，或读文件
codegraph files [path]            # 查看文件结构（--format --filter --pattern --max-depth --json）
codegraph callers <symbol>        # 查找谁调用了某函数/方法（--limit --json）
codegraph callees <symbol>        # 查找某函数/方法调用了什么（--limit --json）
codegraph impact <symbol>         # 分析修改某符号的影响范围（--depth --json）
codegraph affected [files...]     # 查找受变更影响的测试文件
codegraph daemon                  # 管理后台守护进程（别名 daemons）
codegraph telemetry [on|off]      # 查看或更改匿名使用遥测
codegraph upgrade [version]       # 更新到最新版本（--check --force）
codegraph version                 # 打印版本
codegraph help [command]          # 帮助

查询命令都支持 --json 机器可读输出。

CI 中使用（影响范围测试）

git diff --name-only HEAD | codegraph affected --stdin --quiet | xargs npx vitest run

追踪导入依赖关系，找出哪些测试文件受变更影响，只运行相关测试。

八、配置

零配置默认：语言支持根据文件扩展名自动识别，遵循 .gitignore，无需写任何配置。

可选配置文件 codegraph.json（置于项目根目录）：

{
  "exclude": ["static/", "**/vendor/**"],       // 排除已跟踪目录
  "include": ["Tools/", "Local/typescript/"],   // 强制纳入 gitignored 源码
  "extensions": { ".dota_lua": "lua", ".tpl": "php" },  // 自定义扩展名映射
  "includeIgnored": ["packages/", "services/"]  // 索引嵌套 git 仓库
}

默认跳过： - 依赖/构建/缓存目录：node_modules、vendor、dist、build、target、.venv、Pods、.next 等 - .gitignore 中的内容 - 大于 1MB 的文件

九、支持的语言（24 种，自动识别）

十、框架感知路由

CodeGraph 不只理解代码结构，还理解 Web 框架的路由。它能识别路由文件，把 URL 模式链接到对应处理函数。查询某 Controller 的调用者时，同时显示绑定的 URL 路径。

支持框架：Django、Flask、FastAPI、Express、NestJS、Laravel、Drupal、Rails、Spring、Gin/chi/gorilla、Axum/actix/Rocket、ASP.NET、Vapor、React Router/SvelteKit 等。

十一、作为 TypeScript 库使用

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 context = await cg.buildContext('fix login bug', {
  maxNodes: 20, includeCode: true, format: 'markdown'
});

cg.watch();   // 自动同步文件变化
cg.close();

十二、平台支持与卸载

支持平台

• Windows (x64, arm64)
• macOS (x64, arm64)
• Linux (x64, arm64)

每个版本附带自包含构建（捆绑 Node 运行时，无需编译）。

卸载

codegraph uninstall           # 从所有代理移除配置
codegraph uninit [path]       # 从项目移除索引（--force 跳过确认）

uninstall 删除 MCP 配置、指令、权限，但保留项目索引 .codegraph/。

十三、适用场景

1. 大型代码库：项目越大，探索税越重，收益越明显
2. 高频 AI 编程：每天用 Claude Code / Cursor 写代码，token 费用是实际开销
3. 团队协作：新人用 AI Agent 理解陌生代码库，预索引大幅缩短理解时间
4. CI/CD 集成：codegraph affected 精确运行受影响测试，跳过无关测试

十四、生态系统中的相关项目

GitHub 上还有多个相关的 codegraph 项目：

十五、技术细节总结

• TypeScript 编写，自包含 Node.js 运行时，无需编译
• tree-sitter 解析源码，语言特定查询提取符号和关系
• SQLite + WAL 模式存储，并发读不阻塞写
• FTS5 全文搜索引擎
• 原生文件监控 + 2 秒防抖增量同步
• 零配置：遵循 .gitignore，跳过 >1MB 文件
• 提取是确定性的——来自 AST，绝不 LLM 摘要
• MIT 开源协议
• 100% 本地运行，无 API 密钥，无外部服务

总结

CodeGraph 是目前最热门的代码知识图谱工具（6 万星），专为 AI 编程助手设计。它通过 tree-sitter 将代码库解析为符号和关系图谱，存入本地 SQLite，通过 MCP 暴露给各类 AI 代理（Claude Code、Cursor、Codex 等）。实测在大型项目中可减少 70% 工具调用、节省 35% 费用、加速 49%。安装只需 3 步（安装 CLI、连接代理、初始化项目），零配置开箱即用，支持 24 种语言，100% 本地运行，无外部依赖。