GitNexus 深度解析：35K Star 的零服务端代码智能引擎——从知识图谱构建到 Graph RAG 的全链路技术实战

代码库越来越大，AI Agent 却越来越「瞎」——改一个函数忘了依赖方，重构一个模块断了调用链。GitNexus 用 12 阶段 DAG 流水线 + LadybugDB 图数据库 + Graph RAG，把整个代码库变成一张可查询的知识图谱，让 AI Agent 真正「看见」你的代码。

一、背景：为什么代码理解需要知识图谱？

现代代码库的复杂度早已超越了人类直觉能驾驭的范围。一个中型的微服务项目，动辄数百个模块、数千个文件、数万个符号，它们之间的依赖关系、调用链路、继承层次交织成一张密不透风的网。

传统的代码理解工具有两个致命问题：

1. 索引是扁平的：无论是 IDE 的符号索引还是 grep/ripgrep，本质上都是「符号 → 位置」的映射。你能找到函数定义在哪，但不知道谁调用了它、它依赖了谁、修改它会波及哪些模块。
2. AI Agent 是盲的：当前的 AI 编程助手（Cursor、Copilot、Claude Code）主要依赖两样东西——文件内容检索和上下文窗口。它们「看」代码的方式本质上是线性阅读，缺乏对代码结构的整体认知。改一个函数签名，它可能忘了还有 17 个调用方；删一个中间件，它可能没发现整条请求链路断了。

知识图谱（Knowledge Graph）天然适合解决这个问题。它把代码中的每一个符号、文件、模块建模为节点（Node），把依赖、调用、继承等关系建模为边（Edge），形成一张有向图。在这张图上，你可以：

• 做影响分析（Blast Radius）：修改函数 A，沿调用链向上游/下游遍历，找出所有受影响的模块
• 做代码导航：不只是跳转定义，而是理解「这个函数在整个系统中的角色」——它被谁调用？它调用了谁？它参与了哪些业务流程？
• 做语义搜索：不是文本匹配，而是基于图结构的 RAG（Retrieval-Augmented Generation），让 AI Agent 在检索时就能理解代码的上下文关系

GitNexus 正是这样一个工具。它的核心能力可以浓缩为一句话：把任何代码库索引成知识图谱，然后通过 MCP（Model Context Protocol）把这个图谱暴露给 AI Agent，让 Agent 从「瞎子摸象」变成「拿着地图找路」。

二、GitNexus 是什么？核心定位

GitNexus 是一个 零服务端代码智能引擎（Zero-Server Code Intelligence Engine）。关键在「零服务端」——整个索引和查询过程都可以在浏览器里完成，不需要部署任何后端服务。

它的两个核心使用模式：

两种模式通过 gitnexus serve 桥接——Web UI 自动检测本地服务，直接浏览 CLI 索引过的仓库，无需重复上传或重建索引。

2.1 CLI + MCP：让 AI Agent 真正理解你的代码

MCP（Model Context Protocol）是 Anthropic 提出的标准协议，让 AI Agent 能调用外部工具获取上下文。GitNexus 通过 MCP 暴露了 16 个工具，覆盖了从搜索到影响分析到跨仓库追踪的全链路能力：

# 一键索引当前仓库
npx gitnexus analyze

# 配置 MCP（一次性）
gitnexus setup

执行 analyze 后，GitNexus 会：

1. 索引整个代码库，构建知识图谱
2. 自动安装 Agent Skills（技能文件）
3. 注册 Claude Code Hooks
4. 创建 AGENTS.md / CLAUDE.md 上下文文件

你的 AI 编辑器从此就能调用这些工具：

• query：混合搜索（BM25 + 向量 + RRF 融合排序）
• context：360° 符号视图——谁调用了我、我调用了谁、我参与了哪些流程
• impact：修改影响分析，带深度分组和置信度
• detect_changes：Git Diff 影响映射——哪些符号和流程受影响
• rename：图辅助的多文件协同重命名
• cypher：直接写 Cypher 查询语句探查图谱

2.2 Web UI：浏览器里的代码探索器

不需要安装任何东西，打开 gitnexus.vercel.app，拖入一个 GitHub 仓库或 ZIP 文件，就能获得：

• 交互式知识图谱：可视化代码的依赖关系、调用链路、功能聚类
• AI 对话：基于 Graph RAG 的代码问答，不只是文本检索，而是理解代码结构后的深度回答
• 集群视图：自动识别代码的功能模块边界（基于 Leiden 社区发现算法）

受浏览器内存限制，Web UI 模式适合约 5000 文件以内的仓库。更大的项目建议用 CLI 模式。

三、架构深度拆解：12 阶段 DAG 流水线

GitNexus 的核心是一个 12 阶段的有向无环图（DAG）流水线，从源代码扫描到知识图谱构建，每个阶段有明确的依赖关系和类型安全的输入输出。

3.1 整体流程

scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
  → crossFile → mro → communities → processes

用更直观的方式理解：

