当前位置：首页 > news >正文

CodeGraph 使用指南

news 2026/7/19 16:12:51

快速安装

一键安装（推荐，无需 Node.js）

bash

# 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

安装完成后，打开新终端窗口继续下一步。

通过 npm 安装（需要 Node.js）

bash

npm i -g @colbymchenry/codegraph

升级

bash

codegraph upgrade # 升级到最新版 codegraph upgrade --check # 检查是否有新版本 codegraph upgrade <版本号> # 锁定特定版本

关联 AI 代理

安装 CLI 后，运行以下命令将 CodeGraph 连接到你的 AI 编码代理：

bash

codegraph install

这会自动检测你已安装的 AI 代理（Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI 等），并为每个代理配置 MCP 服务器。你只需选择要启用的代理即可。

支持的非交互式安装：

bash

codegraph install --yes # 自动检测并安装 codegraph install --target=claude,opencode --yes # 指定目标代理 codegraph install --print-config claude # 仅打印配置片段，不写入文件

可选参数：

参数	可选值	说明
`--target`	`auto` ,`all`,`none`, 或 csv	指定要配置的代理
`--location`	`global` ,`local`	全局生效或仅当前项目
`--yes`	(布尔值)	非交互模式
`--print-config`	代理 ID	仅打印配置片段

初始化项目

进入你的项目目录，运行：

bash

cd your-project codegraph init

这会在项目根目录创建.codegraph/目录并构建完整的知识图谱。构建完成后会自动监听文件变化并增量更新索引。

各代理中的使用方式

Claude Code

codegraph install会自动配置 Claude Code 的 MCP 服务器。安装后重启 Claude Code 即可。Claude Code 会自动使用codegraph_exploreMCP 工具来查询代码结构。

如需手动配置，编辑~/.claude.json：

json

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

可选：在~/.claude/settings.json中启用自动授权：

json

{ "permissions": { "allow": [ "mcp__codegraph__*" ] } }

OpenCode

codegraph install同样支持自动检测 OpenCode。安装后重启 OpenCode 即可。

OpenCode 的 MCP 配置会被写入对应的 MCP 配置文件中，CodeGraph 会自动创建~/.config/opencode/mcp.json或类似路径的配置。

Codex CLI

Codex CLI 同样被codegraph install自动支持。配置完成后重启 Codex CLI，CodeGraph 的 MCP 工具即可在 Codex 中使用。

Hermes Agent

同样支持自动配置。安装后重启 Hermes Agent 即可使用。

ZCode

CodeGraph 未被codegraph install自动检测列表收录，需手动添加 MCP 服务器配置。

方式一：通过 ZCode 设置面板添加

打开 ZCode，进入设置 → MCP 服务器
点击右上角新建 MCP 服务器，类型选择stdio（本地命令）
填写以下信息：

字段	值
名称	`codegraph`
命令	`codegraph`
参数	`serve --mcp`

选择作用域（用户作用域让所有项目可用，工作区仅当前项目）
点击添加并确认开关处于启用状态

方式二：手动编辑配置文件

ZCode 读取以下配置路径：

用户级：~/.zcode/cli/config.json，键mcp.servers
项目级：<项目根>/.zcode/config.json，键mcp.servers

在mcp.servers中添加：

json

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

方式三：通过导入功能（如果你已在其他代理中配置过）

ZCode 支持从 Claude Code、Codex CLI、OpenCode 等外部 Agent 一键导入 MCP 配置。在MCP 服务器页面点击右上角导入图标，勾选 CodeGraph 即可。

配置完成后重启 ZCode，即可在项目中看到 CodeGraph 的codegraph_explore工具自动可用。

CLI 常用命令

命令	说明
`codegraph status`	查看当前索引统计
`codegraph explore <查询>`	核心功能 — 一次查询返回相关源码 + 调用链 + 影响范围
`codegraph node <符号/文件>`	查看单个符号的源码或读取文件（带行号）
`codegraph callers <符号>`	查找谁调用了某个函数
`codegraph callees <符号>`	查找某个函数调用了什么
`codegraph impact <符号>`	分析修改某符号的影响范围
`codegraph affected <文件...>`	找出受更改影响的测试文件
`codegraph query <搜索>`	搜索符号
`codegraph files`	查看文件结构
`codegraph index [路径]`	手动全量索引
`codegraph sync [路径]`	增量更新索引
`codegraph uninstall`	从所有代理中移除 CodeGraph 配置（加`--keep-cli`保留 CLI）
`codegraph uninit [路径]`	移除项目的索引

affected 命令的典型用法：

bash

# 找出 git 变动的受影响测试文件 git diff --name-only HEAD | codegraph affected --stdin --quiet # 然后在 CI 中只运行受影响测试 npx vitest run $(git diff --name-only HEAD | codegraph affected --stdin --quiet)