给 AI 一张代码地图:CodeGraph 上手指南

把一个项目交给 AI，问它“登录流程是怎么走的”，它往往要先找入口、读文件，再顺着函数调用往下查。一个问题还没回答，工具已经调用了好几轮。

CodeGraph 想减少的，就是这段找代码、拼关系的过程。它先为项目建立本地代码图谱，让 AI 能按问题取到相关源码和调用路径。

单看一个函数，AI 通常不难解释。真正费事的是把它放回项目里：谁调用它，参数从哪来，结果交给谁，改了以后会影响哪些地方。

CodeGraph 把这些结构信息提前整理出来。AI 再遇到“这段逻辑在哪”“这个函数会影响谁”一类问题，就有一份现成的地图可以查。

这里介绍的是 colbymchenry/codegraph，一个采用 MIT 许可证的开源项目。它会解析本地源码，提取函数、类、方法等符号，以及调用、导入、继承等关系，保存到项目里的 SQLite 数据库。

这里的“图谱”可以拆成两样东西：节点记录代码里的对象，边记录对象之间的关系。一个函数是节点，另一个函数调用它，就形成一条调用边。文件、类、方法，以及框架中的路由，也可以成为节点。

这张图不是把文件内容换个地方存起来。它的作用在于把分散在不同文件里的结构连接起来。建立图谱，大致经过下面三步。

CodeGraph 使用 tree-sitter 等解析能力，把源码解析成语法树，再从中提取符号。函数或方法对应的记录中，会保留名字、类型、所属文件、起止行号，以及签名、注释等信息。

例如，两个文件里都定义了 login，只存名字就容易混淆。节点还需要带上文件和限定名称，才能区分“用户服务的 login”和“后台管理的 login”。这也是为什么查询时附上文件路径，通常比只说一个函数名更明确。

读到 auth.login()，还不能直接确定它调用了哪个实现。需要继续追踪 auth 的来源：它从哪个文件导入，是否改过名字，是否经过路径别名，方法属于哪个类。

因此，提取符号之后还有一层引用解析。CodeGraph 会结合导入、名称等信息，把调用连接到对应定义，也会处理继承、接口实现等关系。对支持的框架，还能把路由节点连接到处理函数。

这里要区分关系的含义：路由“引用”一个处理函数，类“继承”另一个类，函数“调用”另一个函数，三者都能帮助找代码，却不是同一种联系。沿调用链分析执行逻辑时，不能把所有连线都当成函数调用。

提取出来的节点、关系和文件信息，保存在项目的 .codegraph/codegraph.db 中。这是 SQLite 数据库，查询入口可以先找到符号，再沿已有关系查相关实现。

其中的 FTS5 全文索引用于检索符号名、限定名称、注释和签名等字段。“本地代码图谱”保存的是项目结构，不会自动保存上一轮对话中讨论过的业务背景或决策。

这份图谱来自源码解析和关系解析，建索引的过程不依赖大模型为整个仓库逐个生成摘要。TypeScript、JavaScript、Python、Go、Java、Rust 等多种语言都在项目的支持范围内。

接入 AI 时，CodeGraph 提供 MCP 服务。当前默认开放的查询工具是 codegraph_explore。AI 把问题或相关符号、文件名交给它，工具会组织与问题相关的源码和关系信息。

可以把这个过程理解为：先找入口，再沿图谱查相关节点，最后选取需要阅读的源码。这是一种便于理解的概括，具体选取范围还会受查询内容、相关性和输出预算影响。

返回内容中，主要是按文件组织、带原始行号的源码，以及调用路径和可能的影响范围信息。比如 AI 查到认证服务时，不必只拿着一个函数名继续猜，可以直接看到实现，并顺着路径找到密码校验或令牌生成的位置。

它不会把整个仓库一次塞进上下文。关系较多时，相关代码的展示可能有详有略；一个较宽泛的问题，也不保证把所有关联位置都列全。发现某个分支没有展开，可以带着具体符号和文件范围继续查。

读到这些上下文后，AI 才继续解释流程、提出修改方案或编辑代码。代码图谱负责提供线索，后续的理解和判断仍由 AI 完成。

假设你想弄清“登录失败后为什么没有返回错误”。关键词搜索、向量检索和图谱查询，能提供的线索有所不同。

