GitNexus

面向 AI Agent 的预计算架构知识图谱平台，除调用图外还提前计算功能社区、执行流程、API 路由与可选 PDG/污点分析。

#type / resource #status / evergreen #tech / ai #resource / gitnexus #purpose / development #media / tool #interface / ai #interface / cli

[!info] related notes

GitNexus

这是什么

GitNexus 是面向 AI Agent 的预计算架构知识图谱平台。它不只存函数和调用边，还提前计算功能社区（Leiden）、执行流程（Process）、API 路由、变更影响，甚至可以选择构建 PDG、控制依赖和污点传播图。

  • 版本与许可证：v1.6.9，PolyForm Noncommercial 1.0.0（非商业许可证，商业用途需注意）
  • 仓库：abhigyanpatwari/GitNexus

定位是“面向 AI Agent 的静态分析平台和代码架构数据库”——让图数据库在索引阶段先理解架构，而不是每次查询时临时推导。

工作方式 / 架构

15 阶段 DAG

GitNexus 的索引过程不是简单的“解析 → 入库”，而是一个包含 15 个阶段的 DAG：

scan → structure → markdown / cobol → parse → routes / tools / orm → crossFile
→ scopeResolution → pruneLocalSymbols → mro → di → communities → processes

大致分五层：

  1. 文件和目录结构
  2. 语法和符号提取
  3. 跨文件语义解析
  4. 架构和流程推断
  5. 检索、图查询和 Agent 工具

语义 scope resolution

GitNexus 不只是匹配函数名，还会处理：变量作用域、类成员归属、方法重载、返回类型传播、跨文件类型传播、继承和 MRO、接口实现、依赖注入、callable value、参数中传递的函数、属性分发、导入别名、框架路由。

例如：

const parser = factory.createParser();
parser.parse(url);

它会尽量通过 createParser() 的返回类型，推断 parser 的真实类型，然后把 当前函数 → Parser.parse 连接起来。其 scope-resolution 流水线依次处理：receiver-bound calls、free calls、references、property dispatch、callable-value flow、imports。

真正的属性图数据库 LadybugDB

GitNexus CLI 使用 LadybugDB（而不是普通 SQLite 表模拟图），采用多个节点表：

File, Folder, Function, Class, Interface, Method, Route, Tool, Community, Process, BasicBlock ...

所有关系统一放在 CodeRelation 中，通过 type 区分：

MATCH (f:Function)-[r:CodeRelation {type: 'CALLS'}]->(g:Function)
RETURN f, g

Function 节点直接保存文件路径、开始和结束行、源代码内容、描述。Community / Process / Route / Tool / BasicBlock 都直接建模为一等节点，因此可以直接用 Cypher 查询复杂关系。

预计算功能社区（Leiden）

GitNexus 使用 Leiden 社区发现算法，将图中联系紧密的符号分组：

下载任务社区 / Bilibili API 社区 / 媒体处理社区 / 配置社区 / CLI 社区

社区不是源代码中真实存在的模块，而是根据调用关系、文件关系、导入关系、图连接密度计算出来的功能聚类。Community 节点保存 label、keywords、description、cohesion、symbolCount。默认使用 Graphology 的 Leiden 实现，也提供实验性的 Icebug 路径。

适合回答：

  • 这个陌生项目可以划分为哪些功能模块？
  • 哪些函数实际上属于同一个业务领域？
  • 项目中最核心的功能聚类是什么？

预计算执行流程（Process）

在社区分析之后，GitNexus 还会检测执行流程，并创建 Process 节点、STEP_IN_PROCESS 边、ENTRY_POINT_OF 边。例如：

Process: Download Bilibili Video
  Step 1: parseUrl
  Step 2: resolveVideoId
  Step 3: fetchVideoInfo
  Step 4: fetchPlayUrl
  Step 5: downloadVideoStream
  Step 6: downloadAudioStream
  Step 7: mergeWithFFmpeg

