Calude Code - 25 CodeGraph：让 AI 真正读懂你的代码库

一款基于代码知识图谱的智能索引工具，为 AI 编程助手提供精准的代码上下文，告别盲猜式 grep。

一、什么是 CodeGraph？

CodeGraph 是一个代码智能知识图谱工具，它会在你的项目中构建一个本地 SQLite 数据库，将代码中的函数、类、变量、接口等符号（Symbol）以及它们之间的调用关系（Edge）全部索引起来。

简单来说，它做了三件事：

解析代码：静态分析你的源码，提取所有符号定义
构建关系：记录谁调用了谁、谁依赖了谁，形成一张有向图
提供查询：通过 CLI 或 MCP 协议，让人和 AI 都能快速检索代码上下文

它不是一个简单的文本搜索引擎，而是一个理解代码结构的语义索引。grep 只能匹配字符串，CodeGraph 能告诉你"这个函数被哪些地方调用了"、"改了这个类会影响哪些文件"。

当前最新版本为 v1.2.0 ，后端使用 Node.js 内置的 node:sqlite（WAL 模式），支持 TypeScript、JavaScript、TSX、Python、YAML 等多种语言。

二、CodeGraph 能解决什么问题？

2.1 AI 编程助手的"上下文盲区"

使用 Claude Code、Cursor 等 AI 编程工具时，最大的痛点是：AI 并不真正了解你的代码库。

传统的工作流是这样的：

perl 复制代码

用户：帮我修改 handleRequest 函数
AI：（grep 搜索 → 读取文件 → 再 grep → 再读取 → 反复多轮）

这个过程有几个问题：

Token 消耗大：AI 需要读取大量不相关的文件来拼凑上下文
响应速度慢：多轮工具调用，每轮都有网络延迟
容易遗漏：grep 只能做文本匹配，动态调用、跨文件依赖很容易漏掉
无法理解影响面：改了一个函数，不知道哪些地方会受影响

2.2 CodeGraph 的解决方案

CodeGraph 通过预先构建的知识图谱，一次调用就能返回：

相关符号的完整源码（带行号，与 Read 工具一致）
符号之间的调用路径（caller → callee）
影响面分析（blast radius）：修改某个符号会波及哪些文件
测试覆盖情况提示

一次 explore 调用，替代了原本需要 5-10 轮 grep + Read 的循环。

2.3 适用场景

场景	传统方式	CodeGraph
理解一个函数的调用链	多次 grep + Read	一次 `explore`
查找谁调用了某个方法	grep 文本匹配（可能漏）	`callers` 精确查找
评估改动影响范围	靠经验猜测	`impact` 自动分析
AI 理解新代码库	反复试探性搜索	MCP 工具直接查询
代码审查	人工追踪依赖	图谱可视化调用关系

三、如何安装

3.1 环境要求

Node.js：v18 或以上版本（推荐 v20+）
操作系统 ：macOS、Linux、Windows（WSL2 建议加 --no-watch 参数）
npm：随 Node.js 自带即可

3.2 全局安装

bash 复制代码

npm install -g codegraph

安装完成后验证：

bash 复制代码

codegraph --version
# 输出：1.2.0

3.3 安装 MCP Server 到 AI 助手

CodeGraph 最强大的用法是作为 MCP（Model Context Protocol）服务器接入 AI 编程助手。一条命令搞定：

bash 复制代码

codegraph install

它会交互式地让你选择目标 Agent：

Claude Code
Cursor
Codex CLI
opencode
Hermes Agent

也可以非交互式安装：

bash 复制代码

# 自动检测已安装的 Agent，全局安装
codegraph install -y

# 指定安装到 Claude Code
codegraph install -t claude-code -l global

安装完成后，以 Claude Code 为例，它会在你的配置中写入：

json 复制代码

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

同时自动添加权限放行规则，AI 调用 CodeGraph 工具时无需每次确认。

四、CodeGraph 基础使用方法

4.1 初始化项目索引

进入项目根目录，执行：

bash 复制代码

cd your-project
codegraph init

这会：

在项目根目录创建 .codegraph/ 目录
解析所有源码文件，提取符号和调用关系
构建 SQLite 索引数据库
启动文件监听器（后续修改自动增量同步）

根据项目大小，初始化时间从几秒到几分钟不等。以一个 475 文件的中型项目为例：

yaml 复制代码

Files:     475
Nodes:     20,710
Edges:     64,756
DB Size:   54.03 MB

4.2 查看索引状态

bash 复制代码

codegraph status

输出示例：

vbnet 复制代码

CodeGraph Status

Project: /Users/you/your-project

Index Statistics:
  Files:     475
  Nodes:     20,710
  Edges:     64,756
  DB Size:   54.03 MB
  Backend:   node:sqlite --- built-in (full WAL)

Nodes by Kind:
  function     5,964
  variable     3,673
  class        224
  interface    298
  ...

✓ Index is up to date

4.3 核心命令一览

