GitNexus 代码库知识图谱技术方案分析

• gitnexus analyze 在仓库内创建 .gitnexus/ 索引（可移植，gitignored）
• 在 ~/.gitnexus/registry.json 注册指针
• MCP 服务器读取注册表，按需懒加载 KuzuDB 连接（5 分钟不活动后回收，最多 5 个并发）

二、技术栈

2.1 核心技术选型

2.2 支持的语言

TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust（共 9 种）

三、架构设计

3.1 索引流水线（Indexing Pipeline）

GitNexus 通过多阶段流水线构建完整的知识图谱：

关键阶段说明：

1. 结构扫描（0-15%）：遍历文件系统，建立 File/Folder 节点
2. AST 解析（15-70%）：使用 Tree-sitter 并行解析，提取符号（Function, Class, Method, Interface）
3. 导入解析（70-75%）：语言感知的导入解析，建立 IMPORTS 关系
4. 调用解析（75-80%）：通过 Tree-sitter 查询匹配调用点，建立 CALLS 关系（带置信度）
5. 继承解析（80-85%）：提取 EXTENDS/IMPLEMENTS 关系
6. 社区检测（85-90%）：使用 Leiden 算法基于 CALLS 边进行功能聚类
7. 流程追踪（90-95%）：从入口点（调用他人但很少被调用的函数）追踪执行流程
8. 嵌入生成（95-98%）：使用 transformers.js 生成符号嵌入向量
9. 搜索索引（98-100%）：构建 BM25 索引和向量索引，支持混合搜索

3.2 知识图谱模式（Graph Schema）

节点类型：

• File, Folder - 文件系统结构
• Function, Class, Method, Interface - 代码符号
• Community - 功能集群
• Process - 执行流程

边类型（CodeRelation.type）：

• CALLS - 函数调用（带置信度）
• IMPORTS - 导入依赖
• EXTENDS - 类继承
• IMPLEMENTS - 接口实现
• DEFINES - 符号定义
• MEMBER_OF - 社区成员关系
• STEP_IN_PROCESS - 流程步骤关系

3.3 MCP 服务器架构

MCP 工具（7 个）：

1. list_repos - 发现所有已索引仓库
2. query - 流程分组的混合搜索（BM25 + 语义 + RRF）
3. context - 360 度符号视图（分类引用、流程参与）
4. impact - 爆炸半径分析（深度分组、置信度）
5. detect_changes - Git 差异影响分析
6. rename - 多文件协调重命名（图 + 文本搜索）
7. cypher - 原始 Cypher 图查询

MCP 资源：

• gitnexus://repos - 所有已索引仓库列表
• gitnexus://repo/{name}/context - 代码库统计、过期检查
• gitnexus://repo/{name}/clusters - 所有功能集群
• gitnexus://repo/{name}/processes - 所有执行流程
• gitnexus://repo/{name}/schema - 图模式

四、目录结构分析

4.1 核心目录

GitNexus-main/
├── gitnexus/ # CLI + MCP 核心包
│   ├── src/
│   │   ├── cli/ # CLI 命令实现
│   │   │   ├── analyze.ts # 索引命令
│   │   │   ├── mcp.ts # MCP 服务器启动
│   │   │   ├── setup.ts # MCP 配置
│   │   │   └── wiki.ts # Wiki 生成
│   │   ├── core/ # 核心引擎
│   │   │   ├── ingestion/ # 索引流水线
│   │   │   │   ├── pipeline.ts # 主流水线
│   │   │   │   ├── parsing-processor.ts # AST 解析
│   │   │   │   ├── import-processor.ts # 导入解析
│   │   │   │   ├── call-processor.ts # 调用解析
│   │   │   │   ├── heritage-processor.ts # 继承解析
│   │   │   │   ├── community-processor.ts # 社区检测
│   │   │   │   ├── process-processor.ts # 流程追踪
│   │   │   │   └── workers/ # 并行解析 Worker
│   │   │   ├── graph/ # 知识图谱数据结构
│   │   │   ├── kuzu/ # KuzuDB 适配器
│   │   │   ├── embeddings/ # 嵌入生成
│   │   │   └── search/ # 混合搜索
│   │   ├── mcp/ # MCP 服务器实现
│   │   │   ├── server.ts # MCP 服务器主逻辑
│   │   │   ├── tools.ts # 工具定义
│   │   │   ├── resources.ts # 资源定义
│   │   │   └── local/ # 本地后端实现
│   │   └── storage/ # 仓库管理
│   │       └── repo-manager.ts # 全局注册表管理
│   ├── hooks/ # 编辑器钩子
│   │   └── claude/ # Claude Code 集成
│   └── skills/ # AI 智能体技能
│       ├── exploring.md
│       ├── debugging.md
│       ├── impact-analysis.md
│       └── refactoring.md
├── gitnexus-web/ # Web UI 前端
│   ├── src/
│   │   ├── core/ # 共享核心逻辑（与 CLI 类似）
│   │   ├── components/ # React 组件
│   │   │   ├── GraphCanvas.tsx # Sigma.js 图可视化
│   │   │   ├── QueryFAB.tsx # 查询浮动按钮
│   │   │   └── ProcessesPanel.tsx # 流程面板
│   │   ├── workers/ # Web Workers
│   │   │   └── ingestion.worker.ts # 索引 Worker
│   │   └── services/ # 服务层
│   │       └── git-clone.ts # Git 克隆服务
│   └── public/wasm/ # WASM 文件（KuzuDB, Tree-sitter）
├── eval/ # 评估框架
├── agents/ # AI 智能体实现
├── bridge/ # MCP 桥接
└── configs/ # 评估配置
└── gitnexus-claude-plugin/ # Claude Code 插件
└── hooks/ # 会话钩子

