Codegraph 使用手册：给 AI Agent 的本地代码知识图谱

Vibe Coding 2 / 2

上一篇：记录 Claude Code、OpenCode、Codex-Cli 的 请求/响应 数据

系列目录

1. 记录 Claude Code、OpenCode、Codex-Cli 的 请求/响应 数据
2. Codegraph 使用手册：给 AI Agent 的本地代码知识图谱

摘要

• 本文写 CodeGraph 的安装、把 MCP 接到 Cursor 等 Agent、给项目建索引，以及日常用 codegraph_explore / CLI 查符号、调用链和改动影响面。索引落在项目本地的 .codegraph/，不上传代码。
• 操作环境按 macOS，CLI 按 @colbymchenry/codegraph 1.6.2。Linux / Windows 安装命令一并给出；Agent 侧以 Cursor 为主，顺带覆盖 Claude Code、Codex CLI、opencode 等安装器支持的目标。
• Get Started，Installation，CLI，MCP Server，Integrations。同系列流量追踪见 记录 Claude Code、OpenCode、Codex-Cli 的 请求/响应 数据。

它解决什么问题

Agent 要搞清「请求怎么到数据库」「改这个函数会砸到谁」时，通常会反复 grep、glob、Read，把调用链自己拼出来。CodeGraph 先把仓库解析成一张本地知识图谱（符号、调用边、依赖），再通过 MCP 把相关源码、调用路径和影响范围一次交回去。

图存在项目下的 .codegraph/（SQLite），解析用 Tree-sitter / Rust 内核，默认不碰 node_modules、dist 等依赖与构建目录，也遵守 .gitignore。没有 API Key，代码不离开本机。

默认 MCP 只暴露一个工具：codegraph_explore。官方测量里，一个强工具比一长串窄工具更不容易选错，也更省会话上下文。其余工具仍可用 CLI，或用环境变量重新挂上 MCP。

安装 CLI

本文按 1.6.2。自带运行时，不必为 CodeGraph 单独装 Node；本机已有 Node 时也可以用 npm。

macOS / Linux：

# 下载对应平台的自包含构建，并把 codegraph 放进 PATH
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

已有 Node 时：

npm i -g @colbymchenry/codegraph

也可以一条命令跑安装器（下载并进入交互安装）：

npx @colbymchenry/codegraph

安装脚本改的是 PATH，不会刷新当前 shell。关掉终端再开一个，再执行：

codegraph version

应看到类似 1.6.2。对不上或找不到命令，先新开终端；仍不行再检查安装方式（bundle / npm）是否写进了你实际在用的 shell 配置。

以后升级：

# 只看有没有新版本
codegraph upgrade --check

# 按当前安装方式原地升级
codegraph upgrade

接到 Agent

装好 CLI 还不够：必须再跑一次安装器，把 codegraph serve --mcp 写进各 Agent 的 MCP 配置。这一步只接线，不建索引。

交互安装：

codegraph install

它会探测本机已装的 Agent，询问写全局还是只写当前项目，并写入 MCP 配置。支持的目标包括 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，以及 GitHub Copilot（VS Code / Copilot CLI / JetBrains）。

对 Claude Code、Codex CLI、Gemini CLI、opencode，安装器还会在 CLAUDE.md / AGENTS.md / GEMINI.md 里加一小段带标记的 CodeGraph 说明，方便子 Agent 或非 MCP 场景改用 codegraph explore。Cursor 等以 MCP 配置为主。这些写入可用 codegraph uninstall 干净拆掉。

非交互示例：

# 自动探测 Agent，默认写全局
codegraph install --yes

# 只给 Cursor 和 Claude Code 接线
codegraph install --target=cursor,claude --yes

# 探测到的 Agent，配置写在当前项目
codegraph install --target=auto --location=local --yes

# 接线后立刻给当前目录建索引（脚本 / CI 一键）
codegraph install --yes --init

选项	取值	作用
--target	auto、all、none，或逗号列表如 cursor,claude	选哪些 Agent；不加则交互询问
--location	global 或 local	全局配置还是项目内配置
--yes	布尔	跳过询问，按默认值走
--init	布尔	接线后对当前目录执行 codegraph init
--no-permissions	布尔	不写 Claude Code 的自动放行列表
--print-config <id>	如 cursor、claude	只打印片段，不写文件

改完配置后重启 Agent（Cursor 整窗重启一次），MCP 子进程才会加载新配置。

Cursor 手动接线