┌─────────┐    ┌────────────┐    ┌──────────┐    ┌─────────┐
│  scan   │───▶│ structure  │───▶│ markdown │───▶│  parse  │
│(文件扫描)│    │(目录结构)   │    │(MD解析)  │    │(符号提取)│
└─────────┘    └────────────┘    └──────────┘    └────┬────┘
                                                      │
                                    ┌─────────────────┼─────────────────┐
                                    ▼                 ▼                 ▼
                              ┌──────────┐    ┌──────────┐    ┌──────────┐
                              │  routes  │    │  tools   │    │   orm    │
                              │(路由提取) │    │(工具提取) │    │(ORM提取) │
                              └─────┬────┘    └─────┬────┘    └─────┬────┘
                                    │               │               │
                                    └───────────────┼───────────────┘
                                                    ▼
                                              ┌──────────┐
                                              │crossFile │
                                              │(跨文件分析)│
                                              └─────┬────┘
                                                    ▼
                                              ┌──────────┐
                                              │   mro    │
                                              │(方法解析) │
                                              └─────┬────┘
                                                    ▼
                                              ┌──────────┐
                                              │communities│
                                              │(社区发现) │
                                              └─────┬────┘
                                                    ▼
                                              ┌──────────┐
                                              │processes │
                                              │(流程追踪) │
                                              └──────────┘

3.2 各阶段详解

Phase 1: scan（文件扫描）

输入：仓库路径
输出：文件路径列表 + 文件大小

扫描仓库中的所有文件，过滤掉 .git、node_modules、build 等无关目录。这是最轻量的阶段，但它的输出决定了后续所有阶段的处理范围。

// 伪代码示意
interface ScanOutput {
  filePaths: string[];    // 所有待处理文件的路径
  fileSizes: Map<string, number>;  // 文件大小，用于后续分批处理
}

Phase 2: structure（目录结构）

依赖：scan
输出：文件/文件夹节点，CONTAINS 边，全局路径集合

这一阶段把文件系统结构建模为图。每个文件夹和文件都是节点，文件夹「包含」文件的边就是 CONTAINS 边。

interface StructureOutput {
  allPathSet: Set<string>;        // 全局路径集合，后续阶段快速判断文件是否存在
  folderNodes: FolderNode[];      // 文件夹节点
  fileNodes: FileNode[];          // 文件节点
  containsEdges: ContainsEdge[];  // CONTAINS 边
}

Phase 3: markdown / cobol（特殊格式处理）

依赖：structure
输出：Markdown 章节节点 + 交叉链接边 / COBOL 程序结构

这两个阶段是并行分支，处理两种特殊文件格式：

• markdown：解析 .md/.mdx 文件，提取章节标题作为节点，识别 Markdown 内的交叉链接（如 [链接](./other.md)）作为边
• cobol：对 COBOL 源码用正则提取程序/段落/节（不依赖 tree-sitter，因为 COBOL 的 tree-sitter 支持有限）

// Markdown 阶段输出
interface MarkdownOutput {
  sectionNodes: SectionNode[];       // 章节节点
  crossLinkEdges: CrossLinkEdge[];   // 交叉引用边
}

Phase 4: parse（符号提取）—— 最核心的阶段

依赖：structure, markdown, cobol
输出：符号节点，IMPORTS/CALLS/EXTENDS 边，提取的路由/工具/ORM 查询

这是整个流水线最重的阶段。它使用 tree-sitter 解析源代码的 AST（抽象语法树），提取：

1. 符号节点：函数、类、方法、变量、类型定义等
2. IMPORTS 边：模块间的导入关系
3. CALLS 边：函数调用关系（6 阶段调用解析 DAG 的输出）
4. EXTENDS 边：类继承和接口实现关系

interface ParseOutput {
  symbolNodes: SymbolNode[];
  importEdges: ImportEdge[];
  callEdges: CallEdge[];
  extendsEdges: ExtendsEdge[];
  // 还包含提取的路由、工具定义、ORM 查询
  extractedRoutes: RouteInfo[];
  extractedTools: ToolInfo[];
  extractedOrmQueries: OrmQueryInfo[];
  // 所有解析的路径集合
  allPaths: Set<string>;
}

tree-sitter 的选择非常巧妙——它是增量式的、支持 40+ 语言、编译为 WASM 可以在浏览器中运行。GitNexus 在 CLI 模式下使用原生绑定（更快），在 Web UI 模式下使用 WASM 版本。

Phase 5-7: routes / tools / orm（领域特定提取）

这三个阶段依赖 parse 的输出，分别提取三种领域特定信息：

• routes：从 Next.js、Express、Expo、PHP 路由等提取路由定义，创建 Route 节点和 HANDLES_ROUTE 边
• tools：提取 MCP/RPC 工具定义，创建 Tool 节点和 HANDLES_TOOL 边
• orm：从 Prisma、Supabase 等 ORM 定义中提取数据库查询，创建 QUERIES 边

// 路由提取示例 - Next.js App Router
// 文件: app/api/users/route.ts
// 提取结果:
{
  route: "/api/users",
  method: "GET",
  handler: "getUsersHandler",
  file: "app/api/users/route.ts"
}

