03 - GitNexus：把代码库索引为知识图谱

GitHub: abhigyanpatwari/GitNexus官网: gitnexus.vercel.app（在线 Web UI） 技术栈: Node.js + Tree-sitter + KuzuDB + transformers.js 核心定位: 把代码仓库自动索引为知识图谱，追踪依赖、调用链、功能聚类与执行流，通过 MCP 暴露给 Claude Code / Cursor / Codex / Windsurf。

1. 项目背景

1.1 GitNexus 解决的核心问题

AI 编程代理（Claude Code 等）在分析和修改代码时常常：

遗漏隐含依赖：改了 A 函数，没注意到 B 文件也在调用它
猜架构：靠 README.md 或目录名猜，错过实际的模块边界
不知道爆炸半径：动一个核心函数可能触发雪崩，但 AI 看不到
重构不安全：跨文件重命名漏改、改错

GitNexus 的解题思路：

把代码库变成一张可被 LLM 通过 MCP 查询的"知识图谱"：每个符号是节点，调用/继承/import/测试覆盖都是边，再叠一层向量语义搜索。

1.2 与 code-review-graph 的差异

维度	GitNexus	code-review-graph
技术栈	Node.js	Python
图数据库	KuzuDB（原生图数据库，支持 Cypher）	SQLite
嵌入	transformers.js（浏览器/Node 原生跑）	sentence-transformers 等
Web UI	✅ 提供在线 + Bridge 模式	提供 D3.js 静态可视化
MCP 工具数	7 个核心 + Resources	28 个 + 5 prompt
Skills 集成	7 个专项 Skills 自动安装到 `~/.claude/skills/`	不附带 Skills
Hooks	PreToolUse / PostToolUse 自动注入图谱上下文	Git hook 增量更新
多语言	11 种	23 种

GitNexus 更侧重与 Claude Code 生态深度集成（Skills + Hooks + MCP 三位一体），code-review-graph 更侧重语言广度和图分析深度。

2. 核心概览

2.1 索引六阶段流水线

源码项目
   ↓
① 结构解析（Tree-sitter 解析 AST）
   ↓
② 符号解析（提取函数、类、变量等符号）
   ↓
③ 功能聚类（社区检测，把相关代码归类）
   ↓
④ 执行流构建（追踪入口函数到出口的典型路径）
   ↓
⑤ 混合搜索索引（BM25 + 向量嵌入）
   ↓
⑥ 落库到 KuzuDB（.gitnexus/）

2.2 索引产物

your-project/
├── .gitnexus/                    # 当前项目的知识图谱数据
│   ├── graph.kuzu               # KuzuDB 图数据库文件
│   ├── embeddings/              # 向量嵌入（可选）
│   └── ...
├── .claude/
│   └── settings.json            # 项目级 hooks 配置（可选）
└── .mcp.json                    # 项目级 MCP 配置（可选）

~/.gitnexus/
└── registry.json                # 全局多仓库注册表

~/.claude/
├── claude.json                  # MCP 配置（全局）
├── settings.json                # Hooks 配置（全局）
└── skills/
    ├── gitnexus-cli/            # Skills 1: 索引管理
    ├── gitnexus-exploring/      # Skills 2: 代码探索
    ├── gitnexus-debugging/      # Skills 3: 调试追踪
    ├── gitnexus-impact-analysis/ # Skills 4: 影响分析
    ├── gitnexus-refactoring/    # Skills 5: 安全重构
    ├── gitnexus-pr-review/      # Skills 6: PR 审查
    └── gitnexus-guide/          # Skills 7: 工具参考

2.3 支持的语言

TypeScript、JavaScript、Python、Java、C、C++、C#、Go、Rust、PHP、Swift。

3. 实现原理

3.1 整体架构

┌─────────────────────────────────────────────┐
│            源码（Git 仓库）                    │
└──────────────────┬──────────────────────────┘
                   │ gitnexus analyze
                   ▼
┌─────────────────────────────────────────────┐
│   六阶段索引流水线                              │
│   解析 → 符号 → 聚类 → 执行流 → 索引 → 入库      │
└──────────────────┬──────────────────────────┘
                   │
       ┌───────────┴───────────────┐
       ▼                           ▼
┌──────────────┐         ┌──────────────────┐
│  KuzuDB 图库   │         │  向量嵌入        │
│  (.gitnexus/)│         │  transformers.js │
└──────┬───────┘         └────────┬─────────┘
       │                          │
       └───────────┬──────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│   gitnexus mcp（MCP Server）                  │
