[Open Source] **程式碼知識圖譜 GitNexus，現在開始，時間不多了！**

讓你的AI助手更懂你的程式碼：GitNexus 深度解析與實用指南（給台灣開發者的超詳細介紹）

各位台灣的程式開發朋友們，大家好！

在現今AI蓬勃發展的時代，我們越來越常使用 AI 工具來輔助我們的程式開發工作。像是Cursor、Claude Code 等等，這些 AI 輔助工具都非常強大，可以幫我們寫程式、除錯、重構等等。但是，你有沒有覺得它們還是不夠「懂」你的程式碼？它們可能沒辦法完全理解你的專案架構，導致它們在修改程式碼時，可能會造成意想不到的錯誤。

今天，我要向大家介紹一個非常棒的工具：GitNexus。它就像是 AI 助手的大腦，讓你的 AI 工具可以更深入地了解你的程式碼，提升工作效率，減少錯誤發生的機率。

什麼是 GitNexus？ 它的核心概念是什麼？

GitNexus 是一個程式碼知識圖譜建構工具。簡單來說，它會 索引（index） 你的程式碼庫，建立一個 知識圖譜（knowledge graph）， 這個知識圖譜就像是程式碼的「地圖」，記錄了程式碼中 所有 的依賴關係、呼叫鏈、程式碼群組、執行流程等等。

• 知識圖譜（Knowledge Graph）： 就像是你的程式碼的「百科全書」和「關係圖」，它不只是記錄程式碼的描述，更記錄了程式碼之間的 關係。例如，哪個函數被哪些其他函數呼叫、哪些檔案互相依賴等等。
• 索引（Index）： GitNexus 會分析你的程式碼，把重要的資訊提取出來，建立知識圖譜。
• AI 助手的大腦： GitNexus 讓 AI 工具（例如 Cursor、Claude Code）能夠更準確地理解你的程式碼結構，避免在修改程式碼時，發生意想不到的錯誤。

GitNexus 的核心價值在於，它 預先計算 了程式碼之間的各種關聯，這讓 AI 助手在處理程式碼時，可以更快速地獲得 完整的上下文資訊。

想像一下，當你在修改一個函數時，你的 AI 助手可以立刻知道：

• 哪些其他函數會呼叫這個函數？
• 哪些地方會用到這個函數的回傳值？
• 這個函數屬於哪個程式碼群組？
• 等等…

有了這些資訊，AI 助手就能夠更安全、更有效地幫你修改程式碼，減少出錯的風險。

GitNexus 的兩種使用方式：CLI + MCP 與 Web UI

GitNexus 提供了兩種主要的使用方式：

1. CLI + MCP (推薦): 這是一種 本地端 的使用方式。你需要透過 指令列 (CLI) 索引你的程式碼庫，然後運行一個 MCP (Model Context Protocol) 伺服器，讓你的 AI 助手可以存取 GitNexus 建立的知識圖譜。
2. Web UI: 這是一種 瀏覽器 上的使用方式。你可以直接在瀏覽器上開啟 GitNexus 的 Web UI，上傳你的程式碼（支援 ZIP 壓縮檔），然後就可以在 Web UI 上進行程式碼探索、使用 AI 聊天等功能。

以下表格比較了這兩種方式：

對於台灣的開發者，我個人推薦使用 CLI + MCP 的方式。 這種方式可以讓你更深入地整合 GitNexus 到你的開發流程中，並讓你的 AI 助手獲得更完整的程式碼知識。

Bridge mode（橋接模式） 也很棒。你可以使用 gitnexus serve 命令啟動本地伺服器，然後在 Web UI 中連線到這個伺服器，這樣 Web UI 就可以存取你用 CLI 索引的程式碼庫了。這就等於是把 CLI 的強大索引能力和 Web UI 的視覺化探索功能結合起來。

如何開始使用 GitNexus (CLI + MCP)?

如果你想開始使用 GitNexus，請按照以下步驟操作：

1. 安裝 GitNexus:

   在你的終端機 (terminal) 中，執行以下指令：

   npm install -g gitnexus
   

   這會全局安裝 GitNexus，讓你可以從任何地方使用它。

2. 進入你的程式碼庫的根目錄:

   使用 cd 命令進入你的程式碼庫的根目錄，例如：

   cd /path/to/your/project
   

