本文目录8 个章节
CodeGraph 会把代码库解析成可查询的本地知识图谱。图中包含文件、函数、类、调用、导入与继承等关系。AI 编程 Agent 可以直接查询相关源码、调用路径和改动影响范围，不必每次从 grep 和逐文件读取开始重建代码结构。
这篇教程使用 colbymchenry/codegraph。完成后，你可以安装 CLI、接入 Codex 或其他受支持的 Agent、为项目建立索引，并用 explore、impact 和 affected 完成代码理解、改动评估与测试筛选。
01. CodeGraph 的工作方式
CodeGraph 的核心产物是一个 本地代码知识图谱。它用 Tree-sitter 解析源码，提取符号与关系，再把结果写入项目内的 SQLite 数据库。默认目录是 .codegraph/。
Agent 通过 MCP 查询这张图。一次 codegraph_explore 调用可以返回相关符号的带行号源码、符号之间的调用路径，以及依赖这些符号的代码范围。它适合回答“登录请求如何到达数据库”“修改这个接口会影响什么”这类结构问题。
Source files
|
v
Tree-sitter extraction
|
v
.codegraph/codegraph.db
|
v
MCP / CLI query
|
v
Source + call paths + blast radius代码仍在本机完成解析和查询。 官方同时提供可关闭的匿名使用遥测。它不等同于把代码、路径、符号名或查询内容上传给外部模型服务。
02. 安装 CLI 并接入 Agent
完整设置包含 安装 CLI、接入 Agent、初始化项目 三个动作。只安装 CLI 不会自动配置 MCP；只运行 codegraph install 也不会替项目建立索引。
CodeGraph 初始设置
-
安装 CodeGraph CLI
使用官方独立安装脚本，或通过 npm 安装全局包。
-
接入 AI 编程 Agent
运行交互式安装器，让它检测并配置 Codex CLI、Claude Code、Cursor、Gemini CLI 等受支持客户端。
-
初始化目标项目
进入代码库后运行
codegraph init。命令会创建.codegraph/并在同一步完成首次建图。
# Install the CodeGraph CLI globally with npm
npm i -g @colbymchenry/codegraph
# One-shot alternative: download and run the interactive installer
npx @colbymchenry/codegraph没有 Node.js 时，可以改用官方 Installation 页面提供的 Windows、macOS 或 Linux 独立安装器。独立安装器把 codegraph 加入 PATH 后，不会刷新当前终端。建议打开一个新终端，再运行后续命令。
# Connect CodeGraph to detected agents
codegraph install
# Confirm that the CLI resolves in the new terminal
codegraph version安装器可以检测 Codex CLI、Claude Code、Cursor、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 与 Kiro。配置完成后重启 Agent，让 MCP 服务在新会话中加载。
03. 初始化项目并完成第一次查询
进入目标代码库后运行 codegraph init。这个命令会同时 创建项目索引并完成首次全量建图，无需再补一次 codegraph index。
# Enter the project that should be indexed
cd your-project
# Create .codegraph/ and build the first full graph
codegraph init
# Verify file, node, edge, SQLite, and journal statistics
codegraph statuscodegraph status 应显示文件、节点和边的数量，以及 SQLite 后端与 journal mode。若命令报告项目尚未初始化，通常是当前目录不对，或该项目还没有运行过 codegraph init。
第一次查结构时，优先使用 自然语言入口 codegraph explore。它会把相关源码、关系图和影响范围合在一次结果中。
# Ask a natural-language architecture question
codegraph explore "how does login work"
# Find a class by name
codegraph query UserService --kind class --limit 10
# Inspect both directions of a call relationship
codegraph callers handleRequest
codegraph callees handleRequest| 命令 | 适合的问题 | 主要输出 |
|---|---|---|
explore | 一段流程如何工作，或多个符号如何关联 | 相关源码、调用路径与影响摘要 |
query | 某个函数、类或符号在哪里 | 匹配符号及其位置 |
node | 读取单个符号或文件 | 带行号源码与调用关系 |
callers | 谁调用了这个符号 | 反向调用关系 |
callees | 这个符号调用了谁 | 正向调用关系 |
04. 在 Codex 与其他 Agent 中使用
Agent 启动项目会话时，会自动运行 codegraph serve --mcp。你通常 不需要手动启动 MCP 服务。项目存在 .codegraph/ 后，默认工具 codegraph_explore 才会出现在 Agent 的可用工具中。
Agent 查询 CodeGraph 的执行链路
-
接收结构问题
Agent 识别函数、文件、业务流程或改动目标。
-
调用
codegraph_exploreMCP 服务从当前项目的本地图谱中检索相关符号。
-
返回源码与关系
结果按文件组织带行号源码，并附上调用路径与改动影响摘要。
-
执行修改与验证
Agent 根据图谱结果定位代码，再运行项目自己的测试与检查。
可以直接向 Agent 提出以下问题：
- “登录请求从路由到数据库经过哪些函数？”
- “修改
AuthMiddleware前，列出调用方、下游调用和可能受影响的测试。” - “解释
UserService与缓存层的关系，并给出对应源码位置。”
把文件名、符号名和目标流程写进问题，结果通常更稳定。 如果一个工作区包含多个已索引项目，Agent 还可以通过 projectPath 查询另一份索引；没有索引的路径会回退到 Agent 自带的搜索工具。
05. 改代码前检查影响范围
codegraph impact 从目标符号向外追踪依赖关系。codegraph affected 则从变更文件出发，沿导入依赖查找可能受影响的测试。两者组合后，可以形成 改动前查影响、改动后筛测试 的工作流。
改动影响检查
-
先理解目标符号
用
explore查看实现、调用路径和已有影响摘要。 -
扩大影响追踪深度
用
impact --depth检查更远的依赖层级，并确认高风险调用方。 -
选择相关测试
把变更文件交给
affected，再将输出接入项目实际使用的测试命令。
# Inspect the blast radius of a symbol
codegraph impact AuthMiddleware --depth 3
# Find tests affected by one changed source file
codegraph affected src/auth.ts
# Feed the current Git diff into affected-test discovery
git diff --name-only | codegraph affected --stdin
# Produce machine-readable impact data for a script
codegraph impact AuthMiddleware --depth 3 --jsonaffected 默认最多遍历五层依赖，也支持自定义测试文件 glob 和纯路径输出。它适合缩小测试集合，但不能代替完整测试策略。
静态依赖图无法覆盖所有运行时关系。 反射、运行时依赖注入、动态字符串路由和外部服务契约，仍需通过集成测试、日志或人工审查补足。
06. 保持索引同步
MCP 服务默认启动文件 watcher。源码发生创建、修改或删除后，CodeGraph 会合并短时间内的连续写入，再增量更新图谱。正常的 Agent 会话不需要反复手动运行 codegraph sync。
# Check index health and statistics
codegraph status
# Manually apply changed files when the watcher is unavailable
codegraph sync
# Rebuild the complete graph when configuration or mappings changed
codegraph index --force
# Remove a confirmed stale indexing lock
codegraph unlock| 命令 | 使用时机 | 代价 |
|---|---|---|
status | 检查节点、边、文件、SQLite 后端与 journal mode | 只读检查 |
sync | watcher 被沙箱禁用，或脚本运行前需要预检 | 只处理变更文件 |
index --force | 扩展名映射、包含范围或索引状态需要彻底重建 | 重新处理整个项目 |
unlock | 已确认没有索引进程，但陈旧锁仍阻塞建图 | 移除锁文件后再建图 |
如果 Agent 刚修改了文件，查询结果会在短暂同步窗口内标出待更新文件。看到 staleness 提示时，Agent 应直接读取该文件，或等待增量同步完成后再查询。
07. 控制索引范围与本地数据
索引范围由 支持的文件扩展名、默认排除目录和 .gitignore 共同决定。node_modules、vendor、dist、build、.next 等依赖或构建目录默认不进入图谱；超过 1 MB 的文件也会跳过。
提交到仓库但不应索引的目录，可以放进项目根目录的 codegraph.json。非标准扩展名也可以在同一文件里映射到受支持的语言。
{
"exclude": ["static/", "**/vendor/**"],
"include": ["Tools/", "Local/typescript/"],
"extensions": {
".dota_lua": "lua",
".tpl": "php"
}
}修改 codegraph.json 后运行 codegraph index --force，让范围和扩展名映射完整生效。exclude 优先级高于 include，内置排除目录不能通过 include 重新加入。
官方说明称，源码、路径、符号名与查询内容不会进入匿名遥测。如果组织策略要求完全关闭使用统计，可以执行：
# Disable anonymous usage telemetry
codegraph telemetry off08. 排查问题与清理安装
排查 CodeGraph 时，先看 codegraph status，再判断连接、锁或索引范围问题。不要在 MCP 连接失败时手动常驻运行 serve --mcp；受支持的 Agent 会自行启动服务。
| 症状 | 首先检查 | 处理方式 |
|---|---|---|
CodeGraph not initialized | 当前目录是否为目标项目 | 在项目根目录运行 codegraph init |
| MCP 服务无法连接 | 索引状态与 Agent 配置路径 | 运行 status，必要时重跑 codegraph install |
| 缺少新符号 | 文件是否待同步、受支持或被排除 | 稍候自动同步，或运行 codegraph sync |
database is locked | 版本、journal mode、网络盘或 WSL 路径 | 升级版本；把项目和索引移到本地文件系统 |
| 索引速度异常 | 依赖目录和生成目录是否进入扫描范围 | 修正 .gitignore 或 codegraph.json 后重建 |
# Check whether an upgrade is available
codegraph upgrade --check
# Upgrade the current installation
codegraph upgrade
# Remove only this project's .codegraph/ index
codegraph uninit
# Remove agent configurations but keep the CLI
codegraph uninstall --keep-cli
# Remove configured integrations and the CLI
codegraph uninstallREFERENCES