GitNexus 完整教程

AI Agent 的代码情报引擎。把代码库索引成知识图谱，让 Cursor / Claude Code / Codex 真正「看懂」你的架构。

目录

1. 它解决什么问题
2. 工作原理
3. 安装
4. 配置编辑器集成（MCP）
5. 索引代码库
6. MCP 工具速查
7. 实践工作流
8. Web UI 使用
9. 进阶技巧

一、它解决什么问题

Cursor、Claude Code、Codex 等 AI 工具很强，但它们有一个根本缺陷：它们不真正了解你的代码库结构。它们只能看到附近的文件，无法知道「47 个其他函数依赖于这个函数」。GitNexus 解决的就是这个问题。

没有 GitNexus： AI 编辑某函数，不知道 47 个其他函数依赖它 → 盲目修改 → 生产环境 bug。每次都需要 10+ 次图谱查询才能理解一个函数上下文。

有 GitNexus： 预计算所有依赖关系 → 单次工具调用返回完整上下文 → AI 精准操作，不再破坏调用链。

核心能力：

• AI Agent 上下文增强
• 调用链精确追踪
• diff 影响范围分析
• 多文件协调重命名
• 多仓库统一管理
• 代码不上传云端（隐私保护）

二、工作原理

GitNexus 的核心是「索引时预计算」：不是让 LLM 在回答时探索图谱，而是提前把所有关系算好存起来，查询时直接返回答案。

flowchart TD
    A([代码库]) --> B

    subgraph PARSE[解析阶段 本地 零网络]
        B[Tree-sitter 读取源码] --> C[生成 AST 抽象语法树]
        C --> D[提取符号 函数 / 类 / 导入 / 导出]
    end

    subgraph GRAPH[图构建阶段]
        E[建立节点关系] --> F[调用链 / 继承 / 类型注解]
        F --> G[执行流聚类]
        G --> H[写入 LadybugDB 图数据库]
    end

    subgraph EXPOSE[暴露阶段]
        I[MCP Server 启动] --> J[16 个工具等待调用]
        J --> K[AI Agent 单次查询 完整上下文]
    end

    D --> E
    H --> I

为什么 Graph RAG 比普通 RAG 好

普通 RAG 把代码切成块，通过相似度找「看起来像」的代码，但切块会破坏调用关系。GitNexus 保留完整的函数调用链、类继承、模块导入关系，通过 Cypher 图查询精确回答「这个函数被谁调用」这类问题。

flowchart LR
    subgraph BAD[普通向量 RAG]
        A1[代码切块] --> A2[相似度搜索]
        A2 --> A3[找到相似代码]
        A3 --> A4[调用关系断裂]
    end

    subgraph GOOD[GitNexus Graph RAG]
        B1[完整 AST 解析] --> B2[节点和边关系图]
        B2 --> B3[Cypher 精确遍历]
        B3 --> B4[完整调用链返回]
    end

三、安装

📋 前置要求

Node.js 18 及以上版本。验证：node --version

全局安装（推荐，最快启动）

全局安装可以绕过 npx 每次冷启动的延迟，适合日常开发使用：

npm install -g gitnexus@latest

提速技巧：跳过可选语法解析

如果没有 C++ 工具链（或不需要 Dart / Swift / Kotlin 支持），可以大幅缩短安装时间：

# 跳过可选语法编译（Dart/Swift/Kotlin 不可用，其他语言正常）
GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 npm install -g gitnexus

验证安装

gitnexus --version

也可使用 npx（无需全局安装，但首次运行较慢）：npx gitnexus@latest --version

四、配置编辑器集成（MCP）

只需运行一次 setup 命令，GitNexus 会自动检测你已安装的编辑器并写入正确的 MCP 配置：

# 自动检测所有已安装编辑器（推荐）
gitnexus setup

# 只配置指定编辑器
gitnexus setup -c cursor,claude-code

# 或使用 npx 版本
npx gitnexus setup

手动配置 Claude Code

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

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

手动配置 Cursor / Codex

# Codex
codex mcp add gitnexus -- npx -y gitnexus@latest mcp

setup 执行流程

flowchart LR
    A[gitnexus setup] --> B{检测已安装编辑器}
    B --> C[Claude Code\nMCP + skills + hooks]
    B --> D[Cursor\nMCP config]
    B --> E[Codex\nMCP config]
    B --> F[Windsurf / Cline\n等其他编辑器]
    C --> G[写入全局 MCP 配置]
    D --> G
    E --> G
    F --> G

💡 Claude Code 的深度集成

Claude Code 获得最完整的集成：MCP 工具 + 4 个 Agent 技能（探索 / 调试 / 影响分析 / 重构）+ PreToolUse hooks（搜索前自动注入图谱上下文）+ PostToolUse hooks（提交后自动重建索引）+ 自动生成 CLAUDE.md / AGENTS.md 上下文文件。

五、索引代码库

步骤 1：索引当前仓库

进入项目根目录（需要是 Git 仓库），运行一条命令完成所有初始化：

# 进入项目
cd /path/to/your/project

# 索引（同时安装 skills、hooks、生成 CLAUDE.md）
npx gitnexus analyze

# 或全局安装后
gitnexus analyze

索引结果写入 .gitnexus/ 目录，并注册到全局 ~/.gitnexus/registry.json

步骤 2：查看索引状态

# 查看当前仓库索引状态（符号数 / 关系数 / 更新时间）
gitnexus status

# 列出所有已索引仓库
gitnexus list

步骤 3：更新与重建索引

# 增量更新（只处理变化的文件）
gitnexus analyze

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

# 跳过 embedding 生成（更快）
gitnexus analyze --skip-embeddings

# 开启 embedding 生成（搜索质量更好）
gitnexus analyze --embeddings

