[开源项目] GitNexus + Claude Code 配置与使用指南

AI智能摘要

GitNexus 是一款将代码仓库自动索引为知识图谱的工具，它会追踪项目中的每个依赖、调用链、集群和执行流，并通过 MCP（Model Context Protocol）暴露给 Claude Code，使 AI 代理真正理解代码的全局架构与复杂关系。在实际开发场景中，GitNexus 的核心价值体现在四个方面：让 AI 在分析和修改代码时不再遗漏隐含依赖和调用链；在改动代码前，可以准确评估变更的“爆炸半径”，降低引入潜在 bug 的风险；调试时能沿着调用链快速锁定错误源头，节省排查时间；进行重构和多文件重命名时更安全可控，减少对线上系统的影响。

此摘要由AI分析文章内容生成，仅供参考。

1. 简介

GitNexus 将代码仓库索引为知识图谱——追踪每个依赖、调用链、集群和执行流——然后通过 MCP（Model Context Protocol）暴露给 Claude Code，让 AI 代理拥有深层的代码架构理解能力。

核心价值：

AI 代理不再遗漏依赖关系和调用链
改代码前能准确评估爆炸半径
调试时能快速追踪错误来源
重构时能安全地进行多文件重命名

开源仓库地址：https://github.com/abhigyanpatwari/GitNexus

2. 环境要求

依赖	最低版本	说明
Node.js	>= 18.x	推荐使用 nvm 管理版本
npm	>= 9.x	随 Node.js 安装
Git	>= 2.x	仓库必须是 git 仓库
Claude Code	最新版	CLI 工具
操作系统	Linux / macOS / Windows (WSL)	原生 Linux/macOS 最佳

3. 安装

3.1 一键安装（推荐）

npm install -g gitnexus

验证安装：

gitnexus --version
# 输出示例: 1.6.3

3.2 从源码构建

适用于需要最新功能或参与开发的场景：

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

# 构建 CLI 包
cd gitnexus
npm install
npm run build

# 全局链接（可选，方便直接使用 gitnexus 命令）
npm link

4. 配置 Claude Code

4.1 自动配置（推荐）

GitNexus 提供一键配置命令，会自动检测并配置所有已安装的 AI 编辑器：

gitnexus setup

输出示例：

  GitNexus Setup
  ==============

  Configured:
    + Claude Code
    + Claude Code skills (7 skills → ~/.claude/skills/)
    + Claude Code hooks (PreToolUse, PostToolUse)

  Skipped:
    - Cursor (not installed)
    - OpenCode (not installed)
    - Codex (not installed)

  Summary:
    MCP configured for: Claude Code, Claude Code hooks
    Skills installed to: Claude Code skills (7 skills)

  Next steps:
    1. cd into any git repo
    2. Run: gitnexus analyze
    3. Open the repo in your editor — MCP is ready!

该命令会自动完成以下配置（均为全局配置）：

配置项	写入位置	作用
MCP Server	`~/.claude.json` → `mcpServers.gitnexus`	让 Claude Code 能调用 GitNexus 工具
Hooks	`~/.claude/settings.json` → `hooks`	在搜索/执行命令时自动注入图谱上下文
Skills	`~/.claude/skills/gitnexus-*/`	提供 7 个专项工作流指南

MCP Server 和 Hooks 也支持项目级配置，详见 4.2 手动配置。

4.2 手动配置

如果自动配置失败，可以手动完成。MCP Server 和 Hooks 都支持全局和项目级两种配置方式。

4.2.1 配置 MCP Server

MCP Server 有两种配置方式：

方式一：全局配置（所有项目生效）

编辑 ~/.claude.json，在 mcpServers 字段中添加：

{
  "mcpServers": {
    "gitnexus": {
      "command": "gitnexus",
      "args": ["mcp"]
    }
  }
}

方式二：项目级配置（仅当前项目生效）

在项目根目录下创建 .mcp.json 文件：

{
  "mcpServers": {
    "gitnexus": {
      "command": "gitnexus",
      "args": ["mcp"]
    }
  }
}

