企业官网建设流程全解析

1. 为什么 Claude Code 在大型项目里总在“瞎找代码”

如果你用 Claude Code 分析过一个超过五万行的仓库，大概率见过这样的场景：你问“OrderService.createOrder 被谁调用了”，它先 grep 一遍，再读十几个文件，然后继续 grep，最后给你一个不太确定的答案。整个过程 Token 烧得飞快，响应还慢。问题不在于模型不够聪明，而在于它缺少一张“代码地图”——它不知道类与类、函数与函数之间的真实关系，只能靠文本搜索去猜。

CodeGraph 就是来解决这件事的。它是一个本地运行的代码知识图谱工具，用 Tree-sitter 把仓库解析成语法树，再抽取出定义、调用、继承、引用这些关系，存进 SQLite（带 FTS5 全文索引），最后通过 MCP（Model Context Protocol）暴露给 Claude Code、Cursor、Codex CLI 这类 AI 编程工具。AI 不再需要反复扫描整个仓库，而是直接查询“某个方法在哪里定义”“谁调用了这个方法”“改这个函数会影响哪些模块”。

这篇手册面向的是本地代码库索引场景，重点讲清楚三件事：CodeGraph 的 MCP 怎么接进 Claude Code、Tree-sitter 和 SQLite 索引怎么验证、从配置到查询的闭环怎么跑通。适合已经在用 Claude Code、手里有中大型项目（Spring Boot、微服务、K8s Operator、大型前端都算）的开发者。下面所有命令和配置都可以直接复制。

2. 前置准备：TaoToken 与 Claude Code 环境

在接 CodeGraph 之前，得先保证 Claude Code 本身能正常工作。Claude Code 需要模型服务，这里我用 TaoToken 来做接入，它的 API 地址是 https://taotoken.net/api，兼容 Anthropic 的接口格式，配置起来比较直接。

先拿到 API Key。打开 https://taotoken.net/api-keys ，创建一个 Key，复制出来。然后配置环境变量，让 Claude Code 走这个端点：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key"

如果你用的是 Claude Code 的 settings.json，可以写成这样：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key" } }

验证一下 Claude Code 能不能正常对话：

claude -p "用一句话说明什么是 MCP"

能返回内容就说明模型通道没问题。这一步很关键，因为 CodeGraph 的 MCP Server 是挂在 Claude Code 上的，如果 Claude Code 本身连不上模型，后面查图谱也白搭。

注意：ANTHROPIC_BASE_URL 不要带结尾斜杠，Key 不要提交到 Git 仓库，建议放在 shell 的 profile 文件或本地 settings.json 里。

环境准备好之后，确认 Node.js 版本在 18 以上，因为 CodeGraph 的 CLI 和 MCP Server 都依赖 Node 运行时：

node -v npm -v

3. 安装 CodeGraph 并生成 MCP 配置骨架

CodeGraph 提供三种安装方式，我实测下来最省事的是全局安装加codegraph install，因为它会自动检测你机器上已经装了哪些 Agent，并帮你写好 MCP 配置。

npm install -g @colbymchenry/codegraph codegraph install

执行codegraph install后，会出现一个交互式选择界面，大致长这样：

◆ Which agents should CodeGraph configure? │ ◼ Claude Code (detected) │ ◼ Cursor (detected) │ ◼ Codex CLI (detected) — global only │ ◼ opencode (detected) │ ◻ Gemini CLI (detected) └

勾选 Claude Code，然后它会问你是应用到所有项目还是当前项目：

◆ Apply agent configs to all your projects, or just this one? │ ● All projects (~/.claude, ~/.cursor, etc.) │ ○ Just this project

选 All projects 会写入~/.claude.json和~/.claude/settings.json。如果你只想给某个项目用，就选 Just this project，配置会写到项目目录下的.mcp.json或.claude/settings.json。

安装完成后，Claude Code 的 MCP 配置骨架大致是这样（~/.claude/settings.json片段）：

{ "mcpServers": { "codegraph": { "command": "codegraph", "args": ["mcp", "--project", "."], "env": {} } } }

如果你要手动写，注意command必须是codegraph在 PATH 里可执行，args里的--project指向你的代码库根目录。有些版本用的是codegraph serve --mcp，具体以codegraph --help输出为准。

提示：安装器还会问 “Auto-allow CodeGraph commands?”，选 Yes 可以跳过 Claude Code 里的权限提示，查询图谱时不会每次都弹确认。

4. 用 Tree-sitter 建索引并验证 SQLite 图谱

MCP 配置只是“通道”，真正让 Claude Code 能查的是索引。进入你的项目根目录，执行初始化：

cd demo-project codegraph init -i

-i表示交互式，会问你索引哪些语言、是否排除 node_modules 等。执行完后项目下会生成：

