VS Code + Codex + CodeGraph 使用文档

适用场景：已经安装并使用 VS Code + Codex 插件，希望通过 CodeGraph 将项目代码建立成代码知识图谱，并通过 MCP 提供给 Codex 使用。

本文以 Windows + PowerShell 为例。

本文默认已经具备：

  • VS Code
  • VS Code Codex 插件
  • Codex 对话窗口
  • Node.js / npm

VS Code 中的 Codex 已经可以使用 Codex Runtime，并通过 config.toml 配置 MCP。

1. 整体架构

配置完成后，整体关系如下：

VS Code
  │
  └── Codex 插件
        │
        │ MCP
        ▼
    CodeGraph
        │
        ▼
  .codegraph/codegraph.db
        │
        ├── 文件
        ├── 类
        ├── 方法
        ├── 函数
        ├── Import
        ├── 调用关系
        ├── 依赖关系
        └── 影响关系

Codex 不再只依赖普通文件搜索，而可以通过 CodeGraph 查询项目中的代码关系。

例如：

Nutz Module / @At
        ↓
业务方法
        ↓
Service
        ↓
Dao / NutDao
        ↓
Entity
        ↓
MySQL

对于 Spring Boot 项目，也可以分析：

Controller
    ↓
Service
    ↓
Mapper / Repository
    ↓
Entity
    ↓
MySQL

实际项目结构以 CodeGraph 的分析结果为准，不要强行套用某一种框架结构。

2. CodeGraph 是什么

CodeGraph 用于将代码库解析成可查询的代码知识图谱。

主要用于分析：

  • 项目结构
  • 类关系
  • 方法关系
  • 函数调用关系
  • Import / Dependency
  • 调用链
  • 模块依赖
  • 影响范围
  • AI Coding Agent 上下文

通过 MCP 后，Codex 可以查询这些信息。

例如：

修改某个 Service
        ↓
查询调用关系
        ↓
找到调用它的 Module / Controller
        ↓
找到它调用的 Dao
        ↓
找到相关 Entity / 数据表
        ↓
分析修改影响范围

3. 安装 CodeGraph

3.1 使用 npm 安装

打开 VS Code Terminal / PowerShell：

npm install -g @colbymchenry/codegraph

安装完成后检查：

Get-Command codegraph

或者：

codegraph --help

如果能够正常显示帮助信息，说明安装成功。

3.2 查看版本

codegraph --version

如果当前版本不支持 --version，可以使用：

codegraph --help

确认 CLI 可以正常运行即可。

4. 初始化项目图谱

4.1 选择正确的项目根目录

这是最重要的一步。

应该在能够包含所有需要分析模块的项目根目录执行：

cd E:\DevOpsCode\mall-service

然后：

codegraph init

初始化完成后，一般会生成：

mall-service/
├── .codegraph/
│   ├── .gitignore
│   └── codegraph.db
├── ...

其中：

.codegraph/codegraph.db

就是 CodeGraph 的项目图谱数据库。

4.2 项目根目录选择原则

例如：

mall-service/
├── mall-service/
│   ├── module-a/
│   ├── module-b/
│   ├── module-c/
│   └── ...
└── other-project/

如果希望 CodeGraph 分析：

module-a
module-b
module-c

应该：

cd mall-service\mall-service
codegraph init

而不是进入：

module-a

单独初始化。

原则：

CodeGraph 的项目根目录应该尽量选择能够覆盖完整业务代码的根目录。

5. CodeGraph 与 Codex MCP 配置

5.1 找到 Codex 配置文件

Windows 下通常位于：

C:\Users\<用户名>\.codex\config.toml

例如：

C:\Users\Mayn\.codex\config.toml

Codex 的 VS Code 插件使用这个配置体系。

5.2 添加 CodeGraph MCP

在：

C:\Users\<用户名>\.codex\config.toml

中添加：

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]
startup_timeout_sec = 120

如果已有：

[mcp_servers.node_repl]
...

不要删除原来的配置，只需要增加：

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]
startup_timeout_sec = 120

最终类似：

[mcp_servers.node_repl]
args = []
command = '...'
startup_timeout_sec = 120

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]
startup_timeout_sec = 120

6. 如果 Codex 找不到 codegraph

先执行：

Get-Command codegraph

如果能够得到类似：

CommandType     Name
-----------     ----
Application     codegraph.cmd