Cursor 拉起 MCP 子进程时工作目录可能不对。安装器会注入 --path；手写配置时也要带上项目路径。先看官方片段（不写文件）：

codegraph install --print-config cursor

本机 1.6.2 打印的是写入 ~/.cursor/mcp.json 的形态，核心是：

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

${workspaceFolder} 由 Cursor 展开成当前工作区根目录。手写时不要丢掉 --path，否则图可能建在错误目录上，工具会表现为「未初始化」或查不到符号。

确认 MCP 已挂上

在 Cursor 的 MCP 面板里应能看到 codegraph。项目里还没有 .codegraph/ 时，服务端可以处于未激活、不列工具的状态，这是预期行为：索引要你主动 init，Agent 会继续用内置的 Read / Grep。

「配置文件里有 codegraph」和「当前项目能查到符号」不是同一件事。前者只说明 Agent 能启动 serve --mcp；后者还要下面的项目初始化通过。

给项目建索引

每个需要图谱的仓库各做一次：

cd your-project
codegraph init

init 会创建 .codegraph/ 并完成首次全量索引。之后在 Agent 会话里改文件时，MCP 侧的文件监视会增量同步，一般不必再手跑 sync。

脚本或 CI 跳过所有询问：

codegraph init --yes

核对是否生效：

codegraph status

已初始化时会看到文件数、按语言统计、节点 / 边数量等。未初始化时提示 Not initialized，并建议执行 codegraph init。

.codegraph/ 里通常有忽略规则，避免把数据库提交进 Git；目录本身可以按团队约定决定是否纳入仓库。只在本机用、不想在 git status 里看见相关文件时，按官方文档调整忽略规则即可。

codegraph install 和 codegraph init 分工不同：前者改 Agent 的 MCP / 说明文件，后者只服务当前项目的图。只装 CLI、或只接线不 init，Agent 都拿不到可用索引。

日常怎么用

在 Agent 里：默认用 codegraph_explore

有索引之后，问结构、流程、改动影响时，应直接让 Agent 调 codegraph_explore，而不是再开一轮 grep / Read 拼图。适合的问法例如：

• 「UserService 怎么工作」

• 「登录请求从路由到数据库的路径」

• 「改 AuthMiddleware 会影响哪些调用方」

• 查询里直接点名文件或符号，拿到带行号的源码片段

一次调用通常带回：相关符号的源码（按文件分组）、符号之间的调用路径（含回调、React 重渲染、JSX 子组件等静态分析能接上的动态跳转），以及对依赖面的摘要。Agent 应把返回内容当作已经读过，不要再用 grep 复核同一批结果。

刚改过的文件若还在监视器的防抖窗口里（默认约 2 秒），响应开头可能出现「某些文件尚待 sync」的提示。被点名的文件用内置 Read 看磁盘上的最新内容；未点名的待同步文件只会落在页脚说明里。

工作区根没有索引时，仍可通过工具参数 projectPath 去查另一个已 init 的路径（monorepo 里某个子服务、或第二个仓库）。路径上没有图时，工具会提示改用内置工具，而不会硬失败。

需要更多 MCP 工具时

默认只列出 codegraph_explore。下面这些能力仍在，只是默认不出现在工具列表里：

工具	作用
codegraph_node	单个符号的源码与调用关系，或按文件读带行号内容
codegraph_search	按名称搜符号（只要位置）
codegraph_callers	谁调用了这个符号
codegraph_callees	这个符号调用了谁
codegraph_impact	改这个符号的影响范围
codegraph_files	索引里的文件结构
codegraph_status	索引健康与统计

在 MCP 配置的环境变量里用逗号白名单替换默认列表，例如：

CODEGRAPH_MCP_TOOLS=explore,node,search,callers

改完后重启 Agent。不改 MCP 时，用下一节的 CLI 也能做同样的事。

在终端里查

适合脚本、子 Agent、或不想开 MCP 的场合。explore / node 的输出与对应 MCP 工具一致。

# 自然语言或符号名，一次拿源码 + 调用路径
codegraph explore "How does login reach the database?"

# 按名称搜符号
codegraph query UserService --kind class --limit 10

# 单个符号或文件
codegraph node handleRequest
codegraph node src/auth.ts

# 调用方 / 被调用 / 影响面
codegraph callers handleRequest --json
codegraph callees handleRequest
codegraph impact AuthMiddleware --depth 3

# 索引里的文件树；package 格式按最近的 package.json / composer.json 分组
codegraph files
codegraph files --format package