`codegraph explore` --- 探索代码区域（最常用）

一次性返回相关符号的源码 + 调用路径，是 MCP 工具 codegraph_explore 的 CLI 版本：

bash 复制代码

# 自然语言查询
codegraph explore "用户认证中间件"

# 指定符号名
codegraph explore "RequestCache"

# 指定项目路径
codegraph explore "handleLogin" -p /path/to/project

# 限制返回文件数
codegraph explore "支付流程" --max-files 5

输出包含三部分：

Blast Radius：影响面分析，列出依赖这些符号的代码
Source Code：相关文件的完整源码（带行号，逐字读取）
Call Paths：符号之间的调用链路

`codegraph query` --- 搜索符号

bash 复制代码

# 按名称搜索符号
codegraph query "handleRequest"

# 限制结果数量
codegraph query "useStore" -l 20

# 按类型过滤（function、class、method、interface 等）
codegraph query "Auth" -k class

# JSON 格式输出（便于脚本处理）
codegraph query "login" -j

`codegraph node` --- 查看单个符号详情

bash 复制代码

# 查看符号源码 + 调用者/被调用者
codegraph node "RequestCache"

# 文件模式：读取文件并显示行号 + 依赖信息
codegraph node -f src/api/request.ts

# 指定行范围
codegraph node -f src/api/request.ts --offset 10 --limit 50

`codegraph callers` --- 查找调用者

bash 复制代码

# 谁调用了 RequestCache？
codegraph callers "RequestCache"

输出示例：

bash 复制代码

Callers of "RequestCache" (2):

  axios-instance.ts
    apps/web/src/api/core/axios-instance.ts:1

  index.ts
    apps/web/src/api/index.ts:1

`codegraph callees` --- 查找被调用者

bash 复制代码

# RequestCache 调用了哪些东西？
codegraph callees "RequestCache"

`codegraph impact` --- 影响面分析

这是 CodeGraph 最有价值的命令之一。修改一个符号前，用它评估波及范围：

bash 复制代码

codegraph impact "RequestCache"

输出示例：

sql 复制代码

Impact of changing "RequestCache" --- 41 affected symbols:

  apps/web/src/api/core/request-cache.ts
    class    RequestCache:5
    method   set:14
    method   get:26
    method   clear:41
    method   delete:49

  apps/web/src/api/core/axios-instance.ts
    file     axios-instance.ts:1

  apps/web/src/api/core/api-utils.ts
    function clearCache:10
    function deleteCache:16
    function cancelAllRequests:21
  ...

`codegraph sync` --- 手动增量同步

正常情况下文件监听器会自动同步。如果需要手动触发：

bash 复制代码

codegraph sync

`codegraph index` --- 全量重建索引

当索引出现异常或需要全新构建时：

bash 复制代码

codegraph index

4.4 其他实用命令

bash 复制代码

# 显示项目文件结构（基于索引）
codegraph files

# 管理后台守护进程
codegraph daemon

# 清除卡住的锁文件
codegraph unlock

# 从项目中移除 CodeGraph（删除 .codegraph/ 目录）
codegraph uninit

五、项目中如何使用 CodeGraph？

5.1 与 Claude Code 集成（MCP 模式）

这是最推荐的用法。CodeGraph 与 Claude Code 的集成分为三个层面，下面以实际用户配置为例逐一说明。

第一层：MCP Server 定义

Claude Code 的 MCP Server 配置写在 ~/.claude.json 的全局 mcpServers 字段中：

json 复制代码

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

配置完成后，Claude Code 会自动获得一个 MCP 工具：

mcp__codegraph__codegraph_explore

当你向 Claude Code 提问时，它会优先调用 CodeGraph 获取精准的代码上下文，而不是盲目地 grep 和 Read。

如果不想手动编辑 JSON，直接运行 codegraph install 即可自动写入上述配置。

第二层：权限放行与 Prompt Hook

在 ~/.claude/settings.json 中配置权限和 Hook：

json 复制代码

{
  "permissions": {
    "allow": ["mcp__codegraph__*"]
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "codegraph prompt-hook"
          }
        ]
      }
    ]
  }
}

两项配置的作用：

permissions.allow ：自动放行所有 CodeGraph 工具调用（mcp__codegraph__*），无需每次手动确认
hooks.UserPromptSubmit ：每次发送消息时自动执行 codegraph prompt-hook。这个 Hook 会检测当前项目是否存在 .codegraph/ 目录，如果存在，就在全局 CLAUDE.md 中自动注入一段 CodeGraph 使用指令（用  和  标记包裹）

第三层：全局 CLAUDE.md 指令注入

codegraph prompt-hook 自动注入到 ~/.claude/CLAUDE.md 中的指令内容如下：

markdown 复制代码

<!-- CODEGRAPH_START -->
## CodeGraph

In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root),
reach for it BEFORE grep/find or reading files when you need to understand or locate code:

- **MCP tool** (when available): `codegraph_explore` answers most code questions in one call ---
  the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch
  hops grep can't follow.