说明 PowerShell 可以找到 CodeGraph。

如果 PowerShell 能找到，但是 Codex MCP 启动失败，可以使用绝对路径。

例如：

[mcp_servers.codegraph]
command = 'C:\Users\<用户名>\AppData\Roaming\npm\codegraph.cmd'
args = ["serve", "--mcp"]
startup_timeout_sec = 120

实际路径以：

Get-Command codegraph

返回的路径为准。

7. 测试 CodeGraph MCP

可以先在 PowerShell 测试：

codegraph serve --mcp

如果没有立即报错并保持运行，通常说明 MCP Server 可以正常启动。

使用：

Ctrl + C

停止测试。

然后让 Codex 通过 config.toml 自动启动 MCP。

8. 重启 VS Code / Codex

修改：

C:\Users\<用户名>\.codex\config.toml

之后，建议：

关闭 VS Code
        ↓
重新打开 VS Code
        ↓
重新打开项目
        ↓
打开 Codex

这样可以确保 Codex 重新读取 MCP 配置。

9. 验证 Codex 是否识别 CodeGraph

在 Codex 对话窗口输入：

请检查当前可用的 MCP 工具，并确认是否已经连接 CodeGraph。

如果 CodeGraph 配置正确，Codex 应该能够看到 CodeGraph 相关工具。

进一步测试：

请使用 CodeGraph 分析当前项目。

暂时不要修改代码。

请告诉我：
1. 当前项目有哪些主要模块？
2. 主要模块之间是什么关系？
3. 当前项目的主要类和方法调用关系是什么？
4. 找出一个核心业务的完整调用链。
5. 分析修改这个业务可能影响哪些模块。

要求优先使用 CodeGraph 的代码关系和影响分析能力。

10. 补充 / 更新代码图谱

项目代码发生变化后，可以使用：

codegraph sync

用于增量同步。

如果需要重新完整建立索引：

codegraph index --force

两者区别：

codegraph sync
    ↓
增量同步
    ↓
适合日常更新


codegraph index --force
    ↓
完整重新索引
    ↓
适合大量代码变化、初始化遗漏、图谱异常

11. index --force 很慢是否正常

正常。

完整索引需要：

扫描项目
    ↓
解析源码
    ↓
解析类 / 方法 / 函数
    ↓
建立调用关系
    ↓
建立依赖关系
    ↓
写入 codegraph.db

项目越大，耗时越长。

例如：

几百个源码文件
    → 几十秒～几分钟

1000～3000 个文件
    → 几分钟

大型项目
    → 十几分钟甚至更久

Windows 环境、大型 Java 老项目以及包含大量前端源码时可能更慢。

执行过程中不要因为暂时没有明显输出就立即 Ctrl + C。

12. database file is in use 错误

如果执行：

codegraph index --force

出现：

database file is in use
EPERM
Permission denied
codegraph.db

说明当前：

.codegraph/codegraph.db

正在被 CodeGraph MCP Server / daemon 使用。

处理方法：

方法一：关闭 VS Code

关闭 VS Code
        ↓
停止 Codex
        ↓
停止 CodeGraph MCP
        ↓
重新打开 PowerShell
        ↓
codegraph index --force

方法二：检查 CodeGraph 进程

Get-Process | Where-Object {
    $_.ProcessName -match "codegraph"
} | Select-Object Id, ProcessName, Path

如果存在相关进程，可以停止：

Stop-Process -Id <PID> -Force

然后：

codegraph index --force

不要一遇到锁定就删除 .codegraph。

13. 图谱没有包含所有模块

如果发现某些模块没有被 CodeGraph 分析，首先检查项目根目录。

例如：

mall-service/
├── module-a/
├── module-b/
├── module-c/
└── .codegraph/

如果 module-a/b/c 都应该属于当前项目，那么应该在：

mall-service/

执行：

codegraph index --force

14. 检查 .gitignore

CodeGraph 可能受到项目忽略规则影响。

检查：

Get-Content .gitignore

重点查看是否忽略了需要分析的模块：

module-a/
module-b/
supplied-service/
supplied-h5/

如果模块被忽略，需要根据 CodeGraph 当前版本的配置机制调整包含规则，然后重新：

codegraph index --force

15. 嵌套 Git 仓库

有些项目结构是：

project/
├── .git/
├── module-a/
│   └── .git/
└── module-b/
    └── .git/

