GitNexus 使用指南

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

索引流程

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

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(非商业许可)

参考文献

相关推荐
prince_zxill6 小时前
把 17 个散文件装进一个文件夹:拆解 claude-plugins-official 的插件打包术(47,413 Star 实测)
python·github·agent·mcp·claude code
xrlfreedom8 小时前
MCP 面试高频考点:给 MCP Server 加日志、指标与分布式追踪,面试追问你能答到第几层?
结构化输出·mcp·mcp server
leer1 天前
我给 agent 加了一道闸,拦住了自己差点删掉的构建目录
mcp
莪_幻尘1 天前
AI 编程的下一场战争,不在模型,在协议
agent·ai编程·mcp
攒了一袋星辰1 天前
AI 求职长期记忆原理解析:从碎片经历到贝叶斯能力星图
知识图谱·agent·rag·ai工程·校招面试
我不会起名字3222 天前
Agent 总调错工具?MCP 接进 Go 后端的 4 个约束
后端·go·agent·mcp
vivo互联网技术2 天前
研发数字人 Agent:从 0 到 1 的架构与实践
人工智能·agent·mcp
龙腾AI白云3 天前
具身智能的空间导航与未知环境探索
大数据·数据库·人工智能·机器学习·知识图谱
Summer-Bright3 天前
企业落地智能体,供应链签名还是空白:1862 个 MCP 服务器无认证裸奔
服务器·人工智能·github·mcp