CodeGraph 的这条查询路线以符号检索和图关系为基础，建索引不要求先给整个仓库生成向量。它也不排斥其他搜索方式：搜索可以帮助找线索，图谱帮助连接线索，阅读源码则用来确认具体行为。

所以，不能仅凭“登录”“认证”两段代码意思接近，就认定它们属于同一条调用链；也不能因为图谱里有一条边，就认为已经证明了所有运行时行为。

官方流程可以分成三件事：安装命令行工具、接入自己的 AI 工具、为项目建立索引。下面走 npm 这条安装路径，以 Windows 的命令提示符 CMD 为例，电脑上需要先有 Node.js 和 npm。

打开 CMD，执行：

npm install -g @colbymchenry/codegraph

安装完成后，重新打开一个终端，再进行下一步。没有 Node.js 的读者，也可以使用 README 提供的独立安装方式；本文先按同一条路径往下操作。

执行：

codegraph install

安装向导会让你选择要配置的 AI 工具，以及配置作用于所有项目还是当前项目。以 Claude Code 为例，选择它并按提示完成即可；使用 Cursor、Codex CLI、Gemini CLI、OpenCode 等工具时，选择对应目标。

这一步会写入所选工具的 MCP 配置及相关使用指引。完成后，重新启动 AI 工具，让配置生效。

注意，这一步只是完成接入，还没有给项目建立代码索引。

回到 CMD，把下面的路径换成自己的项目目录，再执行：

cd /d "E:\projects\your-project"

codegraph init

codegraph init 会在当前项目创建 .codegraph/ 目录，并建立代码图谱。换一个项目，需要在那个项目里再执行一次。

完成后，可以查看索引状态：

codegraph status

只执行 codegraph install，却没有执行 codegraph init，是两回事。官方说明中，没有索引的工作区会让 MCP 服务保持未激活状态，并且不列出查询工具。

在刚才建立索引的项目里打开 AI 工具。第一次使用，挑一个你知道入口的功能，让它查清完整流程，比直接要求“分析整个项目”更容易看出效果。

假设项目里有登录功能，可以这样问。下面的路径是示例，使用时换成自己的入口位置；如果还不知道入口，也可以先让 AI 查找：

请用 CodeGraph 梳理这个项目的登录流程。

以 src/routes/auth.ts 中的 POST /login 为入口，列出关键函数、文件位置和调用路径。

说明密码校验与登录态生成分别在哪一步发生。

先分析，暂不修改代码。

为了说明怎样读结果，下面用一条简化的登录关系举例。这是讲解用的示意，不是某个仓库的实际查询输出：

POST /login

　　→ loginHandler

　　　　→ AuthService.login

　　　　　　→ UserRepository.findByEmail

　　　　　　→ PasswordHasher.verify

　　　　　　→ TokenService.issue

路由节点关联到 loginHandler，处理函数再调用认证服务；认证服务关联到用户查询、密码校验和令牌生成。这些位置跨了几个文件，但有了关系和源码，AI 就能逐段说明它们如何配合。

这里还有一个容易忽略的区别：关系图展示连接，执行顺序要看源码。上面三个服务方法是否按顺序调用，密码校验失败后有没有提前返回，异常在哪里处理，必须读 AuthService.login 的实现才能确定。

因此，一个有用的分析不应该只给出箭头，还应该指出：校验失败的判断在哪一行，哪一个分支阻止了令牌生成，错误最终由谁返回。图谱帮 AI 找到要读的地方，源码给出答案。

如果准备把密码校验函数的返回值从布尔值改成一个结果对象，就需要从 PasswordHasher.verify 反过来查调用方。下面的符号和路径同样是示例：

我准备把 src/security/password.ts 中 PasswordHasher.verify

的返回值从 boolean 改为 { valid: boolean, reason?: string }。

请用 CodeGraph 查找直接调用方及向上关联的调用路径。

结合调用处源码，说明哪些判断需要修改，哪些上层行为需要验证。

列出需要核对的测试；如果关系是推断出来的，请单独说明。

暂不修改代码。

这时需要分清两类位置。直接调用方可能要修改条件判断，例如原来的 if (!verify(...)) 不能照搬到返回对象的版本中；更上层的登录接口则未必需要改代码，但要验证失败响应、成功登录等行为是否仍然正确。

如果密码重置等流程也调用了同一个校验函数，它们同样需要检查。相反，用户查询函数虽然和校验函数出现在同一条业务链上，也不能仅凭“有关联”就认定它必须修改。