│   7 工具 + 多个 Resources                     │
└──────────────────┬──────────────────────────┘
                   │
       ┌───────────┼───────────┐
       ▼           ▼           ▼
   Claude       Cursor       Codex
   Code         Windsurf     OpenCode
       │
       ▼
   + Skills（7 个）+ Hooks（注入图谱上下文）

3.2 KuzuDB 图数据库

KuzuDB 是一款嵌入式属性图数据库，原生支持 Cypher 查询，相比 SQLite 模拟图结构有以下优势：

节点 / 边天然为一等公民
多跳查询性能远高于 SQL 自连接
内置 Cypher 解析器，AI 可以直接发自定义查询

gitnexus_cypher 工具就是直接把 LLM 写的 Cypher 喂给 KuzuDB，例如：

cypher

MATCH (a:Function)-[r:CALLS]->(b:Function)
WHERE b.name = "validateUser"
RETURN a.name, a.file

3.3 transformers.js 本地嵌入

GitNexus 使用 Hugging Face transformers.js，在浏览器或 Node 中原生运行嵌入模型，不消耗 LLM Token：

默认模型可以在 CPU 上跑
无需外部 API Key
Web UI 在浏览器端跑嵌入，数据不离开本地

但安装时会引入 onnxruntime-node（用于 ONNX 模型推理），这是常见的踩坑点（见后文）。

3.4 Hooks 注入图谱上下文

GitNexus 在 Claude Code 中注册两类 hook：

PreToolUse（匹配 Grep|Glob|Bash）：在 AI 调用搜索类工具前，先调用 gitnexus-hook.cjs，把图谱里的相关上下文注入到工具结果中
PostToolUse（匹配 Bash）：在 AI 执行完 Bash 后，检查图谱索引是否过期，必要时提示重新索引

这种"hook 增强"模式让原生工具自带知识图谱能力，AI 不需要显式调 MCP 也能受益。

4. 环境要求

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

5. 完整使用步骤

5.1 安装

5.1.1 一键安装（推荐）

bash

npm install -g gitnexus
gitnexus --version    # 验证：1.6.3 或更高

5.1.2 从源码构建（开发场景）

bash

git clone https://github.com/abhigyanpatwari/GitNexus.git
cd GitNexus

cd gitnexus
npm install
npm run build

# 全局链接（可选）
npm link

5.2 一键配置 Claude Code

bash

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 个专项工作流

5.3 手动配置（自动失败时）

5.3.1 全局 MCP（所有项目共用）

编辑 ~/.claude.json：

json

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

如果 gitnexus 不在 PATH，用完整路径：

json

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

5.3.2 项目级 MCP（仅当前项目）

在项目根目录创建 .mcp.json：

json

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

个人项目记得把 .mcp.json 加到 .gitignore；团队共享配置则可以提交。

5.3.3 全局 Hooks

编辑 ~/.claude/settings.json：

json

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

5.3.4 项目级 Hooks

把同样的 hooks 内容写到 <项目根>/.claude/settings.json，可以提交到仓库共享。

5.4 索引仓库

bash

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）
`--worker-timeout <s>`	单 worker 超时

bash

gitnexus status     # 检查索引状态
gitnexus list       # 列出所有已索引仓库
gitnexus clean      # 删除当前项目索引
gitnexus clean --all # 清理所有项目索引

5.5 Web UI

GitNexus 提供基于浏览器的可视化图谱探索器 + AI 对话界面。

5.5.1 在线版（零安装）

直接访问 gitnexus.vercel.app：

浏览器上传仓库或输入 GitHub URL
所有处理在浏览器内完成，数据不上传服务器
受浏览器内存限制，适合 ~5000 文件以内的仓库

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

bash

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

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

# 自定义启动
gitnexus serve --port 4748
gitnexus serve --host 0.0.0.0     # 允许局域网访问

Web UI 会自动检测本地服务并展示所有已索引仓库，无需重新上传。

特性	在线版	Bridge 模式
安装	无需	需要 CLI
索引规模	浏览器内存限制 ~5k 文件	无限制
隐私	全部在浏览器内	全部本地
适用场景	快速探索、演示	日常开发、大型仓库

6. MCP 工具

6.1 7 个核心工具

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

6.2 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 查询）

7. 7 个 Skills 工作流

gitnexus setup 会安装到 ~/.claude/skills/，Claude Code 根据问题自动匹配。

7.1 gitnexus-cli（索引管理）

触发："索引这个仓库" / "重建索引" / "生成 wiki"

bash

gitnexus analyze            # 索引
gitnexus analyze --force    # 强制重建
gitnexus analyze --embeddings  # 启用语义搜索
gitnexus status             # 检查状态
gitnexus clean              # 删除索引
gitnexus wiki               # 生成文档
gitnexus list               # 所有已索引仓库

7.2 gitnexus-exploring（代码探索）

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

工作流：

1. READ gitnexus://repo/{name}/context        → 仓库概览
2. gitnexus_query({query: "你想理解的概念"})   → 找相关流
3. gitnexus_context({name: "关键符号"})        → 查 callers/callees
4. READ gitnexus://repo/{name}/process/{name} → 追踪完整执行流
5. 读取源文件获取实现细节

示例：

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

7.3 gitnexus-debugging（调试追踪）

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

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

7.4 gitnexus-impact-analysis（影响分析）

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

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

风险等级矩阵：

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

7.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. 运行受影响执行流的测试

7.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. 汇总发现并评估风险

PR 审查输出模板：

## PR Review: <标题>

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

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

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

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

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

7.7 gitnexus-guide（工具参考）

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

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

8. 典型使用场景

8.1 场景 1：理解陌生代码库

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

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

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

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

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

8.3 场景 3：调试生产问题

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

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

8.4 场景 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() → 确认只有预期文件被修改

9. 常见问题与排坑

9.1 安装问题

`onnxruntime-node` 下载失败（302 重定向）

错误：

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

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

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

bash

npm install -g gitnexus --ignore-scripts

# 手动修改 ~/.nvm/.../onnxruntime-node/script/install-utils.js
# 给 downloadJson 和 downloadFile 加重定向支持
cd $(npm root -g)/gitnexus/node_modules/onnxruntime-node
node script/install.js

# 同样处理 @huggingface/transformers 下的 onnxruntime-node
cd $(npm root -g)/gitnexus/node_modules/@huggingface/transformers/node_modules/onnxruntime-node
node script/install.js

解决方案 B：跳过 onnxruntime（不要 embeddings 时）

bash

ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus

LadybugDB 原生模块加载失败

错误：Error: lbugjs.node: cannot open shared object file

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

bash

cd $(npm root -g)/gitnexus/node_modules/@ladybugdb/core
node install.js

tree-sitter 原生模块找不到

bash

cd $(npm root -g)/gitnexus
npm rebuild tree-sitter-typescript
npm rebuild tree-sitter-javascript

9.2 配置问题

Claude Code 中看不到 MCP 工具

排查：

bash

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

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

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

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

解决：

bash

gitnexus setup
# 然后必须**完全重启** Claude Code（MCP 配置只在启动时加载）

Hooks 不生效

bash

# 检查 hook 脚本
ls ~/.claude/hooks/gitnexus/gitnexus-hook.cjs

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

# 检查 JSON 格式
cat ~/.claude/settings.json | python3 -m json.tool

9.3 索引问题

问题	解决
`Not a git repository`	当前目录不是 git 仓库，先 `git init`
`Index is stale`	`gitnexus analyze` 刷新；严重时 `--force` 全量重建
索引慢	`--max-file-size 256` / `--worker-timeout 15`
索引损坏	`gitnexus clean` 后重建

9.4 MCP 连接问题

错误	解决
`MCP server gitnexus failed to start within 30s`	不要用 `npx -y gitnexus@latest`（冷启动慢），改用 `npm install -g gitnexus` 后 `gitnexus setup`
MCP 工具调用报错	手动 `gitnexus mcp` 测试 + `gitnexus status` 看索引

9.5 性能问题

问题	解决
大仓库 OOM	`--max-file-size 256` 跳过大文件，或在 `.gitignore` 排除
MCP 响应慢	保证索引最新；用更精确的查询；Cypher 限制路径深度（`1..3` 而非 `1..10`）

10. 配置方式对比总结

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

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

11. 快速参考卡

┌─────────────────────────────────────────────────────────┐
│                   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 全局仓库注册表                  │
└─────────────────────────────────────────────────────────┘

12. 适用场景

✅ 强推：

已经在用 Claude Code 的团队（深度集成 Skills + Hooks）
需要"图查询 + 浏览器可视化"两手抓
TS/JS/Python 为主的项目
多人协作、PR Review 重的工作流

⚠️ 慎用：

Node.js / npm 环境复杂的机器（onnxruntime 装机问题多）
不能本地存储索引数据的场景

❌ 不适用：

需要 Python 集成（用 code-review-graph）
23 种语言以外的小众语言

13. 参考链接

GitHub: https://github.com/abhigyanpatwari/GitNexus
在线 Web UI: https://gitnexus.vercel.app/
知乎《GitNexus 保姆级教程：将代码库索引为知识图谱》
知乎《打造 AI 智能体专属的代码知识库：GitNexus 完整上手攻略》
云栖梦泽《[开源项目] GitNexus + Claude Code 配置与使用指南》