- **Shell** (always works): `codegraph explore "<symbol names or question>"` prints the same output.

If there is no `.codegraph/` directory, skip CodeGraph entirely --- indexing is the user's decision.
<!-- CODEGRAPH_END -->

这段指令告诉 Claude Code：

在已索引的项目中，优先使用 CodeGraph 而非 grep/find/Read
MCP 工具可用时走 codegraph_explore，不可用时降级为 Shell 命令 codegraph explore
如果项目没有 .codegraph/ 目录，则完全跳过 CodeGraph，把是否索引的决定权交给用户

这三层配合工作的完整流程：

css 复制代码

用户发送消息
    ↓
UserPromptSubmit 触发 codegraph prompt-hook
    ↓
检测 .codegraph/ 是否存在 → 注入/更新 CLAUDE.md 指令
    ↓
Claude Code 读取指令 → 优先调用 codegraph_explore
    ↓
权限自动放行（mcp__codegraph__*）→ 无需用户确认
    ↓
一次调用返回源码 + 调用链 + 影响面

5.2 实际工作流示例

场景一：理解陌生模块

不用 CodeGraph：

perl 复制代码

你：这个项目的认证流程是怎样的？
AI：让我搜索一下...（grep auth → 读取 3 个文件 → grep login → 读取 2 个文件 → ...）
（消耗 5-8 轮工具调用，等待时间长）

用 CodeGraph：

arduino 复制代码

你：这个项目的认证流程是怎样的？
AI：（一次 codegraph_explore "认证 auth login middleware" → 获取完整调用链和源码）
（1 轮调用，直接给出分析）

场景二：安全地重构

bash 复制代码

# 改之前先看影响面
codegraph impact "UserAuthGuard"

# 输出告诉你：
# - UserAuthGuard 被 6 个控制器引用
# - 间接影响 3 个中间件
# - 有 2 个测试文件覆盖
# 你就知道改动需要验证哪些地方

场景三：Code Review 辅助

bash 复制代码

# 查看某个函数的所有调用者，确认改动是否有遗漏
codegraph callers "parseToken"

# 查看调用链深度
codegraph explore "请求拦截器 认证 错误处理"

5.3 团队协作建议

.codegraph/ 加入 .gitignore：索引数据库是本地生成的，不需要提交到版本库
团队统一安装 ：在项目 README 中说明 codegraph init 的使用
CI 中可选使用 ：在 CI 流水线中用 codegraph impact 分析 PR 的影响面，辅助审查

六、总结

CodeGraph 的核心理念是：让 AI 在理解代码结构的基础上辅助编程，而不是靠文本匹配盲人摸象。

它通过三个层面解决问题：

层面	能力
索引层	静态分析构建代码知识图谱，符号 + 调用关系
查询层	CLI 提供 explore / callers / impact 等精准查询
协议层	MCP Server 让 AI 助手直接查询图谱，替代 grep 循环

如果你正在使用 Claude Code、Cursor 等 AI 编程工具，并且受够了 AI 反复 grep 还找不准代码的问题，CodeGraph 值得一试。

bash 复制代码

npm install -g codegraph
cd your-project
codegraph init
codegraph install -y

三行命令，让你的 AI 助手真正"读懂"你的代码库。

CodeGraph 是一个开源工具，更多信息可通过 codegraph --help 查看完整命令文档。

Calude Code - 25 CodeGraph：让 AI 真正读懂你的代码库

一、什么是 CodeGraph？

二、CodeGraph 能解决什么问题？

2.1 AI 编程助手的"上下文盲区"

2.2 CodeGraph 的解决方案

2.3 适用场景

三、如何安装

3.1 环境要求

3.2 全局安装

3.3 安装 MCP Server 到 AI 助手

四、CodeGraph 基础使用方法

4.1 初始化项目索引

4.2 查看索引状态

4.3 核心命令一览

codegraph explore --- 探索代码区域（最常用）

codegraph query --- 搜索符号

codegraph node --- 查看单个符号详情

codegraph callers --- 查找调用者

codegraph callees --- 查找被调用者

codegraph impact --- 影响面分析

codegraph sync --- 手动增量同步

codegraph index --- 全量重建索引

4.4 其他实用命令

五、项目中如何使用 CodeGraph？

5.1 与 Claude Code 集成（MCP 模式）

第一层：MCP Server 定义

第二层：权限放行与 Prompt Hook

第三层：全局 CLAUDE.md 指令注入

5.2 实际工作流示例

场景一：理解陌生模块

场景二：安全地重构

场景三：Code Review 辅助

5.3 团队协作建议

六、总结

`codegraph explore` --- 探索代码区域（最常用）

`codegraph query` --- 搜索符号

`codegraph node` --- 查看单个符号详情

`codegraph callers` --- 查找调用者

`codegraph callees` --- 查找被调用者

`codegraph impact` --- 影响面分析

`codegraph sync` --- 手动增量同步

`codegraph index` --- 全量重建索引