GitHubhttps://github.com/colbymchenry/codegraph

官方文档https://colbymchenry.github.io/codegraph/

npm 包npx @colbymchenry/codegraph

数据⭐ 26,134 Stars · 1,451 Forks · TypeScript

日期2026-05-26 · 调研人：小K ✨

~35%

更便宜

~57%

更少 tokens

~46%

更快

~71%

更少 tool calls

CodeGraph 深度调研报告

一、项目概览

CodeGraph 是一个本地优先的代码智能工具，将任意代码库转换为可查询的知识图谱，通过 MCP 协议暴露给 AI Coding 代理。

100% 本地运行：数据不离开你的机器，不需要 API key，不需要外部服务。

二、入口地址一览

类型	地址
GitHub	https://github.com/colbymchenry/codegraph
Docs	https://colbymchenry.github.io/codegraph/
npm	`npx @colbymchenry/codegraph`
macOS/Linux	`curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh \| sh`
Windows	`irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 \| iex`

三、实现原理

3.1 整体架构

files → ExtractionOrchestrator (tree-sitter) → DB (nodes/edges/files) ↓ ReferenceResolver (imports, name-matching, framework patterns) ↓ GraphQueryManager / GraphTraverser (callers, callees, impact) ↓ ContextBuilder (markdown/JSON for AI consumption)

四层流水线：

层	职责
Extraction Layer	tree-sitter 解析源码为 AST，语言特定提取器抽取节点和边
Resolution Layer	解析引用——导入→源文件、函数调用→定义、类继承、框架特定模式
Graph Layer	图遍历（callers/callees/impact/trace）
Context Layer	为 AI 消费构建上下文（markdown/JSON）

3.2 核心模块结构（src/）

模块	路径	职责
入口	`src/index.ts`	`CodeGraph` 类，串联所有层
数据库	`src/db/`	SQLite 连接、QueryBuilder、schema.sql
解析	`src/extraction/`	ExtractionOrchestrator、tree-sitter 封装、语言提取器
引用解析	`src/resolution/`	ReferenceResolver、import-resolver、name-matcher、frameworks/
图查询	`src/graph/`	GraphTraverser（BFS/DFS）、GraphQueryManager
上下文	`src/context/`	ContextBuilder、格式化器
全文搜索	`src/search/`	FTS5 查询解析器
文件监听	`src/sync/`	FileWatcher（原生 FSEvents/inotify/RDCW）+ 防抖
MCP 服务	`src/mcp/`	MCPServer、tools、transport、server-instructions
安装器	`src/installer/`	多代理安装器（claude/cursor/codex/opencode）
CLI	`src/bin/codegraph.ts`	命令行入口

3.3 数据模型：NodeKind 和 EdgeKind

NodeKind（节点类型）：

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

EdgeKind（边类型）：

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

3.4 核心技术：tree-sitter 解析

为什么用 tree-sitter：增量解析、跨语言支持、AST 精确提取。

解析引擎：tree-sitter 使用 WASM 格式的语法解析器（.wasm 文件），每个语言一个 grammar，解析结果比正则或简单词法分析精确得多。

Worker 线程：parse-worker.ts 将重型解析任务移出主线程，避免阻塞 UI/CLI。

增量同步：FileWatcher 监听文件变化（原生 OS 事件），防抖 2 秒窗口，只对变更文件增量更新，图谱始终保持最新。

3.5 数据库：SQLite + FTS5

后端：better-sqlite3（原生 Node.js 绑定），回退到 node-sqlite3-wasm（WebAssembly）
WAL 模式：Write-Ahead Logging，支持高并发读取，写入不阻塞读取
FTS5：全文搜索索引，支持按名称模糊搜索符号
数据文件：.codegraph/codegraph.db（项目级，每项目独立）

3.6 引用解析（Reference Resolution）

ReferenceResolver 负责把字符串引用解析为真实图节点：

