GitNexus 完整安装与使用指南

原文：abhigyanpatwari/GitNexus ⭐ 35,400+

GitNexus 是一个零服务器、纯客户端的代码智能引擎。将任何 GitHub 仓库或 ZIP 文件拖入浏览器，即可生成交互式知识图谱，并内置 Graph RAG Agent 进行对话式代码分析。也支持 CLI + MCP 模式，为 Cursor、Claude Code、Codex 等 AI 编程工具提供深度代码库感知。

什么是 GitNexus

GitNexus 的核心能力是将代码库索引为知识图谱——追踪每个依赖关系、调用链、功能集群和执行流——然后通过 MCP 工具暴露给 AI Agent，让 AI 真正"理解"你的代码结构。

解决的问题

传统 AI 编程工具（Cursor、Claude Code、Codex 等）虽然强大，但并不真正了解你的代码库架构：

❌ AI 编辑了 UserService.validate() 方法
❌ 不知道有 47 个函数依赖它的返回值类型
❌ 破坏性修改被推送到生产环境

GitNexus 通过在索引时预计算代码结构（聚类、追踪、评分），让 AI 工具一次性获取完整上下文。

核心创新：预计算关系智能

可靠性 — LLM 不会遗漏上下文，工具响应中已包含完整信息
Token 效率 — 不再需要 10 次查询来理解一个函数
模型民主化 — 较小的 LLM 也能工作，因为工具承担了繁重工作

两种使用方式

维度	CLI + MCP	Web UI
用途	日常开发，与 Cursor/Claude Code/Codex 集成	快速探索、演示、一次性分析
规模	完整仓库，无大小限制	受浏览器内存限制（~5000 文件），或通过后端模式无限
安装	`npm install -g gitnexus`	无需安装 — gitnexus.vercel.app
存储	LadybugDB 原生（快速、持久化）	LadybugDB WASM（内存中，会话级）
解析	Tree-sitter 原生绑定	Tree-sitter WASM
隐私	一切本地，无网络	一切在浏览器，无服务器

桥接模式：gitnexus serve 连接两者 —— Web UI 自动检测本地服务器，可以浏览所有 CLI 索引过的仓库，无需重新上传或重新索引。

方式一：Web UI（浏览器）

快速体验

直接打开 gitnexus.vercel.app，输入 GitHub 仓库地址或上传 ZIP 文件即可。

本地运行前端

# 1. 克隆仓库
git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus

# 2. 构建共享模块
cd gitnexus-shared && npm install && npm run build

# 3. 启动前端
cd ../gitnexus-web && npm install
npm run dev

# 4. 在另一个终端启动后端（Web UI 会自动连接）
npx gitnexus@latest serve

方式二：CLI + MCP（推荐）

安装

# 全局安装
npm install -g gitnexus

# 或使用 npx（无需安装）
npx gitnexus analyze

快速开始

# 进入你的项目目录
cd /path/to/your-project

# 一键索引 + 安装 Agent Skills + 配置编辑器
npx gitnexus analyze

# 配置 MCP 编辑器（运行一次即可）
npx gitnexus setup

编辑器 MCP 配置

编辑器	MCP	Skills	Hooks	支持级别
Claude Code	✅	✅	✅ (PreToolUse + PostToolUse)	完全支持
Cursor	✅	✅	—	MCP + Skills
Codex	✅	✅	—	MCP + Skills
Windsurf	✅	—	—	MCP
OpenCode	✅	✅	—	MCP + Skills

Claude Code 获得最深集成，拥有 MCP 工具 + Agent Skills + 自动上下文增强 Hook。

手动配置各编辑器

Claude Code（完全支持 — MCP + skills + hooks）：

# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

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

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

Codex（编辑 ~/.codex/config.toml）：

[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]

OpenCode（编辑 ~/.config/opencode/config.json）：

