CodeGraph：让 AI Agent 真正读懂你的代码

代码知识图谱引擎——把代码变成可查询、可追踪、可推理的结构化图谱

GitHub：github.com/colbymchenr… 文档站：colbymchenry.github.io/codegraph/ npm：www.npmjs.com/package/@co…

---

为什么需要 CodeGraph？

你一定经历过这些场景：

• 重构前不敢动手——改一个函数，不知道下游有多少调用方，只能全局搜索字符串碰运气
• AI Agent 瞎改代码——给 AI 一段源码，它不知道上下游依赖，改完引入一堆隐式 bug
• grep / ripgrep 只能搜文本，搜不到"谁调用了这个接口的实现类"
• IDE 的"查找引用"在跨框架（如 React Native Bridge）时彻底失效

CodeGraph 做的事情很简单：把你的代码解析成一棵知识图谱——函数、类、路由、组件都是节点，调用关系、导入依赖都是边。然后你就可以像查数据库一样查询代码。

它不是一个静态分析工具，而是一个为 AI Agent 设计的代码智能层：

• 20+ 语言自动识别，零配置
• 框架感知：识别 14+ Web 框架的路由，链接 URL 到 Handler
• 跨语言桥接：Swift↔ObjC、React Native Bridge、TurboModules 都能追踪
• 100% 本地运行，SQLite 存储，无数据外泄

一句话总结：grep 搜文本，IDE 跳定义，CodeGraph 追踪关系。

---

5 分钟快速上手

安装

# npm 全局安装（需要 Node.js）
npm i -g @colbymchenry/codegraph

# 或零安装运行
npx @colbymchenry/codegraph

# macOS / Linux（无需 Node.js，自带运行时）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows PowerShell（无需 Node.js，自带运行时）
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

CodeGraph bundles its own Node runtime——无需编译、无需本地 Node.js，开箱即用。

初始化 + 索引

# 一步完成（推荐）
codegraph init -i

# 或分步执行
codegraph init          # 初始化（生成 .codegraph/ 目录）
codegraph index         # 全量索引

跑完这两步，你的代码已经是图谱了。试试：

codegraph query UserService          # 搜符号
codegraph callers createUser         # 查谁调用了它
codegraph impact TokenService        # 改它会影响谁

零配置——node_modules、dist、build、.gitignore 规则全部自动排除，无需手动设置。

---

核心概念：节点、边、图谱

理解 CodeGraph 只需三个概念：

概念	说明	示例
节点	代码中的符号	function createUser、class UserService、route GET /api/users
边	符号间的关系	createUser 调用了 hashPassword、UserService 导入了 Database
图谱	节点 + 边的集合	存储在 .codegraph/codegraph.db（SQLite）

节点类型

类型	说明
function	独立函数
method	类方法
class	类
interface	接口
component	Vue/React 组件
route	框架路由
variable / constant	变量与常量
import	导入依赖
field	类字段
type_alias	类型别名
enum / enum_member	枚举及成员

支持语言（20+）

TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Lua/Luau、Liquid、Pascal/Delphi、Objective-C（部分）——基本覆盖主流语言。

---

实战场景

场景一：安全重构——改代码前先看影响范围

"我要改 TokenService 的接口，但不知道影响有多大。"

工作流：impact → trace → affected

# 1. 看影响半径（谁会受影响，深度 3 层）
codegraph impact TokenService --depth 3

# 2. 追踪关键调用路径（从入口到目标，看具体怎么调过去的）
codegraph trace RequestHandler TokenService

# 3. 找到需要跑的测试
codegraph affected src/token-service.ts --quiet

如果走 CI，一行命令自动跑受影响的测试：

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

效果：不再"改一行炸一片"，重构前心中有数。

---

场景二：AI Agent 接入——让 AI 真正理解代码上下文

"AI Agent 改代码总是漏掉依赖，怎么破？"

工作流：MCP 集成 → context / explore

第一步，把 CodeGraph 作为 MCP Server 接入你的 AI Agent：

# 启动 MCP 服务
codegraph serve --mcp

配置文件（以 ~/.codebuddy/mcp.json 为例）：

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

或用交互式安装自动配置：

codegraph install          # 交互式，自动检测已安装的 Agent
codegraph install --yes    # 非交互式