import-resolver.ts：解析模块导入路径，支持 tsconfig path aliases 和 Cargo workspace member globs
name-matcher.ts：按名称匹配符号（处理重载、歧义）
frameworks/：14 种框架的特定路由识别（Express, Django, Flask, FastAPI, NestJS, Laravel, Rails, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit）

3.7 动态派发桥接（Dynamic Dispatch Synthesis）

tree-sitter 只能提取静态调用边。动态派发（回调、EventEmitter、React setState→render）没有静态边，CodeGraph 通过合成边来桥接：

动态派发类型	实现文件
Callback / Observer	`src/resolution/callback-synthesizer.ts`
React setState → render	合成边（React re-render）
JSX child component	合成边（render → child）
Django ORM descriptor	合成边（QuerySet 链式调用）
EventEmitter	合成边（emit → on）

所有合成边标记为 provenance:'heuristic' + metadata.synthesizedBy + registeredAt，在 trace/node/context 输出中透明显示。

⚠️ 重要原则：部分桥接比不桥接更糟！ 半完成的流会让 AI 读文件来补全，导致更多读取。只有端到端完成的桥接才能把 Read/Grep 降到 0。

3.8 MCP 协议实现

MCP server 通过 stdio 通信，暴露 10 个工具给 AI 代理：

工具	用途
`codegraph_search`	按名称搜索符号
`codegraph_context`	为任务构建上下文（组合 search + node + callers + callees）
`codegraph_trace`	追踪两个符号之间的路径（含动态派发），每跳显示源码内联
`codegraph_callers`	查找谁调用了函数
`codegraph_callees`	查找函数调用了什么
`codegraph_impact`	分析影响半径（更改符号会影响哪些代码）
`codegraph_node`	获取符号详情（含源码）
`codegraph_explore`	一次性探索多个相关符号的源码和关系
`codegraph_files`	获取索引的文件结构（比文件系统扫描快）
`codegraph_status`	检查索引健康度和统计

3.9 多代理安装器

支持 4 种 AI 代理的自动配置，安装器自动检测已安装的代理：

代理	配置文件	指令文件
Claude Code	`~/.claude.json`	`~/.claude/CLAUDE.md`
Cursor	`.cursor/rules/codegraph.mdc`	—
Codex CLI	`~/.codex/codex.json`	`~/.codex/AGENTS.md`
opencode	`opencode.jsonc`	`~/.config/opencode/AGENTS.md`
Hermes Agent	明确支持

3.10 探索预算（Explore Budget）

codegraph_explore 工具根据仓库文件数动态调整输出预算，确保大型仓库不会超出 AI 上下文窗口：

仓库规模	文件数	explore 调用次数	每 call 输出
小型	< 500	1	~18K chars
中型	500 ~ 5,000	2	~28K chars
大型	5,000 ~ 15,000	3	~35K chars
超大型	15,000 ~ 25,000	4	~38K chars
巨型	≥ 25,000	5	~38K chars

原则：更大的层级永远不能比更小的层级获得更少的每文件输出。

四、使用场景

4.1 架构理解

场景：新加入项目，需要理解"请求如何从入口到达数据库"

codegraph_trace from=handleRequest to=getDataFromDB

输出完整的调用路径，每一跳显示源码内联，包括动态派发链。

4.2 影响分析

场景：修改一个底层函数，需要评估影响范围

codegraph_impact symbol=validateToken depth=2

追踪所有调用者，展开两跳影响半径，列出需要同步修改的文件。

4.3 测试影响评估

场景：代码变更后，找出需要运行的测试文件

git diff --name-only HEAD | codegraph affected --stdin --quiet

追踪 import 依赖传递链，找出受影响的测试文件，可接入 CI 钩子。

4.4 路由追踪

场景：了解某个 URL pattern 对应哪个处理器

codegraph callers /api/users

自动识别 Django/Flask/Rails 等框架的路由配置，找出绑定到 URL 的处理器。

4.5 大型代码库探索

场景：VS Code 级的大型代码库（~10k 文件）问架构问题