这就是查影响范围的意义：先整理候选位置，再看每一处怎样使用结果，形成具体修改和测试清单。图谱提供关联范围，代码和测试决定哪些影响真正成立。

AI 工具启动 CodeGraph 的 MCP 服务后，会监听源码变化，自动增量更新索引。正常使用时，不必每改一个文件就手动同步。

更新需要一个短暂的处理窗口。官方文档说明，查询结果涉及尚未同步的文件时，会提示 AI 直接读取最新文件；服务重新连接时，也会检查会话关闭期间的代码变化。需要排查索引状态时，再用 codegraph status 查看。

源码解析、关系查询和索引存储在本机完成，数据库位于项目的 .codegraph/ 中。CodeGraph 的索引和查询不需要额外配置模型 API Key。

但 AI 助手拿到查询结果后，如果使用的是云端模型，这些源码片段仍可能作为模型上下文发出去。处理公司代码时，需要同时看 AI 工具的数据使用设置和组织要求。

另外，当前项目提供匿名使用统计，官方说明涉及命令、工具、语言等使用情况，不包含源码、路径或查询内容。不想参与，可以执行：

codegraph telemetry off

安装、升级和版本检查也可能联网。因此，“图谱保存在本地”不能直接理解为运行过程中完全没有网络请求。

项目公布了工具调用次数、耗时和 Token 等指标的对比测试。结果会受问题类型、模型和仓库结构影响，不能把某个平均节省比例直接套到自己的项目。

官方还专门讨论了上下文占用：一次返回较完整的源码，可能减少反复查询，却让更多检索内容留在会话里。长时间连续追问时，这部分内容也会占据上下文窗口。

先用自己熟悉的一条调用链做对照：它是否更快找到入口，是否少漏调用方，结果能否帮你做决定。这样的比较比只盯一个节省百分比更实用。

代码图谱主要描述能从源码中解析出的结构关系。有些联系比较直接，有些则需要推断。官方文档提到，回调注册、事件通道、接口到实现等部分关系，会通过专门的规则补充，并标记为 provenance: 'heuristic'，同时记录相关的连接位置。

推断关系是排查线索，不是实际运行记录。 例如，通过事件名称找到生产者和消费者，可以提示 AI 去检查对应代码；至于消费者这次有没有被注册、当前配置是否启用、实际传入了什么数据，还需要结合环境确认。

动态加载、反射、运行时配置，以及外部系统的响应，也可能超出静态关系能确定的范围。再加上检索结果可能只展开相关的一部分，AI 没有看到某个调用方，不等于它一定不存在。

影响范围适合用来列检查清单，修改完成后依然要跑相关测试。先挑一个常用项目，把“找入口、查调用链、再动手修改”这条流程用顺，CodeGraph 的价值就比较容易看出来。

资料核对：2026 年 10 月 7 日；截至核对日，最新发布版本：v1.6.2。

〔01〕CodeGraph 项目与 README

https://github.com/colbymchenry/codegraph

〔02〕官方快速上手

https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/getting-started/quickstart.md

〔03〕安装与 AI 工具接入

https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/getting-started/installation.md

〔04〕MCP 工具说明

https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/reference/mcp-server.md

〔05〕图谱中的节点与关系

https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/core-concepts/knowledge-graph.md

〔06〕引用解析与推断关系

https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/core-concepts/resolution.md

〔07〕节点类型与符号信息

https://github.com/colbymchenry/codegraph/blob/main/src/types.ts

〔08〕本地数据库与 FTS5 索引

https://github.com/colbymchenry/codegraph/blob/main/src/db/schema.sql

〔09〕查询输出与代码选取设计

https://github.com/colbymchenry/codegraph/blob/main/docs/design/adaptive-explore-sizing.md

〔10〕MCP 查询实现

https://github.com/colbymchenry/codegraph/blob/main/src/mcp/tools.ts

〔11〕向量检索概念：Qdrant 官方文档

https://qdrant.tech/documentation/manage-data/vectors/

〔12〕索引与自动同步说明

https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/guides/indexing.md

〔13〕匿名统计与关闭方式

https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md

〔14〕检索结果的上下文占用

https://github.com/colbymchenry/codegraph/blob/main/docs/benchmarks/residual-context-occupancy.md

〔15〕v1.6.2 发布记录

https://github.com/colbymchenry/codegraph/releases/tag/v1.6.2