我手上比較大的專案到後期都會遇到一個老問題：要不要再開一個 codebase RAG，餵給 Claude Code 或 Cursor 用。傳統做法是把整個 repo 切 chunk、丟到向量資料庫，再靠語義搜尋找相關片段；這條路在小型專案還行，但一旦涉及跨檔案的呼叫鏈、繼承層、依賴關係，純 embedding 很容易把不相關但詞彙相似的片段拉出來，反而讓 LLM 走錯方向。
最近翻到 GitNexus 這個專案，剛好踩在我想做但一直沒動手的點：把整個 repo 解析成知識圖（Knowledge Graph），function、class、module、import、call 通通變成節點與邊；查詢時走 graph traversal 而不是純向量比對，再透過 MCP（Model Context Protocol）把整張圖暴露給 Claude Code、Cursor、Codex、Windsurf 這類 AI 程式編輯器。重點是它有兩個跑法——CLI 後端模式給規模大的 repo 用、純瀏覽器模式（gitnexus.vercel.app）拖檔即解析、不用伺服器、graph database 直接跑在 WASM 裡。
下面會依序談 GitNexus 的定位、它的解析與儲存技術、MCP 整合方式、和傳統 vector RAG 的差異，最後給出我自己嘗試後對它適合與不適合場景的看法。
一、GitNexus 想解決的問題
把 codebase 餵給 LLM 這件事，本質上是在處理 context window 與 retrieval 兩端的拉扯。Context window 永遠不夠塞下整份 repo，retrieval 又經常拿不到「正確的那塊」。
過去主流做法分兩派：
第一派是純語義檢索（vector RAG）。把整個 repo 切成 chunk、用 embedding 模型轉向量，查詢時做 cosine similarity。優點是上手簡單、不挑語言；缺點是它本質上是「找詞彙相近的片段」，碰到「這個 function 被誰呼叫過」、「這個 class 的繼承關係如何」這類結構性問題時，常常會錯過真正相關但詞彙不重疊的程式碼。
第二派是把 LLM 自己當搜尋介面（grep + read）。Claude Code、Cursor、Aider 這類工具會主動讀目錄、grep 關鍵字、再決定要看哪個檔案。優點是無需預處理、即時反映變更；缺點是每次提問都要重新「探索」一次 repo，token 花得兇，而且面對巨型 monorepo 時很容易在 grep 階段就漏掉相關檔案。
GitNexus 走的是第三條路：先把 repo 解析成完整的知識圖，把 call、import、inheritance、reference 這些結構性關係預先計算好，查詢時改用圖查詢去命中正確節點，再把節點周圍的子圖回給 LLM。GitHub README 裡用一句話描述這個哲學：「Traditional approaches give the LLM raw graph edges and hope it explores enough. GitNexus precomputes structure at index time.」
對使用者的差別在於：你不用每次都祈禱 LLM 自己會探索到正確的檔案，因為「這個 function 影響哪些下游」、「這條 import 鏈的根源在哪」、「重命名這個 symbol 會影響哪些檔案」這類問題，已經被預先建好索引在等你問。
二、技術堆疊：從 Tree-sitter 到 LadybugDB
2.1 解析層：Tree-sitter 一次處理 14 種語言
GitNexus 用 Tree-sitter 抽 AST，這是 GitHub 自家在用的 incremental parser，原生支援數十種語言，且解析錯誤容忍度高（半寫到一半的程式碼也能解析）。
CLI 模式下走 native bindings，瀏覽器模式則用 Tree-sitter 的 WASM 編譯版。從 README 看到目前有第一級支援的 14 種語言：TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP、Ruby、Swift、C、C++、Dart。每種語言對 import、type annotation、constructor inference 的支援程度不同，但 function call、class definition、method 這些核心節點是齊的。
抽出來之後，每個 symbol 變成一個 graph node，關係（call、import、extend、reference）變成 edge。這一步是純結構抽取，不做語義判斷；好處是快、可重現、不用 GPU，只靠 CPU 平行解析。
2.2 平行化：Web Workers + Comlink / 後端 worker threads
解析大型 repo 時 IO 不是瓶頸、parser 工作量才是。GitNexus 用 Web Workers 把每個檔案丟到不同的 worker 平行解析，主執行緒不被卡，瀏覽器 tab 一邊解析一邊還能畫 UI；通訊用 Comlink 包成 promise based RPC，省掉手寫 postMessage 的麻煩。
CLI 模式則是 Node 的 worker_threads 加上 async IO；同一份 parser code 兩端共用，只是 host 不一樣。
2.3 儲存層：LadybugDB（前 KuzuDB）embedded graph DB
這是 GitNexus 最關鍵也最有技術品味的選擇。LadybugDB（前 KuzuDB）是個嵌入式圖資料庫，直接寫成 lib，不需要單獨開 server；瀏覽器版本編譯成 WASM、CLI 版本用 native binding。同時內建向量索引，所以 GitNexus 可以在同一份儲存裡做圖查詢與向量檢索。
實際運作起來，瀏覽器內查詢的延遲主要由 IndexedDB 的讀寫速度決定，不會像走網路 API 那種 SaaS RAG 動輒幾百毫秒。
2.4 查詢層：BM25 + Semantic + RRF Hybrid Search
光有圖還不夠，使用者問問題時不一定知道準確的 symbol 名字。GitNexus 的查詢是混合式的：
- BM25：傳統 keyword scoring，命中精準但對語義差異敏感
- Semantic embedding：vector similarity，補 BM25 的語義缺口
- RRF（Reciprocal Rank Fusion）：把兩條路的結果用倒序排名加權合併
這是最近幾年資訊檢索界比較成熟的折衷方案：兩條路各擅勝場，用 RRF 合在一起比單跑任一條路都好。對 codebase 場景特別合適，因為使用者問「JWT 在哪生成」這種口語化句子時，純 BM25 會漏掉沒寫 "JWT" 字面的相關函式；純 semantic 又可能把 unrelated 但詞向量接近的片段拉出來。
三、跑起來長什麼樣子
3.1 三種啟動方式
GitNexus 提供三條入口，對應三種使用情境。
純瀏覽器 demo：開 https://gitnexus.vercel.app，把 GitHub URL 貼進去，或者直接拖一個 zip。整個解析過程在你的瀏覽器跑、graph 存在 IndexedDB 裡，不上傳任何檔案到伺服器。限制是被瀏覽器記憶體上限卡住，README 寫大約 5,000 個檔案就會吃緊。
CLI 模式：npm i -g gitnexus（或對應的安裝指令），對著 repo 執行 gitnexus serve，會跑一個 local backend 加 graph DB；瀏覽器 UI 連到 localhost 後就解除 5k 檔案上限，可以吃下完整 monorepo。
Docker compose：docker compose up -d 一行起來，images 放在 GHCR 與 Docker Hub、用 Cosign 簽好。適合放在內網給團隊共用、或 CI 上做 codebase 索引。
3.2 16 個 MCP tools 給 AI editor 用
這部分是我覺得最值得拉出來講的。GitNexus 暴露了 16 個 MCP tools，連到 Claude Code / Cursor / Codex / Windsurf 之後，LLM 不用自己 grep，可以直接呼叫：
query：群組化的混合搜尋，回傳排好序的相關 symbol 與所屬流程impact：blast radius 分析，告訴你修這個 symbol 會影響哪些下游、深度多遠、信心多高context：給定一個 symbol，回傳 360 度視角——所有引用、所有實作、它參與的流程detect_changes：跨提交對比，找出哪些 symbol 被加減、哪些關係被破壞rename：基於圖的安全 rename 預測，回傳所有需要同步改的位置cypher：直接打 Cypher graph query，給進階使用者
對 AI editor 而言，這就是把「我要怎麼搞清楚這個 codebase」這個問題從 LLM 的肩膀上拿走。LLM 不再需要靠 trial-and-error 的 read_file、grep_search 去探索，可以直接 impact("UserService.login") 拿到所有受影響的位置，再用 context() 把那些位置的程式碼補進 context window。
3.3 視覺化介面
瀏覽器版多了個 D3.js force-directed layout 視覺化，把整張 graph 畫出來、點節點看 call chain、選 cluster 看模組分群。這對「我接手一個陌生 repo 想先建立直覺」這種場景很有用——比起翻 200 個 import statement，看一張圖五分鐘抓得到形狀。
四、和傳統 Codebase RAG 的差異
這部分整理一下我自己對幾個競品的觀察，不是嚴謹 benchmark，僅供參考。
4.1 vs Sourcegraph / Cody
Sourcegraph 是這個賽道的元老，從 code search 演化到 Cody（內建 LLM）的路線。它有完整的 LSP-based 結構分析、跨 repo 索引、雲端 SaaS 也有 self-host。
差別在於：Sourcegraph 的 graph 是封閉的、給自家 Cody 用；它不主動暴露 MCP 介面給其他 LLM 客戶端。你想用 Claude Code、Cursor 配 Sourcegraph 的 graph，要自己包一層 wrapper。GitNexus 從一開始就以 MCP 為一級介面、不綁定任何 LLM 客戶端，誰都能接。
另一個差別是部署成本。Sourcegraph 的 self-host 需要 Postgres、Redis、blobstore，整套起來不輕；GitNexus 的瀏覽器模式根本不用伺服器、Docker 模式也是一個 compose 檔案。
4.2 vs Aider / Cline / Continue
這三個都是 LLM-driven 的 code editor。它們解 codebase 上下文的方式比較直接：靠 LLM 自己 grep、read。Aider 多了個 repo map（生成所有 symbol 的簡短 summary 餵給 LLM），但本質還是讓 LLM 在每次提問時自己探索。
GitNexus 的位置是「補在 LLM 工具鏈下面的索引層」。它不是 editor 也不取代 editor，而是給 editor 一個更精準的 retrieval 工具。實務上是 GitNexus + Claude Code、GitNexus + Cursor 這種組合，不是非此即彼。
4.3 vs 純 vector RAG（pgvector / Chroma / Weaviate）
這個是最常見的對比。我自己手上有幾個用 pgvector 切的 codebase RAG，碰過幾種典型的失敗模式：
- 同名 function 在不同檔案散落，向量檢索把無關的全拉回來（沒有 namespace 概念）
- 重構後的舊版本還留在 chunk 裡，因為向量還很相似，常常被誤召回
- 跨檔案 call chain 完全看不出來——LLM 看到 function A 但不知道 A 被 B 呼叫、B 又被 C 呼叫
graph-based 索引在這幾個點都比較硬，因為它有「結構」的概念：A 與 B 之間的 calls 邊，是用 AST 解析確定的，不會因為 chunk 邊界切錯就斷掉。
當然 graph 也有它的劣勢——對「描述性」問題（例如「這個 repo 的整體風格是什麼」）反而 vector RAG 更直觀。理想情況是 hybrid，剛好就是 GitNexus 內部在做的事。
五、實務上踩到的點
5.1 瀏覽器模式的記憶體天花板
5k 檔案不是硬限制，但確實是個分水嶺。我把幾個中型專案丟進去——Next.js 自己的 repo、Tailwind 的 monorepo——都能跑，但會明顯感覺到瀏覽器吃 RAM 變多、解析時間在十幾秒到一分鐘之間。
到 monorepo 等級（10k+ 檔案）就建議換 CLI 或 Docker 模式，不然 IndexedDB 的寫入會變瓶頸，整個 tab 卡住的機率明顯升高。
5.2 MCP 連接 Claude Code / Cursor 的細節
連起來不難，照 README 把 GitNexus 的 MCP server 加到 ~/.claude.json（Claude Code）或 Cursor 的 MCP config 即可。要注意的是 GitNexus 的 MCP server 預設用 stdio transport，跟 Claude Code 的設定一致；但 Cursor 在某些版本只支援 SSE transport，要看具體版本。
我實測下來，連好之後 Claude Code 比較會主動呼叫 GitNexus tools，因為 prompt 設計鼓勵它優先使用結構化工具；Cursor 則要在 system prompt 提醒它「優先使用 GitNexus 而非 grep」才會穩定走索引。
5.3 授權的眉角
GitNexus 用的是 PolyForm Noncommercial 授權。個人非商業用途完全沒問題；公司內部商業使用需要走 commercial license（akonlabs.com）。這點和很多 MIT / Apache 的開源專案不同，要納入評估。
對自架在內網給團隊用的場景，這條授權需要先跟法務確認，避免後面卡關。
六、適合與不適合的場景
整理我自己用幾天下來的感受。
適合：
- 中大型 repo（>1k 檔案），結構複雜、跨檔案呼叫多
- 接 Claude Code / Cursor 想要更精準的 codebase retrieval
- 想對 LLM 暴露結構化查詢介面（impact、context、rename）
- 接手陌生 repo 想先建立架構直覺
不適合：
- 小型專案（<200 檔案），LLM 直接 grep 就夠快
- 主要寫的語言不在支援的 14 種裡
- 嚴格純 MIT / Apache 授權需求的商業環境
- 對「描述性」、「風格性」問題期待高，這類純 vector RAG 反而適合
七、結語
GitNexus 給我的感覺是「終於有人把 codebase RAG 往結構化這條路認真推進」。市面上太多 RAG 工具都是把 vector DB 包一包、丟個 chat UI，沒有真的解決 codebase 特有的結構問題。
它對的點不只是技術選擇（Tree-sitter + LadybugDB + Web Workers），還有產品定位：不做 editor、不綁 LLM、用 MCP 當對外介面，把自己定位成「補在工具鏈下面的索引層」。這種設計能存活的前提，是 MCP 本身要持續被主流客戶端支援；目前 Claude Code、Cursor、Codex、Windsurf 都在 ship MCP，趨勢看來是穩的。
接下來想試的方向是把它接到內部的 monorepo、跑 Docker 模式，用 Claude Code 走完幾個典型重構任務，看看 impact 跟 rename 這兩個 tool 的命中率比起純 grep + LLM 自己探索能省多少 token。如果結果好，就可以正式接到團隊的開發流程裡。
參考資料
- GitNexus GitHub repo：https://github.com/abhigyanpatwari/GitNexus
- 線上 demo：https://gitnexus.vercel.app
- Tree-sitter incremental parser：https://tree-sitter.github.io/tree-sitter/
- LadybugDB（前 KuzuDB）embedded graph database：https://kuzudb.com/
- Model Context Protocol：https://modelcontextprotocol.io/
發佈留言