GitNexus:零服务器的代码知识图谱引擎

Agent 看不见的代码，就是事故现场

Cursor、Claude Code、Codex 这类编码 Agent 已经很强，但它们并不真正了解你的仓库结构。典型的翻车场景是：AI 修改了 UserService.validate()，却不知道有 47 个函数依赖它的返回类型，破坏性变更就这样直接上线。GitNexus 的回答是：先把整个代码库索引成一张知识图谱——每一条依赖、每一条调用链、每一个功能聚类和执行流都在索引期预计算好——再通过一组「智能 MCP 工具」暴露出去，让 Agent 一次查询就拿到完整上下文。

项目对自己的定位是「Agent 上下文的神经系统」（the nervous system for agent context），一句话概括：像 DeepWiki，但更深——DeepWiki 帮你理解代码，GitNexus 让你分析代码，因为知识图谱追踪的是每一层真实关系，而不只是文字描述。项目由 Akon Labs 维护，采用 PolyForm Noncommercial 1.0.0 许可证（个人与开源使用免费，商用走企业授权），仓库创建于 2025 年 8 月，截至收录时已有约 4.7 万 star。

两条命令上手：CLI + MCP 是主战场

GitNexus 提供两种用法，官方推荐的是 CLI + MCP 形态：

# 1. 在仓库根目录索引代码库
npx gitnexus analyze

# 2. 一次性连接你的编辑器（自动探测 Claude Code、Cursor、Codex 等）
npx gitnexus setup

analyze 一条命令完成索引、安装 agent skills、注册 Claude Code 钩子，并生成 AGENTS.md / CLAUDE.md 上下文文件；setup 写入 MCP 配置，之后 Cursor、Claude Code、Antigravity、Codex、Windsurf、OpenCode、CodeBuddy（腾讯）、Qoder（阿里）等编辑器即可调用图谱。其中 Claude Code 与 Codex 集成最深：MCP 工具 + agent skills + PreToolUse/PostToolUse 钩子，工具调用前自动注入图谱上下文，提交后还能检测到索引过期并提示重索引。Codex 甚至支持以插件形式一键安装：codex plugin marketplace add abhigyanpatwari/GitNexus。

第二种形态是浏览器里的 Web UI（gitnexus.vercel.app）：把任意 git 仓库或 ZIP 拖进去，得到交互式知识图谱 + 内置 Graph RAG 对话。整个前端跑在 WASM 里（Tree-sitter WASM、LadybugDB WASM、浏览器内嵌入），代码不出本机；浏览器模式受内存限制大约支持 5 千文件的仓库，也可以连本地 gitnexus serve 后端处理大仓库。Docker Compose 两条命令起服务：docker compose up -d，后端在 4747 端口、Web UI 在 4173 端口。

核心创新：预计算的关系智能

传统 Graph RAG 把原始图边丢给 LLM，赌它能自己探索出答案——一个问题往往要串行四五次查询。GitNexus 把聚类、追踪、打分这些结构化工作全部前移到索引期：

flowchart TB
    subgraph Traditional["传统 Graph RAG"]
        U1["问：谁依赖 UserService？"] --> Q1["查询 1：找调用方"]
        Q1 --> Q2["查询 2：涉及哪些文件？"]
        Q2 --> Q3["查询 3：排除测试？"]
        Q3 --> OUT1["4+ 次查询后才出答案"]
    end
    subgraph GN["GitNexus 智能工具"]
        U2["问：谁依赖 UserService？"] --> TOOL["impact UserService upstream"]
        TOOL --> OUT2["1 次调用：8 个调用方、3 个聚类、全部 90%+ 置信度"]
    end

这套「预计算关系智能」带来三个直接收益：可靠性——上下文已经在工具返回里，LLM 想漏都漏不掉；token 效率——不再需要十连问去理解一个函数；模型平权——小模型也能干活，因为重活都在工具侧完成。

17 个 MCP 工具：从影响面分析到污点追踪

暴露给 Agent 的工具矩阵分三层。第一层是通用图谱工具：query（BM25 + 语义 + RRF 混合检索、按执行流分组）、context（符号 360 度视图）、impact（爆炸半径，按深度分组并给出置信度）、trace（两个符号间最短有向路径）、detect_changes（git diff 映射到受影响的执行流）、rename（图 + 文本检索协同的多文件重命名）、cypher（原始图查询）等 15 个单仓库工具。第二层面向 API 工程：route_map、tool_map、shape_check、api_impact，把「哪些组件请求哪个接口、响应结构和消费方属性访问是否匹配」也纳入图查询。第三层是可选的 --pdg 索引：pdg_query 查询语句级控制/数据依赖，explain 解释 source→sink 的污点分析结果——这已经接近程序依赖图级别的静态分析能力。