将 .mcp.json 添加到 .gitignore 中，避免提交个人配置到仓库。

对比：

方式	配置文件	适用场景
全局配置	`~/.claude.json`	所有项目都使用 GitNexus
项目级配置	`<project>/.mcp.json`	仅特定项目启用，团队可各自配置

注意： 如果 gitnexus 不在 PATH 中，使用完整路径，例如：

{
  "command": "/home/youruser/.nvm/versions/node/v24.14.0/bin/gitnexus",
  "args": ["mcp"]
}

4.2.2 配置 Hooks

Hooks 也有两种配置方式：

方式一：全局配置（所有项目生效）

编辑 ~/.claude/settings.json，添加 hooks 字段：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"/home/youruser/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
            "timeout": 10,
            "statusMessage": "Enriching with GitNexus graph context..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"/home/youruser/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
            "timeout": 10,
            "statusMessage": "Checking GitNexus index freshness..."
          }
        ]
      }
    ]
  }
}

方式二：项目级配置（仅当前项目生效）

在项目根目录下创建 .claude/settings.json 文件，写入相同的 hooks 内容：

your-project/
├── .claude/
│   └── settings.json    ← 项目级 hooks 配置
├── .gitnexus/           ← GitNexus 索引数据（gitnexus analyze 生成）
├── .mcp.json            ← 项目级 MCP 配置（可选）
└── ...

.claude/settings.json 内容：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"/home/youruser/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
            "timeout": 10,
            "statusMessage": "Enriching with GitNexus graph context..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"/home/youruser/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
            "timeout": 10,
            "statusMessage": "Checking GitNexus index freshness..."
          }
        ]
      }
    ]
  }
}

对比：

方式	配置文件	适用场景
全局配置	`~/.claude/settings.json`	所有项目都启用（推荐，hook 会自动跳过未索引的项目）
项目级配置	`<project>/.claude/settings.json`	仅特定项目启用，可纳入版本控制

提示： 项目级 .claude/settings.json 可以提交到仓库，方便团队共享配置。全局 hooks 配置如与项目级冲突，项目级优先。

4.2.3 安装 Skills

将 GitNexus 的 skills 目录复制到 Claude Code 的 skills 目录：

# 从源码仓库
cp -r GitNexus/gitnexus-claude-plugin/skills/* ~/.claude/skills/

# 或从 npm 全局安装目录
cp -r $(npm root -g)/gitnexus/skills/* ~/.claude/skills/

配置方式总览

配置项	全局配置	项目级配置
MCP Server	`~/.claude.json` → `mcpServers.gitnexus`	`<project>/.mcp.json`
Hooks	`~/.claude/settings.json` → `hooks`	`<project>/.claude/settings.json` → `hooks`
Skills	`~/.claude/skills/gitnexus-*/`	仅支持全局安装

场景	推荐配置方式
所有项目都用 GitNexus	全局配置（`gitnexus setup` 一键完成）
只有部分项目需要	项目级配置（`.mcp.json` + `.claude/settings.json`）
团队协作，统一配置	项目级配置并提交到仓库

5. 索引仓库

进入你的项目目录，运行：

cd /path/to/your/project
gitnexus analyze

常用参数：

参数	说明
`--force`	强制全量重建索引（即使索引是最新的）
`--embeddings`	启用向量嵌入，支持语义搜索（需要 OpenAI API key）
`--drop-embeddings`	重建时丢弃已有嵌入
`--skills`	根据检测到的功能社区生成项目专属 skill 文件
`--skip-agents-md`	不更新 AGENTS.md 和 CLAUDE.md 中的 GitNexus 段落
`--name <alias>`	为仓库注册自定义别名
`-v, --verbose`	输出详细的解析警告
`--max-file-size <kb>`	跳过超过指定大小的文件（默认 512KB）

索引完成后：

# 检查索引状态
gitnexus status

# 查看所有已索引的仓库
gitnexus list

索引产物：

.gitnexus/ — 知识图谱数据目录（在项目根目录下）
~/.gitnexus/registry.json — 全局仓库注册表

6. Web UI

GitNexus 提供了基于浏览器的可视化图谱探索器 + AI 对话界面，有两种使用方式：

6.1 在线版（零安装）

直接访问 gitnexus.vercel.app，在浏览器中上传仓库或输入 GitHub URL 即可。

无需安装任何依赖
所有处理都在浏览器内完成，数据不会上传到服务器
受浏览器内存限制，适合 ~5000 文件以内的仓库

6.2 Bridge 模式（推荐，连接本地索引）

Bridge 模式将 CLI 的本地索引与 Web UI 连接起来，Web UI 会自动检测本地服务器并浏览所有已索引的仓库，无需重新上传或索引。

步骤：

# 1. 索引仓库（如果还没索引）
cd /path/to/your/project
gitnexus analyze

# 2. 启动本地 HTTP 服务（默认端口 4747）
gitnexus serve

然后打开 gitnexus.vercel.app，它会自动连接本地服务。

自定义启动参数：

# 指定端口
gitnexus serve --port 4748

# 允许局域网访问（默认仅 localhost）
gitnexus serve --host 0.0.0.0

# 组合使用
gitnexus serve --port 4748 --host 0.0.0.0

6.3 方式对比

特性	在线版 (vercel.app)	Bridge 模式 (`gitnexus serve`)
安装	无需安装	需要 CLI
索引规模	浏览器内存限制 ~5k 文件	无限制
隐私	全部在浏览器内，不上传	全部本地
适用场景	快速探索、演示、小型仓库	日常开发、大型仓库
功能	图谱浏览 + AI 对话	图谱浏览 + AI 对话 + 全部 CLI 索引

6.4 从源码运行 Web UI（开发模式）

如果需要对 Web UI 进行开发或调试：

cd gitnexus-web
npm install
npm run dev        # 启动 Vite 开发服务器
npm run build      # 构建生产版本
npm run preview    # 预览生产构建

7. MCP 工具详解

索引完成后，Claude Code 可通过 MCP 调用以下工具：

工具	功能	典型用途
`query`	混合 BM25 + 向量搜索	"找到与支付处理相关的代码"
`context`	符号的 360 度视图	"谁调用了 validateUser？它又调用了什么？"
`impact`	爆炸半径分析	"改了这个函数会影响什么？"
`detect_changes`	Git diff 映射到符号	"我当前的修改影响了哪些流程？"
`rename`	图谱辅助的多文件重命名	"安全地把 validateUser 改名为 authenticateUser"
`cypher`	直接查询图谱	自定义 Cypher 查询
`list_repos`	列出已索引的仓库	发现可用的仓库

MCP Resources（轻量级只读资源）

资源 URI	内容
`gitnexus://repo/{name}/context`	仓库概览、索引新鲜度检查
`gitnexus://repo/{name}/clusters`	所有功能区域及内聚度评分
`gitnexus://repo/{name}/cluster/{name}`	某功能区域的成员列表
`gitnexus://repo/{name}/processes`	所有执行流
`gitnexus://repo/{name}/process/{name}`	某执行流的逐步追踪
`gitnexus://repo/{name}/schema`	图谱 schema（用于 Cypher 查询）

8. Skills 工作流

gitnexus setup 会安装 7 个 Skills 到 ~/.claude/skills/。每个 Skill 是一个专项工作流指南，Claude Code 会根据你的问题自动匹配。

8.1 gitnexus-cli — 索引管理

触发场景： "索引这个仓库"、"重建索引"、"生成 wiki"

核心命令：

# 索引仓库
gitnexus analyze

# 强制重建
gitnexus analyze --force

# 启用语义搜索
gitnexus analyze --embeddings

# 检查索引状态
gitnexus status

# 删除索引
gitnexus clean

# 生成文档
gitnexus wiki

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

8.2 gitnexus-exploring — 代码探索

触发场景： "这个认证是怎么工作的？"、"项目结构是什么？"、"支付流程是怎样的？"

工作流：

1. READ gitnexus://repo/{name}/context        → 仓库概览，检查索引新鲜度
2. gitnexus_query({query: "你想理解的概念"})    → 找到相关的执行流
3. gitnexus_context({name: "关键符号"})         → 深入查看调用者/被调用者
4. READ gitnexus://repo/{name}/process/{name}  → 追踪完整执行流
5. 读取源文件获取实现细节

示例对话：

你: "支付处理是怎么工作的？"
Claude:
  1. 读取 gitnexus://repo/my-app/context → 918 个符号，45 个执行流
  2. query("payment processing") → CheckoutFlow, RefundFlow, WebhookHandler
  3. context("processPayment") → 调用者: checkoutHandler, webhookHandler
                                  调用: validateCard, chargeStripe, saveTransaction
  4. 读取 src/payments/processor.ts 获取实现细节

8.3 gitnexus-debugging — 调试追踪

触发场景： "这个函数为什么失败？"、"这个错误从哪来的？"、"追踪这个 bug"

工作流：

1. gitnexus_query({query: "错误信息或症状"})    → 找到相关执行流
2. gitnexus_context({name: "嫌疑函数"})         → 查看调用者/被调用者
3. READ gitnexus://repo/{name}/process/{name}  → 追踪执行流
4. gitnexus_cypher({query: "自定义追踪查询"})    → 如需深度追踪

调试模式速查：

症状	GitNexus 方法
错误信息	`query` 搜索错误文本 → `context` 查看抛出点
返回值错误	`context` 查看函数 → 追踪被调用者的数据流
间歇性故障	`context` → 查找外部调用、异步依赖
性能问题	`context` → 找到调用者最多的符号（热点路径）
最近的回归	`detect_changes` 查看修改影响了什么

8.4 gitnexus-impact-analysis — 影响分析

触发场景： "改这个安全吗？"、"谁依赖这个？"、"什么会崩溃？"

工作流：

1. gitnexus_impact({target: "X", direction: "upstream"})  → 找到所有依赖方
2. READ gitnexus://repo/{name}/processes                  → 检查受影响的执行流
3. gitnexus_detect_changes()                               → 映射当前 git 变更
4. 评估风险并向用户报告

风险等级：

深度	风险级别	含义
d=1	将会崩溃	直接调用者/导入者
d=2	可能受影响	间接依赖
d=3	可能需要测试	传递性影响

风险评估矩阵：

影响范围	风险
< 5 个符号，少量执行流	LOW
5-15 个符号，2-5 个执行流	MEDIUM
> 15 个符号或大量执行流	HIGH
关键路径（认证、支付）	CRITICAL

8.5 gitnexus-refactoring — 安全重构

触发场景： "重命名这个函数"、"提取成模块"、"拆分这个服务"

重命名工作流：

1. gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true})
   → 预览所有编辑
2. 审查图谱编辑（高置信度）和 ast_search 编辑（需仔细审查）
3. gitnexus_rename({..., dry_run: false})
   → 应用编辑
4. gitnexus_detect_changes()
   → 验证只有预期的文件被修改
5. 运行受影响执行流的测试

提取模块工作流：

1. gitnexus_context({name: target})              → 查看所有引用
2. gitnexus_impact({target, direction: "upstream"}) → 找到所有外部调用者
3. 定义新模块接口
4. 提取代码，更新导入
5. gitnexus_detect_changes()                      → 验证影响范围
6. 运行测试

8.6 gitnexus-pr-review — PR 审查

触发场景： "审查这个 PR"、"PR #42 改了什么？"、"合并安全吗？"

工作流：

1. gh pr diff <number>                                            → 获取原始 diff
2. gitnexus_detect_changes({scope: "compare", base_ref: "main"}) → 映射到受影响的执行流
3. 对每个变更符号: gitnexus_impact({target, direction: "upstream"}) → 爆炸半径
4. gitnexus_context({name: "关键符号"})                            → 理解上下文
5. 汇总发现并评估风险

审查维度：

维度	GitNexus 如何帮助
正确性	`context` 显示调用者 — 是否都兼容变更？
爆炸半径	`impact` 显示 d=1/d=2/d=3 依赖 — 有遗漏吗？
完整性	`detect_changes` 显示所有受影响的流 — 都处理了吗？
测试覆盖	`impact({includeTests: true})` 显示哪些测试覆盖了变更代码
破坏性变更	PR diff 外的 d=1 调用者 = 潜在破坏

审查输出模板：

## PR Review: <标题>

**风险: LOW / MEDIUM / HIGH / CRITICAL**

### 变更摘要
- <N> 个符号变更，跨 <M> 个文件
- <P> 个执行流受影响

### 发现
1. **[严重性]** 描述
   - 来自 GitNexus 工具的证据
   - 受影响的调用者/执行流

### 缺失覆盖
- PR 中未更新的调用者: ...
- 未测试的执行流: ...

### 建议
APPROVE / REQUEST CHANGES / NEEDS DISCUSSION

8.7 gitnexus-guide — 工具参考

触发场景： "GitNexus 有哪些工具？"、"怎么查询知识图谱？"

这是所有工具和资源的快速参考，当你不确定用哪个工具时，Claude Code 会自动引导你到合适的 Skill。

9. 典型使用场景

场景 1：理解陌生代码库

你: "这个项目的认证流程是怎样的？"

Claude Code 自动执行:
  1. 读取 gitnexus://repo/myapp/context → 检查索引状态
  2. query("authentication login flow") → 找到 LoginFlow, TokenRefresh
  3. context("validateUser") → 调用者: loginHandler, apiMiddleware
  4. 读取 process/LoginFlow → 完整的认证执行流
  5. 读取源文件 → 给你详细的解释

场景 2：修改前的影响评估

你: "如果我改了 calculatePrice 函数，会影响什么？"

Claude Code 自动执行:
  1. impact({target: "calculatePrice", direction: "upstream"})
  2. d=1: checkoutHandler, invoiceGenerator (将会崩溃)
  3. d=2: reportService, taxCalculator (可能受影响)
  4. 评估: MEDIUM 风险，2 个直接调用者，2 个执行流

场景 3：调试生产问题

你: "支付接口间歇性返回 500"

Claude Code 自动执行:
  1. query("payment error handling") → CheckoutFlow, ErrorHandling
  2. context("validatePayment") → 外部调用: fetchRates (无超时!)
  3. 追踪 CheckoutFlow → Step 3 调用 fetchRates
  4. 根因: fetchRates 调用外部 API 没有设置超时

场景 4：安全重构

你: "把 validateUser 重命名为 authenticateUser"

Claude Code 自动执行:
  1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
  2. 12 处编辑: 10 处图谱编辑（安全），2 处 ast_search（需审查）
  3. 你确认后执行 dry_run: false
  4. detect_changes() → 确认只有预期文件被修改

10. 常见问题与排查

10.1 安装问题

问题：`npm install -g gitnexus` 时 onnxruntime-node 安装失败

错误信息：

Error: Failed to download build list. HTTP status code = 302

原因： Node.js 的 https.get 不自动跟随 HTTP 302 重定向。

解决方案 A — 跳过脚本后手动修复：

# 1. 跳过 postinstall 脚本安装
npm install -g gitnexus --ignore-scripts

# 2. 手动修复 onnxruntime-node 的安装脚本
# 编辑文件（路径根据实际版本调整）：
# ~/.nvm/versions/node/vXX/lib/node_modules/gitnexus/node_modules/onnxruntime-node/script/install-utils.js
#
# 在文件顶部添加 http 模块引用:
#   const http = require('http');
#
# 给 downloadJson 和 downloadFile 函数添加重定向支持:
#   在 https.get 回调中加入:
#     if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
#       // 跟随重定向
#       const mod = res.headers.location.startsWith('https') ? https : http;
#       mod.get(res.headers.location, callback);
#       return;
#     }

# 3. 运行 onnxruntime-node 的安装脚本
cd $(npm root -g)/gitnexus/node_modules/onnxruntime-node
node script/install.js