Phase 8: crossFile（跨文件类型传播）

依赖：parse, routes, tools, orm
输出：跨文件的类型传播结果

这个阶段解决一个关键问题：类型信息需要跨文件传播。

比如，utils.ts 定义了 type User = { id: number; name: string }，api.ts 导入了 User 并用它定义了函数参数。在 parse 阶段，每个文件只知道自己文件内的类型信息；crossFile 阶段按照拓扑排序遍历导入图，把类型定义传播到使用它的文件中。

// 跨文件类型传播示意
// utils.ts
export interface User {
  id: number;
  name: string;
  email: string;
}

// api.ts
import { User } from './utils';
export async function getUser(id: number): Promise<User> {
  // crossFile 阶段会知道这里的 User 来自 utils.ts
  // 并在图谱中建立跨文件的类型引用关系
}

传播过程按照导入图的拓扑序进行，确保被依赖的模块先被处理。

Phase 9: mro（方法解析顺序）

依赖：crossFile, structure
输出：METHOD_OVERRIDES + METHOD_IMPLEMENTS 边

MRO（Method Resolution Order）是面向对象语言中确定方法查找顺序的算法。GitNexus 支持 4 种 MRO 策略：

• first-wins：第一个匹配的方法胜出（类似 JavaScript 原型链）
• c3：Python 的 C3 线性化算法
• ruby-mixin：Ruby 的 mixin 继承规则
• none：无继承关系的语言

// MRO 解析示意
class Animal {
  speak() { return "generic"; }
}

class Dog extends Animal {
  speak() { return "woof"; }  // 覆盖父类方法
}

// MRO 阶段会产生:
// Dog.speak -[METHOD_OVERRIDES]-> Animal.speak
// Dog -[METHOD_IMPLEMENTS]-> Animal (通过 speak 方法)

这一步对影响分析至关重要——当你修改 Animal.speak() 时，需要知道 Dog.speak() 覆盖了它，影响可能不会传播到 Dog 的调用方。

Phase 10: communities（社区发现）

依赖：mro, structure
输出：社区节点 + MEMBER_OF 边

这一步使用 Leiden 算法 对知识图谱进行社区发现，自动识别代码的功能模块边界。

Leiden 算法是 Louvain 社区发现算法的改进版，能保证发现的社区是「良连接的」（well-connected），避免了 Louvain 可能产生的内部断裂社区。

// 社区发现结果示意
{
  clusters: [
    {
      name: "用户认证模块",
      members: ["auth/login.ts", "auth/register.ts", "auth/middleware.ts"],
      cohesionScore: 0.92  // 内聚度评分
    },
    {
      name: "数据访问层",
      members: ["db/connection.ts", "db/migrations.ts", "db/seed.ts"],
      cohesionScore: 0.87
    }
  ]
}

每个社区有一个内聚度评分（cohesion score），表示社区内部连接的紧密程度。评分越高，说明这个模块的边界越清晰。

Phase 11: processes（流程追踪）

依赖：communities, routes, tools, structure
输出：流程节点 + STEP_IN_PROCESS 边

这是流水线的最后一公里。它从路由入口（如 API 端点）出发，沿调用链追踪整个请求的处理流程，创建 Process 节点和 STEP_IN_PROCESS 边。

// 流程追踪结果示意
// 请求: POST /api/users
{
  processName: "POST /api/users",
  steps: [
    { step: 1, symbol: "validateUserInput", file: "api/users.ts" },
    { step: 2, symbol: "hashPassword", file: "auth/password.ts" },
    { step: 3, symbol: "createUser", file: "db/users.ts" },
    { step: 4, symbol: "sendWelcomeEmail", file: "email/welcome.ts" },
    { step: 5, symbol: "returnUserResponse", file: "api/users.ts" }
  ]
}

有了流程信息，当你修改 hashPassword 函数时，AI Agent 能立刻告诉你：这个函数参与了「用户注册」流程，位于第 2 步，修改它可能影响整个注册链路。

3.3 DAG Runner：类型安全的阶段调度

GitNexus 的 DAG Runner 有几个精巧的设计：

1. 编译时类型安全

每个阶段声明自己的依赖和输出类型，Runner 在编译时就能检查依赖是否满足：

const myPhase: PipelinePhase<MyPhaseOutput> = {
  name: 'myPhase',
  deps: ['parse'],  // 声明依赖 parse 阶段
  async execute(ctx, deps) {
    // 类型安全地获取 parse 阶段的输出
    const { allPaths } = getPhaseOutput<ParseOutput>(deps, 'parse');
    return { /* MyPhaseOutput */ };
  },
};

2. 拓扑排序 + 环检测

使用 Kahn 算法进行拓扑排序，如果检测到循环依赖，会精确报告循环路径（如 A → B → C → A），而不是笼统地说「存在循环」。

3. 隔离的依赖注入

每个阶段只能访问自己声明的依赖，Runner 会过滤 deps 映射，防止隐式耦合：

// 即使 parse 的输出包含 routes 信息，
// 如果你没在 deps 里声明 'routes'，就访问不到

4. 统一的图累加器