一次典型的 impact 调用长这样：给出目标符号后，按「Depth 1 必坏 / Depth 2 大概率受影响」分层返回调用方与置信度：

impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

TARGET: Class UserService (src/services/user.ts)
UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    handleLogin    [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
  Depth 2 (LIKELY AFFECTED):
    authRouter     [IMPORTS]   -> src/routes/auth.ts

同名符号冲突时不会瞎猜：工具返回按相关度排序的候选列表，再用 target_uid、file_path 或 kind 精确锁定。配套的 10 个 MCP resources（gitnexus://repos、.../clusters、.../processes、.../schema 等）和 2 个 prompts（detect_impact 提交前变更分析、generate_map 生成含 mermaid 图的架构文档）构成完整的发现面。还有一组自动安装的 agent skills：/gitnexus-plan 出实施计划、/gitnexus-work 以影响检查 + detect_changes 门禁执行原子提交、/gitnexus-review 做图支撑的 PR 审查，/gitnexus-lfg 把三者串成完整流水线。

索引管线：六阶段流水线，14 种语言

知识图谱由多阶段管线构建：Structure 走文件树建立目录/文件关系；Parsing 用 Tree-sitter AST 抽取函数、类、方法、接口；Resolution 做跨文件的导入解析、调用解析、继承关系、构造函数推断以及 self/this 接收者类型推断（语言感知）；Clustering 把相关符号聚成功能社区；Processes 从入口点沿调用链追踪执行流；最后 Search 建混合检索索引。

语言支持覆盖 14 种：TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP、Ruby、Swift、C、C++、Dart，各语言在导入解析、类型注解、继承、框架模式识别、入口点启发式等维度能力略有差异（README 提供逐列对照表）。控制流（CFG）目前是 --pdg 可选项，先落在 TypeScript/JavaScript 上，其余语言在规划中。

多仓库走全局注册表：每次 analyze 把索引存在仓库内 .gitnexus/（gitignored，可随仓库搬走），并在 ~/.gitnexus/registry.json 登记一个指针；一个 MCP 服务器因此能同时服务所有已索引仓库，连接池惰性打开、空闲 5 分钟回收。还有 analyze --watch 监听文件变化做增量刷新，gitnexus wiki 从图谱自动生成仓库 wiki（按模块分页 + 交叉引用，需 LLM API key）。

工程底座：WASM 双端同构 + 供应链签名

技术栈刻意做了双端同构：CLI 用 Node.js 原生 Tree-sitter + LadybugDB（前身为 KuzuDB 的嵌入式图数据库，带向量能力）+ transformers.js 嵌入；Web 端是同一套管线的 WASM 版本，可视化用 Sigma.js + Graphology（WebGL），对话是 LangChain ReAct agent，检索两端一致（BM25 + 语义 + RRF）。

供应链安全做得比多数开源项目认真：Docker 镜像版本与 npm 包硬锁定（只有 vX.Y.Z git tag 才发镜像，且必须与 package.json 版本逐字一致），同时发布到 GHCR 与 Docker Hub 且 digest 相同；全部用 Cosign keyless 签名，附带 SLSA provenance 与 SBOM，README 给出可直接复制的 cosign verify 命令；Kubernetes 用户可以直接应用自带的 ClusterImagePolicy，让未签名镜像在准入层就被拒绝。MCP 服务端还有只读模式、仓库白名单、响应 token 预算等一组环境变量级管控。

隐私模型与使用边界

隐私是 GitNexus 的核心卖点之一：CLI 完全本地运行、零网络调用，索引落在 .gitnexus/，全局注册表只存路径与元数据；Web UI 完全在浏览器运行，代码不上传任何服务器，API key 只存 localStorage。Render 一键部署模板约 35 美元/月，适合团队共享索引，但注意该形态下访问令牌是唯一防线。

需要留意的边界：许可证是 PolyForm Noncommercial 1.0.0，商业使用需要联系 Akon Labs 授权；索引是内存敏感操作，超大仓库建议给足内存或拆分；--pdg 控制流目前只覆盖 TS/JS。对想把编码 Agent 用出可靠性的团队来说，这套「把结构预计算进工具」的思路值得直接上手试试。