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 接入 agent：MCP 配置全流程
MCP（Model 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 - 控制台拿 Key：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
拿到 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 Compatible
- Base URL：
https://taotoken.net/api - API Key：你的 Key
- Model 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/api，Key 是OPENAI_API_KEY，Model 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_TOKEN，OpenAI 兼容的用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 排查速查表
| 报错 | 最可能原因 | 处理 |
|---|---|---|
| 401 | Key 错/漏/过期 | 重新复制 Key，检查认证字段名 |
| local proxy failed | 误设代理或 Base URL 指向本地 | 清代理变量，Base URL 填https://taotoken.net/api |
| reading choices | 端点不兼容或 Model ID 错 | curl 验证端点，改 Model ID |
| OAuth 冲突 | 同时存在两种认证 | 只保留 API Key |
| MCP 起不来 | 路径或 PATH 问题 | 用绝对路径，手动跑验证 |
排查的核心思路是分层：先确认模型接入通不通（curl 验证），再确认 MCP server 起不起得来（手动跑），最后确认 agent 有没有正确加载配置（重启后看工具列表）。
6. 让 agent 真正用起来：接入与进阶
配置通了只是开始，怎么让 agent 在日常工作里真正用上图谱，才是关键。
6.1 接入文档与 API Key
如果你还没拿到 Key，或者想确认接入细节，这两个入口：
- 拿 API Key：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite
文档里有各语言、各客户端的完整配置示例，比对着改就行。
6.2 验证模型是否正常工作
配好之后想快速验证模型通不通，可以用模型对话页面发一条测试消息：
https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite
能正常回复，说明 Base URL、Key、Model ID 三件套没问题，再去配 agent 就少一层变量。
6.3 长期编码与 Agent 场景
如果你打算把 codegraph + agent 用在长期项目上，比如持续重构、维护大型代码库，可以考虑 Coding Plan：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite
它更适合高频、长时间的编码 agent 调用场景，比按次调用更划算。
6.4 日常使用建议
第一，每次让 agent 改代码前，先跑codegraph sync，保证图谱是最新的。第二，重构类任务让 agent 先调impact和affected，拿到影响范围再动手。第三，接手新项目时，用explore快速理清核心调用链，比人肉读代码快。第四，把常用的查询命令写成脚本，减少重复输入。
6.5 一个真实的重构流程
最后给一个我实际用的流程。假设要把UserService.findUser的返回类型从User改成Optional<User>：
第一步，codegraph sync更新索引。第二步，codegraph callers "UserService.findUser"找出所有调用方。第三步，codegraph affected "UserService.findUser"找出受影响的测试。第四步，把调用方和测试列表丢给 agent，让它逐个改。第五步，改完编译，跑测试。第六步，codegraph sync再更新一次索引。
这个流程里，agent 不再靠猜，每一步都有图谱数据支撑。改完的东西编译通过率明显比盲改高。
codegraph 的价值不在于它多复杂，而在于它把「项目结构」这件事从 agent 的猜测变成了可查询的事实。SQLite 做存储，MCP 做接口，agent 做消费，三层各司其职。配好之后，你会发现 agent 改代码的准确率有一个肉眼可见的提升。