# 看索引是否跟上工作区
codegraph status

索引维护

Agent 通过 MCP 启动 serve --mcp 之后，监视器会在源文件增删改后防抖同步。多数时候不用手跑：

# 增量：只处理变更（监视器禁用或脚本预检时用）
codegraph sync

# 全量重建
codegraph index --force

# 索引被陈旧锁文件挡住时
codegraph unlock

防抖间隔可用 CODEGRAPH_WATCH_DEBOUNCE_MS 覆盖，默认 2000，夹在 100～60000 毫秒。构建或格式化会短时间写很多文件时，可以调到 5000 或 10000，合并成一次 sync。

禁用共享后台进程时设 CODEGRAPH_NO_DAEMON=1；这时每个 serve --mcp 各自写索引，同一项目不要并行开多个 writer。

可选配置 codegraph.json

默认零配置即可用。需要时在项目根放 codegraph.json：

把已提交进仓库、但又不想进图的目录排除出去（.gitignore 管不了已跟踪路径）：

{
  "exclude": ["static/", "**/vendor/**"]
}

源码被 .gitignore 故意忽略、却仍要索引时：

{
  "include": ["Tools/", "Local/typescript/"]
}

目录仍要可搜，但不要在重名符号上压过主业务代码时：

{
  "deprioritize": ["optional-skills/", "scripts/"]
}

非标准扩展名映射到已支持语言：

{
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

改映射后执行一次 codegraph index，新规则才会进图。格式错误或语言 id 写错只会警告并跳过该项，不会中断索引。

匿名遥测

安装器会询问是否开启匿名用量统计（用了哪些命令 / 语言等）。不含代码、路径、符号名、查询内容或 IP。随时关闭：

codegraph telemetry off

环境变量 CODEGRAPH_TELEMETRY=0 或 DO_NOT_TRACK=1 同样关闭。

卸载与恢复

只拆 Agent 侧配置，保留 CLI：

codegraph uninstall --keep-cli

配置和 CLI 一起拆（安装器会先列出将删除的内容）：

codegraph uninstall

只拆某个 Agent、或非交互：

codegraph uninstall --target=cursor --yes

某个项目不要图了，删除该项目的 .codegraph/：

codegraph uninit
# 跳过确认
codegraph uninit --force

uninstall 不动各项目的 .codegraph/；uninit 不动 Agent 的 MCP 配置。两边都要清时，两条都跑。

恢复到「能用」的状态：重新 codegraph install（或手写 Cursor 的 mcp.json），再在项目里 codegraph init，重启 Agent，用 codegraph status 确认。

常见问题

• 提示未初始化：在项目根执行 codegraph init，再用 codegraph status 看是否有统计输出。

• MCP 连不上：确认 codegraph 在 Agent 进程能解析到的 PATH 上；Cursor 配置里带有 --path；改完配置后已重启。仍不行就再跑一次 codegraph install 重写配置。

• 找不到符号：等一两秒让监视器 sync；或手跑 codegraph sync。确认文件扩展名受支持，且不在默认排除目录或 .gitignore 内。

• database is locked：优先升级到带自带运行时的版本（本文的 1.6.2 已是该路线）。codegraph status 里 Journal 若不是 wal，常见于网络盘或 WSL2 的 /mnt 路径，把项目（含 .codegraph/）放到本地磁盘。

• 同一项目多个 serve --mcp 抢写：保留默认 daemon，让多个宿主共用一个监视进程；若设了 CODEGRAPH_NO_DAEMON=1，同一项目只保留一个 writer。

• Windows 与 WSL 共用一份检出：不要共用同一个 .codegraph/。WSL 侧可用 CODEGRAPH_DIR=.codegraph-wsl 再 init，两边各管各的索引。

命令速查

命令	含义
codegraph install	把 MCP 接到各 Agent
codegraph uninstall	从 Agent 拆掉配置（可加 --keep-cli）
codegraph init	创建 .codegraph/ 并全量建图
codegraph uninit	删除项目的 .codegraph/
codegraph index / sync	全量重建 / 增量同步
codegraph status	索引统计与健康情况
codegraph explore / node / query	探索、读符号、搜名称
codegraph callers / callees / impact	调用方、被调用、影响面
codegraph affected	按变更文件找受影响的测试
codegraph cycles	列出文件间循环 import
codegraph upgrade / version	升级 / 看版本
codegraph telemetry on|off	匿名遥测开关