支持的 Agent：Claude Code、Cursor、Codex CLI、opencode、Gemini CLI、Kiro 等。

接入后，AI Agent 就能：

# "这个认证流程是怎么工作的？"——自动组合搜索+调用链+源码
codegraph context "用户认证流程" --max-nodes 20

# "看看这几个符号的源码和它们的关系"——多符号聚合浏览
codegraph explore UserService TokenService AuthMiddleware

# "改这个函数会影响谁？"——影响分析
codegraph impact createUser --depth 2

关键区别：没有 CodeGraph 时，AI Agent 只能 grep 搜文本或 Read 文件；有了 CodeGraph，AI 能理解调用链、依赖关系、影响范围——这才是真正的代码智能。

---

场景三：跨框架追踪——从 API 路由到数据库

"一个请求从 URL 进来，经过中间件、Controller、Service，最终到数据库，我想看完整链路。"

CodeGraph 的框架感知路由能力可以识别 14+ 框架的路由定义，把 URL 映射到 Handler：

框架	识别模式
Express	app.get()、router.post()
NestJS	@Controller + @Get/@Post、GraphQL @Resolver
FastAPI	@app.get()、@router.post()
Django	path()、re_path()
Spring	@GetMapping、@PostMapping
Rails	get '/x', to: 'users#index'
Gin / chi	r.GET()、router.HandleFunc()
更多	Flask、Laravel、Drupal、Axum、ASP.NET、Vapor、SvelteKit...

# 追踪：从 HTTP 入口到数据库查询
codegraph trace "GET /api/users" DatabaseQuery

跨语言也没问题——React Native 项目中，JS 调用 NativeModules.X.fn()，CodeGraph 能追踪到原生端的 RCT_EXPORT_METHOD 或 TurboModule 实现：

边界	桥接方式
Swift → ObjC	@objc 自动桥接规则
React Native Bridge	NativeModules.X.fn() → RCT_EXPORT_METHOD
TurboModules	Native<X>.ts 规范接口 → 原生实现
Expo Modules	Expo DSL 解析 → 名称匹配
Fabric 视图	JSX → Codegen 规范 → 约定名称后缀查找

效果：grep 做不到的跨语言、跨框架追踪，CodeGraph 可以。

---

CLI 命令速查

命令	说明	常用选项
codegraph init [-i]	初始化项目	-i 同时执行索引
codegraph index [--force] [--quiet]	全量索引	--force 强制重建
codegraph sync	增量同步	—
codegraph status	索引状态和统计	—
codegraph query <词>	符号搜索	--kind function/class/interface、--limit N、--json
codegraph callers <符号>	查谁调用了它	--limit N、--json
codegraph callees <符号>	查它调用了谁	--limit N、--json
codegraph trace <起> <止>	追踪调用路径	—
codegraph impact <符号>	变更影响分析	--depth N（默认 2）、--json
codegraph affected <文件...>	受影响的测试文件	--stdin、--filter GLOB、--depth N
codegraph context <描述>	为任务构建上下文	--max-nodes N、--format FMT
codegraph files	项目文件结构	--filter GLOB、--max-depth N
codegraph serve --mcp	启动 MCP Server	—
codegraph install	交互式 Agent 安装	--target、--location、--yes
codegraph uninit [--force]	移除 .codegraph/	--force 跳过确认

---

MCP 工具一览

MCP 工具	对应 CLI	说明
codegraph_search	query	按名称搜索符号，返回位置和签名
codegraph_context	context	为任务构建上下文，组合 search + node + callers + callees
codegraph_trace	—	追踪两个符号间的完整调用路径，每跳附带源码，能跟踪动态分发
codegraph_explore	—	多符号源码聚合浏览，一次返回多个符号的源码 + 关系图
codegraph_callers	callers	查找谁调用了指定符号
codegraph_callees	callees	查找指定符号调用了谁
codegraph_impact	impact	分析变更影响范围
codegraph_node	—	获取符号详情（可含源码）
codegraph_files	files	获取项目文件结构
codegraph_status	status	查看索引状态

MCP 工具选择指南

