笔记 | CodeGraph 使用教程：专为代码库打造的知识图谱

项目语言成本Token 用量时间工具调用次数VS CodeTypeScript ~1 万文件省 26%少 63%快 20%少 69%ExcalidrawTypeScript ~640 文件省 40%少 71%快 41%少 82%DjangoPython ~3000 文件多 10%少 45%慢 3%少 64%TokioRust ~790 文件省 30%少 69%快 22%少 71%OkHttpJava ~645 文件多 3%少 32%快 15%少 60%GinGo ~110 文件省 7%少 35%快 8%少 38%AlamofireSwift ~110 文件省 38%少 45%快 6%少 8%

平均：省 18% 成本 · 少 51% Token · 快 16% · 少 57% 工具调用

核心特点

100% 本地运行 — 数据不离机，无需 API Key，无外部服务
零配置 — 按文件扩展名自动识别语言
20+ 种编程语言 — TS/JS/Python/Go/Rust/Java/C#/PHP/Ruby/C/C++/Swift/Kotlin 等
14 种 Web 框架路由识别 — Express/Django/Spring/Laravel/Gin 等
自动同步 — 原生 OS 文件监听（FSEvents/inotify/ReadDirectoryChangesW），编辑后 2 秒内更新

二、安装方式

方式一：直接下载（无需 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 运行时，不需要提前安装 Node.js，在 Windows/macOS/Linux 的 x64 和 ARM64 架构上均可运行。

方式二：npm 安装（已有 Node.js）

# 全局安装
npm install -g @colbymchenry/codegraph

MCP添加到 ~/.claude.json（Claude Code）：

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

添加自动允许权限到 ~/.claude/settings.json（可选）：

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

方式三：安装器一键安装

npx @colbymchenry/codegraph

安装器会自动：

检测各位已安装的 AI 代理（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro）
询问是否把 codegraph 添加到 PATH
询问是全局配置（所有项目）还是本地配置（当前项目）
写入各代理的 MCP 服务器配置
如果选 Claude Code，自动配置权限白名单

非交互模式（适合 CI/脚本）：

codegraph install --yes                              # 自动检测代理，全局安装
codegraph install --target=cursor,claude --yes       # 指定代理
codegraph install --target=auto --location=local     # 本地安装
codegraph install --print-config codex               # 只打印配置片段，不写文件

参数可选值默认--targetauto、all、none 或逗号分隔列表交互提示--locationglobal、local交互提示--yes布尔值每步提示--no-permissions布尔值，跳过 Claude 自动白名单开启

安装完之后要重启 AI 代理（Claude Code / Cursor / Codex CLI 等），让其加载 MCP 服务器。

三、快速开始

初始化项目（构建）

安装完之后打开自己的项目目录，使用一行命令搞定项目初始化。

cd your-project
codegraph init -i

init 创建 .codegraph/ 目录；-i（--index）同时构建初始索引。全局安装后只需在每个项目执行一次，无需重复安装 MCP 配置。

搞定后，只要项目存在 .codegraph/ 目录，AI 代理就会自动使用 CodeGraph 工具。

接下来打开ClaudeCode直接对话即可使用CodeGraph分析项目，示比如下：

卸载办法

codegraph uninstall          # 从所有已配置代理中移除
codegraph uninit             # 移除当前项目的索引（保留代理配置）

四、核心概念

数据流水线

源文件 → tree-sitter 解析（提取节点/边）
            ↓
      引用解析（导入关系、名称匹配、框架模式）
            ↓
      图查询（调用者、被调用者、影响范围）
            ↓
      上下文构建（Markdown/JSON 输出给 AI）

知识图谱结构

节点类型（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（装饰）

动态调度桥接

静态 tree-sitter 解析无法追踪动态调用，CodeGraph 通过合成器（Synthesizer）桥接这些边界：

回调/观察者模式
EventEmitter 事件
React setState → render（React 重渲染）
JSX 子组件（render → 子组件）
Django ORM 描述符

所有合成边带有 provenance: 'heuristic' 标记及 metadata.synthesizedBy 字段，AI 能够清晰识别。

五、CLI 命令参考

基础命令

codegraph                         # 运行交互式安装器
codegraph install                 # 运行安装器（显式）
codegraph uninstall               # 从代理中移除 CodeGraph

项目管理

# 初始化项目
codegraph init [path]             # 初始化（--index 或 -i 同时建索引）
codegraph uninit [path]           # 移除项目索引（--force 跳过确认）

# 建立/更新索引
codegraph index [path]            # 全量索引（--force 强制重建，--quiet 减少输出）
codegraph sync [path]             # 增量更新（只处理变更的文件）

# 查看状态
codegraph status [path]           # 显示节点/边/文件数量和 SQLite 后端信息

查询命令

# 搜索符号
codegraph query           # 搜索符号（--kind 过滤类型，--limit 限制数量，--json 输出 JSON）

# 示例：
codegraph query UserService --kind class --limit 10
codegraph query handleRequest --json

# 调用关系
codegraph callers         # 查找调用该函数的位置（--limit，--json）
codegraph callees         # 查找该函数调用了什么（--limit，--json）
codegraph impact          # 分析修改该符号会影响哪些代码（--depth，--json）

# 文件结构
codegraph files [path]            # 显示文件结构（--format，--filter，--max-depth，--json）

# 上下文构建
codegraph context           # 为 AI 构建上下文（--format，--max-nodes）

codegraph affected — CI 利器

根据变更文件，追踪依赖关系，找出受影响的测试文件：

codegraph affected src/utils.ts src/api.ts          # 直接传文件名
git diff --name-only | codegraph affected --stdin   # 从 git diff 管道输入
codegraph affected src/auth.ts --filter "e2e/*"     # 自定义测试文件 glob

参数说明默认值--stdin从标准输入读取文件列表false-d, --depth <n>最大依赖追踪深度5-f, --filter <glob>自定义测试文件 glob自动检测-j, --json输出 JSONfalse-q, --quiet只输出文件路径false

CI 脚本示例：

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

启动 MCP 服务器

codegraph serve --mcp

一般由 AI 代理自动启动，无需手动执行。

六、MCP 工具详解

当 CodeGraph 作为 MCP 服务器运行时，向 AI 代理暴露以下 10 个工具：

codegraph_search — 符号搜索

按名称在整个代码库搜索符号，支持全文检索（FTS5）。

使用场景： 当各位明白函数/类的名字但不明白在哪个文件时。

codegraph_context — 上下文构建(建议SubAgent中调用)

基于任务描述构建相关代码上下文，内部组合了 search + node + callers + callees，一次调用搞定。

使用场景： 让 AI 理解某个功能区域的全貌。

codegraph_trace — 调用链追踪

追踪两个符号之间的调用路径（“X 是如何到达 Y 的”），每一跳都内联显示函数体，能跨越动态调度边界（回调、React 重渲染、接口实现）——这是 grep 无法做到的。

使用场景： 理解代码流程，比如"请求是如何到达数据库的"。

示例流程（Excalidraw）：
mutateElement → triggerUpdate → [callback] triggerRender
  → [react-render] render → [jsx] StaticCanvas → renderStaticScene

codegraph_callers — 调用者查询

查找哪些地方调用了某个函数。

使用场景： 修改函数前，了解所有调用方以评估影响。

codegraph_callees — 被调用者查询

查找某个函数调用了哪些函数。

使用场景： 理解函数的依赖关系。

codegraph_impact — 影响分析

分析修改某个符号后，会影响哪些代码（BFS 广度优先搜索）。

使用场景： 重构前的安全评估，避免意外破坏其他功能。

codegraph_node — 符号详情

获取某个特定符号的详细信息，可选择附带源代码。

使用场景： 查看函数签名、文档或源码。

codegraph_explore — 多符号探索(建议SubAgent中调用)

一次调用返回多个相关符号的源码（按文件分组）以及它们之间的关系图。

使用场景： 当需要同时理解多个相关符号时，避免多次单独调用。

codegraph_files — 文件结构

获取已索引的文件结构（比文件系统扫描快得多）。

使用场景： 快速了解项目文件布局。

codegraph_status — 索引状态

查看索引健康状况和统计数据，包括待同步文件列表。

使用场景： 确认索引是否是最新的。

工具选用指南

AI 代理会根据任务自动选择工具，以下是选择逻辑：

任务类型推荐工具搜索某个类/函数的位置codegraph_search了解某个功能区域codegraph_context追踪代码执行流程（X 如何到达 Y）codegraph_trace查找谁调用了某个函数codegraph_callers查找某函数调用了什么codegraph_callees修改前评估影响范围codegraph_impact查看单个符号的详情/源码codegraph_node同时查看多个相关符号codegraph_explore了解文件结构codegraph_files确认索引状态codegraph_status

七、支持的编程语言

语言支持完全自动，根据文件扩展名识别，无需任何配置。

语言文件扩展名支持状态TypeScript.ts, .tsx完整支持JavaScript.js, .jsx, .mjs完整支持Python.py完整支持Go.go完整支持Rust.rs完整支持Java.java完整支持C#.cs完整支持PHP.php完整支持Ruby.rb完整支持C.c, .h完整支持C++.cpp, .hpp, .cc完整支持Objective-C.m, .mm, .h部分支持（类、协议、方法、属性、导入；.mm 可能解析不完整）Swift.swift完整支持Kotlin.kt, .kts完整支持Scala.scala, .sc完整支持（含 Scala 3 枚举）Dart.dart完整支持Svelte.svelte完整支持（含 Svelte 5 runes，SvelteKit 路由）Vue.vue完整支持（含 <script setup>，Nuxt 路由/API/中间件）Liquid.liquid完整支持Pascal / Delphi.pas, .dpr, .dpk, .lpr完整支持（含 DFM/FMX 表单文件）Lua.lua完整支持（函数、方法、局部变量、require 导入）Luau.luau完整支持（含类型别名、Roblox instance-path require）

八、框架路由识别

CodeGraph 能识别 Web 框架的路由文件，并将 URL 模式与处理函数关联。查询控制器的调用者时，能够看到绑定它的 URL 路由。

框架识别的路由形式Djangopath()、re_path()、url()、include()（CBV .as_view()、虚线路径）Flask@app.route('/path', methods=[...])，Blueprint 路由FastAPI@app.get(...)、@router.post(...) 等所有标准方法Expressapp.get(...)、router.post(...) 含中间件链NestJS@Controller + @Get/@Post/...、GraphQL @Resolver、@MessagePattern、@SubscribeMessageLaravelRoute::get()、Route::resource()、Controller@action、元组语法Drupal*.routing.yml、hook_* 实现Railsget '/x', to: 'users#index'，=> 语法Spring@GetMapping、@PostMapping、@RequestMappingGin / chi / gorilla muxr.GET(...)、router.HandleFunc(...)Axum / actix / Rocket.route("/x", get(handler))ASP.NET[HttpGet("/x")] 属性Vaporapp.get("x", use: handler)React Router / SvelteKit路由组件节点

九、iOS/React Native 混合开发支持

真实的 iOS 和 React Native 项目往往跨越多种语言，静态解析在每个语言边界处断裂。CodeGraph 通过桥接合成器跨语言连接这些调用链。

边界类型JS/Swift 侧原生侧桥接方式Swift → ObjCSwift obj.foo(bar:)ObjC 选择子 -fooWithBar:@objc 自动桥接规则（含 Cocoa 介词前缀）ObjC → SwiftObjC [obj fooWithBar:]Swift @objc func foo(bar:)反向桥接名称候选RN Legacy BridgeJS NativeModules.X.fn(...)ObjC RCT_EXPORT_METHOD / Java @ReactMethod解析宏/注解，构建 JS 名称 → 原生方法映射RN TurboModulesJS import M from './NativeM'原生实现匹配 Codegen Spec以 Native<X>.ts Spec 接口为基准RN 原生 → JS 事件JS NativeEventEmitter.addListener('e', cb)ObjC/Swift/Java sendEvent("e", ...)以字面量事件名为键的跨语言事件通道Expo ModulesJS requireNativeModule('X').fn(...)Swift/Kotlin Module { Name("X"); ... }解析 Expo DSL 字面量Fabric View ComponentsJSX <MyView />TS Codegen Spec + 原生实现类Spec → component 节点，基于约定的名称+后缀查找Paper Legacy View ManagersJSX <MyView />ObjC RCT_EXPORT_VIEW_PROPERTY同 Fabric，Paper 声明同样生成节点

所有合成边带有 provenance: 'heuristic' 标记，metadata.synthesizedBy 字段指明桥接类型（如 swift-objc-bridge、rn-event-channel）。

十、自动同步机制

CodeGraph 提供三层自动同步，确保 AI 代理永远不会读取到过期数据：

第一层：文件监听 + 防抖自动同步

codegraph serve --mcp 启动时会开启原生文件监听：

macOS → FSEvents
Linux → inotify
Windows → ReadDirectoryChangesW

每次源文件创建/修改/删除后，经过 2000ms 防抖窗口合并批量操作，自动触发增量同步。

代理修改 src/Widget.ts
  → 监听器触发（通常  console.log(`${p.phase}: ${p.current}/${p.total}`)
});

// 搜索符号
const results = cg.searchNodes('UserService');

// 查找调用者
const callers = cg.getCallers(results[0].node.id);

// 构建 AI 上下文
const context = await cg.buildContext('修复登录 Bug', {
  maxNodes: 20,
  includeCode: true,
  format: 'markdown'
});

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

// 文件监听
cg.watch();   // 开启自动同步
cg.unwatch(); // 停止监听

// 关闭连接
cg.close();

十二、配置说明

CodeGraph 是零配置工具 — 无需任何配置文件，按文件扩展名自动识别语言。

默认排除的目录

以下目录开箱即用自动跳过（即使不在 .gitignore 中）：

Node.js：node_modules、dist、build、.next
Python：.venv、__pycache__
Rust：target
iOS/macOS：Pods、.build
PHP：vendor

自定义排除

把各位不想索引的目录加入 .gitignore：

/logs/
/tmp/

强制包含被排除的目录

在 .gitignore 中使用否定规则：

!vendor/my-local-lib/   # 把 vendor 下的某个本地库纳入索引

文件大小限制

超过 1MB 的文件会自动跳过（生成的 bundle、压缩的 JS、vendor 文件）。

数据存储位置

每个项目的数据存储在项目根目录的 .codegraph/codegraph.db（SQLite 数据库）。数据不会离开你的机器。

十三、故障排除

“CodeGraph not initialized” 错误

原因： 项目未初始化。

解决：

cd your-project
codegraph init -i

索引速度很慢

原因： 大型目录（如 node_modules）未被排除。

解决：

1. 确认 node_modules 等目录在 .gitignore 中
2. 使用 --quiet 参数减少输出开销
3. 运行 codegraph status 查看已索引的文件数量

MCP 报 database is locked

原因： 通常是旧版本（< 0.9）安装的问题。

解决：

# 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

# 或通过 npm
npm i -g @colbymchenry/codegraph@latest

如果 codegraph status 显示 Journal: 不是 wal，说明当前文件系统不支持 WAL 模式（常见于网络共享目录和 WSL2 /mnt 路径）。把项目（含 .codegraph/ 目录）移到本地磁盘。

MCP 服务器无法连接

排查步骤：

1. 确认项目已初始化：codegraph status
2. 验证 MCP 配置文件中的路径
3. 命令行测试：codegraph serve --mcp（看是否能正常启动）

符号缺失 / 找不到函数

可能原因及解决：

1. 文件刚保存，还在等待同步 — 等 2 秒后重试，或执行 codegraph sync
2. 文件语言不支持 — 查看支持语言表格
3. 文件被 .gitignore 排除 — 检查 .gitignore 规则
4. 文件在默认排除目录中 — 如 node_modules、dist、vendor 等

查看当前索引状态

# CLI 方式
codegraph status

# 在 AI 代理会话中（MCP 工具 codegraph_status 输出示例）：
## CodeGraph Status
节点数：9,289 | 边数：47,832 | 文件数：643
SQLite 后端：native (better-sqlite3)
Journal: wal

### Pending sync:
- src/Widget.ts（1200ms 前修改）

如果没有 ### Pending sync: 部分，说明索引是最新的。

附录：支持的 AI 代理

代理安装器支持Claude Code含自动权限白名单Cursor含开发目录修复Codex CLITOML 配置格式opencodeJSONC 格式，保留用户注释Hermes Agent支持Gemini CLI支持Antigravity IDE支持Kiro支持

本文档基于 CodeGraph 仓库代码及官方文档整理，当前版本参考 v0.9.7（2026-05-28）。

🎬 博客主页：https://xiaoy. 🎥 本文由呆呆敲代码的小Y 原创 🙉 🎄 学专栏推荐：Unity系统学专栏 🌲 游戏制作专栏推荐：游戏制作 🌲Unity实战100例专栏推荐：Unity 实战100例教程 🏅 欢迎

资料白嫖，技术互助

学路线指引（点击解锁）知识定位人群定位🧡 Unity系统学习专栏入门级本专栏从Unity入门开始学习，快速达到Unity的入门水平💛 Unity实战类项目进阶级计划制作Unity的 100个实战案例！助你进入Unity世界，争取做最全的Unity原创博客大全。❤️ 游戏制作专栏难度偏高分享学习一些Unity成品的游戏Demo和其他语言的小游戏！💚 游戏爱好者万人社区互助/吹水数万人游戏爱好者社区，聊天互助，白嫖奖品💙 Unity100个实用技能Unity查漏补缺针对一些Unity中经常用到的一些小知识和技能进行学习介绍，核心目的就是让我们能够快速学习Unity的知识以达到查漏补缺

以上就是这次整理的全部内容，希望对你有所启发。如果有不同见解，欢迎在评论区交流讨论。

笔记 | CodeGraph 使用教程：专为代码库打造的知识图谱

- CodeGraph 用教程：专为代码库打造的知识图谱

CodeGraph 用教程：专为代码库打造的知识图谱

一、项目简介

开发原理

实测性能提升（7 个真实开源项目，每组 4 次运行取中位数）

核心特点

二、安装方式

方式一：直接下载（无需 Node.js）

方式二：npm 安装（已有 Node.js）

方式三：安装器一键安装

三、快速开始

初始化项目（构建）

卸载办法

四、核心概念

数据流水线

知识图谱结构

动态调度桥接

五、CLI 命令参考

基础命令

项目管理

查询命令

codegraph affected — CI 利器

启动 MCP 服务器

六、MCP 工具详解

codegraph_search — 符号搜索

codegraph_context — 上下文构建(建议SubAgent中调用)

codegraph_trace — 调用链追踪

codegraph_callers — 调用者查询

codegraph_callees — 被调用者查询

codegraph_impact — 影响分析

codegraph_node — 符号详情

codegraph_explore — 多符号探索(建议SubAgent中调用)

codegraph_files — 文件结构

codegraph_status — 索引状态

工具选用指南

七、支持的编程语言

八、框架路由识别

九、iOS/React Native 混合开发支持

十、自动同步机制

第一层：文件监听 + 防抖自动同步

十二、配置说明

默认排除的目录

自定义排除

强制包含被排除的目录

文件大小限制

数据存储位置

十三、故障排除

“CodeGraph not initialized” 错误

索引速度很慢

MCP 报 database is locked

MCP 服务器无法连接

符号缺失 / 找不到函数

查看当前索引状态

附录：支持的 AI 代理

评论 (0)