3. 索引你的程式碼庫:

   執行以下指令，GitNexus 就會開始分析你的程式碼：

   npx gitnexus analyze
   

   這會索引你的程式碼庫，安裝 AI 助手所需的技能，建立 AGENTS.md 和 CLAUDE.md 的上下文檔案。

   小提醒： 如果你的程式碼庫很大，索引可能需要一些時間。
   如果你只需要重新索引一部分，可以指定路徑，例如 npx gitnexus analyze src/components。

4. (只需要執行一次) 配置 MCP (Model Context Protocol) 伺服器:

   MCP 伺服器是 GitNexus 和你的 AI 助手之間的橋樑。你只需要執行一次以下指令，GitNexus 就會自動配置好你的 AI 助手：

   npx gitnexus setup
   

   GitNexus 會自動偵測你的編輯器，並寫入正確的 MCP 全局配置。

   如果你的編輯器配置失敗，或你想手動配置，可以參考以下的配置方式。

5. 啟動 MCP 伺服器:

   執行以下指令，啟動 MCP 伺服器：

   gitnexus mcp
   

   小提醒： 啟動 MCP 伺服器後，它會在終端機中保持運行。你需要讓它持續運行，你的 AI 助手才能夠使用 GitNexus 的功能。

現在，你的 AI 助手 (例如 Cursor 或 Claude Code) 就可以利用 GitNexus 建立的知識圖譜，更聰明地理解你的程式碼了！

MCP 設置 (手動配置)

如果你需要手動配置 MCP，可以參考以下步驟：

1. 編輯器支援

   GitNexus 支援多種編輯器，以下是針對不同編輯器的配置方式：

   編輯器	MCP	Skills	Hooks (自動增強)	支援程度
   Claude Code	是	是	是 (PreToolUse)	完全支援
   Cursor	是	是	否	MCP + Skills
   Windsurf	是	否	否	MCP
   OpenCode	是	是	否	MCP + Skills

   Claude Code 享有最深入的整合： MCP 工具 + agent skills + PreToolUse hooks，可以自動使用知識圖譜的上下文資訊來增強 grep/glob/bash 呼叫。

2. Claude Code 配置 (完全支援):

   在 Claude Code 中，你需要添加 GitNexus 的 MCP 設定。 你可以依照以下步驟配置：

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

   說明： 這行指令會告訴 Claude Code，使用 npx gitnexus@latest mcp 指令來啟動 GitNexus 的 MCP 伺服器。

3. Cursor 配置:

   在 Cursor 中，你需要編輯你的全域 MCP 設定檔案 (~/.cursor/mcp.json)。如果這個檔案不存在，你需要先創建它。 加入以下設定：

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

   說明： 這段 JSON 設定告訴 Cursor，當你啟動 AI 功能時，它會使用 npx gitnexus@latest mcp 指令來啟動 GitNexus 的 MCP 伺服器。

4. OpenCode 配置:

   在 OpenCode 中，你需要編輯你的設定檔 (~/.config/opencode/config.json)，加入以下設定：

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

   說明： 這段 JSON 設定告訴 OpenCode，當你啟動 AI 功能時，它會使用 npx gitnexus@latest mcp 指令來啟動 GitNexus 的 MCP 伺服器。

CLI 指令總覽

除了上述的 npx gitnexus analyze 和 npx gitnexus setup 指令， GitNexus 還提供了其他一些有用的 CLI 指令：

• gitnexus analyze [path]: 索引程式碼庫 (或更新已過時的索引)。
  • --force: 強制重新索引。
  • --skip-embeddings: 跳過嵌入向量生成 (加快速度)。
• gitnexus mcp: 啟動 MCP 伺服器 (標準輸出)。
• gitnexus serve: 啟動本地 HTTP 伺服器 (多程式碼庫)，以便與 Web UI 連接。
• gitnexus list: 列出所有已索引的程式碼庫。
• gitnexus status: 顯示目前程式碼庫的索引狀態。
• gitnexus clean: 刪除目前程式碼庫的索引。
  • --all --force: 刪除所有索引。
• gitnexus wiki [path]: 從知識圖譜生成程式碼庫 Wiki 文件。
  • --model <model>: 使用自訂的 LLM 模型 (預設: gpt-4o-mini)。
  • --base-url <url>: 使用自訂的 LLM API 基本 URL。

你的 AI 助手可以獲得什麼？

透過 GitNexus，你的 AI 助手可以獲得以下幾項功能：

