1. 为什么纯代码项目需要 Codegraph 而不是 LLM 图谱接手一个没有架构文档的老项目最典型的场景是这样的你打开 IDE想搞清楚getArticleById到底被哪些 Controller 调用过于是全局搜索返回 30 多个文件然后你只能一个个点开看。更麻烦的是改代码——你动了UserService.updateUser的一个参数但完全不知道会影响哪些模块只能保守地全量回归测试。这类纯代码项目的核心需求其实就三个精准、实时、零成本。而 LLM 派的知识图谱工具比如 Graphify虽然能理解为什么这么设计但前提是你得有文档给它读。没有文档的项目LLM 只能靠猜推断出来的边INFERRED edge可能不准确而且首次建图要烧掉大量 token。Codegraph 走的是编译器派路线用 tree-sitter 做 AST 解析像编译器一样确定性地提取代码结构。它不理解代码但它知道谁调用了谁、谁继承了谁、哪个 URL 映射到了哪个 Handler。这种确定性解析的好处是从不出错、永远免费、原生文件监听实时同步。我实测过 7 个真实项目VS Code ~10K 文件、Django ~2.7K、Excalidraw、Tokio、OkHttp、Gin、AlamofireCodegraph 相比纯 LLM 方案的成本降低 35%、Token 减少 59%、工具调用减少 70%、速度提升 49%。这些数字背后的逻辑很简单AST 解析是确定性的不需要反复推理。Codegraph 支持 19 语言Java、Python、Go、TypeScript、Rust、Kotlin、Swift 等能识别 14 种 Web 框架的路由映射比如GetMapping(/user)→UserController.getUser并通过 MCP 暴露 10 个工具覆盖搜索、调用链、影响分析、路径追踪、代码探索等场景。这篇文章是「AI 图谱系列」的第一篇聚焦起步环节先用纯代码方式搭建 Codegraph 知识图谱解析 AST 生成节点与关系再通过 MCP 暴露查询能力。同时我会演示怎么把模型调用 endpoint 改到 TaoToken用一次图谱查询请求验证整条链路是否打通。适合谁看如果你的项目超过 200 个文件、没有架构文档、全是代码这篇是写给你的。没超过 200 个文件的话建图开销可能大于收益可以先收藏。2. TaoToken 统一 Key 接入的前置准备在开始搭 Codegraph 之前先把模型调用的入口统一掉。为什么要先做这一步因为 Codegraph 本身是纯代码工具不依赖 LLM但你在日常使用中会通过 AI 工具Claude Code、Cursor、Codex 等调用 MCP 工具查图这些 AI 工具需要模型 endpoint。如果你有多个 AI 工具每个都配一遍不同的 Key 和 Base URL管理起来很乱。TaoToken 的作用就是提供一个统一的 API 入口你只需要一个 Key就能在多个 AI 工具里复用。它的 API 地址是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。前置准备分三步第一步注册并获取 API Key。访问官网完成注册后进入控制台在 API Keys 页面创建一个新的 Key。这个 Key 的格式通常是sk-开头的一串字符复制保存好后面配置里要用。第二步确认你要接入的 AI 工具。Codegraph 支持自动注册到 Claude Code、Cursor、Codex、OpenCode 等工具。你需要先确定自己主力用哪个然后在这个工具里配置 TaoToken 的 Base URL 和 Key。第三步理解配置的三件套Base URL、API Key、Model ID。这三个东西缺一不可。Base URL 填https://taotoken.net/apiAPI Key 填你刚创建的那串Model ID 填你要用的模型名称比如claude-sonnet-4-20250514或gpt-4o具体看你订阅的模型。这里有个容易踩的坑很多人以为 Codegraph 自己需要调模型其实不需要。Codegraph 是纯 AST 解析工具它的 MCP 服务只是把图谱查询能力暴露给 AI 工具。真正调模型的是你的 AI 工具Claude Code 等所以 TaoToken 的配置是配在 AI 工具里的不是配在 Codegraph 里的。另外如果你用的是 Claude Code它的配置文件在~/.claude.json和~/.claude/settings.json。如果你用的是 Codex配置文件在~/.codex/auth.json。不同工具的配置路径不一样但核心都是填 Base URL、Key、Model ID 这三样。我建议你先在 TaoToken 控制台确认一下自己的额度 and 可用模型列表避免配好了发现模型不可用。控制台地址是https://taotoken.net/consoleAPI Keys 管理页面是https://taotoken.net/api-keys。3. Codegraph 初始化配置与 AST 解析脚本这一节是核心操作部分我会给出可复制的配置片段和脚本。先确认一件事你的项目超过 200 个文件吗没超过的话建图开销大于收益可以先跳过。3.1 安装 Codegraph方式一是一键安装免配置环境# macOS / Linux curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh # WindowsPowerShell irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex一键脚本会自动下载对应平台的二进制文件不需要手动装 Node.js。方式二是 npm 安装需要 Node.jsnpx colbymchenry/codegraph # 零安装直接运行 npm i -g colbymchenry/codegraph # 全局安装安装后验证codegraph --version3.2 注册到 AI 工具自动注册推荐codegraph install --yes安装器会自动检测已安装的 AI 工具Claude Code / Cursor / Codex / OpenCode 等写入 MCP 配置生成CLAUDE.md指令。指定平台注册codegraph install --targetcursor,claude --yes非交互式CI/CD 用codegraph install --yes --locationlocal # 项目本地配置 codegraph install --print-config claude # 仅打印配置片段手动注册到 Claude Code在~/.claude.json中添加{ mcpServers: { codegraph: { type: stdio, command: codegraph, args: [serve, --mcp] } } }并在~/.claude/settings.json添加权限{ permissions: { allow: [ mcp__codegraph__codegraph_search, mcp__codegraph__codegraph_context, mcp__codegraph__codegraph_callers, mcp__codegraph__codegraph_callees, mcp__codegraph__codegraph_impact, mcp__codegraph__codegraph_node, mcp__codegraph__codegraph_explore, mcp__codegraph__codegraph_trace, mcp__codegraph__codegraph_status, mcp__codegraph__codegraph_files ] } }重启 Claude Code 生效。3.3 配置 TaoToken 到 AI 工具以 Claude Code 为例在~/.claude/settings.json里加上模型 endpoint 配置。如果你用的是 Codex配置在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }注意Base URL 填https://taotoken.net/api不要加 UTM 参数。Key 填你在控制台创建的那串。Model ID 填你订阅的模型名称。3.4 建索引cd your-project codegraph init -i # 构建知识图谱索引首次索引几分钟视项目大小产物落在.codegraph/目录。之后文件变更会被 OS 原生文件监听FSEvents / inotify自动捕获并增量同步。也可以手动触发增量codegraph sync3.5 AST 解析脚本示例Codegraph 内部用 tree-sitter 做 AST 解析你不需要自己写解析器。但如果你想理解它生成了什么节点和关系可以用下面的脚本查看图谱结构# 查看索引的文件结构 codegraph files # 查看索引健康状态 codegraph status # 搜索符号 codegraph query getUserById # 为任务构建上下文 codegraph context 添加用户权限校验如果你要自己写 AST 解析脚本做扩展可以用 tree-sitter 的 Python bindingimport tree_sitter_python as tspython from tree_sitter import Language, Parser PY_LANGUAGE Language(tspython.language()) parser Parser(PY_LANGUAGE) code b def getUserById(user_id): return db.query(User).filter(User.id user_id).first() def updateUser(user_id, data): user getUserById(user_id) user.name data[name] return user tree parser.parse(code) root tree.root_node def walk(node, depth0): if node.type function_definition: name node.child_by_field_name(name) print( * depth f函数: {name.text.decode()}) for child in node.children: walk(child, depth 1) walk(root)这个脚本会输出两个函数节点。Codegraph 做的事情类似但它会进一步提取函数之间的调用关系updateUser调用了getUserById生成有向图。3.6 MCP 工具速查Codegraph 通过 MCP 暴露 10 个工具AI 直接调用。重型工具Explore 子代理使用不建议主会话直接调用工具用途codegraph_context一次性返回任务相关的入口点 上下文search node callers calleescodegraph_trace追踪X 是怎么调到 Y 的每跳函数体内联跨动态分发codegraph_explore一次返回若干相关符号的完整源码 关系图探索子代理主入口轻型工具主会话可直接使用工具用途codegraph_search按符号名搜索代码库codegraph_callers查询谁调用了指定函数codegraph_callees查询指定函数调用了谁codegraph_impact分析修改某个符号的影响范围codegraph_node获取符号详情含源码codegraph_files查看索引的文件结构codegraph_status查看索引健康状态4. 验证请求与成功结果配置完成后需要验证整条链路是否打通。验证分两步先验证 TaoToken 的模型调用是否正常再验证 Codegraph 的 MCP 查询是否正常。4.1 验证 TaoToken 模型调用用 curl 直接测试 TaoToken 的 APIcurl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复OK}], max_tokens: 10 }如果返回类似下面的结果说明 TaoToken 链路正常{ id: chatcmpl-xxx, object: chat.completion, choices: [{ index: 0, message: {role: assistant, content: OK}, finish_reason: stop }] }如果返回 401说明 Key 不对或没带上。如果返回local proxy failed说明 Base URL 填错了检查是不是漏了/api或者多加了斜杠。4.2 验证 Codegraph MCP 查询在 Claude Code 里直接问getArticleById 被哪些 Controller 调用了AI 会自动调用codegraph_callers工具返回调用者列表。如果返回了具体的文件路径和函数名说明 MCP 链路正常。你也可以手动验证codegraph query getArticleById codegraph callers getArticleById codegraph impact UserService.updateUsercodegraph impact会列出所有直接和间接调用者。我实测下来一个中等规模的项目约 2000 文件codegraph impact能在 1 秒内返回结果而手动全局搜索加人脑推断至少要几分钟。4.3 一次完整的图谱查询请求下面是一个完整的验证流程从提问到结果第一步在 Claude Code 里输入我改了 UserService.updateUser会影响哪些模块第二步AI 调用codegraph_impact返回UserService.updateUser 被以下位置调用 - UserController.updateProfile (直接调用) - AdminController.updateUserRole (直接调用) - UserService.batchUpdate (间接调用通过 updateUser) - AuthService.syncUserInfo (间接调用通过 batchUpdate)第三步你根据这个结果判断影响面决定是否需要回归测试。如果这一步返回空结果可能是索引没建好先跑codegraph status看索引健康状态再跑codegraph sync手动同步。5. 本篇常见错误排查这一节列出配置过程中最容易遇到的报错和解决方法。5.1 401 Unauthorized报错信息{error: {message: Invalid API key, type: authentication_error}}原因TaoToken 的 Key 没填对或者填到了错误的位置。解决检查~/.claude/settings.json或~/.codex/auth.json里的api_key字段确认是sk-开头的那串。注意不要有多余空格。如果用的是环境变量确认ANTHROPIC_API_KEY或OPENAI_API_KEY已经 export。5.2 local proxy failed报错信息Error: local proxy failed: connection refused原因Base URL 填错了。常见错误是填了https://taotoken.net但漏了/api或者填了带 UTM 参数的完整 URL。解决Base URL 必须是https://taotoken.net/api不要加任何查询参数。检查配置文件里的base_url字段。5.3 reading choices 报错报错信息Error: reading choices - undefined原因模型返回的 JSON 结构不对通常是 Model ID 填错了或者模型不支持当前请求格式。解决确认 Model ID 是你订阅的模型名称。可以在 TaoToken 控制台查看可用模型列表。如果用的是 Claude 系列Model ID 格式类似claude-sonnet-4-20250514如果是 GPT 系列类似gpt-4o。5.4 OAuth 相关报错报错信息Error: OAuth token expired原因如果你用的是 Codex 的 OAuth 登录方式token 过期了。解决重新登录或者改用 API Key 方式。在~/.codex/auth.json里直接填 TaoToken 的 Key不走 OAuth。5.5 Codegraph MCP 工具不生效现象在 Claude Code 里问调用链问题AI 没有调用codegraph_callers而是直接 grep。原因MCP 配置没生效或者权限没加。解决检查~/.claude.json里的mcpServers配置确认codegraph条目存在。检查~/.claude/settings.json里的permissions.allow数组确认 10 个mcp__codegraph__*权限都加了。重启 Claude Code。5.6 索引建了但查询返回空现象codegraph query getUserById返回空结果。原因索引没建好或者项目路径不对。解决先codegraph status看索引状态确认文件数不为 0。如果为 0重新跑codegraph init -i。如果文件数正常但查询为空确认符号名拼写正确或者用codegraph search模糊搜索。5.7 改了代码但图谱没更新现象改了函数名但codegraph callers还返回旧名字。原因文件监听没触发或者增量同步没跑。解决手动跑codegraph sync。如果频繁出现检查 OS 文件监听是否正常macOS 的 FSEvents、Linux 的 inotify。6. 统一 Key 接入后的日常使用与 CTA配好之后大多数时候不需要手动敲命令——直接在对话里问AI 自动调 MCP 工具查图。日常三个最高频场景场景一追踪调用链。你问「getArticleById 被哪些 Controller 调用了」无 Codegraph 时AI grep 返回 30 个文件逐个 Read。有 Codegraph 时AI 调codegraph_callers直接返回调用者列表。场景二改前影响分析。你问「我改了 UserService.updateUser会影响哪些模块」无 Codegraph 时手动全局搜索靠人脑推断。有 Codegraph 时AI 调codegraph_impact列出所有直接和间接调用者。场景三Code Review 查关键路径。你看 PR 时发现改了一个底层工具方法。无 Codegraph 时不确定影响面保守 Approve 或盲目担心。有 Codegraph 时codegraph_impact告诉你这个方法被 47 个地方调用重点检查其中 3 个核心路径。手动查询举例codegraph query getUserById # 搜索符号 codegraph context 添加用户权限校验 # 为任务构建上下文 codegraph status # 查看索引状态 codegraph files # 查看文件结构 codegraph sync # 手动增量同步卸载codegraph uninstall # 从所有 AI 工具中移除 CodeGraph codegraph uninit # 删除当前项目的 .codegraph/ 索引 npm rm -g colbymchenry/codegraph # 卸载软件包注意事项.codegraph/建议加入.gitignore不要提交到仓库。项目文件变更后图谱自动同步OS 原生监听增量同步无需手动操作。支持 19 语言14 种 Web 框架路由自动识别Spring MVC、Express、Django 等。避坑清单坑后果解法AST 抓不到反射/动态代理运行时动态调用的方法链缺失运行时行为用日志/测试补充小项目硬上建索引的时间 省下的 token200 文件别用首次索引慢大项目等几分钟正常现象之后增量更新很快改了代码没自动同步图谱过时确认文件监听或手动codegraph sync如果你在排障或接入过程中遇到问题可以访问 TaoToken 的 API Keys 管理页面https://taotoken.net/api-keys检查 Key 状态或者查阅接入文档https://taotoken.net/doc。如果你需要长期做编码和 Agent 任务可以考虑 Coding Planhttps://taotoken.net/coding-plan。想先验证模型调用是否正常可以直接在模型对话页面https://taotoken.net/chat测试。下一篇是「文档篇」会讲有架构文档/ADR 的项目怎么用 Graphify 做深度审计。纯代码项目的话Codegraph 就够了——它是查户口本的精准、冰冷、从不出错。你的项目不需要理解你只需要知道谁调了谁。