所有阶段共享同一个 KnowledgeGraph 实例（通过 PipelineContext），每个阶段往里面添加节点和边。这是经典的累加器模式——避免了阶段间复杂数据传递，同时保证了图的完整性。

四、调用解析 DAG：6 阶段调用链路重建

在 parse 阶段内部，还有一个嵌套的 6 阶段 DAG，专门用于解析函数调用关系并生成 CALLS 边。这是代码理解中最难的部分之一。

extract-call → classify-form → infer-receiver → select-dispatch → resolve-target → emit-edge
     (1)           (2)            (3) [hook]       (4) [hook]        (5)            (6)

4.1 六阶段详解

4.2 语言 Hook 机制：为什么需要它？

不同语言的方法分派规则差异巨大。以 Ruby 为例：

class UserService
  def initialize(user)
    @user = user
  end
  
  # 隐式 self 调用
  def process
    validate  # 等价于 self.validate，但 self 是隐式的
    save
  end
  
  def self.bulk_process(users)
    # 类方法，self 是类本身
    users.each { |u| new(u).process }  # new 是隐式的类方法调用
  end
end

Ruby 的隐式 self 调用在 AST 层面没有接收者，但语义上它调用的 validate 和 save 应该在 UserService 的实例方法 MRO 中查找。GitNexus 通过两个 Hook 解决这个问题：

inferImplicitReceiver Hook：当检测到裸标识符调用（如 validate）时，查找外层类上下文，将其重写为 self.validate，并标记 receiverSource: 'implicit-self'。

selectDispatch Hook：根据 receiverSource 和 hint，决定分派策略。对于隐式 self 调用：

• primary: 'owner-scoped'：在当前类的方法解析链中查找
• fallback: 'free-arity-narrowed'：如果当前类没找到，按参数数量在自由函数中搜索
• ancestryView: 'instance' 或 'singleton'：决定走实例继承链还是类继承链

4.3 Scope Resolution：新一代调用解析

GitNexus 正在从传统的 6 阶段 DAG 迁移到基于 作用域索引注册表（Scope-Indexed Registry）的新方案。新方案的核心思路是：

不再沿继承链逐级查找，而是在索引阶段就建好「符号名 → 作用域 → 定义」的注册表，调用解析直接查注册表。

目前 Python 和 C# 已经迁移到新方案，两种方案在 CI 中同时运行（ci-scope-parity.yml），确保迁移不引入回归。

关键设计：同图保证——新方案和旧方案生成的 CALLS 边在图中是不可区分的，下游工具不需要做任何适配。

五、图数据库：LadybugDB 的选择

GitNexus 选择了 LadybugDB 作为图数据库，而不是更流行的 Neo4j。原因有几个：

1. 嵌入式部署：LadybugDB 是嵌入式图数据库，不需要独立的服务进程，CLI 模式下数据持久化在 .gitnexus/ 目录，Web UI 模式下通过 WASM 在浏览器中运行
2. Cypher 支持：支持 Cypher 查询语言，用户可以直接写图查询
3. 零配置：不需要安装、不需要配置文件、不需要端口

# 直接写 Cypher 查询探查图谱
gitnexus cypher "MATCH (f:Function)-[:CALLS]->(g:Function) 
                  WHERE f.name = 'createUser' 
                  RETURN g.name, g.file"

5.1 图 Schema 设计

GitNexus 的图 Schema 包含以下核心节点和边类型：

节点类型：

• File：源文件
• Folder：目录
• Function：函数/方法
• Class：类/接口/类型
• Variable：变量/常量
• Route：API 路由端点
• Tool：MCP/RPC 工具
• Community：功能集群
• Process：业务流程
• Section：Markdown 章节

边类型：

• CONTAINS：文件/文件夹包含关系
• IMPORTS：模块导入
• CALLS：函数调用（带置信度评分）
• EXTENDS：类继承
• IMPLEMENTS：接口实现
• METHOD_OVERRIDES：方法覆盖
• HANDLES_ROUTE：函数处理路由
• QUERIES：ORM 数据库查询
• MEMBER_OF：符号属于社区
• STEP_IN_PROCESS：流程步骤

// CALLS 边带置信度
interface CallEdge {
  from: string;        // 调用方符号 ID
  to: string;          // 被调用方符号 ID
  confidence: 'high' | 'medium' | 'low';  // 解析置信度
  callForm: 'free' | 'member' | 'constructor';
}

六、混合搜索：BM25 + 向量 + RRF 融合

GitNexus 的 query 工具不是简单的全文搜索，而是 三路混合检索 + Reciprocal Rank Fusion（RRF）融合排序。

6.1 三路检索

1. BM25：经典的概率检索模型，基于词频和逆文档频率，擅长精确关键词匹配
2. 向量检索：基于 Embedding 的语义搜索，能理解「用户认证」和「登录验证」是语义相近的
3. 图结构检索：基于知识图谱的结构化查询，能找到「与目标符号在同一个流程中」的相关代码

6.2 RRF 融合排序

三种检索方式各自返回排序列表后，用 RRF 算法融合：