• 7 個透過 MCP 提供的工具:
  

  工具	功能	repo 參數
  list_repos	顯示所有已索引的程式碼庫	—
  query	混合搜尋（BM25 + 語義 + RRF）	可選
  context	360 度符號檢視 — 分類引用、流程參與	可選
  impact	影響範圍分析，包含深度分組和信心評分	可選
  detect_changes	Git 差異影響 — 將已變更的程式碼行映射到受影響的流程	可選
  rename	跨多個檔案的協調重命名，包含圖譜和文字搜尋	可選
  cypher	原始 Cypher 圖譜查詢	可選

  如果只索引了一個程式碼庫，repo 參數是可選的。 如果有多個程式碼庫，請指定是哪一個程式碼庫，例如：query({query: "auth", repo: "my-app"})。

• 即時上下文的資源:
  

  資源	目的
  gitnexus://repos	列出所有已索引的程式碼庫 (請先閱讀此內容)
  gitnexus://repo/{name}/context	程式碼庫統計數據、過時檢查和可用工具
  gitnexus://repo/{name}/clusters	所有功能集群及其內聚力評分
  gitnexus://repo/{name}/cluster/{name}	集群成員和詳細信息
  gitnexus://repo/{name}/processes	所有執行流程
  gitnexus://repo/{name}/process/{name}	完整的流程追蹤
  gitnexus://repo/{name}/schema	用於 Cypher 查詢的圖譜模式

• 2 個 MCP 提示詞 (prompt) ，用於引導式工作流程:
  

  提示詞	功能
  detect_impact	預提交變更分析 — 範圍、受影響的流程、風險等級
  generate_map	從知識圖譜生成架構文件，包含 mermaid 圖表

• 4 個自動安裝到 .claude/skills/ 的 AI 助手技能:
  • Exploring（探索） — 使用知識圖譜導航不熟悉的程式碼。
  • Debugging（除錯） — 追蹤透過呼叫鏈的錯誤。
  • Impact Analysis（影響分析） — 在修改程式碼前，分析影響範圍。
  • Refactoring（重構） — 使用依賴關係映射，規劃安全的重構。

多程式碼庫 MCP 架構

GitNexus 使用 全域登錄 (global registry)，因此一個 MCP 伺服器可以服務多個已索引的程式碼庫。 不需要針對每個專案單獨配置 MCP。 你只需要配置一次，它就可以在任何地方使用。

以下是 GitNexus 的架構圖，可以幫助你更好地理解：

flowchart TD
    subgraph CLI [CLI 指令]
        Setup["gitnexus setup"]
        Analyze["gitnexus analyze"]
        Clean["gitnexus clean"]
        List["gitnexus list"]
    end

    subgraph Registry ["~/.gitnexus/"]
        RegFile["registry.json"]
    end

    subgraph Repos [專案程式碼庫]
        RepoA[".gitnexus/ in 程式碼庫 A"]
        RepoB[".gitnexus/ in 程式碼庫 B"]
    end

    subgraph MCP [MCP 伺服器]
        Server["server.ts"]
        Backend["LocalBackend"]
        Pool["連線池"]
        ConnA["KuzuDB 連線 A"]
        ConnB["KuzuDB 連線 B"]
    end

    Setup -->|"寫入全域 MCP 設定"| CursorConfig["~/.cursor/mcp.json"]
    Analyze -->|"註冊程式碼庫"| RegFile
    Analyze -->|"儲存索引"| RepoA
    Clean -->|"取消註冊程式碼庫"| RegFile
    List -->|"讀取"| RegFile
    Server -->|"讀取登錄"| RegFile
    Server --> Backend
    Backend --> Pool
    Pool -->|"延遲開啟"| ConnA
    Pool -->|"延遲開啟"| ConnB
    ConnA -->|"查詢"| RepoA
    ConnB -->|"查詢"| RepoB

運作方式： 每次執行 gitnexus analyze 指令，GitNexus 都會將索引儲存在程式碼庫內的 .gitnexus/ 資料夾中 (可移植，且被 git 忽略)， 並在 ~/.gitnexus/registry.json 中註冊一個指標。 當 AI 助手啟動時，MCP 伺服器會讀取登錄檔，並可以服務任何已索引的程式碼庫。 KuzuDB 連接會在首次查詢時延遲開啟，並在 5 分鐘不活動後逐出 (最多 5 個並發)。 如果只索引了一個程式碼庫，則在所有工具上，repo 參數是可選的 — 助手們不需要做任何更改。

