Codegraph 实战：用知识图谱让 AI 编程效率翻倍

写代码时，你是否遇到过：AI 助手对你的项目上下文一无所知，每次都要花大量时间解释代码结构？Codegraph 用一种直接的方式解决这个问题------把代码转化为知识图谱，让 AI 在编写代码前就能理解项目整体架构。

一、Codegraph 是什么

Codegraph 是一个 TypeScript 编写的代码分析工具，通过构建代码间的语义关系图，让 AI 编程工具能够真正理解代码库的结构。与传统基于向量检索的方法不同，知识图谱能够表达代码之间的多层关系：

函数调用链：追踪函数的调用关系
模块依赖：分析模块间的依赖网络
数据流向：可视化数据的传递路径

核心特性一览

特性	说明
本地化运行	无需任何外部服务
多工具兼容	支持 Claude Code、Codex、Cursor、OpenCode、OpenClaw
高效索引	直接解析 AST，数秒完成数万行代码索引
增量更新	运行 `codegraph update` 仅重新索引改动部分
隐私优先	代码不上传任何外部服务

二、安装与索引

确保系统已安装 Node.js 18+（推荐 LTS），执行：

bash 复制代码

npm install -g codegraph

进入你的代码目录，初始化并索引：

bash 复制代码

codegraph init          # 创建 .codegraph 配置
codegraph index         # 开始索引代码

首次索引时，如果项目包含 node_modules，可能会很慢。建议先在 .codegraph/config.json 中排除它们（见第五节）。

⚠️ 索引成功后，所有查询命令必须在项目根目录下运行，否则会提示"找不到索引数据"。

三、配置 AI 工具（可操作步骤）

Claude Code（MCP 方式）

找到 Claude Code 的项目配置目录（通常是项目根目录下的 .claude/）。
编辑 mcp_settings.json（如果没有则创建）：

json 复制代码

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

重启 Claude Code。之后在对话中，Claude 可以自动调用 Codegraph 查询代码结构。

Cursor（自定义命令方式）

由于 Cursor 暂未提供官方 Codegraph 扩展，推荐使用以下方法：

在项目根目录创建 .cursorrules 文件。
写入：

bash 复制代码

# 项目结构助手
当需要了解代码依赖或函数调用关系时，请执行以下命令（在项目根目录的终端中）：
- 查看模块依赖：codegraph deps --module <模块路径>
- 追踪函数调用：codegraph trace --function <函数名> --file <文件路径>
- 影响分析：codegraph impact --file <文件路径>

在 Cursor 的 AI 对话中，你可以要求它"运行 codegraph trace ..."并分析输出。也可以手动在终端执行后把结果粘贴给 AI。

OpenClaw 对接配置

不同版本有差异

配置 MCP服务

方式1：使用命令

bash 复制代码

$ openclaw mcp set codegraph '{"command":"npx","args":["-y","@memoryx/codegraph-mcp"]}'

方式2：使用配置文件，文件 ~/.openclaw/mcporter.json：

json 复制代码

"mcp": {
    "servers": {
          "codegraph": {
            "codegraph": {
              "command": "npx",
              "args": ["-y", "@memoryx/codegraph-mcp"],
              "transport": "stdio"
            }
      	}
    }
}

验证配置

bash 复制代码

openclaw mcp list

查看配置：

bash 复制代码

openclaw mcp show

在 OpenClaw 中使用

配置完成后，在 OpenClaw 中直接使用自然语言指令：

"分析当前项目的模块依赖结构"
"追踪 processOrder 函数的调用关系"
"评估修改 api.ts 的影响范围"

OpenClaw 会自动将请求路由到 Codegraph，返回结构化的代码分析结果。

安全提示：企业环境下建议配置 MCPorter 的访问控制，防止敏感代码数据通过未授权渠道外泄。

四、基础使用教程

列出所有顶层模块：

bash 复制代码

codegraph list modules

查看某个文件依赖了哪些其他模块：

bash 复制代码

codegraph deps --module "services/order"

追踪函数被谁调用（必须指定所在文件）：

bash 复制代码

codegraph trace --function "processOrder" --file "src/services/order.ts"

生成项目概览报告：

bash 复制代码

codegraph overview --format markdown > overview.md

实战示例：重构订单处理函数

bash 复制代码

# 1. 找到函数定义位置
codegraph search --symbol "processOrder"

# 2. 查看调用链
codegraph trace --function "processOrder" --file "services/order.ts"

# 3. 查看该模块依赖的数据模型
codegraph deps --module "services/order"

输出结果会列出：

函数的入参/返回类型（从 TS/JS 注释或类型推导）
直接调用者（文件名+行号）
内部调用的其他函数
相关的数据模型定义

以前花半小时阅读代码才能获得这些信息，现在几秒钟。

五、常见坑与解决方案

索引慢到崩溃？

原因：默认索引了整个 node_modules。
解决：编辑 .codegraph/config.json，添加排除列表：

json 复制代码

{
  "exclude": ["node_modules", "dist", "build", ".git"]
}

然后执行 codegraph index --force 重新索引。

查询不到任何结果？

原因：不在项目根目录，或忘记执行 codegraph index。
解决：cd 到包含 .codegraph 的目录，运行 codegraph index 后再查询。

Claude Code 无法调用 codegraph？

检查：

终端中输入 which codegraph，确认路径正确。
如果全局安装后仍找不到，尝试在 mcp_settings.json 中使用绝对路径，例如 "command": "/home/你的用户名/.nvm/versions/node/v18.xx/bin/codegraph"。
重启 Claude Code 再试。

OpenClaw 中无法调用 Codegraph？

运行 openclaw mcp list 检查服务状态
检查 ~/.openclaw/mcporter.json 配置文件的语法是否正确

Cursor 中执行命令报错？

确保 Cursor 的终端当前目录是项目根目录。
如果提示 codegraph: command not found，说明 PATH 环境变量未继承。可以在 Cursor 设置中指定 Shell 为 login shell（例如 bash -l），或直接在命令中使用绝对路径。

多项目切换

每个项目独立执行 codegraph init & index 即可。切换时直接 cd，无需额外操作。在 OpenClaw 中可通过 cd <项目目录> && codegraph <命令> 的方式切换索引上下文。

六、总结

Codegraph 的核心价值在于弥平 AI 编程工具与代码库之间的上下文断层。15.8K个 GitHub star 说明了社区对这类工具的认可。

工具使用门槛很低：安装 → 配置排除规则 → 索引 → 集成到 AI 工具，十分钟内可完成。核心优势是完全本地化运行，这对于不能将代码发送到云端的开发者是刚需功能。索引数据通常占原代码体积的 5%～10%，这个存储开销完全可以接受。

如果你还在用"复制粘贴文件内容"的方式向 AI 传递上下文，不妨试试 Codegraph + 知识图谱方案。

相关资源：

GitHub：colbymchenry/codegraph