codegraph 本地代码知识图谱：给 agent 用的 SQLite + MCP 配置指南

1. 为什么 agent 需要一张本地代码知识图谱先说一个我反复遇到的场景让编码 agent 改一个方法签名它信心满满地改完编译一跑十几个调用方全红。原因不复杂——agent 对项目结构的理解来自上下文窗口里那点片段它看不到完整的调用链只能靠猜。项目小的时候猜得准项目一大就开始编。codegraph 想解决的就是这件事。它是一个本地代码知识图谱工具专门给 AI agent 用。核心逻辑很直接把代码库解析成图结构符号是节点调用和依赖关系是边全部落到本地 SQLite 文件里再通过 CLI 或 MCP 协议暴露给 agent 查询。支持 Python、Java、TypeScript、Go 等主流语言。它给编码 agent 带来的实际价值我按使用顺序列一下减少幻觉。agent 不再靠猜代码结构而是查真实的图数据。你问「谁调用了 findUser」它去 SQLite 里 select而不是从记忆里编一个答案。节省上下文。不用把整个代码库塞进 prompt按需查询相关片段就行。一个 700 多文件的项目索引文件 55MB但 agent 每次只取它需要的那几十行。避免改坏东西。改之前先查影响范围知道要一起改哪些测试和调用方。这个能力在重构时特别值钱。理解遗留代码。面对不熟悉的代码库能快速理清调用链和依赖关系比人肉 grep 快得多。适合谁用需要让 AI 编程助手理解项目结构的开发者尤其是维护中大型项目、经常做重构、或者接手别人代码的人。如果你只是写几十行脚本用不上但项目一旦超过几百个文件agent 的「盲改」问题就会变得很痛。这篇会交付三件事SQLite 存储的初始化、MCP 服务接入 agent 的可复制配置、以及用真实仓库验证图谱查询与 agent 调用链路的完整步骤。全程可跟做。2. 安装 codegraph 并初始化 SQLite 索引2.1 安装与国内源加速codegraph 通过 npm 分发。国内网络直接装官方源会比较慢建议走镜像npm install -g colbymchenry/codegraph --registry https://registry.npmmirror.com装好后确认一下位置。如果你用 nvm 管理 Node路径大概长这样which codegraph # ~/.nvm/versions/node/v24.18.0/bin/codegraph能打印出路径就说明装好了。如果提示 command not found检查一下 npm 全局 bin 目录是否在 PATH 里。2.2 建索引init 与 index进入你的项目根目录执行初始化cd /path/to/your-project codegraph init这一步会在项目下创建.codegraph/目录并生成codegraph.db。接着建索引codegraph index索引过程会遍历源码文件解析出符号和关系写入 SQLite。项目越大耗时越长700 多个 Java 文件的项目大概几十秒到一两分钟。索引完成后用 status 看统计codegraph status输出类似这样CodeGraph Status Project: /Users/xxx/code_work/xx Index Statistics: Files: 771 Nodes: 20,406 Edges: 35,840 DB Size: 55.41 MB Backend: node:sqlite — built-in (full WAL) Journal: wal Nodes by Kind: import 8,238 method 5,411 field 3,425 file 761 namespace 723 class 707 enum_member 610 constant 422 enum 58 interface 21 function 20 variable 10 Files by Language: java 724 xml 36 properties 5 yaml 5 python 1 ✓ Index is up to date这里有几个点值得注意。Backend 显示node:sqlite — built-in (full WAL)说明它用的是 Node 内置的 SQLite 模块开启了 WAL 日志模式。WAL 的好处是读写并发更友好agent 查询时不会阻塞索引更新。Nodes by Kind 里 import 占了 8238 个说明这个项目依赖关系很密这正是图谱能发挥价值的地方。2.3 增量更新sync代码改了之后不需要重新全量索引用 sync 做增量更新codegraph sync它只处理变更的文件速度快很多。建议在 agent 开始工作前跑一次保证图谱和当前代码一致。2.4 常用查询命令速查codegraph 的 CLI 提供了一组查询命令先列出来后面会逐个演示命令作用query搜索符号callers查谁调用了某符号callees查某符号调用了谁explore一次性看源码 调用链 影响范围impact分析改某符号会影响哪些代码affected找受影响的测试文件这些命令是后面 MCP 接入的基础agent 通过 MCP 调用的其实就是同一套能力。3. 把 codegraph 接入 agentMCP 配置全流程MCPModel Context Protocol是 agent 调用外部工具的协议。codegraph 作为 MCP server 启动后agent 就能把图谱查询当成一个工具来用。这一节给出可复制的配置。3.1 先拿 API Key 和 Base URL如果你用的是云端模型驱动的 agent比如 Claude Code、Cline 这类需要先准备好模型接入信息。我用的是 TaoToken 的接入方式Base URL 和 Key 在控制台拿API 地址https://taotoken.net/api控制台拿 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到 Key 后模型 ID 按你实际用的填比如claude-sonnet-4-5这类。三件套Base URL Key Model ID在下面每个配置里都会出现别漏。3.2 Claude Code 的 MCP 配置Claude Code 的 MCP 配置放在项目或用户级的 settings 里。在项目根目录创建.mcp.json{ mcpServers: { codegraph: { command: codegraph, args: [mcp, --db, ./.codegraph/codegraph.db], env: {} } } }如果你希望 Claude Code 同时走 TaoToken 的模型接入在~/.claude/settings.json里配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要带 UTM 参数。Key 从上面控制台链接拿。3.3 Cline 的 MCP 配置Cline 的 MCP 配置在 VS Code 的设置里路径是cline_mcp_settings.json。内容{ mcpServers: { codegraph: { command: codegraph, args: [mcp, --db, ./.codegraph/codegraph.db], disabled: false, autoApprove: [query, callers, callees, impact] } } }autoApprove里列的是允许 agent 自动调用的工具不用每次弹窗确认。查询类工具可以放进去写操作类的建议保留确认。Cline 的模型接入同样走三件套在 Cline 的 API 配置里填API Provider 选 OpenAI CompatibleBase URLhttps://taotoken.net/apiAPI Key你的 KeyModel ID按实际填3.4 Codex 的 auth.json 配置如果你用 Codex CLI模型接入信息放在~/.codex/auth.json{ OPENAI_API_KEY: 你的_API_KEY, OPENAI_BASE_URL: https://taotoken.net/api }MCP server 的注册在 Codex 的配置文件里把 codegraph 加进去[mcp_servers.codegraph] command codegraph args [mcp, --db, ./.codegraph/codegraph.db]三件套在这里同样齐全Base URL 是https://taotoken.net/apiKey 是OPENAI_API_KEYModel ID 在 Codex 的 config 里指定。3.5 配置检查清单配完之后对照检查第一codegraph mcp --db ./.codegraph/codegraph.db能不能手动跑起来不报错。第二agent 重启后能不能看到 codegraph 这个工具。第三Base URL 有没有误填成带 UTM 的地址。第四Key 有没有过期。第五Model ID 和实际模型是否匹配。这五条任何一条出问题agent 都会调不通下一节讲怎么验证。4. 验证图谱查询与 agent 调用链路配置完不能只看「没报错」就完事得实际验证。这一节用真实仓库跑一遍。4.1 直接用 sqlite3 验证索引codegraph 生成的是标准 SQLite 文件可以直接用 sqlite3 查。先看节点表sqlite3 ./.codegraph/codegraph.db SELECT * FROM nodes LIMIT 10;再看边表也就是调用和依赖关系sqlite3 ./.codegraph/codegraph.db SELECT * FROM edges LIMIT 10;输出类似1|file:src/Logger.java|class:eb9696a85f1d51e6cfc23212d3bd6543|contains|||| 2|class:eb9696a85f1d51e6cfc23212d3bd6543|method:4768bf7673844a5fec20e4ae4f6989c3|contains|||| 3|file:src/User.java|class:89e1ddb5e0719a82e1de008802f4c305|contains|||| 4|class:89e1ddb5e0719a82e1de008802f4c305|field:3d1b9111729baeb1f37d982b4af9fa09|contains||||每行格式是id | 源节点 | 目标节点 | 关系类型 | ...。contains表示包含关系比如文件包含类、类包含方法。这个结构就是图谱的骨架。4.2 用 CLI 查调用关系拿一个具体方法试。假设有个UserService.findUser查谁调用了它codegraph callers UserService.findUser查它调用了谁codegraph callees UserService.findUser看完整上下文包括源码、调用链、影响范围codegraph explore UserService.findUser分析改动影响codegraph impact UserService.findUser找受影响的测试codegraph affected UserService.findUser这几个命令的输出就是 agent 通过 MCP 能拿到的数据。你可以先手动跑一遍确认图谱数据是对的再让 agent 去调。4.3 在 agent 里验证调用链路打开配好 MCP 的 agent问一个需要图谱才能答准的问题比如项目里 UserService.deleteUser 调用了哪些方法如果我要改它的返回值类型哪些测试文件会受影响agent 应该会调用 codegraph 的callees和affected工具然后基于返回结果回答。如果它直接凭记忆编说明 MCP 没接上。验证成功的标志agent 的回答里出现了具体的文件路径和方法名而且这些信息和你手动跑 CLI 得到的一致。这时候调用链路就通了。4.4 一个完整的验证脚本把上面的步骤串成一个脚本方便每次改完代码后跑#!/bin/bash set -e echo 同步索引 codegraph sync echo 查看状态 codegraph status echo 验证调用关系 codegraph callers UserService.findUser codegraph callees UserService.findUser echo 验证影响分析 codegraph impact UserService.findUser codegraph affected UserService.findUser echo 验证 SQLite 可读 sqlite3 ./.codegraph/codegraph.db SELECT COUNT(*) FROM nodes; sqlite3 ./.codegraph/codegraph.db SELECT COUNT(*) FROM edges;跑通这个脚本说明图谱和查询链路都没问题。5. 常见报错排查401、local proxy failed、reading choices配置过程中最容易踩的坑集中在模型接入和 MCP 通信两块。逐个说。5.1 401 Unauthorized这是最常见的。agent 调用模型时返回 401说明 Key 不对或没带上。排查顺序第一确认 Key 是从控制台复制的完整字符串没有多余空格。第二确认 Base URL 填的是https://taotoken.net/api不是首页地址也没带 UTM 参数。第三确认请求头里的认证字段名对——Claude Code 用ANTHROPIC_AUTH_TOKENOpenAI 兼容的用Authorization: Bearer。第四Key 是否过期或被禁用去控制台看一眼。如果手动 curl 能通但 agent 不通多半是 agent 的配置文件路径不对或者改了没重启。5.2 local proxy failed这个报错通常出现在 agent 尝试走本地代理但代理没起来的时候。检查两点一是你的配置里有没有误设HTTP_PROXY或HTTPS_PROXY环境变量有的话清掉二是 agent 的 Base URL 有没有被写成localhost或127.0.0.1开头的地址。正确做法是直接填https://taotoken.net/api让 agent 直连。5.3 Error reading choices / 响应解析失败这个报错说明请求发出去了但返回的 JSON 结构不符合 agent 预期。常见原因Base URL 填成了不兼容 OpenAI 格式的端点或者 Model ID 填错导致服务端返回了错误结构。排查先用 curl 直接打一次看返回的 JSON 长什么样curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: hi}] }如果返回里有choices字段说明端点没问题问题在 agent 配置如果返回的是错误信息按错误提示改 Model ID 或 Key。5.4 OAuth 相关报错有些 agent 默认走 OAuth 登录流程如果你用的是 API Key 接入需要在配置里显式关掉 OAuth。比如 Claude Code 里如果同时存在 OAuth token 和 API Key可能会冲突。检查~/.claude/下的凭据文件确保只保留一种认证方式。5.5 MCP server 起不来如果 agent 报「MCP server codegraph failed to start」先手动跑一遍codegraph mcp --db ./.codegraph/codegraph.db看报什么错。常见的是 db 路径不对相对路径在不同工作目录下解析不同建议用绝对路径。另一个是 codegraph 不在 PATH 里MCP 配置里的command要写绝对路径。5.6 排查速查表报错最可能原因处理401Key 错/漏/过期重新复制 Key检查认证字段名local proxy failed误设代理或 Base URL 指向本地清代理变量Base URL 填https://taotoken.net/apireading choices端点不兼容或 Model ID 错curl 验证端点改 Model IDOAuth 冲突同时存在两种认证只保留 API KeyMCP 起不来路径或 PATH 问题用绝对路径手动跑验证排查的核心思路是分层先确认模型接入通不通curl 验证再确认 MCP server 起不起得来手动跑最后确认 agent 有没有正确加载配置重启后看工具列表。6. 让 agent 真正用起来接入与进阶配置通了只是开始怎么让 agent 在日常工作里真正用上图谱才是关键。6.1 接入文档与 API Key如果你还没拿到 Key或者想确认接入细节这两个入口拿 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite文档里有各语言、各客户端的完整配置示例比对着改就行。6.2 验证模型是否正常工作配好之后想快速验证模型通不通可以用模型对话页面发一条测试消息https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite能正常回复说明 Base URL、Key、Model ID 三件套没问题再去配 agent 就少一层变量。6.3 长期编码与 Agent 场景如果你打算把 codegraph agent 用在长期项目上比如持续重构、维护大型代码库可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它更适合高频、长时间的编码 agent 调用场景比按次调用更划算。6.4 日常使用建议第一每次让 agent 改代码前先跑codegraph sync保证图谱是最新的。第二重构类任务让 agent 先调impact和affected拿到影响范围再动手。第三接手新项目时用explore快速理清核心调用链比人肉读代码快。第四把常用的查询命令写成脚本减少重复输入。6.5 一个真实的重构流程最后给一个我实际用的流程。假设要把UserService.findUser的返回类型从User改成OptionalUser第一步codegraph sync更新索引。第二步codegraph callers UserService.findUser找出所有调用方。第三步codegraph affected UserService.findUser找出受影响的测试。第四步把调用方和测试列表丢给 agent让它逐个改。第五步改完编译跑测试。第六步codegraph sync再更新一次索引。这个流程里agent 不再靠猜每一步都有图谱数据支撑。改完的东西编译通过率明显比盲改高。codegraph 的价值不在于它多复杂而在于它把「项目结构」这件事从 agent 的猜测变成了可查询的事实。SQLite 做存储MCP 做接口agent 做消费三层各司其职。配好之后你会发现 agent 改代码的准确率有一个肉眼可见的提升。