GitNexus：把任何程式碼庫變成互動式知識圖譜（14K 星）

AI Agent 的地圖問題

想像一位送貨司機來到一座從沒去過的城市。他手上有一份街道名稱清單，能讀路牌。但他沒有地圖。他不知道榆樹街是死巷、主街過了橋就變成快速道路、從倉庫到醫院最快的路線是穿過公園而不是繞過它。

這就是大多數 AI 程式代理與你程式碼庫互動的方式。它們能讀個別檔案，能搜尋函式名稱。但它們沒有一張標示所有連結的地圖。當你叫 Claude Code 重構一個函式，它看得到函式本身，卻不會自動看到散落在八個檔案裡的十四個呼叫者、它實作的三個介面，或者返回型別一改就會壞掉的測試套件。

結果很容易預料。Agent 做了一個孤立來看完全正確的修改，但三層呼叫鏈之外的東西壞了。你在 code review 時抓到，解釋相依關係，agent 修好了。下一次又是另一個它漏掉的相依。問題不在智力，而在結構感知。

GitNexus 是一個開源工具，直接針對這個缺口。它把你整個程式碼庫解析成知識圖譜，再透過 MCP 工具暴露出來，讓任何相容的 AI agent 查詢。Agent 拿到的是地圖，不只是路牌。

這個專案在 GitHub 上突破 14K+ 星，單日就增加超過 2,000 星。這個速度說明它解決的問題引起了大量開發者的共鳴。

GitNexus 實際建構了什麼

把 GitNexus 指向一個 repository 時，它不是單純索引檔案內容。它建構一個圖形資料庫，其中節點代表程式碼實體（函式、類別、方法、介面、模組），邊代表關係（呼叫、匯入、匯出、型別繼承、建構子模式）。

把它想成幫你的程式碼庫建立神經系統。在人體中，如果你碰到一個燙鍋子，訊號沿著特定的神經路徑傳到特定的腦區，觸發特定的肌肉反應。鏈條上的每一段都很重要。一條神經受損，整個反應就失靈。

程式碼的運作方式一樣。使用者按了一個按鈕。這觸發一個 handler。Handler 呼叫驗證服務。驗證服務查詢資料庫 adapter。Adapter 使用連線池。改動鏈條上的任何節點，下游全部受影響。GitNexus 把這些鏈條明確地繪製出來。

圖譜捕捉幾個面向：

相依關係。 不只是「檔案 A 匯入檔案 B」，而是具體匯入了哪些符號、怎麼使用、綁定是 named 還是 default。

呼叫鏈。 函式 X 呼叫函式 Y，Y 又呼叫函式 Z。GitNexus 跨檔案追蹤這些路徑，給你從進入點到末端函式的完整執行故事。

叢集。 使用 Leiden 社群偵測演算法，GitNexus 把相關符號分組成功能社群。這些叢集是自然湧現的，演算法從圖譜結構中發現它們，而不是從資料夾組織推導。一個叢集可能跨越多個目錄，但代表單一功能模組。

執行流程。 從進入點出發（API 路由、CLI handler、事件監聽器），GitNexus 追蹤完整的執行路徑。這些流程追蹤展示了面對使用者的功能實際上如何流過系統。

運作方式：六個階段，零伺服器

「零伺服器」不是行銷話術。GitNexus 真的完全在你的機器上執行（CLI 模式）或完全在瀏覽器裡執行（Web UI 模式）。沒有任何程式碼離開你的環境，沒有後端服務處理你的原始碼。

索引管線有六個階段：

階段一：結構。 走訪檔案樹。對應資料夾和檔案關係。建立圖譜骨架。

階段二：解析。 使用 Tree-sitter AST 擷取，提取每一個函式、類別、方法和介面。Tree-sitter 是 Neovim 和 Zed 等編輯器使用的同一套增量解析程式庫。GitNexus 針對 13 種語言使用語言專屬文法：TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP、Ruby、Swift、C 和 C++。

階段三：解析（Resolution）。 跨檔案解析 import 和函式呼叫。這是最困難的部分。GitNexus 套用語言感知的解析邏輯，處理 named import、default export、re-export、型別繼承和基於建構子的型別推論。每種語言的規則差異很大，Python 的 import 系統和 Go 的套件系統完全不同，所以每種語言都有自己的 resolver。

