GitNexus 核心引擎：架构、流程与优化实践

2.2 社区检测算法流程

社区检测用的是 Leiden 算法，这是一种改进的 Louvain 算法，能检测更高质量的社区结构。

算法关键点：

• 图构建：只包含符号节点（Function, Class, Method, Interface）和 CALLS/EXTENDS/IMPLEMENTS 边，忽略 File/Folder 节点。
• 分辨率参数：resolution=1.0 是默认值，控制社区大小。值越大，社区越小、越细粒度。
• 内聚度计算：采样社区成员（最多 50 个），计算内部边密度。内聚度 = 内部边数 / 总边数。

2.3 流程追踪算法流程

流程追踪从入口点开始，用 BFS 算法追踪调用链，生成执行流程。

入口点评分策略：

// 入口点分数 = 基础分数 × 导出加成 × 名称模式加成
const baseScore = callees.length / (callers.length + 1);
const exportBoost = isExported ? 1.5 : 1.0;
const namePatternBoost = matchesPattern(name) ? 1.3 : 1.0;
const score = baseScore * exportBoost * namePatternBoost;

追踪限制：

• maxTraceDepth=10：最大追踪深度
• maxBranching=4：每个节点最多追踪 4 个分支
• minSteps=3：最小流程步数（2 步只是'A 调用 B'，不算流程）

2.4 混合搜索流程

混合搜索结合 BM25 关键词搜索和语义向量搜索，使用 RRF（Reciprocal Rank Fusion）融合结果。

RRF 融合公式：

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

其中：

• K = 60（标准 RRF 常数）
• rank_i(d) 是文档 d 在第 i 个搜索结果中的排名
• 最终分数是各排名分数的总和

三、关键实现点说明

3.1 Worker 池并行解析优化

GitNexus 用 Worker 池实现并行 AST 解析，对大代码库的索引速度提升明显。

实现要点：

// 创建 Worker 池（自动检测 CPU 核心数）
const workerPool = createWorkerPool(workerUrl);

// 分发任务到 Worker 池
const chunkResults = await workerPool.dispatch<ParseWorkerInput, ParseWorkerResult>(
  parseableFiles,
  (filesProcessed) => {
    onFileProgress?.(filesProcessed, total, 'Parsing...');
  }
);

// 合并结果
for (const result of chunkResults) {
  // 合并节点、关系、符号表
  result.nodes.forEach(node => graph.addNode(node));
  result.relationships.forEach(rel => graph.addRelationship(rel));
  result.symbols.forEach(sym => symbolTable.add(sym.filePath, sym.name, sym.nodeId, sym.type));
}

优雅降级： 如果 Worker 池创建失败（比如单核 CPU），会自动降级为顺序处理，确保在任何环境下都能跑起来。

3.2 语言感知的导入解析

不同语言的导入机制差异很大，GitNexus 为每种语言都写了专门的解析逻辑。

• TypeScript/JavaScript：
  • 相对路径：./utils → 解析为相对于当前文件的路径
  • node_modules：lodash → 查找 node_modules/lodash
  • 路径别名：@/components → 解析 tsconfig.json 的 paths 配置
• Go：
  • 包路径：github.com/user/repo/pkg → 查找 $GOPATH/src/github.com/user/repo/pkg
  • 相对导入：./internal/utils → 相对于当前包的路径
• Python：
  • 相对导入：from .utils import func → 解析为包内相对路径
  • 绝对导入：from pkg.utils import func → 查找 sys.path

3.3 调用关系置信度计算

调用关系的置信度直接影响后续的流程追踪和影响分析。GitNexus 用了多因素评分：

// 1. 精确匹配（名称 + 参数数量）
if (calleeName === targetName && paramCount === expectedParams) {
  confidence = 0.95;
}
// 2. 名称匹配（仅名称）
else if (calleeName === targetName) {
  confidence = 0.70;
}
// 3. 模糊匹配（部分名称）
else if (calleeName.includes(targetName) || targetName.includes(calleeName)) {
  confidence = 0.50;
}
// 4. 全局匹配（未解析的标识符）
else {
  confidence = 0.30;
}

流程追踪过滤： 只用置信度 ≥ 0.5 的 CALLS 边进行流程追踪，避免模糊匹配导致的跨模块跳跃。

3.4 社区内聚度采样优化

对于大型社区（>50 个成员），完整计算内聚度的复杂度是 O(N²)。GitNexus 用了采样优化：

const SAMPLE_SIZE = 50;
const sample = memberIds.length <= SAMPLE_SIZE ? memberIds : memberIds.slice(0, SAMPLE_SIZE);

// 仅对采样成员计算边密度
for (const nodeId of sample) {
  graph.forEachNeighbor(nodeId, (neighbor) => {
    totalEdges++;
    if (memberSet.has(neighbor)) {
      internalEdges++;
    }
  });
}
const cohesion = internalEdges / totalEdges;

误差控制： 采样误差在可接受范围内（<5%），同时将计算复杂度从 O(N²) 降至 O(N)。

3.5 嵌入生成与设备选择

GitNexus 用 transformers.js 生成嵌入向量，支持多种设备后端。

设备优先级：

1. Windows：DirectML（DirectX12 GPU 加速）
2. Linux：CUDA（NVIDIA GPU 加速）
3. Fallback：CPU（兼容性最好）

实现策略：

const devicesToTry: Array<'dml' | 'cuda' | 'cpu' | 'wasm'> = 
  (requestedDevice === 'dml' || requestedDevice === 'cuda') 
    ? [requestedDevice, 'cpu'] // 尝试 GPU，失败则回退 CPU
    : [requestedDevice];

for (const device of devicesToTry) {
  try {
    embedderInstance = await pipeline('feature-extraction', modelId, {
      device: device,
      dtype: 'fp32',
    });
    currentDevice = device;
    break; // 成功则退出
  } catch (deviceError) {
    // 继续尝试下一个设备
  }
}

模型选择： 默认用 snowflake-arctic-embed-xs（22M 参数，384 维，~90MB），在质量和速度之间取得平衡。

四、总结

GitNexus 的核心引擎通过三个相互协作的子系统，实现了从代码库到知识图谱的完整转换：

1. 索引流水线：9 阶段流水线，从文件扫描到 KuzuDB 加载，每个阶段都有明确的职责和进度反馈。Worker 池并行解析和 AST 缓存优化显著提升了性能。
2. 社区与流程检测：Leiden 算法实现功能聚类，BFS 算法追踪执行流程。入口点评分、追踪限制和去重策略确保了流程质量。
3. 混合搜索与嵌入：BM25 + 语义搜索 + RRF 融合，支持多设备后端（DirectML/CUDA/CPU）。RRF 融合无需分数归一化，简单高效。

技术亮点：

• 并行优化：Worker 池并行解析，优雅降级保证兼容性
• 语言感知：9 种语言的专门解析逻辑，覆盖主流编程语言
• 置信度评分：多因素调用关系置信度，过滤低质量边
• 采样优化：社区内聚度采样，O(N²) → O(N) 复杂度优化
• 设备自适应：GPU 优先，CPU 回退，最大化性能

这些设计使得 GitNexus 能够在合理的时间内（通常几分钟）完成大型代码库的索引，并生成高质量的知识图谱，为后续的查询、分析和智能体集成奠定基础。