也就是项目内部包含多个独立 Git 仓库。

这种情况下需要特别检查：

  • .gitignore
  • 子目录是否被父项目忽略
  • CodeGraph 的 include / includeIgnored 配置

否则可能出现：

项目目录存在
    ↓
CodeGraph 初始化成功
    ↓
但是部分模块没有进入图谱

16. 不建议随便删除 .codegraph

.codegraph 中：

.codegraph/
└── codegraph.db

保存的是当前项目图谱。

正常情况下：

codegraph sync

或：

codegraph index --force

即可更新。

只有在图谱数据库损坏、初始化状态异常等情况下，才考虑删除并重新：

codegraph init

如果需要删除：

Remove-Item .codegraph -Recurse -Force

然后：

codegraph init

执行前建议先确认没有正在运行的 CodeGraph MCP Server。

17. Nutz 项目推荐的 Codex 分析提示词

对于 Nutz 项目，不要让 Codex 按 Spring Boot 的：

Controller → Service → Mapper

模式理解。

可以使用：

请使用 CodeGraph 分析当前 Nutz 项目，不要修改任何代码。

这是一个基于 Nutz Framework 的 Java 项目，请不要按照 Spring Boot 项目假设项目结构。

重点回答：

1. 当前项目有哪些主要业务模块？
   - 按 package、目录和核心类进行归纳
   - 区分后台管理、H5、公共模块、业务模块等
   - 不要仅根据目录名称猜测，结合类之间的实际依赖关系分析

2. 当前项目的 Nutz 架构是什么？

重点分析：
- @IocBean
- @At
- @Ok
- @Fail
- Dao / NutDao
- Entity / POJO
- Service
- Module
- Action
- Ioc 配置
- 其他 Nutz 特有组件

3. 分析主要 HTTP 请求调用链。

不要使用 Controller → Service → Mapper 的 Spring Boot 模式。

按照实际项目关系分析：

HTTP 请求
    ↓
Nutz Module / @At
    ↓
Service / 业务类
    ↓
Dao / NutDao
    ↓
Entity / 数据库表

如果实际结构不同，以 CodeGraph 分析结果为准。

4. 找出当前项目核心业务模块，并列出：
- 入口类
- 核心业务类
- DAO
- Entity
- 数据库表
- 依赖的其他业务模块

5. 分析项目数据库访问关系：
- Dao / NutDao
- SQL
- Entity
- 数据库表
- 表之间关系
- 哪些业务类访问哪些表

6. 分析项目中的核心业务功能。

不要只搜索关键词。

请通过 CodeGraph 的：
- 类关系
- 方法调用关系
- 数据访问关系
- 依赖关系
- 影响分析

确定真实业务关系。

7. 找出指定业务的完整调用链。

例如：

用户请求
    ↓
Nutz Module / @At
    ↓
参数处理
    ↓
业务处理
    ↓
DAO
    ↓
数据库

如果存在：
- Excel / CSV 导入
- 异步处理
- 定时任务
- 消息队列
- Redis
- 消息通知
- 导入记录

也要纳入调用链。

8. 使用 CodeGraph 做影响分析：

如果修改某个核心业务逻辑：
- 哪些类会受到影响？
- 哪些方法会受到影响？
- 哪些入口会受到影响？
- 哪些数据库表会受到影响？
- 哪些其他业务模块可能受到影响？

重要要求：

- 优先使用 CodeGraph 的代码关系、调用图和影响分析能力。
- 不要只通过 grep、文件名搜索或关键词搜索判断业务关系。
- 不要假设项目使用 Spring Boot。
- 不要假设存在 Controller、Mapper、Repository。
- 不要修改任何代码。
- 如果 CodeGraph 无法确定某个关系，明确标记“无法从当前代码关系确定”，不要猜测。
- 尽可能给出对应的类、方法和文件路径。

18. 推荐的 AGENTS.md

可以在项目根目录创建：

AGENTS.md

推荐内容：

# Project Instructions

## 项目架构

这是一个基于 Nutz Framework 的 Java 项目。

不要按照 Spring Boot 项目假设项目结构。

重点关注：

- Nutz Module
- @At
- @IocBean
- Ioc 配置
- Dao / NutDao
- Entity
- Service
- SQL
- 定时任务
- 消息处理
- Redis
- 其他项目实际使用的基础设施

## CodeGraph