-85%

Tool calls

-78%

Tokens

-52%

时间

-26%

成本

五、使用案例详解

5.1 Excalidraw 案例（TypeScript/React，643 文件）

问题："Excalidraw 如何渲染和更新画布元素？"

完整流程跨越三个 React 边界（6 跳）：

mutateElement → triggerUpdate (callback) → triggerRender (React re-render) → render (JSX child) → StaticCanvas → renderStaticScene

配置	时长	Read	Grep	codegraph
无 CodeGraph	115–139s	9–10	10–11	0
修复后（budget+合成边）	64–112s	0–2	2–4	3–10
trace-first 优化	51–74s	0–2	0–4	3–4

最佳结果：0 Read / 0 Grep / 3 codegraph 调用 / 51s，4 次运行中 2 次完全清洁。

5.2 Tokio 案例（Rust，790 文件）

问题："Tokio 如何调度和运行异步任务？"

-82%

成本 $2.41→$0.42

-86%

Tokens 2.6M→379K

-71%

时间 3m→53s

-92%

Tool calls 53→4

5.3 VS Code 案例（TypeScript，~10k 文件）

问题："扩展主机如何与主进程通信？"

-26%

成本 $0.80→$0.60

-78%

Tokens 2.8M→601K

-52%

时间 2m26s→1m10s

-85%

Tool calls 55→8

六、Benchmark 数据汇总

测试方法：Claude Code (headless, Opus 4.7)，同一问题 WITH vs WITHOUT CodeGraph，各 4 次运行取中位数。

代码库	语言/规模	成本	Tokens	时间	Tool calls
VS Code	TypeScript · ~10k 文件	-26%	-78%	-52%	-85%
Excalidraw	TypeScript · ~640	-52%	-90%	-73%	-96%
Django	Python · ~3k	-12%	-36%	-19%	-53%
Tokio	Rust · ~790	-82%	-86%	-71%	-92%
OkHttp	Java · ~645	-2%	-13%	-31%	-45%
Gin	Go · ~110	-21%	-34%	-27%	-40%
Alamofire	Swift · ~110	-47%	-64%	-48%	-83%
平均	—	~35%	~57%	~46%	~71%

七、快速上手

安装

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

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

# Node.js 环境
npx @colbymchenry/codegraph

初始化项目

cd your-project
codegraph init -i

配置 AI 代理（自动）

codegraph install
# 自动检测并配置 Claude Code, Cursor, Codex CLI, opencode, Hermes Agent

常用命令

codegraph status              # 查看索引统计
codegraph search <name>      # 搜索符号
codegraph context <task>     # 为任务构建上下文
codegraph trace <from> <to>  # 追踪调用路径
codegraph callers <symbol>   # 查看调用者
codegraph impact <symbol>    # 影响半径
codegraph affected --stdin    # 找出受影响的测试
codegraph sync                # 增量同步
codegraph serve --mcp         # 启动 MCP 服务器

八、与 Hermes Agent 的关系

CodeGraph 明确支持 Hermes Agent 作为目标代理之一。Hermes Agent 是一个多代理协作框架，CodeGraph 为其提供代码知识图谱能力。

在 Hermes Agent 的多代理架构中，探索代理（Explore Agent）可以使用 CodeGraph 的 MCP 工具直接查询图谱，而不是派生出文件扫描子代理，从而显著降低 token 消耗和执行时间。

九、核心亮点总结

亮点	说明
预索引知识图谱	把代码库预先索引为 SQLite 图数据库，AI 查询代替文件扫描
动态派发桥接	合成边覆盖 React/回调/EventEmitter 等动态调用场景
Framework 感知	14 种 web 框架路由自动识别，URL pattern → 处理器直接映射
零配置	语言自动检测，node_modules/第三方库自动过滤，无需配置文件
MCP 原生	为 Claude Code/Cursor/Codex/opencode/Hermes Agent 原生设计，开箱即用
完全本地	数据不离开你的机器，不需要 API key