CodeGraph 使用教程：用知识图谱重构代码库检索链路

1. 大型代码库里，AI 代理为什么总在“重新找路”

维护一个几万文件的老仓库时，我最大的感受是：AI 代理并不笨，它只是每次都在从零开始认路。你问它“登录请求最终落到哪个数据库方法”，它会先 grep 关键词，再 glob 找文件，再 Read 一堆候选，最后拼出一个大概的答案。这个过程里，真正用于推理的 token 被大量消耗在“找文件”上，而不是“理解逻辑”上。

CodeGraph 想解决的就是这件事。它是一个本地优先的代码知识图谱工具，用 tree-sitter 把代码解析成 AST，抽出函数、类、方法、类型这些节点，以及调用、导入、继承这些边，存进本地 SQLite，再通过 MCP 协议、CLI 或 TypeScript 库暴露给 AI 代理。简单说，它把“每次重新扫描文件”换成了“预先建好一张图，代理直接查图作答”。

它适合谁？适合手里有中大型代码库、已经在用 Claude Code / Cursor / Codex CLI 这类代理、并且明显感觉到“代理找代码比写代码还慢”的开发者。如果你只是维护一个几百文件的小项目，收益有限；但当你面对 VS Code 这种约一万文件的 TypeScript 仓库时，差距就出来了。官方在 7 个真实开源项目上做过对比，平均省 18% 成本、少 51% token、快 16%、少 57% 工具调用次数，这些数字背后其实就是“少走冤枉路”。

这篇教程不堆概念，我会按“装好 → 建图 → 配 Key → 验证一次检索 → 排错”的顺序走一遍，中间给出可复制的config.toml骨架和 TaoToken 统一 Key 的配置示例，让你能快速判断它值不值得接进现有工程。

2. 前置准备：装 CodeGraph，并让 TaoToken 统一管 Key

CodeGraph 本身是 100% 本地运行的，建图和查询都不需要 API Key，数据也不出机器。但你在实际工作流里，代理要调用模型来“读图作答”，这部分模型调用需要一个稳定的入口。我的做法是用 TaoToken 统一管理 Key，这样 CodeGraph 负责“图”，TaoToken 负责“模型通道”，两边职责清晰。

先装 CodeGraph。如果你机器上已经有 Node.js，直接全局装最省事：

npm install -g @colbymchenry/codegraph

没有 Node.js 也行，官方提供带内置运行时的安装脚本：

# 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

装完可以用安装器一键把 MCP 配置写进你已有的代理里，它会自动检测 Claude Code、Cursor、Codex CLI 等：

npx @colbymchenry/codegraph

非交互场景（比如脚本里）可以这样：

codegraph install --target=claude --yes codegraph install --print-config codex # 只打印配置片段，不写文件

接下来是 TaoToken 这边。先去控制台拿一个统一 Key，地址是https://taotoken.net/api-keys，登录后创建一个 Key 并复制。这个 Key 后面会写进config.toml，作为模型调用的统一凭证。TaoToken 的 API 入口是https://taotoken.net/api，兼容常见的 OpenAI 风格调用方式，所以配置起来就是填 base_url 和 api_key 两件事。

注意：CodeGraph 的建图和查询完全本地，不需要 Key；Key 只用于代理侧的模型调用。两者不要混在一起理解。

3. 可复制配置：config.toml 骨架与统一 Key 写法

CodeGraph 本身是零配置的，按文件扩展名自动识别语言，默认还会跳过node_modules、dist、.venv、target、Pods、vendor这些目录。所以这里的config.toml主要是给“代理 + 模型通道”用的，把 TaoToken 的统一 Key 和 CodeGraph 的 MCP 服务串起来。

下面是一份可以直接抄的骨架，放在项目根目录或你的代理配置目录下都行：

# config.toml —— 代理侧统一配置骨架 [model] # TaoToken 统一入口，兼容 OpenAI 风格 base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken统一Key" # 按你实际使用的模型名填写 model = "claude-sonnet-4-5" timeout_seconds = 120 [codegraph] # CodeGraph 以 MCP stdio 方式启动 command = "codegraph" args = ["serve", "--mcp"] # 项目索引目录，默认就是项目根下的 .codegraph/ data_dir = ".codegraph" [codegraph.sync] # 文件监听防抖窗口，单位毫秒，范围 [100, 60000] debounce_ms = 2000 # 沙箱或 CI 里可关闭守护进程，改用手动 sync no_daemon = false

如果你用的是 Claude Code，MCP 那段也可以直接写进~/.claude.json，效果等价：

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

几个参数我解释一下，避免你抄完不知道在调什么。debounce_ms控制的是文件改动后多久触发增量同步，默认 2000ms，批量写入场景可以调到 5000；no_daemon在沙箱环境里文件监听被禁用时设为 true，然后靠codegraph sync手动补；data_dir一般不用改，索引就存在项目根的.codegraph/codegraph.db。

提示：Key 不要提交进 Git。建议用环境变量注入，比如在 shell 里export TAOTOKEN_API_KEY=...，然后配置里写api_key = "${TAOTOKEN_API_KEY}"。

配置写完后，进项目目录初始化并建索引：

cd your-project codegraph init -i

init会创建.codegraph/目录，-i表示同时构建初始索引。这一步只做一次，之后靠自动同步维护。建完可以看一眼状态：

codegraph status

正常会输出节点数、边数、文件数，以及 SQLite 后端信息。如果看到Journal: wal，说明用的是 WAL 模式，并发读写更稳。

