GitNexus 使用指南

概述

GitNexus 将代码仓库索引为知识图谱（包含依赖关系、调用链、功能集群、执行流），并通过 MCP 工具暴露给 AI 编程代理（Claude Code、Cursor、Codex、Windsurf 等），使其具备深层架构感知能力。

核心价值：让 AI 代理不再遗漏依赖、破坏调用链或盲目修改代码。

两种使用模式

	CLI + MCP	Web UI
用途	本地索引仓库，通过 MCP 连接 AI 代理	浏览器中可视化图谱 + AI 对话
规模	不限大小	~5k 文件（受浏览器内存限制）
安装	`npm install -g gitnexus`	无需安装，访问 gitnexus.vercel.app
隐私	完全本地，无网络请求	完全浏览器端，无上传

桥接模式：gitnexus serve 启动本地服务，Web UI 自动检测并浏览 CLI 索引的仓库。

快速开始

bash 复制代码

# 在仓库根目录执行，一键完成索引、安装技能、注册钩子
npx gitnexus analyze

npm 11.x 用户如遇问题：

bash 复制代码

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

跳过可选语法编译（无需 C++ 工具链）：

bash 复制代码

GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 npm install -g gitnexus

MCP 配置

运行一次即可自动检测编辑器并写入全局 MCP 配置：

bash 复制代码

gitnexus setup

编辑器支持

Claude Code --- 完整支持（MCP + Skills + 钩子）
Cursor --- 完整支持（MCP + Skills + 钩子）
Antigravity (Google) --- 完整支持
Codex --- MCP + Skills
Windsurf --- 仅 MCP
OpenCode --- MCP + Skills

手动配置

Claude Code：

bash 复制代码

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

Cursor (~/.cursor/mcp.json)：

json 复制代码

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

常用 CLI 命令

bash 复制代码

gitnexus setup                      # 配置编辑器 MCP（一次性）
gitnexus analyze [path]             # 索引仓库
gitnexus analyze --force            # 强制全量重建
gitnexus analyze --skills           # 生成仓库专属技能文件
gitnexus analyze --skip-embeddings  # 跳过嵌入生成
gitnexus analyze --default-branch develop  # 指定默认分支
gitnexus analyze --skip-git         # 索引非 Git 目录
gitnexus mcp                        # 启动 MCP 服务（stdio）
gitnexus serve                      # 启动本地 HTTP 服务供 Web UI 使用
gitnexus list                       # 列出所有已索引仓库
gitnexus status                     # 显示当前仓库索引状态
gitnexus clean                      # 删除当前仓库索引
gitnexus wiki                       # 从知识图谱生成文档

MCP 工具（16 个）

核心工具

工具	用途
`list_repos`	列出所有已索引仓库
`query`	混合搜索（BM25 + 语义 + RRF 融合）
`context`	符号 360° 视图（调用者、被调用者、导入关系）
`impact`	爆炸半径分析（带置信度评分）
`detect_changes`	Git diff 影响映射
`rename`	多文件协同重命名
`cypher`	原生 Cypher 图查询

工具使用示例

影响分析：

复制代码

impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

语义搜索：

复制代码

query({query: "authentication middleware"})

符号上下文：

复制代码

context({name: "validateUser"})

变更检测：

复制代码

detect_changes({scope: "all"})

安全重命名（dry run）：

复制代码

rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})

多仓库管理

bash 复制代码

gitnexus group create <name>           # 创建仓库组
gitnexus group add <group> <path> <name>  # 添加仓库到组
gitnexus group sync <name>             # 同步跨仓库契约
gitnexus group contracts <name>        # 查看跨仓库链接
gitnexus group query <name> <q>        # 跨仓库搜索

项目配置（`.gitnexusrc`）

在仓库根目录放置 JSON 配置文件：

json 复制代码

{
  "defaultBranch": "develop",
  "skipContextFiles": true,
  "embeddings": true,
  "workerTimeout": 60
}

常用配置项：defaultBranch、skipSkills、embeddings、maxFileSize、workerTimeout、workers。

支持的语言（14 种）

TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP、Ruby、Swift、C、C++、Dart

索引流程

结构扫描 --- 遍历文件树，映射目录/文件关系
AST 解析 --- 通过 Tree-sitter 提取函数、类、方法
引用解析 --- 解析 import、调用、继承、构造器
社区聚类 --- 将符号分组为功能社区
执行流追踪 --- 从入口点沿调用链追踪执行路径
搜索索引 --- 构建混合搜索索引

Docker 部署

bash 复制代码

docker compose up -d

用途	镜像
CLI/后端（端口 4747）	`ghcr.io/abhigyanpatwari/gitnexus:latest`
Web UI（端口 4173）	`ghcr.io/abhigyanpatwari/gitnexus-web:latest`

Wiki 生成

bash 复制代码

gitnexus wiki                    # 默认使用 gpt-4o-mini
gitnexus wiki --model gpt-4o    # 指定模型
gitnexus wiki --lang chinese    # 指定语言
gitnexus wiki --force            # 强制重新生成

需要配置 LLM API Key。读取索引图谱，通过 LLM 将文件按模块分组并生成文档。

许可证

PolyForm Noncommercial 1.0.0（非商业许可）

GitNexus 使用指南