你想做什么	用哪个工具
"X 是怎么工作的？" / 架构理解	codegraph_context
"X 怎么到达 Y？"	codegraph_trace
浏览多个相关符号的源码	codegraph_explore
按名称找符号	codegraph_search
单跳调用链	codegraph_callers / codegraph_callees
编辑前检查影响范围	codegraph_impact
获取单个符号源码	codegraph_node

---

进阶：自动同步与编程 API

三层同步机制

MCP Server 运行时，索引与代码始终一致：

层级	机制	说明
1	文件监视 + 防抖	原生 OS 事件，2 秒防抖窗口，批量编辑合并为一次同步
2	过期标记	返回未同步文件时加 ⚠️，提示 Agent 直接 Read
3	连接时追赶	重连时通过 (size, mtime) + 内容哈希补齐离线变更

环境变量：

变量	说明	默认值
CODEGRAPH_WATCH_DEBOUNCE_MS	防抖窗口（ms）	2000（范围 100~60000）
CODEGRAPH_NO_DAEMON	禁用文件监视守护进程	—

手动同步（沙箱环境、CI 脚本化查询时）：codegraph sync

编程 API（Node.js 库）

CodeGraph 可作为 Node.js 库直接使用：

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'
});

// 影响分析
const impact = cg.getImpactRadius(results[0].node.id, 2);

// 自动同步
cg.watch();   // 开启文件监视
cg.unwatch(); // 停止监视
cg.close();   // 关闭

---

可视化：让图谱"看得见"

CodeGraph 本质上是一个 SQLite 数据库（.codegraph/codegraph.db），没有内置可视化 UI。但这并不意味着你只能对着表格想象关系——以下 6 种方案从轻到重，按需选择：

方案速览

方案	操作	效果	适合场景
1. SQLite 直接查	DB Browser for SQLite 打开 .codegraph/codegraph.db	查看 nodes/edges 表，写 SQL 查询关系	临时探查、验证索引
2. 架构图生成	用 architecture-diagram skill 生成 HTML/SVG	✅ 已验证可行，静态架构图	文档/分享
3. Graphviz/DOT	从 SQLite 导出节点和边，生成 .dot 文件	标准有向图，可交互缩放	调用链可视化、论文/文档
4. D3.js 交互图	写脚本读取 SQLite 生成力导向图	可拖拽、缩放、悬停查看详情	交互式探索、演示
5. Neo4j 导入	导出为 CSV 导入 Neo4j	专业图数据库可视化 + Cypher 查询	复杂图谱分析、团队共享
6. JetBrains 插件	安装 Code Graph 插件	IDE 内调用关系可视化	日常开发（注：与本项目不同）

方案 1：SQLite 直接查询（零依赖，最轻量）

# 安装 DB Browser for SQLite（或用 sqlite3 CLI）
# 打开数据库
sqlite3 .codegraph/codegraph.db

# 查看表结构
.schema

# 查看所有函数节点
SELECT name, kind, file_path FROM nodes WHERE kind = 'function' LIMIT 20;

# 查看某个函数的调用者
SELECT n.name, n.file_path
FROM edges e
JOIN nodes n ON n.id = e.source_id
WHERE e.target_id = (SELECT id FROM nodes WHERE name = 'createUser');

优点：零配置，立即可用，适合验证和调试。 缺点：纯文本/表格，没有图形化关系展示。

方案 2：架构图生成（已验证）

利用 AI Agent 的 architecture-diagram skill，输入 CodeGraph 的查询结果，自动生成 HTML/SVG 架构图：

# 1. 用 CLI 查询关系
codegraph impact UserService --depth 2 --json > impact.json

# 2. 让 AI Agent 根据查询结果生成架构图
# 效果：静态但美观的组件关系图，可直接在浏览器打开

优点：效果美观，适合文档和分享；已验证可行。 缺点：静态图，不可交互；需要手动更新。

方案 3：Graphviz/DOT（推荐，平衡效果与复杂度）

从 SQLite 导出数据，生成标准有向图：

# 导出节点和边为 DOT 格式（示例脚本逻辑）
# 1. 查询 nodes 表获取符号
# 2. 查询 edges 表获取调用关系
# 3. 生成 .dot 文件

生成的 .dot 文件示例：

digraph CodeGraph {
  rankdir=LR;
  node [shape=box, style=rounded, fontname="Arial"];

  // 节点
  UserService     [label="UserService\nclass"];
  createUser      [label="createUser\nmethod"];
  hashPassword    [label="hashPassword\nfunction"];
  Database        [label="Database\nclass"];

  // 边（调用关系）
  UserService -> createUser;
  createUser -> hashPassword;
  createUser -> Database;
}

用 Graphviz 渲染：

# 安装 Graphviz
# macOS: brew install graphviz
# Ubuntu: sudo apt install graphviz
# Windows: choco install graphviz

# 生成 SVG（可交互缩放）
dot -Tsvg codegraph.dot -o codegraph.svg

# 生成 PNG
dot -Tpng codegraph.dot -o codegraph.png

# 生成可交互的 HTML（用 xdot 或在线查看器）

优点：标准有向图，支持交互缩放（SVG）；布局算法成熟；可编程批量生成。 缺点：大型项目节点多时需要过滤子图，否则图会过于密集。

方案 4：D3.js 交互图（最灵活）

写脚本读取 SQLite，生成力导向交互图：

// 核心思路：从 SQLite 导出 JSON，用 D3.js 力导向图渲染
// 1. 读取 nodes 和 edges
// 2. 构建 { nodes: [...], links: [...] } 数据结构
// 3. D3 forceSimulation 渲染
// 4. 支持拖拽、缩放、悬停查看详情、点击跳转源码

优点：完全可交互（拖拽、缩放、悬停、筛选）；视觉效果最佳。 缺点：需要写前端代码；对大型项目需要做聚类/分层处理。

方案 5：Neo4j 导入（专业图数据库）

将 CodeGraph 数据导入 Neo4j，获得专业级图可视化 + Cypher 查询能力：

# 1. 从 SQLite 导出 CSV
sqlite3 .codegraph/codegraph.db -header -csv \
  "SELECT id, name, kind, file_path FROM nodes;" > nodes.csv

sqlite3 .codegraph/codegraph.db -header -csv \
  "SELECT source_id, target_id, kind FROM edges;" > edges.csv

# 2. 导入 Neo4j（neo4j-admin import 或 Cypher LOAD CSV）
# 3. 用 Neo4j Browser 可视化

优点：专业图数据库，Cypher 查询语言强大；团队共享。 缺点：需要安装和维护 Neo4j；导入流程需要脚本化。

方案 6：JetBrains 插件（IDE 内集成）

在 IntelliJ / WebStorm 等 IDE 中安装 Code Graph 插件，可在 IDE 内直接看到调用关系图。

⚠️ 注意：这是 JetBrains 生态的独立插件，与本文的 CodeGraph 项目不是同一个工具，但可以互补使用。

优点：零切换，IDE 内直接看。 缺点：不同项目，数据不互通；仅限 JetBrains IDE。

我的推荐

你的需求	推荐方案
快速验证索引数据	方案 1（SQLite 直接查）
写文档/博客配图	方案 2（架构图）或方案 3（Graphviz）
日常探索调用关系	方案 3（Graphviz），可控且效果好
做演示/交互式探索	方案 4（D3.js）
团队共享/复杂分析	方案 5（Neo4j）

---

常见问题

问题	解决方案
error: unknown option '--exclude'	CodeGraph 零配置，不支持 --exclude，自动排除 node_modules/dist/build 等
codegraph_status 不是命令	命令是 codegraph status（空格分隔，不是下划线）
MCP 报 database is locked	确认 WAL 模式：codegraph status 显示 Journal: wal。旧版本请重新安装
索引不完整	运行 codegraph index --force 强制重建
查询无结果	确认文件语言在支持列表中，且不在 .gitignore 排除目录内
可视化需求	无内置可视化，参见可视化章节的 6 种替代方案
大型项目索引慢	确认 node_modules 等大目录已排除；使用 --quiet 减少输出开销
MCP 连接失败	确认项目已初始化/索引，检查 MCP 配置中的路径，命令行验证 codegraph serve --mcp
WSL2 上 WAL 模式无法启用	常见于网络挂载路径，将项目移至本地磁盘
额外排除目录	在项目 .gitignore 中添加即可。如需将默认排除的目录拉回索引，用否定语法：!vendor/
codegraph index 不支持 --exclude	零配置设计，所有排除规则通过 .gitignore 管理