# 4. 同样处理 @huggingface/transformers 下的 onnxruntime-node（如果存在）
cd $(npm root -g)/gitnexus/node_modules/@huggingface/transformers/node_modules/onnxruntime-node
node script/install.js

解决方案 B — 设置环境变量跳过：

# 如果不需要 embeddings 功能，可以跳过 onnxruntime 安装
ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus

问题：LadybugDB 原生模块加载失败

错误信息：

Error: lbugjs.node: cannot open shared object file: No such file or directory

原因： 使用了 --ignore-scripts 安装，原生模块未构建。

解决方案：

# 运行 LadybugDB 的安装脚本，它会复制预编译的二进制文件
cd $(npm root -g)/gitnexus/node_modules/@ladybugdb/core
node install.js

问题：tree-sitter 原生模块找不到

错误信息：

Error: Cannot find module 'tree-sitter-typescript' 或类似

原因： tree-sitter 语言包的预编译二进制未正确安装。

解决方案：

# tree-sitter 包自带预编译的 .node 文件，通常不需要额外构建
# 如果缺失，尝试重新安装该特定包：
cd $(npm root -g)/gitnexus
npm rebuild tree-sitter-typescript
npm rebuild tree-sitter-javascript
# ... 其他需要的语言包

10.2 配置问题

问题：Claude Code 中看不到 GitNexus 的 MCP 工具

排查步骤：

# 1. 确认 MCP 配置存在
cat ~/.claude.json | grep -A 5 "gitnexus"

# 应该看到:
# "gitnexus": {
#   "command": "/path/to/gitnexus",
#   "args": ["mcp"]
# }

# 2. 确认 gitnexus 命令可用
which gitnexus
gitnexus --version

# 3. 确认 hooks 配置存在
cat ~/.claude/settings.json | grep -A 10 "hooks"

# 4. 确认 skills 已安装
ls ~/.claude/skills/gitnexus-*

解决方案：

# 重新运行 setup
gitnexus setup

# 重启 Claude Code（必须！MCP 配置只在启动时加载）

问题：Hooks 不生效（搜索时没有图谱上下文注入）

排查步骤：

# 1. 检查 hook 脚本是否存在
ls ~/.claude/hooks/gitnexus/gitnexus-hook.cjs

# 2. 手动测试 hook 脚本
echo '{}' | node ~/.claude/hooks/gitnexus/gitnexus-hook.cjs

# 3. 检查 settings.json 中的 hooks 配置格式是否正确
cat ~/.claude/settings.json | python3 -m json.tool

10.3 索引问题

问题：`gitnexus analyze` 报 "Not a git repository"

原因： 当前目录不在 git 仓库内。

解决方案：

# 确认当前目录是 git 仓库
git status

# 如果不是，先初始化
git init
# 或者 cd 到正确的 git 仓库目录

问题：索引报告 "Index is stale"

原因： 仓库有新的 commit，但索引还未更新。

解决方案：

# 刷新索引
gitnexus analyze

# 强制全量重建（如果增量更新有问题）
gitnexus analyze --force

问题：索引速度太慢

解决方案：

# 跳过大型文件
gitnexus analyze --max-file-size 256

# 不生成 embeddings（默认就是关闭的）
gitnexus analyze

# 减少 worker 超时
gitnexus analyze --worker-timeout 15

问题：索引损坏或异常

解决方案：

# 删除索引并重建
gitnexus clean
gitnexus analyze

# 清理所有仓库的索引
gitnexus clean --all

10.4 MCP 连接问题

问题：MCP server 启动超时

错误信息：

MCP server gitnexus failed to start within 30s

原因： 使用 npx -y gitnexus@latest 时冷启动需要下载依赖。

解决方案：

# 全局安装比 npx 快得多（启动约 1 秒）
npm install -g gitnexus

# 重新配置
gitnexus setup

问题：MCP 工具调用报错

排查步骤：

# 1. 手动启动 MCP server 测试
gitnexus mcp
# 应该看到 stdio 模式等待输入

