GitNexus：把你的代码库变成 AI 能读懂的知识图谱

用 AI 写代码这件事，大家都已经习惯了。但一个尴尬的现实是：AI 在修改代码的时候，经常不知道自己改的那个函数被多少地方调用、改完之后会不会连锁反应把别的功能搞崩。这不是 AI 模型不够聪明，而是它看不到代码库的全貌——依赖关系、调用链路、执行流程，这些结构性的信息在普通的文件搜索里是丢失的。

[[GitNexus]] 就是为了解决这个问题而生的。它把你的代码仓库索引成一张知识图谱，然后通过 [[MCP]]（Model Context Protocol）把这些结构化的上下文喂给 AI Agent，让 AI 在动手之前就能看清楚”改这个函数会影响到哪些地方”。

GitNexus 是什么

GitNexus 是一个开源的零服务器代码智能引擎，由 abhigyanpatwari 开发。它有两种使用模式：

CLI + MCP 模式（推荐）：在本地索引代码库，通过 MCP 协议与 Claude Code、Cursor、Windsurf、OpenCode 等 AI 编程工具集成
Web UI 模式：完全在浏览器里运行，拖入 GitHub 仓库链接或 ZIP 文件即可生成可视化的知识图谱

核心技术栈是 [[Tree-sitter]]（语法解析）+ LadybugDB（图数据库）+ MCP 协议。CLI 模式下使用 Tree-sitter 原生绑定，Web 模式下编译为 WebAssembly 在浏览器里运行。不管哪种模式，所有数据都留在本地，不会上传到任何外部服务器。

项目在 2025 年 8 月创建，最初并没有引起太大关注。到了 2026 年 2 月底，随着 AI 编程工具的普及，开发者们对”AI 改代码改出 bug”这件事的痛感越来越强，GitNexus 在短短几周内就积累了超过 16,000 个 GitHub Star。

为什么需要代码知识图谱

传统的 AI 编程工具在处理代码时，本质上做的是文本检索——grep 搜索、文件读取、语义搜索。这些方法能找到代码在哪里，但找不到代码之间的关系。

举个实际的例子。在我们的项目里，假设你要修改一个 AccountService 里的 read 方法。用普通搜索你能找到这个方法的定义和一些调用点，但你很难一次性看清楚：

哪些 Controller 直接调用了这个方法？（直接依赖）
这些 Controller 又被哪些路由引用？（间接依赖）
修改这个方法会影响到哪些执行流程？（爆炸半径）
有没有其他 Service 也通过某个中间层间接依赖它？（传递依赖）

这些关系在代码库里是隐含的，需要一个人花很长时间去追踪才能理清。而知识图谱把这些关系预先计算好了，AI Agent 只需要一次查询就能拿到完整的上下文。

GitNexus 官方用了一个很形象的说法：传统 RAG 是把原始代码片段扔给 AI，让它自己去发现关系；GitNexus 是把预先计算好的关系直接给 AI，一次调用就能拿到完整上下文。

安装和配置

前提条件

需要 [[Node.js]] 运行环境。

安装

全局安装：

npm install -g gitnexus

索引代码库

进入项目目录，运行一行命令即可完成索引：

npx gitnexus analyze

这个命令会：

使用 Tree-sitter 解析所有支持语言的源代码文件
构建符号（函数、类、方法）之间的依赖关系图
识别功能集群（高内聚的代码模块）和执行流程
将结果存储在 .gitnexus/ 目录下的 LadybugDB 数据库中
自动在 .claude/skills/gitnexus/ 安装 Agent 技能文件
在 CLAUDE.md 中追加 GitNexus 使用指南

以我们大约 1500 个文件的 Java 项目为例，索引过程大约花了 29 秒，生成了 12,847 个节点、50,347 条边、1,258 个功能集群和 300 个执行流程。

常用的索引选项：

gitnexus analyze --force          # 强制完整重建索引
gitnexus analyze --embeddings     # 启用 embedding 生成（更好的语义搜索，但更慢）
gitnexus analyze --skip-embeddings # 跳过 embedding（更快）
gitnexus analyze --verbose        # 显示跳过的文件
gitnexus analyze --skills         # 生成仓库特定的技能文件

配置 MCP 服务器

这是让 AI 编程工具能调用 GitNexus 的关键步骤。

Claude Code（最深度的集成）：

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Windsurf / OpenCode / Codex 也都支持，配置方式类似，具体可参考官方文档。

一键自动配置所有已安装的编辑器：

npx gitnexus setup

核心功能

7 个 MCP 工具

配置好 MCP 之后，AI Agent 可以调用以下工具：

工具	用途	示例
`query`	按概念搜索代码	`gitnexus_query({query: "auth validation"})`
`context`	查看某个符号的 360 度全景	`gitnexus_context({name: "AccountService"})`
`impact`	修改前的爆炸半径分析	`gitnexus_impact({target: "read", direction: "upstream"})`
`detect_changes`	提交前的变更范围检查	`gitnexus_detect_changes({scope: "staged"})`
`rename`	基于图谱的安全重命名	`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})`
`cypher`	原始图查询	`gitnexus_cypher({query: "MATCH ..."})`
`list_repos`	列出所有已索引的仓库	—

爆炸半径分析

这是我觉得最有价值的功能。在修改任何函数之前，先跑一次 impact 分析，它会告诉你：

d=1（直接依赖）：直接调用者/导入者，修改后必须同步更新
d=2（间接依赖）：间接依赖方，需要测试确认
d=3（传递依赖）：更远的传递依赖，如果在关键路径上需要测试

风险等级分为 LOW、MEDIUM、HIGH、CRITICAL，AI Agent 在收到 HIGH 或 CRITICAL 警告时会主动提醒你。

变更检测

在准备提交代码之前，detect_changes 会基于 git diff 分析你的变更影响了哪些符号和执行流程。这相当于一个智能的 pre-commit 检查——不是检查代码风格，而是检查你的变更是否只影响了预期的范围。

功能集群和执行流程

GitNexus 会自动识别代码库中的功能集群（高内聚的代码模块）和执行流程（从入口点到输出的完整路径）。这对于理解不熟悉的代码库特别有帮助。你可以通过 MCP Resource 访问：

gitnexus://repo/<repo-name>/clusters    # 所有功能集群
gitnexus://repo/<repo-name>/processes   # 所有执行流程
gitnexus://repo/<repo-name>/process/<name>  # 某个执行流程的详细步骤

多仓库支持

GitNexus 使用一个全局注册表（~/.gitnexus/registry.json）来管理多个仓库的索引。一个 MCP 服务器可以同时服务多个已索引的仓库，LadybugDB 连接会按需懒加载（最多 5 个并发连接，5 分钟无活动后自动回收）。

支持的语言

GitNexus 支持 13 种编程语言：TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP、Ruby、Swift、C 和 C++。

支持的特性包括：导入解析、命名绑定追踪、导出检测、类继承映射、类型注解提取、构造函数推断、配置文件解析、框架检测和入口点评分。

日常使用工作流

修改代码前

gitnexus_impact({target: "要修改的函数名", direction: "upstream"})
查看爆炸半径和风险等级
如果风险是 HIGH 或 CRITICAL，评估是否需要更谨慎的方案

探索不熟悉的代码

gitnexus_query({query: "你想了解的功能描述"})
找到相关的执行流程
gitnexus_context({name: "感兴趣的函数名"}) 查看完整上下文

重构前

gitnexus_context({name: "目标函数"}) 查看所有引用
gitnexus_impact({target: "目标函数", direction: "upstream"}) 查看爆炸半径
如果是重命名，用 gitnexus_rename 的 dry_run 模式先预览

提交前

1. gitnexus_detect_changes({scope: "staged"})
2. 确认变更只影响了预期的范围

保持索引新鲜

代码变更提交后，索引会变得过时。重新索引：

npx gitnexus analyze

如果之前启用了 embedding，加上 --embeddings 参数以保留它们。Claude Code 用户会有一个 PostToolUse hook 在 git commit 后自动重新索引。

其他常用命令

gitnexus status    # 查看当前仓库的索引状态
gitnexus list      # 列出所有已索引的仓库
gitnexus clean     # 删除当前仓库的索引
gitnexus serve     # 启动本地 HTTP 服务器，用于 Web UI 浏览
gitnexus wiki      # 从知识图谱生成 Wiki 文档

Web UI

如果你更喜欢可视化的方式来浏览代码知识图谱，可以直接访问 gitnexus.vercel.app 在浏览器里使用。支持拖入 GitHub 仓库链接或 ZIP 文件，无需安装任何东西。

也可以在本地启动：

gitnexus serve

然后打开浏览器，Web UI 会自动检测本地服务器并展示所有已索引的仓库。

隐私和存储

这一点值得单独强调：

CLI 模式：所有处理都在本地完成，不会发起任何网络请求。索引数据存储在项目根目录的 .gitnexus/ 文件夹中（已被 gitignore）
Web UI 模式：所有处理都在浏览器内完成，不会向服务器发送任何数据。存储基于会话的内存

对于有严格数据合规要求的企业来说，这种完全本地化的架构是一个很大的优势。

总结

AI 编程工具的瓶颈正在从”代码生成”转向”代码理解”。生成一段代码很容易，但理解这段代码在整个系统中的位置、修改它会产生什么连锁反应，这才是真正困难的部分。GitNexus 通过把代码库预先索引为知识图谱，让 AI Agent 在修改代码之前就能看到完整的依赖关系和调用链路，从根本上减少了”AI 改代码改出 bug”的概率。

安装只需要 npm install -g gitnexus，索引一个中等规模的项目不到 30 秒，配置 MCP 也只是一行命令的事情。如果你正在用 Claude Code 或 Cursor 做日常开发，值得花几分钟试一下。

GitHub: abhigyanpatwari/GitNexus
Web UI: gitnexus.vercel.app

GitNexus：把你的代码库变成 AI 能读懂的知识图谱 一个零服务器的代码智能引擎，让 AI Agent 真正理解你的架构