docs

hook

watcher

03 - GitNexus：把代码库索引为知识图谱 ​

1. 项目背景 ​

1.1 GitNexus 解决的核心问题 ​

1.2 与 code-review-graph 的差异 ​

2. 核心概览 ​

2.1 索引六阶段流水线 ​

2.2 索引产物 ​

2.3 支持的语言 ​

3. 实现原理 ​

3.1 整体架构 ​

3.2 KuzuDB 图数据库 ​

3.3 transformers.js 本地嵌入 ​

3.4 Hooks 注入图谱上下文 ​

4. 环境要求 ​

5. 完整使用步骤 ​

5.1 安装 ​

5.1.1 一键安装（推荐） ​

5.1.2 从源码构建（开发场景） ​

5.2 一键配置 Claude Code ​

5.3 手动配置（自动失败时） ​

5.3.1 全局 MCP（所有项目共用） ​

5.3.2 项目级 MCP（仅当前项目） ​

5.3.3 全局 Hooks ​

5.3.4 项目级 Hooks ​

5.4 索引仓库 ​

5.5 Web UI ​

5.5.1 在线版（零安装） ​

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

6. MCP 工具 ​

6.1 7 个核心工具 ​

6.2 MCP Resources（轻量级只读） ​

7. 7 个 Skills 工作流 ​

7.1 gitnexus-cli（索引管理） ​

7.2 gitnexus-exploring（代码探索） ​

7.3 gitnexus-debugging（调试追踪） ​

7.4 gitnexus-impact-analysis（影响分析） ​

7.5 gitnexus-refactoring（安全重构） ​

7.6 gitnexus-pr-review（PR 审查） ​

7.7 gitnexus-guide（工具参考） ​

8. 典型使用场景 ​

8.1 场景 1：理解陌生代码库 ​

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

8.3 场景 3：调试生产问题 ​

8.4 场景 4：安全重构 ​

9. 常见问题与排坑 ​

9.1 安装问题 ​

onnxruntime-node 下载失败（302 重定向） ​

LadybugDB 原生模块加载失败 ​

tree-sitter 原生模块找不到 ​

9.2 配置问题 ​

Claude Code 中看不到 MCP 工具 ​

Hooks 不生效 ​

9.3 索引问题 ​

9.4 MCP 连接问题 ​

9.5 性能问题 ​

10. 配置方式对比总结 ​

11. 快速参考卡 ​

12. 适用场景 ​

13. 参考链接 ​

03 - GitNexus：把代码库索引为知识图谱

1. 项目背景

1.1 GitNexus 解决的核心问题

1.2 与 code-review-graph 的差异

2. 核心概览

2.1 索引六阶段流水线

2.2 索引产物

2.3 支持的语言

3. 实现原理

3.1 整体架构

3.2 KuzuDB 图数据库

3.3 transformers.js 本地嵌入

3.4 Hooks 注入图谱上下文

4. 环境要求

5. 完整使用步骤

5.1 安装

5.1.1 一键安装（推荐）

5.1.2 从源码构建（开发场景）

5.2 一键配置 Claude Code

5.3 手动配置（自动失败时）

5.3.1 全局 MCP（所有项目共用）

5.3.2 项目级 MCP（仅当前项目）

5.3.3 全局 Hooks

5.3.4 项目级 Hooks

5.4 索引仓库

5.5 Web UI

5.5.1 在线版（零安装）

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

6. MCP 工具

6.1 7 个核心工具

6.2 MCP Resources（轻量级只读）

7. 7 个 Skills 工作流

7.1 gitnexus-cli（索引管理）

7.2 gitnexus-exploring（代码探索）

7.3 gitnexus-debugging（调试追踪）

7.4 gitnexus-impact-analysis（影响分析）

7.5 gitnexus-refactoring（安全重构）

7.6 gitnexus-pr-review（PR 审查）

7.7 gitnexus-guide（工具参考）

8. 典型使用场景

8.1 场景 1：理解陌生代码库

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

8.3 场景 3：调试生产问题

8.4 场景 4：安全重构

9. 常见问题与排坑

9.1 安装问题

`onnxruntime-node` 下载失败（302 重定向）

LadybugDB 原生模块加载失败

tree-sitter 原生模块找不到

9.2 配置问题

Claude Code 中看不到 MCP 工具

Hooks 不生效

9.3 索引问题

9.4 MCP 连接问题

9.5 性能问题

10. 配置方式对比总结

11. 快速参考卡

12. 适用场景

13. 参考链接