RRF_score(d) = Σ (1 / (k + rank_i(d)))

其中 k 是平滑常数（通常取 60），rank_i(d) 是文档 d 在第 i 个排序列表中的排名。

RRF 的优势是不需要归一化分数——BM25 和向量相似度的分数范围差异很大，直接加权融合效果不稳定，而 RRF 只依赖排名，天然归一化。

// RRF 融合示意
const bm25Results = [
  { id: 'auth.ts:login', rank: 1 },
  { id: 'auth.ts:validate', rank: 2 },
  { id: 'user.ts:create', rank: 3 },
];

const vectorResults = [
  { id: 'user.ts:create', rank: 1 },
  { id: 'auth.ts:login', rank: 2 },
  { id: 'session.ts:check', rank: 3 },
];

const graphResults = [
  { id: 'session.ts:check', rank: 1 },
  { id: 'auth.ts:login', rank: 2 },
  { id: 'middleware.ts:auth', rank: 3 },
];

// RRF 融合 (k=60)
// auth.ts:login → 1/(60+1) + 1/(60+2) + 1/(60+2) = 0.0492
// user.ts:create → 1/(60+3) + 1/(60+1) = 0.0328
// session.ts:check → 1/(60+3) + 1/(60+1) = 0.0328
// → auth.ts:login 排第一

6.3 进程分组

搜索结果不是扁平的列表，而是按进程（Process）分组的。这意味着当你搜索「用户认证」时，结果会按照业务流程组织：

🔍 用户认证

📋 POST /api/login（登录流程）
  ├── validateCredentials  [auth.ts:23]
  ├── verifyPassword       [auth.ts:45]
  ├── generateToken        [jwt.ts:12]
  └── setSessionCookie     [session.ts:8]

📋 POST /api/register（注册流程）
  ├── validateUserInput    [validation.ts:15]
  ├── hashPassword         [crypto.ts:30]
  ├── createUser           [db/users.ts:22]
  └── sendWelcomeEmail     [email/welcome.ts:5]

这种组织方式让搜索结果不只是「找到了」，而是让你理解代码在业务流程中的位置。

七、影响分析：Blast Radius 的数学

影响分析是 GitNexus 最强大的工具之一。当你修改一个符号时，impact 工具会沿图谱的边进行双向遍历：

• 下游影响（Downstream）：沿 CALLS 边向下，找到所有直接和间接调用方
• 上游依赖（Upstream）：沿 IMPORTS/EXTENDS 边向上，找到所有依赖项

7.1 深度分组

影响不是扁平的——修改的影响随传播深度衰减。GitNexus 用深度分组（Depth Grouping）来量化：

interface ImpactResult {
  symbol: string;
  downstream: {
    depth1: SymbolRef[];  // 直接调用方
    depth2: SymbolRef[];  // 间接调用方（经过 1 层中间调用）
    depth3: SymbolRef[];  // 更远的影响
  };
  upstream: {
    depth1: SymbolRef[];  // 直接依赖
    depth2: SymbolRef[];  // 间接依赖
  };
  riskSummary: 'low' | 'medium' | 'high';
}

7.2 置信度

CALLS 边的置信度影响最终的风险评估：

• high：静态分析确定的调用关系
• medium：通过类型推断但不确定的调用
• low：通过启发式推断的调用（如动态分派）

// 影响分析实战
// 你修改了 db/users.ts:findUserById

gitnexus impact --symbol findUserById

// 输出:
// ⚠️ 下游影响（Medium Risk）
//   Depth 1: getUserProfile, updateUserSettings, deleteUser
//   Depth 2: profilePage, settingsPage, adminPanel
//   Depth 3: userDashboard (low confidence)
//
// 📋 涉及流程:
//   GET /api/users/:id → getUserProfile → findUserById
//   PUT /api/users/:id/settings → updateUserSettings → findUserById
//   DELETE /api/users/:id → deleteUser → findUserById

八、跨仓库分析：Group + Contract Bridge

现代项目通常是多仓库（Multi-repo）架构。GitNexus 通过 Repository Group + Contract Bridge 机制支持跨仓库的代码理解。

8.1 创建仓库组

# 创建一个仓库组
gitnexus group create my-platform

# 添加仓库到组（支持层级路径）
gitnexus group add my-platform auth/api auth-service
gitnexus group add my-platform user/api user-service
gitnexus group add my-platform frontend/web web-app

# 同步跨仓库的契约（Contract）
gitnexus group sync my-platform

8.2 Contract Bridge

group sync 会提取每个仓库对外暴露的 契约（API 接口、事件定义、共享类型），然后在仓库之间建立 Contract Bridge——一张跨仓库的关联图。

// Contract Bridge 示例
// auth-service 暴露了 POST /api/auth/verify
// web-app 和 user-service 都调用了这个端点
// Contract Bridge 会建立:
// web-app:api.ts -[CONSUMES]-> auth-service:POST /api/auth/verify
// user-service:middleware.ts -[CONSUMES]-> auth-service:POST /api/auth/verify