{
  "mcp": {
    "gitnexus": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

Docker 部署

一键启动

docker compose up -d

启动后：

服务端：http://localhost:4747
Web UI：http://localhost:4173

镜像说明

用途	GHCR 镜像	Docker Hub 镜像
CLI / 后端服务	`ghcr.io/abhigyanpatwari/gitnexus:latest`	`akonlabs/gitnexus:latest`
静态 Web UI	`ghcr.io/abhigyanpatwari/gitnexus-web:latest`	`akonlabs/gitnexus-web:latest`

挂载主机代码目录

# 将主机代码目录挂载到容器内
WORKSPACE_DIR=$HOME/code docker compose up -d

# 在容器内索引代码（只读挂载）
docker compose exec gitnexus-server gitnexus index /workspace/my-repo

直接 docker run

# 启动服务端
docker run --rm -d \
  --name gitnexus-server \
  -p 4747:4747 \
  -v gitnexus-data:/data/gitnexus \
  ghcr.io/abhigyanpatwari/gitnexus:latest

# 启动 Web UI
docker run --rm -d \
  --name gitnexus-web \
  -p 4173:4173 \
  ghcr.io/abhigyanpatwari/gitnexus-web:latest

供应链安全验证

GitNexus Docker 镜像使用 Cosign 无密钥签名。拉取前验证：

cosign verify ghcr.io/abhigyanpatwari/gitnexus:latest \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

CLI 命令参考

索引与分析

gitnexus analyze [path]             # 索引仓库（或更新过期索引）
gitnexus analyze --force            # 强制完全重建索引
gitnexus analyze --skills           # 从检测到的功能社区生成仓库专属 Skill 文件
gitnexus analyze --skip-embeddings  # 跳过向量嵌入生成（更快）
gitnexus analyze --skip-agents-md   # 保留自定义的 AGENTS.md/CLAUDE.md 编辑
gitnexus analyze --skip-git         # 索引非 Git 仓库的文件夹
gitnexus analyze --embeddings       # 启用向量嵌入生成（更慢，搜索质量更高）
gitnexus analyze --verbose          # 记录因解析器不可用而跳过的文件
gitnexus analyze --worker-timeout 60 # 增加 Worker 空闲超时（秒），处理慢速解析

MCP 与配置

gitnexus setup                      # 自动检测编辑器并配置 MCP（运行一次）
gitnexus mcp                        # 启动 MCP 服务器（stdio）
gitnexus serve                      # 启动本地 HTTP 服务器，供 Web UI 连接

管理与维护

gitnexus list                       # 列出所有已索引的仓库
gitnexus status                     # 显示当前仓库索引状态
gitnexus clean                      # 删除当前仓库索引
gitnexus clean --all --force        # 删除所有索引

Wiki 生成

gitnexus wiki [path]                # 从知识图谱生成仓库 Wiki
gitnexus wiki --model gpt-4o        # 指定 LLM 模型（默认 gpt-4o-mini）
gitnexus wiki --base-url <url>      # 自定义 LLM API 地址
gitnexus wiki --force               # 强制完全重新生成

仓库组管理（多仓库 / Monorepo）

# 创建仓库组
gitnexus group create <name>

# 添加仓库到组
gitnexus group add <group> <groupPath> <registryName>

# 从组中移除仓库
gitnexus group remove <group> <groupPath>

# 列出组或显示组配置
gitnexus group list [name]

# 提取跨仓库服务契约并匹配
gitnexus group sync <name>

# 检查已提取的契约和交叉链接
gitnexus group contracts <name>

# 跨仓库搜索执行流
gitnexus group query <name> <q>

# 检查组中仓库的过期状态
gitnexus group status <name>

MCP 工具详解

通过 MCP 暴露 16 个工具给 AI Agent：

单仓库工具（11 个）

工具	功能	repo 参数
`list_repos`	发现所有已索引的仓库	—
`query`	进程分组的混合搜索（BM25 + 语义 + RRF）	可选
`context`	360 度符号视图 — 分类引用、进程参与	可选
`impact`	爆炸半径分析（深度分组 + 置信度）	可选
`detect_changes`	Git-diff 影响分析 — 映射变更行到受影响的进程	可选
`rename`	多文件协调重命名（图谱 + 文本搜索）	可选
`cypher`	原始 Cypher 图谱查询	可选

仓库组工具（5 个）

工具	功能
`group_list`	列出配置的仓库组
`group_sync`	提取契约并跨仓库/服务匹配
`group_contracts`	检查已提取的契约和交叉链接
`group_query`	跨仓库搜索执行流
`group_status`	检查组中仓库的过期状态

使用示例

# 影响分析
impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

# 进程分组搜索
query({query: "authentication middleware"})

# 360 度符号视图
context({name: "validateUser"})

# 提交前变更检测
detect_changes({scope: "all"})

# 多文件重命名（先试运行）
rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})

# Cypher 查询
MATCH (c:Community {heuristicLabel: 'Authentication'})
<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
WHERE r.confidence > 0.8
RETURN caller.name, fn.name, r.confidence

2 个 MCP 提示词

提示词	功能
`detect_impact`	提交前变更分析 — 范围、受影响进程、风险级别
`generate_map`	从知识图谱生成架构文档（含 Mermaid 图表）

支持的编程语言