Routes 和 MCP Tools 还可以与相应流程入口连接：

Route POST /download → ENTRY_POINT_OF → Process Download Video

这对生成架构文档和业务流程图非常有价值。但要注意：Process 是静态图上的推断流程，不是真实运行时 Trace。存在动态分发、配置驱动、反射或条件分支时，可能漏路径或生成近似路径。

检索：BM25 + 可选 Embedding + RRF

GitNexus 的查询可以同时执行 BM25 关键词搜索与向量语义搜索，然后用 Reciprocal Rank Fusion 合并：

RRF score = 1 / (60 + rank)

一个结果如果同时被 BM25 和语义搜索命中，分数会叠加。因此即使代码里没有 cleanup download failure 这种明确名称，Embedding 也可能找到 removeTemporaryFiles / rollbackTask / disposeStreams / cleanupOnError。

Embedding 是可选能力，需要 gitnexus analyze --embeddings；默认基础能力仍依赖 BM25 和图关系。

17 个 MCP 工具

GitNexus 默认提供 17 个 MCP 工具，例如：

  • query：混合搜索
  • context：一个符号的完整上下文
  • impact：影响范围
  • trace：两个符号之间的最短路径
  • detect_changes：Git diff 影响分析
  • cypher：原始 Cypher
  • route_map：API 路由图
  • tool_map：MCP / RPC 工具图
  • shape_check：API 响应形状检查
  • api_impact：接口修改影响
  • explain：污点传播解释
  • pdg_query：控制和数据依赖
  • group_sync：跨仓库契约图

它还把 Community 和 Process 作为 MCP Resource：

gitnexus://repo/{name}/clusters
gitnexus://repo/{name}/processes
gitnexus://repo/{name}/process/{name}

Agent 可以直接读取“已经计算好的架构知识”，而不需要每次重新推导。

可选 PDG

使用 gitnexus analyze --pdg，GitNexus 可以额外建立 CFG（控制流图）、REACHING_DEF（定义到使用的数据流）、CDG（控制依赖图）、TAINTED、SANITIZES、TAINT_PATH。这能回答更细的问题：

  • 这个外部 URL 最后流向了哪个 HTTP 请求？
  • 这个用户输入是否可能进入 shell 命令？
  • FFmpeg 参数在哪里被净化？
  • 哪个 if 条件控制了下载失败分支？

这已经超出普通调用图，进入静态程序分析领域。注意：--pdg 当前并非所有语言都拥有同等覆盖，不应把结果当成完整运行时事实。

核心能力

  • 功能社区（Leiden）与执行流程（Process）预计算
  • BM25 + 可选 Embedding + RRF 混合检索
  • Cypher 查询复杂图关系
  • API 路由图、工具图、接口影响分析
  • 可选 CFG / PDG / 污点分析
  • 跨仓库契约图（Repo Group / Contract Registry / 跨仓库 trace）

优势与局限

优势：

  • 架构理解强（社区、流程、route map、architecture map）
  • Cypher 灵活，可选 PDG 深入
  • 适合生成架构文档与 Mermaid 图
  • 对“陌生项目有哪些模块 / 核心流程 / 扩展点”极强

局限：

  • 部署复杂度高（LadybugDB 属性图、多阶段索引）
  • 更新靠 analyze 与 hooks 检测陈旧，非文件监听自动同步
  • Token 消耗可能更大
  • PDG 语言覆盖不均
  • 非商业许可证限制商业用途

适用场景

  • 初次系统研究陌生项目、生成详细架构文档
  • 还原 URL → 下载文件的完整流程
  • 找后续功能扩展位置、评估跨模块影响
  • 需要社区 / 流程 / API 契约 / 污点分析

官方入口

npx gitnexus analyze --embeddings --skills
npx gitnexus setup
  • 追加数据流分析（注意 --pdg 语言覆盖不均）：
npx gitnexus analyze --pdg --embeddings --skills --force
创建于 2026/7/23 更新于 2026/7/23