索引支持的语言：

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

*Swift / Kotlin 需要 C++ 工具链，或设置 GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 跳过。

六、MCP 工具速查

GitNexus 通过 MCP 协议暴露 16 个工具给 AI Agent。以下是最常用的核心工具：

命令行直接使用（无需 MCP 守护进程）

# 搜索概念（process-grouped 混合搜索）
gitnexus query "用户认证流程"

# 360° 符号视图
gitnexus context AuthService

# 分析修改某符号的影响范围
gitnexus impact UserRepository

# 当前 diff 的影响分析
gitnexus detect_changes

# 原始 Cypher 查询
gitnexus cypher "MATCH (f:Function)-[:CALLS]->(g:Function {name:'login'}) RETURN f.name"

七、实践工作流

场景一：理解一个陌生的大型仓库

flowchart TD
    A([克隆仓库]) --> B[gitnexus analyze]
    B --> C[gitnexus status\n确认索引完成]
    C --> D[在 Claude Code 中提问\n这个仓库的架构是什么]
    D --> E[Claude 调用 gitnexus context]
    E --> F[按推荐路径\n用 query 逐步深入]
    F --> G([具备全局架构认知])

场景二：提交代码前风险评估

# 1. 做完代码修改后，运行影响分析
gitnexus detect_changes

# 输出示例：
# Changed: src/auth/token.ts (3 functions modified)
# Affected processes: user-login-flow, api-middleware, refresh-token-flow
# Risk: HIGH — 23 call sites affected
# Recommendation: review middleware tests before committing

# 2. 在 Claude Code 中确认安全后再提交
# PostToolUse hook 会在 git commit 后自动触发重建索引

flowchart LR
    A([修改代码]) --> B[gitnexus detect_changes]
    B --> C{风险评估}
    C -->|LOW| D[直接提交]
    C -->|HIGH| E[检查受影响的测试]
    E --> F{测试通过}
    F -->|是| D
    F -->|否| G[修复再提交]
    D --> H([git commit\n自动重建索引])

场景三：大规模重命名重构

# 把 UserService 重命名为 AccountService（跨所有文件）

# 步骤 1：预览影响（dry-run，不实际修改）
gitnexus rename UserService AccountService --dry-run

# 步骤 2：确认无误后执行
gitnexus rename UserService AccountService

# GitNexus 使用图谱追踪高置信度调用处，文本搜索兜底其他处
# 比手动 global replace 更安全，因为了解实际调用关系

八、Web UI 使用

GitNexus 提供两种方式使用 Web UI：

方式一：在线版 打开 gitnexus.vercel.app，拖入 GitHub 仓库 URL 或 ZIP 文件。100% 浏览器内运行（WebAssembly），代码不离开本地。适合快速探索陌生仓库。

方式二：本地桥接模式 先用 CLI 索引项目，再用 gitnexus serve 启动本地服务器。Web UI 自动检测并显示所有已索引仓库，Agent 工具也路由到本地后端。

# 启动本地服务器（Web UI 桥接模式）
gitnexus serve

# 服务器运行在 http://localhost:4747
# 打开 gitnexus.vercel.app 后 Web UI 会自动检测到本地服务器

flowchart LR
    A[gitnexus serve\nlocalhost:4747] <-->|自动检测| B[gitnexus.vercel.app\nWeb UI]
    B --> C[浏览所有已索引仓库]
    B --> D[图可视化探索]
    B --> E[AI Chat 对话]
    B --> F[Cypher 查询]

九、进阶技巧

多仓库管理

GitNexus 使用全局注册表，一个 MCP Server 可以同时服务多个仓库：

# 每个仓库只需运行一次 analyze，就会注册到全局
cd ~/projects/frontend && gitnexus analyze
cd ~/projects/backend && gitnexus analyze
cd ~/projects/shared-lib && gitnexus analyze

# 列出所有已注册仓库
gitnexus list

# MCP Server 自动服务所有已注册仓库
# AI Agent 可以跨仓库查询

生成仓库 Wiki

# 基于知识图谱生成 LLM 驱动的文档
gitnexus wiki

# 指定模型
gitnexus wiki --model gpt-4o-mini

清理索引

# 删除当前仓库的索引
gitnexus clean

# 删除所有索引
gitnexus clean --all --force

⚠️ 常见问题

索引过时： 切换分支或大量提交后，在 Claude Code 中读取 gitnexus://repo/{name}/context 会显示索引新鲜度，若过时运行 gitnexus analyze 更新，然后重启 Claude Code 让 MCP 重新加载。

ℹ️ 局限性说明

GitNexus 对纯文档 / 配置仓库（HTML、CSS、Markdown 为主）效果有限——这类文件缺乏符号结构。初次索引大型仓库耗时较长，建议在网络良好时进行。npm 11.x 可能有兼容问题，可改用 npm i -g gitnexus 全局安装规避。

整体使用流程

flowchart TD
    A([开始]) --> B[npm install -g gitnexus]
    B --> C[gitnexus setup\n配置编辑器 MCP]
    C --> D[进入项目根目录]
    D --> E[gitnexus analyze\n索引代码库]
    E --> F{选择使用方式}
    F --> G[Claude Code / Cursor\nAI Agent 辅助开发]
    F --> H[gitnexus serve\nWeb UI 可视化]
    F --> I[命令行直接查询\ngitnexus query / impact]
    G --> J[AI 获得完整架构上下文]
    H --> K[图可视化加 AI 对话]
    I --> L[精确影响分析]
    J --> M([高效精准的 AI 辅助开发])
    K --> M
    L --> M

GitHub：github.com/abhigyanpatwari/GitNexus · Web UI：gitnexus.vercel.app · MIT 许可证 · 教程整理于 2026 年 6 月