// 跨仓库影响分析
// 如果 auth-service 修改了 /api/auth/verify 的返回格式:
gitnexus impact --symbol "auth-service:verifyToken" --repo "@my-platform"

// 输出:
// 🌐 跨仓库影响
//   auth-service (提供方): verifyToken 函数签名变更
//   ├── web-app (消费方): api.ts:checkAuth - 需要适配新返回格式
//   └── user-service (消费方): middleware.ts:authGuard - 需要适配新返回格式

8.3 跨仓库搜索

# 跨仓库执行流搜索
gitnexus group query my-platform "user login flow"

# 查看契约列表
gitnexus group contracts my-platform

# 检查仓库组的索引状态
gitnexus group status my-platform

跨仓库搜索使用与单仓库相同的 RRF 融合排序，但会合并所有仓库的搜索结果，最终按统一排名输出。

九、实战：从零搭建 GitNexus 工作流

9.1 安装和初始化

# 全局安装（推荐）
npm install -g gitnexus

# 或者用 npx（无需安装）
npx gitnexus --help

9.2 索引一个真实项目

以一个 Next.js + Prisma 项目为例：

cd my-nextjs-project

# 一键索引
npx gitnexus analyze

# 输出类似:
# 🔍 Scanning repository...
# 📁 Found 342 files across 28 directories
# 🏗️ Building structure graph...
# 📝 Processing 15 markdown files...
# 🔧 Parsing source files (TypeScript, JavaScript, CSS)...
# 🛤️ Extracted 23 routes, 5 MCP tools, 12 ORM queries
# 🔗 Cross-file type propagation complete
# 🧬 MRO analysis: 8 class hierarchies resolved
# 🏘️ Community detection: 5 clusters identified
# 🔄 Process tracing: 18 execution flows mapped
# ✅ Knowledge graph built: 2,847 nodes, 6,231 edges
# 💾 Stored in .gitnexus/

9.3 配置 MCP 给 Cursor

# 自动配置（推荐）
gitnexus setup

# 手动配置 ~/.cursor/mcp.json

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

9.4 在 Cursor 中使用

配置完成后，Cursor 的 AI 助手就能调用 GitNexus 的工具了。一些实用场景：

场景 1：理解不熟悉的代码库

你：帮我理解这个项目的认证模块是怎么工作的

Cursor（调用 GitNexus）：
→ 调用 query("authentication")
→ 调用 context("AuthService")
→ 返回：认证模块位于 src/auth/，包含 3 个核心类：
  - AuthService：主服务类，处理登录/注册/验证
  - TokenManager：JWT token 生成和验证
  - SessionStore：会话存储（Redis 后端）
  参与的流程：POST /api/login、POST /api/register、GET /api/me
  外部依赖：Redis（会话存储）、bcrypt（密码哈希）

场景 2：重构前的安全检查

你：我想把 findUserById 的返回值从 User 改成 User | null

Cursor（调用 GitNexus）：
→ 调用 impact("findUserById")
→ 调用 detect_changes（模拟修改）
→ 返回：⚠️ 影响范围分析：
  Depth 1（直接调用方，6个）：
  - getUserProfile：已处理 null 情况 ✅
  - updateUserSettings：未处理 null ❌ 需要添加空检查
  - deleteUser：未处理 null ❌
  - ...
  Depth 2（间接影响，3个）：
  - profilePage：依赖 getUserProfile 的返回值
  - settingsPage：依赖 updateUserSettings 的返回值
  涉及流程：3 个 API 端点可能受影响
  建议：先修改 Depth 1 的 6 个调用方，再修改 Depth 2

场景 3：跨仓库变更追踪

你：auth-service 修改了 /api/auth/verify 的返回格式，需要适配吗？

Cursor（调用 GitNexus）：
→ 调用 group_impact("@my-platform", "auth-service:verifyToken")
→ 返回：🔍 跨仓库影响：
  auth-service (v2.3.1→v2.4.0):
  - POST /api/auth/verify 返回值从 {valid: boolean} 改为 {valid: boolean, expiresAt: string}
  你的仓库受影响的位置：
  1. src/middleware/auth.ts:checkAuth() - 使用了 response.valid，需要处理 expiresAt
  2. src/hooks/useAuth.ts - 需要更新类型定义

9.5 生成代码 Wiki

# 基于知识图谱自动生成代码文档
gitnexus wiki

# 使用自定义模型
gitnexus wiki --model gpt-4o-mini

# 使用自定义 API
gitnexus wiki --base-url https://api.my-llm.com/v1

生成的 Wiki 不是简单的文件列表，而是基于知识图谱的结构化文档——每个模块有清晰的职责描述，模块间的关系有明确的说明。

9.6 性能优化实践

对于大型仓库，索引可能比较慢。一些优化技巧：

# 跳过 Embedding 生成（快 2-3 倍，但语义搜索质量下降）
gitnexus analyze --skip-embeddings

# 保留自定义的 AGENTS.md 编辑
gitnexus analyze --skip-agents-md

# 索引非 Git 目录
gitnexus analyze --skip-git

# 增加解析超时（大型/特殊文件）
gitnexus analyze --worker-timeout 120