语言	导入解析	命名绑定	导出	继承	类型注解	构造函数推断	配置	框架	入口点
TypeScript	✓	✓	✓	✓	✓	✓	✓	✓	✓
JavaScript	✓	✓	✓	✓	—	✓	✓	✓	✓
Python	✓	✓	✓	✓	✓	✓	✓	✓	✓
Java	✓	✓	✓	✓	✓	✓	—	✓	✓
Kotlin	✓	✓	✓	✓	✓	✓	—	✓	✓
C#	✓	✓	✓	✓	✓	✓	✓	✓	✓
Go	✓	—	✓	✓	✓	✓	✓	✓	✓
Rust	✓	✓	✓	✓	✓	✓	—	✓	✓
PHP	✓	✓	✓	—	✓	✓	✓	✓	✓
Ruby	✓	—	✓	✓	—	✓	—	✓	✓
Swift	—	—	✓	✓	✓	✓	✓	✓	✓
C	—	—	✓	—	✓	✓	—	✓	✓
C++	—	—	✓	✓	✓	✓	—	✓	✓
Dart	✓	—	✓	✓	✓	✓	—	✓	✓

工作原理

GitNexus 通过多阶段索引管线建立完整的代码知识图谱：

1. 结构扫描 → 遍历文件树，映射文件夹/文件关系
2. AST 解析 → 使用 Tree-sitter 提取函数、类、方法、接口
3. 关系解析 → 解析导入、函数调用、继承、构造函数推断
4. 社区聚类 → 将相关符号分组为功能社区（Leiden 算法）
5. 进程追踪 → 从入口点追踪执行流到调用链
6. 搜索索引 → 构建 BM25 + 语义混合搜索索引

技术栈

层级	CLI	Web
运行时	Node.js (原生)	浏览器 (WASM)
解析	Tree-sitter 原生绑定	Tree-sitter WASM
数据库	LadybugDB 原生	LadybugDB WASM
向量嵌入	HuggingFace transformers.js (GPU/CPU)	transformers.js (WebGPU/WASM)
搜索	BM25 + 语义 + RRF	BM25 + 语义 + RRF
Agent 接口	MCP (stdio)	LangChain ReAct agent
可视化	—	Sigma.js + Graphology (WebGL)
前端	—	React 18, TypeScript, Vite, Tailwind v4
并发	Worker threads + async	Web Workers + Comlink

常见问题

Q: 索引数据存在哪里？

CLI 模式：索引存储在项目目录的 .gitnexus/ 下（已 gitignored）
全局注册表：~/.gitnexus/registry.json 仅存储路径和元数据

Q: 代码会上传到服务器吗？

不会。 CLI 模式：一切在本地运行，无网络调用。Web 模式：一切在浏览器内运行，无服务器。代码永远不会离开你的机器。

Q: 支持大仓库吗？

CLI 模式支持任意大小的仓库。Web 模式受浏览器内存限制（约 5000 个文件）。对于更大的仓库，可使用 gitnexus serve 后端模式。

Q: 如何更新索引？

# 重新运行 analyze，GitNexus 自动检测变更并增量更新
gitnexus analyze

# 强制完全重建
gitnexus analyze --force

Q: Claude Code Hooks 做了什么？

GitNexus 为 Claude Code 安装了两个 Hook：

PreToolUse — 在搜索操作前用图谱上下文丰富查询
PostToolUse — 检测提交后索引是否过期，提示 Agent 重新索引

Q: 如何处理解析超时？

# 增加 Worker 超时
gitnexus analyze --worker-timeout 120

# 或设置环境变量
export GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=120000

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

GitNexus 完整安装与使用指南

目录

什么是 GitNexus

解决的问题

核心创新：预计算关系智能

两种使用方式

方式一：Web UI（浏览器）

快速体验

本地运行前端

方式二：CLI + MCP（推荐）

安装

快速开始

编辑器 MCP 配置

手动配置各编辑器

Docker 部署

一键启动

镜像说明

挂载主机代码目录

直接 docker run

供应链安全验证

CLI 命令参考

索引与分析

MCP 与配置

管理与维护

Wiki 生成

仓库组管理（多仓库 / Monorepo）

MCP 工具详解

单仓库工具（11 个）

仓库组工具（5 个）

使用示例

2 个 MCP 提示词

支持的编程语言

工作原理

技术栈

常见问题

Q: 索引数据存在哪里？

Q: 代码会上传到服务器吗？

Q: 支持大仓库吗？

Q: 如何更新索引？

Q: Claude Code Hooks 做了什么？

Q: 如何处理解析超时？

相关链接

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages