GitNexus：给 AI 代理装上代码知识图谱

改 UserService.validate() 的返回值，助手不知道还有 40 多个调用方------改完才踩坑。

GitNexus（Akon Labs，2025 年 8 月开源）在本地把仓库索引成知识图谱，调用关系、执行流都落在 LadybugDB（.gitnexus/），再通过 MCP（Model Context Protocol，编辑器连外部工具的协议）接到 Cursor、Claude Code、Codex。代码不上传。

和普通 Graph RAG 的差别：analyze 阶段就算好结构，MCP 查一次就够，不用让模型多轮 grep 自己拼。

上手：两行命令

在 Git 仓库根目录：

bash 复制代码

npx gitnexus analyze    # 建索引，写 .gitnexus/，注册到 ~/.gitnexus/
npx gitnexus setup      # 写 MCP 配置（自动识别 Cursor、Claude Code、Codex 等）

setup 只需跑一次。也可手动配 ~/.cursor/mcp.json：

json 复制代码

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

npm 11 下 npx 可能崩溃，改用：

bash 复制代码

pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze

或 npm i -g gitnexus 全局安装------MCP 冷启动会快不少。安装踩坑见 GitHub README · Quick Start（文档站无对应章节）。

macOS：libssl.3.dylib 加载失败

LadybugDB 原生模块（lbugjs.node）依赖 OpenSSL 3，而 macOS 自带的是 LibreSSL，两者不兼容。报错类似：

bash 复制代码

Library not loaded: @rpath/libssl.3.dylib

安装 Homebrew 的 OpenSSL 3 即可（二进制会从 /opt/homebrew/opt/openssl@3/lib 加载）：

bash 复制代码

brew install openssl@3
gitnexus serve    # 或 analyze / mcp

仍报错时，按提示跑修复脚本（全局安装示例）：

bash 复制代码

node $(npm root -g)/gitnexus/node_modules/@ladybugdb/core/install.js

npx 临时运行时，把路径换成报错信息里 @ladybugdb/core/install.js 的实际位置。

Web UI 与 Bridge 模式

gitnexus serve 默认监听 http://127.0.0.1:4747。1.6.x 起，官网 gitnexus.vercel.app 打开就是「启动本地服务器」------必须先跑 serve，页面才会自动连上，否则一直停在「正在监听服务器...」。

入口	地址	要不要本地 serve
本地自带 UI	`http://localhost:4747`	要
官网 Web UI	gitnexus.vercel.app	要（Bridge，自动连 4747）

README 早期版本提过纯浏览器 WASM 解析（选本地文件夹、约 5000 文件上限），当前部署的官网已不走这条入口 ------实际用法就是：终端 gitnexus serve → 浏览器开官网 → 自动 Bridge。

官网怎么连上本地服务？

Vercel 只托管前端页面，图谱数据仍在你的机器上：

终端跑 gitnexus serve（4747 端口；需 Node.js 22.18+ 或 24.11+）
浏览器打开 gitnexus.vercel.app------JS 从 Vercel 下载，运行在你浏览器里
页面定时请求 http://localhost:4747/api/repos（heartbeat），检测到后自动进入图谱
之后的查询、AI Chat 都走本地 HTTP API，源码不上传到 Vercel

Chrome 130+ 还需本地服务返回 Access-Control-Allow-Private-Network 头（GitNexus 1.6.5+ 已支持）。

有无风险？

Bridge 模式风险可控：默认只绑 127.0.0.1，源码本地索引不经过 Vercel；但 serve 无鉴权 ，勿用 --host 0.0.0.0；Web UI 填 OpenAI/Anthropic Key 时，对话会发到对应 API。

Ctrl+C 关不掉服务？

Ctrl+C 只杀当前终端前台进程 。4747 仍被占用，常见原因是另一个终端还在跑 gitnexus serve，或后台任务启动的实例。

确认并清理：

bash 复制代码

lsof -i :4747              # 看谁占端口
kill $(lsof -t -i :4747)  # 杀掉

关干净后再访问 http://localhost:4747 应连不上；gitnexus.vercel.app 仍可打开，但会回到「等待本地服务」界面。

索引何时过期

图谱是快照。GitNexus 用 git commit hash 判断是否还有效（写在 .gitnexus/gitnexus.json）。HEAD 没变，再跑 analyze 会提示 Already up to date 直接跳过。

注意：同 commit 下有未提交改动，图谱仍是旧的 ，得用 gitnexus analyze --watch 或 --force。

场景	做法
有新 commit	再跑 `gitnexus analyze`
开发中持续改代码	`gitnexus analyze --watch`（MCP / serve 自动加载，不用重启）
索引坏了或升级 GitNexus 后	`gitnexus analyze --force`
提交前看 diff 影响	`gitnexus detect-changes`（只映射 diff，不更新图谱）
确认状态	`gitnexus status`

Claude Code / Codex / Cursor 的 Hook 可以在 git commit 后提醒重跑 analyze；Cursor 的 Hook 要按 cursor-integration README 单独装。

改代码前查什么

当前共 17 个 MCP 工具 ，完整列表在 GitHub README；文档站 MCP 页仍只列 7 个，未同步。我改公共类前最常用这几个：

工具	干什么
`query`	混合搜索，结果按执行流分组
`context`	某符号谁调它、它调谁、在哪个流程里
`impact`	改这里会波及多大范围
`detect_changes`	当前 diff 影响到哪些执行流
`trace`	两个符号之间最短调用链
`route_map`	API 路由和 Handler 的对应关系

还有 rename、api_impact、shape_check、cypher 等。多仓库先读 gitnexus://repos。

MCP 用下划线（detect_changes），CLI 用连字符（detect-changes），终端和编辑器里对着调。

Java 后端

多模块 Maven、公共 DTO、跨模块调用------这类棕地项目图谱最顺手。我在一个 Spring 项目里跑完 analyze，改公共枚举前先调 impact，比纯 grep 少漏跨模块引用。

根目录 gitnexus analyze → gitnexus setup -c cursor
改代码前：impact / context
提交前：detect-changes
写文档：gitnexus wiki，或 MCP Prompt generate_map

已有自定义 AGENTS.md 的话，analyze 加 --skip-agents-md；团队环境可设 GITNEXUS_MCP_READ_ONLY=1 关掉 cypher、rename 等写操作。

日常开发走 CLI + MCP ；Web UI 需先 gitnexus serve，适合看图谱和 demo。

参考内容

GitHub：abhigyanpatwari/GitNexus
官方文档：gitnexus.mintlify.app
MCP 工具：MCP Overview
Web UI：gitnexus.vercel.app
隐私说明：Privacy & Security