# 强制全量重建（增量索引出问题时）
gitnexus analyze --force

# 只重新生成 Embedding（索引已有但 Embedding 缺失时）
gitnexus analyze --embeddings

十、Graph RAG：让 AI 理解代码结构

GitNexus 的 Graph RAG 是区别于传统 RAG 的关键创新。传统 RAG 的检索是「向量相似度 → 文本片段」的线性流程，而 Graph RAG 的检索是「图遍历 + 向量检索 + 结构化查询」的三维流程。

10.1 传统 RAG 的问题

用户问：修改 hashPassword 函数会影响什么？

传统 RAG:
1. Embedding 查询 → 找到 hashPassword 的代码片段
2. 返回代码片段给 LLM
3. LLM 基于片段猜测影响范围

问题：
- 只能找到「文本相似」的代码，找不到「结构相关」的代码
- 不知道 hashPassword 被谁调用、参与了哪些流程
- 无法区分「直接调用」和「间接影响」

10.2 Graph RAG 的工作方式

用户问：修改 hashPassword 函数会影响什么？

Graph RAG:
1. 在图谱中定位 hashPassword 节点
2. 沿 CALLS 边向上游遍历 → 找到所有调用方
3. 沿 STEP_IN_PROCESS 边遍历 → 找到参与的流程
4. 结合 BM25 搜索 → 找到代码注释中提到 password 的地方
5. 向量搜索 → 找到语义相关的安全处理代码
6. RRF 融合排序 → 按相关性排列所有结果
7. 返回结构化的影响报告给 LLM

结果：
- 精确的影响范围（基于图遍历，不是猜测）
- 业务流程上下文（不只是代码片段）
- 置信度分级（high/medium/low）

10.3 Resource 机制：零查询的即时上下文

除了工具调用，GitNexus 还通过 MCP Resource 提供即时上下文，Agent 不需要主动查询就能获得：

这些 Resource 会在 Agent 启动时自动加载，相当于给 AI 一个「代码库地图」的概览，后续的工具调用基于这个概览进行精确查询。

十一、与竞品的对比

GitNexus 的差异化优势在于：

1. 图谱深度：不只是符号索引，而是完整的关系图（调用链、继承链、流程图、社区结构）
2. AI 原生：从第一天就为 MCP 设计，16 个工具覆盖了 AI Agent 需要的所有上下文
3. 零服务端：不需要部署任何后端，浏览器和本地 CLI 都能完整运行
4. 跨仓库：Group + Contract Bridge 是目前同类工具中最成熟的跨仓库解决方案

十二、性能考量与最佳实践

12.1 索引性能

GitNexus 的索引是增量式的——它会检查 lastCommit 和 HEAD 的差异，只重新索引变更的文件。完整的索引性能参考：

12.2 Staleness 检测

GitNexus 会自动检测索引是否过期。每次 MCP 工具调用时，如果检测到索引落后于当前 commit，会返回一个 staleness 提示：

// Claude Code 的 PostToolUse Hook 会在每次提交后检测：
// 如果索引过期，提示 Agent 重新索引
{
  staleness: {
    indexedCommit: "abc123",
    currentCommit: "def456",
    behindBy: 3,  // 落后 3 个 commit
    suggestion: "Run `gitnexus analyze` to update the index"
  }
}

12.3 Embedding 策略

GitNexus 支持两种 Embedding 模式：

• 无 Embedding（--skip-embeddings）：只使用 BM25 + 图结构搜索，速度快但语义搜索弱
• 有 Embedding（--embeddings）：额外生成向量 Embedding，支持语义搜索，但索引时间增加 2-3 倍

对于日常开发，建议先不带 Embedding 索引（快速迭代），等项目稳定后再生成 Embedding（深度搜索）。

十三、源码导读：如何扩展 GitNexus

13.1 添加新语言支持

GitNexus 的语言支持基于 tree-sitter，添加新语言需要：

1. 在 gitnexus-shared/src/languages.ts 中注册语言

export const SUPPORTED_LANGUAGES = {
  // ...existing languages
  'zig': {
    extensions: ['.zig'],
    treeSitterWasm: 'tree-sitter-zig.wasm',
    parserConfig: { /* ... */ },
  },
};

2. 在 src/core/ingestion/languages/ 创建语言处理器

// languages/zig.ts
import type { LanguageProvider } from '../language-provider.js';

export const zigProvider: LanguageProvider = {
  language: 'zig',
  
  // 可选：隐式接收者推断
  inferImplicitReceiver: ({ calledName, callForm, callNode, filePath }) => {
    // Zig 没有隐式 self，返回 null
    return null;
  },
  
  // 可选：自定义分派策略
  selectDispatch: ({ calledName, callForm, receiverTypeName }) => {
    // Zig 没有继承，使用默认策略
    return null;
  },
  
  // MRO 策略
  mroStrategy: 'none',
};

3. 添加 tree-sitter 查询规则（tree-sitter-queries.ts）