4.2 关键文件说明

gitnexus/src/core/ingestion/pipeline.ts

作用：索引流水线主控制器
关键逻辑：

• 协调各处理阶段（结构 → 解析 → 导入 → 调用 → 继承 → 社区 → 流程）
• 管理 AST 缓存（避免重复解析）
• 进度回调（支持 CLI 进度条）
• Worker 池管理（并行解析）

gitnexus/src/mcp/local/local-backend.ts

作用：MCP 工具实现后端
关键逻辑：

• 多仓库管理（从注册表加载）
• KuzuDB 连接池（懒加载、超时回收）
• 工具实现（query, context, impact, rename 等）
• 资源读取（context, clusters, processes）

gitnexus/src/core/ingestion/community-processor.ts

作用：社区检测（功能聚类）
关键逻辑：

• 构建 Graphology 图（仅符号节点 + CALLS 边）
• 运行 Leiden 算法（分辨率 1.0）
• 生成社区节点和成员关系

gitnexus/src/core/ingestion/process-processor.ts

作用：执行流程追踪
关键逻辑：

• 查找入口点（调用他人但很少被调用的函数）
• 从入口点追踪调用链（深度限制、去重）
• 创建流程节点和步骤关系

五、部署与使用

5.1 CLI + MCP 部署

安装：

npm install -g gitnexus

快速开始：

# 在仓库根目录运行 npx gitnexus analyze

自动完成：

• 索引代码库
• 安装智能体技能到 .claude/skills/
• 注册 Claude Code 钩子
• 创建 AGENTS.md / CLAUDE.md 上下文文件

MCP 配置（自动）：

npx gitnexus setup

手动配置（Cursor）：
编辑 ~/.cursor/mcp.json：

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

5.2 Web UI 部署

在线使用：
访问 Web 端即可开始。

本地运行：

git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus/gitnexus-web
npm install && npm run dev

5.3 使用场景示例

场景 1：影响分析

AI 智能体调用：impact({target: "UserService", direction: "upstream"})
返回：
- Depth 1 (WILL BREAK): 8 个调用者，90%+ 置信度
- Depth 2 (LIKELY AFFECTED): 3 个导入者

场景 2：流程分组搜索

AI 智能体调用：query({query: "authentication middleware"})
返回：
- processes: LoginFlow (优先级 0.042, 7 步)
- process_symbols: validateUser (步骤 2/7)
- definitions: AuthConfig (接口)

场景 3：360 度上下文

AI 智能体调用：context({name: "validateUser"})
返回：
- symbol: Function:validateUser (src/auth/validate.ts:15)
- incoming: [handleLogin, handleRegister, UserController]
- outgoing: [checkPassword, createSession]
- processes: [LoginFlow (step 2/7), RegistrationFlow (step 3/5)]

六、总结

GitNexus 是一个工程化程度极高的代码库智能分析系统，其核心价值在于：

1. 预计算的关系智能：在索引时完成聚类、追踪、评分，而非查询时探索
2. 双模式架构：CLI + MCP 用于日常开发，Web UI 用于快速探索
3. 多仓库支持：全局注册表 + 懒加载连接池，一次配置全局使用
4. 完整的工具生态：7 个 MCP 工具 + 资源 + 提示词，覆盖代码理解全场景
5. 浏览器端完整实现：WASM 技术栈，零服务器、完全隐私

适用场景：

• AI 代码助手增强（Cursor, Claude Code, Windsurf）
• 代码库架构分析
• 影响范围评估（预提交检查）
• 代码重构规划
• 新成员代码库探索

技术亮点：

• Tree-sitter 多语言 AST 解析
• Leiden 算法代码聚类
• KuzuDB 图数据库（原生 + WASM）
• transformers.js 浏览器端嵌入
• MCP 协议标准化集成