Web UI (瀏覽器版)

GitNexus 也提供了一個基於瀏覽器的 Web UI。 這個 Web UI 是一個 完全在客戶端運行的 圖譜探索器和 AI 聊天介面。 也就是說，你的程式碼 永遠不會離開你的瀏覽器，並且 不需要安裝任何東西。

立即嘗試： gitnexus.vercel.app — 拖曳一個 ZIP 壓縮檔，然後開始探索。

[圖片：GitNexus Web UI 介面截圖，請參考原文]

或者，你也可以在本地運行 Web UI：

git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus/gitnexus-web
npm install
npm run dev

Web UI 使用與 CLI 相同的索引流程，但 完全 在 WebAssembly 中運行 (Tree-sitter WASM, KuzuDB WASM, 嵌入向量在瀏覽器中)。 它非常適合快速探索，但受限於瀏覽器的記憶體，對於較大的程式碼庫，可能會有一定的限制。

本地後端模式： 執行 gitnexus serve 並在本地開啟 Web UI — 它會自動偵測伺服器，並顯示你所有已索引的程式碼庫，並提供完整的 AI 聊天支援。 不需要重新上傳或重新索引。 助手的工具 (Cypher 查詢、搜尋、程式碼導航) 會自動透過後端 HTTP API 路由。

GitNexus 解決了什麼問題？

目前的 AI 程式碼輔助工具，例如 Cursor、Claude Code、Cline、Roo Code 和 Windsurf 等，雖然功能強大，但它們 並不能真正了解 你的程式碼庫結構。

可能發生的情況：

1. AI 編輯 UserService.validate() 函數。
2. AI 不知道有 47 個函數依賴於這個函數的回傳值。
3. 導致程式碼的重大變更被提交，進而造成錯誤發生。

傳統圖譜 RAG vs GitNexus

傳統方法是將原始圖譜邊緣提供給 LLM，並希望它探索足夠的資訊。 GitNexus 在索引時預先計算結構 — 叢集、追蹤、評分 — 讓工具在一個呼叫中返回完整的上下文資訊：

flowchart TB
    subgraph Traditional["傳統圖譜 RAG"]
        direction TB
        U1["使用者：什麼依賴 UserService?"]
        U1 --> LLM1["LLM 接收原始圖譜"]
        LLM1 --> Q1["查詢 1：找出呼叫者"]
        Q1 --> Q2["查詢 2：哪些檔案？"]
        Q2 --> Q3["查詢 3：過濾測試？"]
        Q3 --> Q4["查詢 4：高風險？"]
        Q4 --> OUT1["回答，經過 4+ 次查詢"]
    end

    subgraph GN["GitNexus 智慧工具"]
        direction TB
        U2["使用者：什麼依賴 UserService?"]
        U2 --> TOOL["影響 UserService 上游"]
        TOOL --> PRECOMP["預先構建的回答：
        8 個呼叫者，3 個集群，全部 90%+ 置信度"]
        PRECOMP --> OUT2["完整回答，1 次查詢"]
    end

核心創新：預先計算的關係智能

• 可靠性 — LLM 不會遺漏上下文資訊，它已經在工具的回應中。
• Token 效率 — 不需要 10 次查詢鏈來理解一個函數。
• 模型平民化 — 較小的 LLM 也能工作，因為工具負責繁重的工作。

GitNexus 的運作方式

GitNexus 透過一個多階段的索引流程，建立你程式碼庫的完整知識圖譜：

1. 結構 — 遍歷檔案樹，映射檔案夾/檔案關係。
2. 解析 — 使用 Tree-sitter ASTs 提取函數、類別、方法和介面。
3. 解析 — 使用語言感知邏輯，解析檔案間的導入和函數呼叫。
4. 集群 — 將相關的符號分組到功能社群中。
5. 流程 — 從入口點追蹤透過呼叫鏈的執行流程。
6. 搜尋 — 建立混合搜尋索引，以便快速檢索。

支援的程式語言

GitNexus 目前支援以下程式語言：

• TypeScript
• JavaScript
• Python
• Java
• C
• C++
• C#
• Go
• Rust
• PHP
• Swift

工具範例

以下是一些 GitNexus 工具的範例，讓你了解它的強大功能：

• Impact Analysis (影響分析)

  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
  

  選項： maxDepth, minConfidence, relationTypes (CALLS, IMPORTS, EXTENDS, IMPLEMENTS), includeTests

• Process-Grouped Search (流程分組搜尋)

  query({query: "authentication middleware"})
  
  processes:
    - summary: "LoginFlow"
      priority: 0.042
      symbol_count: 4
      process_type: cross_community
      step_count: 7
  
  process_symbols:
    - name: validateUser
      type: Function
      filePath: src/auth/validate.ts
      process_id: proc_login
      step_index: 2
  
  definitions:
    - name: AuthConfig
      type: Interface
      filePath: src/types/auth.ts
  

• Context (360 度符號檢視)

  context({name: "validateUser"})
  
  symbol:
    uid: "Function:validateUser"
    kind: Function
    filePath: src/auth/validate.ts
    startLine: 15
  
  incoming:
    calls: [handleLogin, handleRegister, UserController]
    imports: [authRouter]
  
  outgoing:
    calls: [checkPassword, createSession]
  
  processes:
    - name: LoginFlow (step 2/7)
    - name: RegistrationFlow (step 3/5)
  

• Detect Changes (預提交)

  detect_changes({scope: "all"})
  
  summary:
    changed_count: 12
    affected_count: 3
    changed_files: 4
    risk_level: medium
  
  changed_symbols: [validateUser, AuthService, ...]
  affected_processes: [LoginFlow, RegistrationFlow, ...]
  

• Rename (多檔案)

  rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})
  
  status: success
  files_affected: 5
  total_edits: 8
  graph_edits: 6     (high confidence)
  text_search_edits: 2  (review carefully)
  changes: [...]
  