# 2. 检查索引是否存在
gitnexus status

# 3. 检查索引目录
ls -la .gitnexus/

10.5 性能问题

问题：大型仓库索引占用内存过多

解决方案：

# GitNexus 内部会自动处理大堆内存
# 如果仍然 OOM，可以限制文件大小
gitnexus analyze --max-file-size 256

# 或者排除不需要的目录（在 .gitignore 中配置）

问题：MCP 响应慢

原因： 知识图谱查询在大型仓库上可能较慢。

解决方案：

确保索引是最新的（stale index 会导致额外检查）
使用更精确的查询词
对于 Cypher 查询，限制路径深度（*1..3 而非 *1..10）

附录：快速参考卡

┌─────────────────────────────────────────────────────────┐
│                   GitNexus 快速命令                       │
├─────────────────────────────────────────────────────────┤
│  gitnexus setup          一键配置 Claude Code             │
│  gitnexus analyze        索引当前仓库                      │
│  gitnexus analyze -f     强制重建索引                      │
│  gitnexus status         检查索引状态                      │
│  gitnexus list           列出所有已索引仓库                 │
│  gitnexus clean          删除当前仓库索引                  │
│  gitnexus wiki           生成仓库文档                      │
│  gitnexus serve          启动 HTTP 服务（供 Web UI 使用）   │
│  gitnexus mcp            启动 MCP server（Claude Code 用） │
├─────────────────────────────────────────────────────────┤
│  配置文件位置:                                             │
│  ~/.claude.json           MCP Server 配置                 │
│  ~/.claude/settings.json  Hooks 配置                      │
│  ~/.claude/skills/        Skills 文件                     │
│  .gitnexus/               项目索引数据                     │
│  ~/.gitnexus/registry.json 全局仓库注册表                  │
└─────────────────────────────────────────────────────────┘

2026 年 5 月
日	一	二	三	四	五	六
					1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30
31

1. 简介

2. 环境要求

3. 安装

3.1 一键安装（推荐）

3.2 从源码构建

4. 配置 Claude Code

4.1 自动配置（推荐）

4.2 手动配置

4.2.1 配置 MCP Server

4.2.2 配置 Hooks

4.2.3 安装 Skills

配置方式总览

5. 索引仓库

6. Web UI

6.1 在线版（零安装）

6.2 Bridge 模式（推荐，连接本地索引）

6.3 方式对比

6.4 从源码运行 Web UI（开发模式）

7. MCP 工具详解

MCP Resources（轻量级只读资源）

8. Skills 工作流

8.1 gitnexus-cli — 索引管理

8.2 gitnexus-exploring — 代码探索

8.3 gitnexus-debugging — 调试追踪

8.4 gitnexus-impact-analysis — 影响分析

8.5 gitnexus-refactoring — 安全重构

8.6 gitnexus-pr-review — PR 审查

8.7 gitnexus-guide — 工具参考

9. 典型使用场景

场景 1：理解陌生代码库

场景 2：修改前的影响评估

场景 3：调试生产问题

场景 4：安全重构

10. 常见问题与排查

10.1 安装问题

问题：npm install -g gitnexus 时 onnxruntime-node 安装失败

问题：LadybugDB 原生模块加载失败

问题：tree-sitter 原生模块找不到

10.2 配置问题

问题：Claude Code 中看不到 GitNexus 的 MCP 工具

问题：Hooks 不生效（搜索时没有图谱上下文注入）

10.3 索引问题

问题：gitnexus analyze 报 "Not a git repository"

问题：索引报告 "Index is stale"

问题：索引速度太慢

问题：索引损坏或异常

10.4 MCP 连接问题

问题：MCP server 启动超时

问题：MCP 工具调用报错

10.5 性能问题

问题：大型仓库索引占用内存过多

问题：MCP 响应慢

附录：快速参考卡

问题：`npm install -g gitnexus` 时 onnxruntime-node 安装失败

问题：`gitnexus analyze` 报 "Not a git repository"