涉及以下任务时，优先使用 CodeGraph：

- 项目结构分析
- 复杂业务分析
- 调用链分析
- 影响范围分析
- 核心业务修改
- 数据访问关系分析
- 跨模块修改

分析时：

1. 优先查询 CodeGraph 中的类关系。
2. 查询方法调用关系。
3. 查询模块依赖关系。
4. 查询影响范围。
5. 根据实际代码关系判断项目架构。
6. 不要因为项目不是 Spring Boot 就强行套用 Spring Boot 架构。

## 修改代码

修改前先确认：

- 调用入口
- 核心业务类
- DAO
- Entity
- 数据库表
- 上下游调用关系
- 修改影响范围

如果发现代码引用了不存在的类、方法、组件或配置：

- 不要直接忽略。
- 继续检查其引用关系。
- 判断它是否属于当前业务实现。
- 如果确实缺失，并且当前任务要求完整实现，应补齐必要代码。

## 代码修改原则

- 只修改当前任务涉及的代码。
- 保持现有项目架构。
- 不要将 Nutz 项目改造成 Spring Boot 风格。
- 不要无关重构。
- 不要修改无关文件。

19. 日常使用建议

第一次建立项目

cd E:\项目根目录
codegraph init

日常代码变化

codegraph sync

怀疑图谱不完整

codegraph index --force

MCP 测试

codegraph serve --mcp

检查 CodeGraph CLI

codegraph --help

检查安装路径

Get-Command codegraph

20. 推荐工作流

以后使用 Codex 修改复杂业务，可以采用：

提出需求
   ↓
Codex 读取 AGENTS.md
   ↓
CodeGraph 查询项目结构
   ↓
查询相关类 / 方法
   ↓
查询调用链
   ↓
分析影响范围
   ↓
确定修改文件
   ↓
修改代码
   ↓
再次通过 CodeGraph 检查调用关系

对于复杂业务，例如：

积分导入
订单
售后
供应商
消息通知
权限

不要直接让 Codex：

“找到 xxx.java 然后修改”

而应该让它：

“先通过 CodeGraph 分析 xxx 业务的完整调用链和影响范围，再修改。”

这样可以显著降低 AI 只修改单个文件、漏掉上下游业务逻辑的概率。

21. 常用命令速查

操作 命令
查看帮助 codegraph --help
查看命令 codegraph --help
初始化项目 codegraph init
增量同步 codegraph sync
完整重建 codegraph index --force
启动 MCP codegraph serve --mcp
查找安装路径 Get-Command codegraph
查看版本 codegraph --version
检查进程 Get-Process | Where-Object {$_.ProcessName -match "codegraph"}

22. 最终目录结构示例

完整配置后：

mall-service/
│
├── AGENTS.md
│
├── .codegraph/
│   ├── .gitignore
│   └── codegraph.db
│
├── module-a/
├── module-b/
├── module-c/
│
├── pom.xml
└── README.md

整体关系：

                    VS Code
                       │
                       ▼
                 Codex 插件
                       │
             ┌─────────┴─────────┐
             │                   │
             ▼                   ▼
        AGENTS.md            CodeGraph
             │                   │
        工作规则              MCP Server
                                 │
                                 ▼
                           codegraph.db
                                 │
                  ┌──────────────┼──────────────┐
                  ▼              ▼              ▼
                类关系         调用关系       依赖关系
                  │              │              │
                  └──────────────┼──────────────┘
                                 ▼
                              Codex
                                 │
                                 ▼
                             修改代码

核心原则：

  • AGENTS.md：告诉 Codex 应该怎么工作。
  • CodeGraph：告诉 Codex 项目代码之间是什么关系。
  • codegraph.db：保存当前项目的代码图谱。
  • MCP：负责让 Codex 能够查询 CodeGraph。
  • sync：日常增量更新。
  • index --force：图谱不完整或需要彻底重建时使用。
# arcgis
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

四天蒸发近2000亿，宇树科技股价近乎“腰斩”；苹果举办库克告别派对：9月1日正式卸任CEO；Anthropic两款新Claude模型曝光 | 极客头条

avatar AI编程社区
cover

Claude Code反超GitHub Copilot登顶第一、90%程序员已用上Agent，最新AI编码调查报告来了

avatar AI编程社区
cover

如何用好 Claude Code 写后端代码

avatar AI编程社区