CodeGraph

CodeGraph

官方GitHub地址

https://github.com/colbymchenry/codegraph

工具安装

1.全局安装

1
npm install -g @colbymchenry/codegraph

2.一键自动配置(MCP)

1
codegraph install

执行上述命令后会提供一些选项供你选择：

  1. 编辑器选择：工具自动检测到本机已安装 的编辑器,这里我仅勾选opencode进行测试；
  2. PATH 环境注册：确认将 codegraph CLI 写入系统环境变量，保证编辑器可正常拉起 MCP 服务；
  3. 作用范围选择：选用 All projects 全局配置模式，将 CodeGraph MCP 服务写入 OpenCode 全局配置文件 ~\.config\opencode\opencode.jsonc；
  4. 执行结果：程序自动更新 OpenCode 配置、生成配套说明文档 AGENTS.md；
  5. 快速入门提示：配置完成后，进入对应项目目录执行 codegraph init -i，即可一键创建项目代码图谱索引，让 OpenCode AI 调用代码分析能力。

补充关键点：全局配置仅为编辑器开通 CodeGraph 工具调用权限，不会自动生成项目代码数据库，每个代码仓库需手动执行初始化命令构建本地图谱。

image-20260615215543207

3.创建代码图谱索引

1
codegraph init -i

4.更改代码后更新索引

更新索引可以执行以下两个命令,各有不同的适用场景:

对比项 codegraph index codegraph sync
扫描范围 项目全部源码文件，无视是否改动 仅对比文件修改时间 + 哈希，只处理变更文件
执行速度 大型项目耗时久（上千文件分钟级） 秒级完成，只解析少量变更文件
底层行为 清空旧库，完整重解析 AST、重建所有函数 / 类 / 调用关系 保留原有完整图谱，局部更新变动文件对应的节点与关联边
适用场景 1. 新项目首次构建图谱（init -i 底层就是执行它）2. 切换 Git 分支、大量文件增删3. 索引数据库损坏、数据错乱4. 手动强制全量刷新（加--force） 1. 日常写完代码手动刷新索引2. Git 拉取少量更新后同步3. MCP 自动后台执行的默认逻辑
配套参数 --force：强制清空旧库重建--quiet：关闭进度输出 无强制重建参数，仅增量更新；支持--quiet静默输出

5.基础使用命令

一、环境安装与配置类（安装 MCP、环境校验）

  1. codegraph install

    交互式配置各编辑器 MCP 服务，可选择目标编辑器、全局 / 局部生效范围，自动写入 MCP 配置文件

  2. codegraph doctor

    一键自检工具：校验 CLI 可用性、PATH 环境、项目索引、编辑器 MCP 配置，自动输出问题与修复方案

  3. codegraph -v / codegraph --version

    查看当前 CodeGraph CLI 版本

  4. codegraph help

    查看全部命令帮助文档

二、项目图谱初始化与更新（核心建索引命令）

  1. codegraph init

    仅在项目根目录创建空 .codegraph配置文件夹，不扫描代码、不生成数据库

  2. codegraph init -i / codegraph init --index

    一步完成：创建目录 + 全量扫描代码、构建完整代码图谱数据库（新项目首次使用推荐）

  3. codegraph index

    全量重建索引：清空旧数据库，完整扫描项目所有源码，重新生成全部 AST 关联关系

  4. codegraph index --force

    强制全量重建，无视缓存，适合切分支、大量文件改动、索引损坏场景

  5. codegraph sync

    增量同步索引：仅对比上次索引后新增 / 修改 / 删除的文件，局部更新图谱，日常开发手动刷新用

  6. codegraph status

    查看当前项目索引状态：已解析文件数量、待同步变更文件、数据库存储信息

三、代码查询分析命令（终端手动检索代码）

  1. codegraph query "符号名"

    全局检索类、函数、接口、变量等定义，示例：codegraph query "AddressController"

    附加参数：--kind class只匹配类；--json以 JSON 结构化输出结

  2. codegraph callers "符号名"

    查询所有调用该目标的上层代码，查看上游依赖链路

  3. codegraph callees "符号名"

    查询目标内部调用的所有下层函数、方法，查看内部依赖

  4. codegraph impact --of "符号名"

    影响范围分析：输出修改该代码会牵连到的全部文件、调用处，用于重构风险评估

  5. codegraph context "自然语言描述"

    根据语义提取一段业务对应的全套关联代码，模拟 AI 获取上下文逻辑

四、MCP 服务相关命令（对接 OpenCode/Cursor 等编辑器）

  1. codegraph serve --mcp

    手动启动 MCP 服务进程，编辑器配置文件内自动调用此命令打通 AI 工具通道

五、配套使用流程速记

  1. 首次全局配置编辑器：codegraph install
  2. 新项目初始化图谱：codegraph init -i
  3. 日常改完代码刷新索引：codegraph sync
  4. 手动查函数调用链：codegraph callers "类名/方法名"
  5. 环境异常排查：codegraph doctor