階段四：叢集化。 對圖譜套用 Leiden 演算法偵測社群。Leiden 演算法（Louvain 的改良版）識別出彼此之間連結密度高於與圖譜其餘部分連結密度的節點群組。用程式碼的術語說，它找到形成自然功能單元的模組。

階段五：流程。 從進入點出發，透過呼叫鏈追蹤執行流程。這個階段產生「process」視圖：一個功能如何運作的敘事，從第一個函式呼叫到最後一個。

階段六：搜尋。 建立混合搜尋索引，結合 BM25 詞彙排名、語義嵌入（透過 HuggingFace transformers.js）和 reciprocal rank fusion 評分。這驅動了自然語言查詢介面。

結果儲存在 LadybugDB，一個嵌入式直欄式圖形資料庫。CLI 使用原生綁定；Web UI 使用 WebAssembly 版本。不論哪種方式，圖譜都住在專案內的 .gitnexus/ 目錄中，全域登錄檔在 ~/.gitnexus/registry.json 追蹤所有已索引的 repository。

Graph RAG 的差異

如果你在程式碼上用過 RAG（檢索增強生成），大概體驗過它的局限。傳統 RAG 把程式碼切成區塊、做嵌入，agent 問問題時檢索相關區塊。問題在於：沒有結構脈絡的程式碼區塊，就像從小說裡撕下來的段落。你拿到片段，但失去了故事線。

Graph RAG 的做法根本不同。它檢索的不是原始文字，而是結構化關係。當 agent 問「如果我改了這個函式的簽名會怎樣？」，GitNexus 不會回傳函式的原始碼然後指望 agent 自己推出影響。它回傳的是：

• 每一個呼叫它的函式（直接相依者）
• 每一個呼叫「那些」函式的函式（傳遞相依者）
• 那些函式所屬的叢集（受影響的功能）
• 經過它的執行流程（受影響的使用者端流程）
• 每個影響層級的信心分數

這是預先計算的情報，不是即時分析。圖譜已經包含所有這些關係。查詢是一次圖形遍歷，不是一次運算。回應又快又完整，而不是又慢又近似。

CLI 與 MCP 整合

這是 GitNexus 對 AI 程式工作流直接有用的地方。CLI 透過 npm 全域安裝：

npm install -g gitnexus

索引你的 repository：

gitnexus analyze

或跳過全域安裝：

npx gitnexus analyze

analyze 指令走完六個階段，把圖譜儲存在本機。以一個中型 TypeScript 專案（約 500 個檔案）來說，索引通常不到一分鐘。

連接 Claude Code

GitNexus 暴露一個 MCP server，任何相容 MCP 的 agent 都能連接。Claude Code 的設定方式：

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Cursor 的話，加到 ~/.cursor/mcp.json：

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

連接後，agent 取得七個 MCP 工具：

單一 MCP server 實例服務所有已索引的 repository。連線池管理最多五個並行資料庫連線，閒置五分鐘後自動回收。

實際使用場景

你叫 Claude Code 重構一個支付處理函式。沒有 GitNexus 時，Claude 讀函式、做修改，你事後才發現三個 webhook handler 和一個帳單報表產生器壞了。

有了 GitNexus，Claude 先查詢 impact 工具。它拿到依深度分組的相依清單：深度 1 的直接呼叫者、深度 2 的間接呼叫者，依此類推。每個項目都有信心分數。Claude 在動手之前就知道影響範圍。它能計畫重構時更新所有受影響的呼叫點，或標記它不確定的部分。

detect_changes 工具同樣實用。修改完成後，agent 能把 Git diff 對應到受影響的流程和叢集。如果它改了一個資料庫 adapter，圖譜顯示這個 adapter 參與了結帳流程、認證流程和管理後台，agent 就知道要驗證這三個，而不只是原本被要求處理的那個。

GitNexus vs. Termdock 內建 AST 分析

如果你使用 Termdock 的 AST 程式碼分析，可能好奇 GitNexus 相較之下如何。誠實的答案：它們解決的問題相關但不同，而且互相補強。