4. 验证一次：从索引到图谱检索的完整动作

配置对不对，跑一次检索就知道。我建议按“CLI 查询 → MCP 查询 → 影响分析”三步验证，每步都有明确的成功标志。

第一步，用 CLI 直接查符号，确认图里有东西：

codegraph query UserService --kind class --limit 10

如果返回了类名、所在文件、行号，说明索引和查询链路是通的。想拿 JSON 方便脚本处理就加--json：

codegraph query handleRequest --json

第二步，验证调用关系。这是知识图谱相对 grep 的核心价值——grep 只能告诉你“这个词出现在哪”，图能告诉你“谁调用了它”：

codegraph callers handleRequest --limit 20 codegraph callees handleRequest --limit 20

callers找的是“谁调用了 handleRequest”，callees找的是“handleRequest 调用了谁”。改函数前先跑一遍callers，能快速评估影响面。

第三步，做一次影响分析，模拟重构前的安全评估：

codegraph impact UserService --depth 2

它会用 BFS 往外扩散，列出改动这个符号后可能受影响的代码。--depth控制追踪深度，默认 5，深度越大越全但越慢。

如果你更想在代理会话里验证，那就重启 Claude Code 或 Cursor，让它加载 MCP 服务，然后直接对话：“用 codegraph 查一下 UserService 的调用者”。代理会调用codegraph_callers工具，返回结构化结果。成功标志是：代理不再先 grep 再 Read 一堆文件，而是直接给出调用点列表。

还有一个 CI 场景的验证，很实用：

git diff --name-only HEAD | codegraph affected --stdin --quiet

它会根据变更文件追踪依赖，找出受影响的测试文件。配合 vitest 就能只跑相关测试：

AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet) if [ -n "$AFFECTED" ]; then npx vitest run $AFFECTED; fi

跑通这三步，基本可以判断 CodeGraph 适不适合你的工程了。

5. 本篇常见错排查：从 not initialized 到 database is locked

实际接入时踩的坑，大多集中在初始化、索引和 MCP 连接这三块。我把高频问题和处理方式列一下。

“CodeGraph not initialized” 错误：最常见，就是项目没初始化。进项目目录跑codegraph init -i即可。注意每个项目都要单独 init 一次，全局装完不代表所有项目都建好图了。

索引速度很慢：先确认node_modules、dist、vendor这些有没有被排除。CodeGraph 默认会跳过一批目录，但如果你项目结构特殊，最好把它们写进.gitignore。另外可以用--quiet减少输出开销，再用codegraph status看已索引文件数是否异常偏大。

MCP 报database is locked：多半是旧版本（< 0.9）的问题，升级到最新版通常就好：

npm i -g @colbymchenry/codegraph@latest

如果升级后还报，跑codegraph status看Journal是不是wal。如果不是，说明当前文件系统不支持 WAL，常见于网络共享目录和 WSL2 的/mnt路径。把项目（含.codegraph/）移到本地磁盘即可。

MCP 服务器无法连接：按顺序排查——先codegraph status确认已初始化；再检查 MCP 配置里的 command 路径对不对；最后命令行手动跑codegraph serve --mcp，看能不能正常启动，能启动说明是代理侧配置问题。

符号缺失 / 找不到函数：几种可能。文件刚保存还在防抖窗口内，等 2 秒重试或跑codegraph sync；文件语言不在支持列表里；文件被.gitignore排除了；文件在默认排除目录中。对照支持语言表（TS/JS/Python/Go/Rust/Java/C#/PHP/Ruby/C/C++/Swift/Kotlin 等 20 多种）确认一下。

索引状态怎么确认：CLI 用codegraph status，代理会话里用codegraph_status工具。输出里如果有### Pending sync:段，说明有文件待同步；没有这段就是最新的。

注意：自动同步有三层保障——文件监听 + 防抖、过期提示横幅、连接时追赶同步。绝大多数情况下你不需要手动codegraph sync，只有在沙箱禁用监听、设了CODEGRAPH_NO_DAEMON=1、或 CI 脚本开头需要确保最新时才手动跑。

6. 接入建议：把图检索接进你的日常编码流

跑完验证、排完错，最后说下怎么把它真正用起来。我的经验是分两条线：一条是“查”，一条是“改”。

查的线，交给代理自动选工具就行。CodeGraph 暴露了 10 个 MCP 工具，代理会根据任务自动挑：找符号位置用codegraph_search，理解功能区域用codegraph_context，追调用链用codegraph_trace，改前评估用codegraph_impact。你不需要记这些名字，但知道它们存在，能在代理答得不对时手动指定，比如“用 codegraph_trace 追一下请求到数据库的路径”。

改的线，重点用codegraph affected接进 CI。每次提交前跑一次，只测受影响的文件，比全量跑测试省时间。配合codegraph impact做重构前评估，能避免“改一个函数，崩三个模块”的意外。

如果你还在选模型通道，TaoToken 的统一 Key 在这里的价值是：CodeGraph 负责本地图检索，模型调用走一个稳定入口，两边解耦。想先体验模型对话可以走https://taotoken.net/models；长期做编码和 Agent 工作流，可以看 Coding Planhttps://taotoken.net/coding-plan；接入细节和参数说明在文档https://taotoken.net/doc；Key 管理在控制台https://taotoken.net/console。把这些串起来，你的代码库检索链路就从“每次重新找路”变成了“查图直达”。