export const ZIG_QUERIES = {
  functionDefinition: `(function_declaration name: (identifier) @name)`,
  structDefinition: `(struct_declaration name: (identifier) @name)`,
  callExpression: `(call_expression function: (identifier) @name)`,
};

13.2 添加新的 Pipeline 阶段

// pipeline-phases/security-audit.ts
import type { PipelinePhase, PhaseResult } from './types.js';
import { getPhaseOutput } from './types.js';
import type { ParseOutput } from './parse.js';

export interface SecurityAuditOutput {
  vulnerabilities: VulnerabilityInfo[];
  riskEdges: RiskEdge[];
}

export const securityAudit: PipelinePhase<SecurityAuditOutput> = {
  name: 'securityAudit',
  deps: ['parse', 'routes'],  // 依赖 parse 和 routes 阶段
  async execute(ctx, deps) {
    const { symbolNodes, callEdges } = getPhaseOutput<ParseOutput>(deps, 'parse');
    const { routes } = getPhaseOutput<RoutesOutput>(deps, 'routes');
    
    // 检测安全风险模式
    const vulnerabilities = detectSecurityPatterns(symbolNodes, callEdges, routes);
    
    // 在图谱中添加风险标记
    for (const vuln of vulnerabilities) {
      ctx.graph.addNode('Vulnerability', {
        type: vuln.type,
        severity: vuln.severity,
        location: vuln.location,
      });
      ctx.graph.addEdge(vuln.symbolId, vuln.vulnId, 'HAS_VULNERABILITY');
    }
    
    return { vulnerabilities, riskEdges: [] };
  },
};

13.3 添加自定义 MCP 工具

// 在 src/mcp/tools.ts 中添加
{
  name: 'security_scan',
  description: 'Scan for security vulnerabilities in the codebase',
  inputSchema: {
    type: 'object',
    properties: {
      repo: { type: 'string', description: 'Repository name' },
      severity: { 
        type: 'string', 
        enum: ['critical', 'high', 'medium', 'low'],
        description: 'Minimum severity level'
      }
    }
  },
  handler: async ({ repo, severity }) => {
    const graph = await loadGraph(repo);
    const vulns = graph.query(
      'MATCH (v:Vulnerability) WHERE v.severity >= $min RETURN v',
      { min: severity }
    );
    return { content: [{ type: 'text', text: JSON.stringify(vulns) }] };
  }
}

十四、企业版与生态

GitNexus 提供 企业版（SaaS 或自部署），额外包含：

• PR Review：自动化的影响范围分析，在 Pull Request 中直接展示修改的爆炸半径
• Auto-updating Code Wiki：始终最新的代码文档，索引更新时自动同步
• Auto-reindexing：知识图谱自动跟随代码变更保持最新
• Multi-repo Support：统一图跨仓库查询（社区版也支持 Group，但企业版更完善）
• OCaml Support：额外的语言覆盖
• 优先支持：新语言/功能优先开发

社区生态

• pi-gitnexus：pi 的 GitNexus 插件（pi install npm:pi-gitnexus）
• gitnexus-stable-ops：稳定化运维部署工作流

十五、总结与展望

GitNexus 代表了代码智能的一个新范式：从文本检索到图谱理解。

传统工具让 AI 「读」代码——一段一段地看，像翻书一样。GitNexus 让 AI 「理解」代码——看整张关系网，像看地图一样。

核心价值：

1. 结构化理解：12 阶段 DAG 流水线把源代码变成结构化的知识图谱，每一条边都是可验证的关系
2. AI 原生设计：16 个 MCP 工具 + Resource + Prompt，让 AI Agent 不只是搜索，而是真正理解代码架构
3. 零服务端部署：浏览器和 CLI 都能完整运行，没有数据外泄的风险
4. 可扩展架构：清晰的语言 Hook 机制和 Pipeline 扩展点，添加新语言或新能力都很简单

适用场景：

• 🏗️ 大型项目开发：让 AI 编辑器理解项目架构，减少「改了这忘了那」的问题
• 🔍 代码审查：自动分析 PR 的影响范围，审查更高效
• 📚 项目交接：新人通过知识图谱快速理解项目结构
• 🤖 AI Agent 增强：给 Cursor/Claude Code/Codex 装上「代码透视眼」

局限与改进方向：

• 动态语言的调用解析置信度偏低（如 Python 的鸭子类型、JavaScript 的动态 import）
• Web UI 受浏览器内存限制，大项目必须用 CLI
• 社区版缺少自动重新索引，需要手动或通过 CI 触发
• 当前许可证为 PolyForm Noncommercial，商业使用需要企业版授权

随着 AI 编程助手越来越普及，「让 AI 真正理解代码」的需求只会越来越强烈。GitNexus 用知识图谱给出了一个优雅的答案——不是让 AI 读更多代码，而是让它看懂代码之间的连接。

# 开箱即用，一行命令开始
npx gitnexus analyze

项目地址：github.com/abhigyanpatwari/GitNexus
在线体验：gitnexus.vercel.app
Star 数：35K+（且在快速增长中）
许可证：PolyForm Noncommercial 1.0.0（非商业免费，商业需企业授权）