Termdock 的 AST 分析直接整合在你的終端工作流中。它在你工作時提供即時的結構分析：函式簽名、型別階層、符號定義，不需要額外的索引步驟。它針對終端多工器情境中的速度和即時性最佳化。當你在瀏覽程式碼、檢視 diff 或撰寫 skill 檔案時，Termdock 的 AST 在你工作的地方直接給你結構 context。

GitNexus 建構一個持久的、可查詢的完整程式碼庫知識圖譜。它的強項是跨 repository 分析、社群偵測、執行流程追蹤和影響範圍評估。圖譜在 session 之間持久存在，任何相容 MCP 的 agent 都能查詢。

把它想成手電筒和衛星地圖的差別。手電筒（Termdock AST）即時照亮你指向的地方，是你自然工作流的一部分。衛星地圖（GitNexus）展示整片地形，所有道路、河流和邊界都標好了，但你要先索引再透過工具查詢。

實用的設定是兩者並用：

它們不是競爭關係。Termdock 處理即時的、戰術性的視圖。GitNexus 處理策略性的、架構性的視圖。

設定指南

快速開始

# 全域安裝
npm install -g gitnexus

# 切到你的專案
cd your-project

# 索引程式碼庫
gitnexus analyze

# 設定你編輯器的 MCP
gitnexus setup

setup 指令自動偵測已安裝的編輯器（Claude Code、Cursor、Windsurf）並為每一個設定 MCP 連線。

產生 Skill 檔案

GitNexus 能產生描述你程式碼庫架構的 repository 專屬 skill 檔案：

gitnexus analyze --skills

這產生的 skill 檔案能被任何相容 agent skills 的工具消費，讓 agent 取得預先建構的架構知識，不需要在執行時查詢圖譜。

Web UI

如果你偏好視覺介面，GitNexus 在 gitnexus.vercel.app 提供瀏覽器版探索器。拖放一個 repository ZIP 或貼上 GitHub URL。整個索引管線透過 WebAssembly 在你的瀏覽器裡執行。不上傳到伺服器，不需要帳號。

Web UI 使用 Sigma.js（WebGL 加速）渲染知識圖譜，你可以視覺化探索叢集、追蹤執行流程，並透過聊天介面與 Graph RAG agent 互動。

你也能橋接 CLI 和 Web UI。執行 gitnexus serve 啟動本機 HTTP server，Web 介面會自動偵測，讓你瀏覽 CLI 已索引的 repository 而不需要重新上傳。

其他指令

# 列出所有已索引的 repository
gitnexus list

# 產生 LLM 驅動的文件
gitnexus wiki

# 清除索引資料
gitnexus clean

這對 AI Agent 品質為什麼重要

AI 程式代理的根本挑戰不在生成品質。現代模型能寫出語法正確、邏輯健全的程式碼。挑戰在 context 品質。一個不理解修改的架構影響的 agent，會產出局部正確但全域崩壞的程式碼。

這不是新問題。人類開發者也面對同樣的事。差別在於有經驗的開發者花數月甚至數年建立程式碼庫的心智模型。他們知道動支付模組就要更新稽核日誌，因為半年前他們吃過苦頭。

AI agent 沒有半年的時間。它們只有一個 context window。GitNexus 把數月的架構理解壓縮成一個可查詢的圖譜，按需放進那個 window。

更大的趨勢值得注意。像 GitNexus 這樣的工具代表了從「給 agent 更多文字」到「給 agent 結構化知識」的轉變。RAG 是第一步：檢索相關文字。Graph RAG 是下一步：檢索相關關係。Agent 不只知道有什麼程式碼，它知道程式碼之間如何連接。

對於讓 AI agent 做非平凡工作的團隊（重構、功能開發、相依升級），提供結構感知的工具不是選配。它們是讓 agent 需要持續監督和可以被信任理解修改後果之間的差距。

GitNexus 是開源的（ISC 授權），積極維護中，執行時不會把你的程式碼傳到任何地方。如果你已經在使用相容 MCP 的 agent，把它加入工作流只需要兩行指令。

試試看。索引一個你熟悉的專案。查詢一個你以前做過的修改的影響範圍。看看圖譜是不是符合你的心智模型。如果符合，你就把你花了好幾個月建立的理解，交給了你的 AI agent。