• Cypher Queries (Cypher 查詢)

  -- 尋找哪些高信賴度的程式碼呼叫了身份驗證函數
  MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
  MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
  WHERE r.confidence > 0.8
  RETURN caller.name, fn.name, r.confidence
  ORDER BY r.confidence DESC
  

• Wiki Generation (Wiki 文件產生)

  # 需要 LLM API 金鑰 (OPENAI_API_KEY, 等等.)
  gitnexus wiki
  
  # 使用自訂模型或供應商
  gitnexus wiki --model gpt-4o
  gitnexus wiki --base-url https://api.anthropic.com/v1
  
  # 強制完全重新生成
  gitnexus wiki --force
  

  Wiki 產生器讀取已索引的圖譜結構，透過 LLM 將檔案分組到模組中，產生每個模組的文件頁面，並建立概覽頁面 — 所有這些都與知識圖譜進行交叉引用。

技術堆疊

以下是 GitNexus 的技術堆疊：

路線圖 (Roadmap)

GitNexus 仍在積極開發中，以下是目前的開發方向：

• 積極開發中
  • [ ] LLM Cluster Enrichment — 透過 LLM API 獲取語義叢集名稱
  • [ ] AST Decorator Detection — 解析 @Controller, @Get 等等
  • [ ] Incremental Indexing — 僅重新索引已變更的檔案
• 近期已完成
  • [X] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
  • [X] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
  • [X] Multi-Repo MCP, Zero-Config Setup, 11 Language Support
  • [X] Community Detection, Process Detection, Confidence Scoring
  • [X] Hybrid Search, Vector Index

安全性與隱私

• CLI：所有操作都在本地機器上運行。 不會進行網路呼叫。 索引儲存在 .gitnexus/ (被 git 忽略)。 全域登錄在 ~/.gitnexus/ 儲存路徑和中繼資料。
• Web：所有操作都在你的瀏覽器中運行。 程式碼不會上傳到任何伺服器。 API 金鑰僅儲存在 localStorage 中。
• 開源 — 你可以自行審閱程式碼。

鳴謝

• Tree-sitter — AST 解析
• KuzuDB — 嵌入式圖譜資料庫，支援向量
• Sigma.js — WebGL 圖譜渲染
• transformers.js — 瀏覽器端機器學習
• Graphology — 圖譜資料結構
• MCP — 模型上下文協議

總結

GitNexus 是一個非常強大的工具，它可以幫助你 提升 AI 助手的能力，讓你更有效地利用 AI 來輔助程式開發。 如果你是正在尋找一種方式，讓你的 AI 助手更了解你的程式碼，那麼 GitNexus 絕對值得一試。

希望這篇文章對你有所幫助！ 祝你程式開發順利！

參考閱讀

https://github.com/abhigyanpatwari/GitNexus