.codegraph/ ├── codegraph.db └── meta.json

codegraph.db就是 SQLite 数据库，里面存的是 Tree-sitter 解析出来的节点和边。你可以直接用 sqlite3 打开验证：

sqlite3 .codegraph/codegraph.db ".tables"

正常会看到类似nodes、edges、files、nodes_fts这些表。nodes_fts是 FTS5 全文索引表，用来做符号搜索。查一下某个类的定义：

sqlite3 .codegraph/codegraph.db \ "SELECT name, kind, file FROM nodes WHERE name='UserService' LIMIT 5;"

如果返回了文件路径和节点类型（class/interface），说明 Tree-sitter 解析和 SQLite 写入都成功了。再查调用关系：

sqlite3 .codegraph/codegraph.db \ "SELECT src.name, dst.name FROM edges e JOIN nodes src ON e.src_id = src.id JOIN nodes dst ON e.dst_id = dst.id WHERE e.kind='calls' AND dst.name='findById' LIMIT 10;"

这条 SQL 会列出所有调用findById的源节点。能查出结果，就证明代码图谱已经建好了。

查看整体状态：

codegraph status

输出会包含数据库大小、索引文件数、节点数、边数、同步状态。如果节点数是 0，说明索引没建上，检查一下项目路径和语言配置。

5. 在 Claude Code 里发起查询并验证闭环

索引建好后，重启 Claude Code（MCP Server 需要重新加载）：

claude

然后直接提问，注意要用“利用 CodeGraph”这样的措辞引导它走图谱查询，而不是默认的 grep：

利用 CodeGraph 分析：UserService.findById 被哪些地方调用？

如果配置正确，Claude Code 会调用 codegraph 的 MCP 工具，返回调用链列表，而不是去读一堆文件。你也可以问更复杂的：

使用 CodeGraph 找出 OrderService.createOrder() 的完整调用链

使用 CodeGraph 分析：如果删除 UserRepository.findByEmail() 会影响哪些代码

实测下来，在五万行以上的项目里，这类问题的响应速度和答案准确度都比纯 grep 模式好很多。原因是 Claude Code 拿到的是结构化的边关系，不需要自己推断。

如果你想验证 MCP 是否真的被调用，可以在 Claude Code 里输入/mcp查看已连接的 Server 列表，应该能看到codegraph处于 connected 状态。如果没连上，检查codegraph命令是否在 PATH 里，以及 settings.json 的 JSON 格式有没有写错。

6. 常见报错与排查清单

报错一：codegraph: command not found

说明全局安装的 bin 目录不在 PATH 里。用npm bin -g找到路径，加到 shell 配置里：

export PATH="$(npm bin -g):$PATH"

报错二：MCP Server 连不上，/mcp显示 failed

先手动跑一下 MCP 命令看报什么错：

codegraph mcp --project .

如果提示找不到项目或数据库，说明--project路径不对，或者还没执行codegraph init -i。另外确认 settings.json 里没有多余的逗号，JSON 格式错误会导致 Claude Code 静默忽略配置。

报错三：索引为空，codegraph status显示 0 nodes

检查项目语言是否被 Tree-sitter 支持。CodeGraph 支持 Java、Python、Go、TypeScript、JavaScript、Rust 等 20 多种语言，但如果你项目里全是某种小众语言，可能解析不了。另外确认没有把整个项目都加进 ignore 规则。

报错四：查询结果过时

代码改了之后索引不会自动更新，需要重新跑：

codegraph init -i

或者看版本是否支持增量同步，codegraph status里会显示同步状态。

报错五：Token 消耗没降下来

确认 Claude Code 真的在走 MCP。如果提问方式太模糊（比如“帮我看看这个项目”），模型可能还是选择 grep。用明确的“利用 CodeGraph 分析 XXX”来引导。

7. 把 CodeGraph 接进你的日常编码流

CodeGraph 的价值在于把“找代码”这件事从文本搜索变成图查询。对于 Spring Boot 的 Controller-Service-Repository 调用链、微服务的跨模块依赖、K8s Operator 的 Reconcile 流程、大型前端的组件依赖，它都能给出结构化的答案。配合 Claude Code 使用时，建议把常用查询写成固定句式，比如“使用 CodeGraph 找出 X 的完整调用链”“使用 CodeGraph 分析删除 Y 会影响哪些代码”，这样模型会稳定地走图谱通道。

如果你还没配好 Claude Code 的模型通道，可以先到 https://taotoken.net/api-keys 拿 Key，再按第 2 节的环境变量配置。MCP 接入和索引验证的完整流程就是上面这些，跑通之后你会发现 Claude Code 对项目的理解明显更“有结构”了。长期做编码和 Agent 任务的，也可以看看 Coding Plan 这类方案，把模型调用和工具链一起管起来。