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 统一管 KeyCodeGraph 本身是 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 --targetclaude --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 的建图和查询完全本地不需要 KeyKey 只用于代理侧的模型调用。两者不要混在一起理解。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 CodeMCP 那段也可以直接写进~/.claude.json效果等价{ mcpServers: { codegraph: { type: stdio, command: codegraph, args: [serve, --mcp] } } }几个参数我解释一下避免你抄完不知道在调什么。debounce_ms控制的是文件改动后多久触发增量同步默认 2000ms批量写入场景可以调到 5000no_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 -iinit会创建.codegraph/目录-i表示同时构建初始索引。这一步只做一次之后靠自动同步维护。建完可以看一眼状态codegraph status正常会输出节点数、边数、文件数以及 SQLite 后端信息。如果看到Journal: wal说明用的是 WAL 模式并发读写更稳。4. 验证一次从索引到图谱检索的完整动作配置对不对跑一次检索就知道。我建议按“CLI 查询 → MCP 查询 → 影响分析”三步验证每步都有明确的成功标志。第一步用 CLI 直接查符号确认图里有东西codegraph query UserService --kind class --limit 10如果返回了类名、所在文件、行号说明索引和查询链路是通的。想拿 JSON 方便脚本处理就加--jsoncodegraph query handleRequest --json第二步验证调用关系。这是知识图谱相对 grep 的核心价值——grep 只能告诉你“这个词出现在哪”图能告诉你“谁调用了它”codegraph callers handleRequest --limit 20 codegraph callees handleRequest --limit 20callers找的是“谁调用了 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/codegraphlatest如果升级后还报跑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_DAEMON1、或 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/docKey 管理在控制台https://taotoken.net/console。把这些串起来你的代码库检索链路就从“每次重新找路”变成了“查图直达”。