GitNexus 教學手冊（企業級完整版）

版本：v1.6.8（2026-06 基準，含 PDG / Taint Analysis、MCP Trace 工具、Private Repos via PAT、DevContainer、MCP HTTP Server）
適用對象：資深工程師 / 架構師 / DevOps / AI Agent 開發者
授權：PolyForm Noncommercial 1.0.0（企業授權另洽 akonlabs.com）
維護單位：內部 AI 開發組
GitHub：github.com/abhigyanpatwari/GitNexus （⭐ 43.3k+ Stars / 163+ Contributors）
OpenSSF Scorecard：securityscorecards.dev

⚠️ 重要警告：GitNexus 沒有官方加密貨幣、代幣或硬幣。任何在 Pump.fun 或其他平台上使用 GitNexus 名稱的代幣/硬幣，均非本專案或其維護者所屬、認可或建立。請勿購買任何聲稱與 GitNexus 相關的加密貨幣。

目錄

• 第 1 章：GitNexus 概述
  • 1.1 GitNexus 是什麼
  • 1.2 核心理念
  • 1.3 與傳統工具比較
  • 1.4 適用場景
• 第 2 章：系統架構說明
  • 2.1 整體架構圖
  • 2.2 核心組件說明
  • 2.3 Web UI vs CLI 架構差異
  • 2.4 Multi-Repo MCP 架構
• 第 3 章：安裝與環境設定
  • 3.1 系統需求
  • 3.2 CLI 安裝
  • 3.3 Web UI 使用
  • 3.4 MCP 編輯器設定
  • 3.5 Docker 部署
  • 3.6 常見問題排除
• 第 4 章：基本操作教學
  • 4.1 建立 Knowledge Graph
  • 4.2 CLI 常用指令
  • 4.3 查詢程式碼關聯
  • 4.4 視覺化圖譜操作
  • 4.5 Repository 群組管理
• 第 5 章：進階應用
  • 5.1 Graph RAG 使用方式
  • 5.2 Impact Analysis（影響分析）
  • 5.3 Process-Grouped Search
  • 5.4 360 度 Symbol Context
  • 5.5 Git-Diff 變更偵測
  • 5.6 Multi-File Rename
  • 5.7 Cypher 原生查詢
  • 5.8 Wiki 自動生成
  • 5.9 Incremental Indexing（增量索引）
  • 5.10 PDG / 程式依賴圖分析
  • 5.11 Taint Analysis（污染分析）
  • 5.12 Trace（呼叫路徑追蹤）
  • 5.13 Private Repos 與 Azure DevOps Server
  • 5.14 HTTP Route Extraction（HTTP 路由提取）
  • 5.15 DevContainer 開發環境
• 第 6 章：整合企業開發流程
  • 6.1 與 GitHub / GitLab 整合
  • 6.2 與 AI 工具整合
  • 6.3 與開發架構整合
  • 6.4 DevOps 整合
  • 6.5 Community Integrations（社群整合）
  • 6.6 開發文件與貢獻指南
  • 6.7 understand-quickly 公開註冊
• 第 7 章：銀行 / 大型系統應用案例
  • 7.1 案例一：批次系統依賴分析
  • 7.2 案例二：跨系統 API 呼叫分析
  • 7.3 案例三：DB Schema 影響分析
• 第 8 章：安全與隱私（SSDLC）
  • 8.1 Zero-Server 優勢
  • 8.2 原始碼保護
  • 8.3 本地 AI 模型風險
  • 8.4 權限控管建議
  • 8.5 安全強化歷史與已知修復
  • 8.6 Taint Analysis 安全審計應用
  • 8.7 供應鏈保護（Supply-Chain Protection）
• 第 9 章：系統升級與維運
  • 9.1 GitNexus 升級流程
  • 9.2 Graph 重建策略
  • 9.3 Repository 更新同步
  • 9.4 效能優化建議
  • 9.5 LadybugDB 遷移指南
  • 9.6 Edge Type 遷移（OVERRIDES → METHOD_OVERRIDES）
• 第 10 章：最佳實務（Best Practices）
  • 10.1 大型專案使用建議
  • 10.2 Monorepo vs Multi-repo
  • 10.3 團隊導入策略
  • 10.4 使用限制與風險
• 第 11 章：常見問題 FAQ
• 第 12 章：未來發展與建議
  • 12.1 Graph RAG 未來趨勢
  • 12.2 與 Agent 系統整合
  • 12.3 企業導入 Roadmap
• 附錄 A：快速檢查清單（Checklist）
• 附錄 B：CLI 指令速查表
• 附錄 C：MCP 工具速查表
• 附錄 D：語言能力詳細矩陣
• 附錄 E：Edge Type（關係類型）速查表
• 附錄 F：Docker 部署速查表
• 附錄 G：.gitnexusrc 專案配置速查表
• 附錄 H：PDG / Taint 邊類型速查表

第 1 章：GitNexus 概述

1.1 GitNexus 是什麼

🎯 目的：讓團隊成員在 5 分鐘內理解 GitNexus 的定位與價值。

📘 說明

GitNexus 是由 Abhigyan Patwari 發起的開源程式碼智慧引擎（Code Intelligence Engine），核心理念為 Zero-Server（零伺服器）。它能將任何 GitHub 儲存庫或本地程式碼庫轉化為互動式知識圖譜（Knowledge Graph），讓 AI Agent 在進行程式碼分析、修改或重構時，能完整掌握每一個依賴關係、呼叫鏈與執行流程。

官方定義：「Building nervous system for agent context — Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart tools so AI agents never miss code.」

Like DeepWiki, but deeper. DeepWiki 幫助你「理解」程式碼。GitNexus 讓你「分析」程式碼 — 因為知識圖譜追蹤每一個關係，而非僅是描述。

專案統計（截至 2026 年 6 月底）：

核心特點：

最新版本：v1.6.8（2026-06 穩定版）— 含 PDG-backed Impact Analysis、Taint Analysis（Java/Python source/sink）、MCP trace 工具、Private Repos via PAT + Azure DevOps Server、MCP HTTP Server、HTTP Route Extraction、C++ CUDA 支援、FTS Stemmer 可配置、circular import cycle check、custom embeddings provider flags

1.2 核心理念

📘 說明

GitNexus 解決了一個關鍵問題：AI Coding Agent（如 Cursor、Claude Code、Codex、Cline、Roo Code、Windsurf、Antigravity）雖然強大，但不真正理解程式碼庫的結構。

典型情境：

1. AI 修改了 UserService.validate()
2. 不知道有 47 個函式依賴其回傳型別
3. 破壞性變更被部署上線

GitNexus vs 傳統 Graph RAG：

graph LR
    subgraph 傳統 Graph RAG
        A[LLM 發送查詢] --> B[取得圖譜邊]
        B --> C[LLM 自行探索]
        C --> D[可能遺漏上下文]
    end

    subgraph GitNexus 預計算智慧
        E[索引時預計算] --> F[聚類 / 追蹤 / 評分]
        F --> G[工具一次返回完整上下文]
        G --> H[LLM 不會遺漏]
    end

核心創新 — Precomputed Relational Intelligence：

• 可靠性：LLM 無法遺漏上下文，因為已在工具回應中
• Token 效率：無需 10 次查詢鏈才能理解一個函式
• 模型民主化：小型 LLM 也能接收完整架構資訊，使其表現可與大型模型競爭

TL;DR：Web UI 是快速與任何 Repo 對話的工具。CLI + MCP 是讓你的 AI Agent 真正可靠的方式 — 它給 Cursor、Claude Code、Codex、Antigravity 等工具一個深度的架構視角，使它們不再遺漏依賴、破壞呼叫鏈或盲目編輯。甚至較小的模型也能獲得完整的架構清晰度，使其表現可與大型模型競爭。

1.3 與傳統工具比較

📌 關鍵差異：DeepWiki 幫你「理解」程式碼，GitNexus 讓你「分析」程式碼 — 因為知識圖譜追蹤每一個關係，而非僅是描述。Cline / Roo Code 雖有 AI Agent 能力，但缺乏預計算的結構化圖譜，仍依賴即時搜尋和局部上下文。Antigravity（Google）雖具備強大的 Gemini 模型能力，但同樣缺乏預計算的程式碼架構圖譜。

1.4 適用場景

💡 最佳實務：在銀行系統中，建議將 GitNexus 加入 SSDLC 流程的「設計審查」與「變更管理」環節。

⚠️ 注意事項：

• Web UI 瀏覽器模式受記憶體限制（約 5,000 檔案），大型專案請使用 CLI
• 商業使用需取得企業授權

第 2 章：系統架構說明

2.1 整體架構圖

🎯 目的：理解 GitNexus 各組件如何協作。

📘 說明

graph TB
    subgraph 索引層 Index Layer
        FS[檔案系統掃描<br/>Structure] --> TP[Tree-sitter AST 解析<br/>Parsing]
        TP --> RES[跨檔解析<br/>Resolution]
        RES --> CL[社群偵測<br/>Clustering]
        CL --> PR[執行流程追蹤<br/>Processes]
        PR --> SI[混合搜尋索引<br/>Search Index]
    end

    subgraph 儲存層 Storage Layer
        LDB[(LadybugDB<br/>圖譜資料庫)]
        EMB[(Embeddings<br/>向量索引)]
        REG[(Registry<br/>~/.gitnexus/registry.json)]
    end

    subgraph 服務層 Service Layer
        MCP[MCP Server<br/>stdio / HTTP]
        HTTP[HTTP Server<br/>gitnexus serve]
    end

    subgraph 消費層 Consumer Layer
        CC[Claude Code<br/>Full Integration]
        CUR[Cursor<br/>MCP + Skills]
        CDX[Codex<br/>MCP + Skills]
        AG[Antigravity<br/>MCP + Skills + Hooks]
        WS[Windsurf<br/>MCP]
        OC[OpenCode<br/>MCP + Skills]
        WEB[Web UI<br/>Browser]
    end

    SI --> LDB
    SI --> EMB
    SI --> REG
    LDB --> MCP
    EMB --> MCP
    REG --> MCP
    MCP --> CC
    MCP --> CUR
    MCP --> CDX
    MCP --> AG
    MCP --> WS
    MCP --> OC
    HTTP --> WEB
    LDB --> HTTP

2.2 核心組件說明

Parser（程式碼解析）

使用 Tree-sitter 進行 AST（Abstract Syntax Tree）解析，支援原生綁定（CLI）和 WASM（Web UI）兩種模式。

解析能力：

Graph Builder（圖譜建構）

多階段索引流水線：

1. Structure — 掃描檔案樹，映射資料夾 / 檔案關係
2. Parsing — 使用 Tree-sitter AST 提取函式、類別、方法、介面
3. Resolution — 解析 import、函式呼叫、繼承、建構子推斷、self/this receiver 型別，使用語言感知邏輯（language-aware logic）
4. Clustering — 使用 Leiden 社群偵測演算法（基於 Graphology 圖結構庫），將相關符號分組為功能模組
5. Processes — 從入口點追蹤執行流程，建立完整呼叫鏈
6. Search — 建構混合搜尋索引（BM25 + 語義 + RRF）

v1.4.0+ 新增的解析能力：

Embedding Engine

使用 HuggingFace transformers.js 進行向量嵌入：

• CLI：GPU / CPU 加速
• Web UI：WebGPU / WASM

Graph RAG 查詢引擎

17 個 MCP 工具（12 個 per-repo + 5 個 group），透過 Model Context Protocol 暴露給 AI Agent。

完整技術棧（Tech Stack）

2.3 Web UI vs CLI 架構差異

Bridge Mode：執行 gitnexus serve 可連接兩者 — Web UI 自動偵測本地伺服器，瀏覽所有 CLI 索引的 Repo，無需重新上傳或重新索引。

Local Backend Mode：執行 gitnexus serve 後開啟 Web UI — 自動偵測伺服器並顯示所有已索引 Repo，支援完整 AI 對話。Agent 的工具（Cypher 查詢、搜尋、程式碼導航）自動透過後端 HTTP API 路由。

2.4 Multi-Repo MCP 架構

📘 說明

GitNexus 使用全域 Registry，一個 MCP Server 可服務多個已索引的 Repo。

運作機制：

1. 每次 gitnexus analyze 將索引儲存在 Repo 內的 .gitnexus/（已 gitignore）
2. 同時在 ~/.gitnexus/registry.json 註冊指標
3. AI Agent 啟動時，MCP Server 讀取 Registry 並可服務任何已索引 Repo
4. LadybugDB 連線採延遲開啟（Lazy），首次查詢時開啟，閒置 5 分鐘後回收（最大 5 個併發）

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 [專案 Repos]
        RepoA[".gitnexus/ in Repo A"]
        RepoB[".gitnexus/ in Repo B"]
    end

    subgraph MCP [MCP Server]
        Server["server.ts"]
        Backend["LocalBackend"]
        Pool["Connection Pool<br/>（最大 5 個併發）"]
        ConnA["LadybugDB conn A"]
        ConnB["LadybugDB conn B"]
    end

    Setup -->|"寫入全域 MCP 配置"| CursorConfig["~/.cursor/mcp.json"]
    Analyze -->|"註冊 Repo"| RegFile
    Analyze -->|"儲存索引"| RepoA
    Clean -->|"取消註冊 Repo"| RegFile
    List -->|"讀取"| RegFile
    Server -->|"讀取 Registry"| RegFile
    Server --> Backend
    Backend --> Pool
    Pool -->|"延遲開啟"| ConnA
    Pool -->|"延遲開啟"| ConnB
    ConnA -->|"查詢"| RepoA
    ConnB -->|"查詢"| RepoB

💡 最佳實務：當只有一個 Repo 被索引時，所有工具的 repo 參數可省略。多 Repo 時需指定：query({query: "auth", repo: "my-app"})。

第 3 章：安裝與環境設定

3.1 系統需求

🎯 目的：確認環境符合最低需求。

3.2 CLI 安裝

🛠️ 操作步驟

方法一：全域安裝（推薦）

npm install -g gitnexus

方法二：使用 npx（免安裝）

npx gitnexus analyze

方法三：從原始碼建置（進階）

git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus
npm install
npm run build
npm link

驗證安裝：

gitnexus --version
# 應輸出 v1.6.8 或更新版本

3.3 Web UI 使用

🛠️ 操作步驟

方法一：線上版（免安裝）

直接訪問：https://gitnexus.vercel.app/

操作流程：

1. 開啟瀏覽器訪問上述 URL
2. 拖放 ZIP 檔案或輸入 GitHub Repo URL
3. 等待索引完成
4. 開始探索圖譜和 AI 對話

方法二：本地建置

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

方法三：Bridge Mode（推薦大型專案）

# 先用 CLI 索引 Repo
cd /path/to/your/repo
gitnexus analyze

# 啟動 HTTP Server
gitnexus serve

# 開啟 Web UI（自動偵測本地 Server）
# 瀏覽器訪問 http://localhost:3000

3.4 MCP 編輯器設定

🛠️ 操作步驟

自動設定（推薦）

gitnexus setup

此指令會自動偵測已安裝的編輯器並寫入正確的 MCP 配置。只需執行一次。

# 指定只設定 Claude Code（跳過偵測其他編輯器）
gitnexus setup -c claude

💡 提示：-c / --client 參數可指定單一編輯器（claude、cursor、codex、windsurf、opencode、antigravity），避免偵測所有編輯器的等待時間。

MCP HTTP Server（v1.6.8+）

除了 stdio 模式外，v1.6.8 起新增 Streamable HTTP 傳輸：

gitnexus mcp --http          # 預設 port 3100
gitnexus mcp --http --port 8080  # 自訂 port

適用場景：

• 遠端 Agent 存取（非本機 stdio）
• 多個 Agent 同時共用一個 MCP Server
• 部署在 Docker / Kubernetes 中由外部 Agent 呼叫

手動設定

Claude Code（完整支援 — MCP + Skills + Hooks）：

# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

Codex（完整支援 — MCP + Skills）：

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

Cursor（~/.cursor/mcp.json）：

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

OpenCode（~/.config/opencode/config.json）：

{
  "mcp": {
    "gitnexus": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

Codex（~/.codex/config.toml）：

[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]

Antigravity (Google)（~/.gemini/antigravity/mcp_config.json）：

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

💡 Antigravity Hooks 說明：gitnexus setup 會自動在 ~/.gemini/settings.json 中合併 AfterTool 項目（遏循 Gemini CLI hooks schema），並將 Skill 安裝至 ~/.gemini/antigravity/skills/。現有使用者 Hooks 會被保留。Augmentation 在 AfterTool 運行，因為 BeforeTool 在 Gemini 協定中沒有上下文注入通道 — Agent 透過 hookSpecificOutput.additionalContext 看到圖譜上下文。

編輯器支援程度

💡 最佳實務：Claude Code 獲得最深度整合：MCP 工具 + Agent Skills + PreToolUse Hooks（以圖譜上下文豐富搜尋） + PostToolUse Hooks（commit 後偵測過期索引並提示 Agent 重新索引）。

💡 提示：建議全域安裝 gitnexus（npm i -g gitnexus）後執行 gitnexus setup — 這會寫入絕對路徑 MCP 配置，完全繞過 npx。下方的 npx 片段為快速開始的備用方案；在冷快取下，npx 安裝可能超過 Claude Code 的 MCP_TIMEOUT 預設值（~30 秒）。

💡 快速安裝提示：設定 GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 後執行 npm install -g gitnexus，可跳過原生 tree-sitter-dart、tree-sitter-proto 和 tree-sitter-swift 編譯。Dart/Proto/Swift 檔案將不被解析，但安裝可在數秒內完成，無需 python3/make/g++。嚴格限定 =1 — 其他值將觸發重新編譯。

3.5 Docker 部署

🎯 目的：使用 Docker 一鍵部署 GitNexus 服務端與 Web UI。

📘 說明

GitNexus 提供官方 Docker 設定，包含兩個已簽章的映像檔，由 docker-compose.yaml 編排。每個映像檔同時發布至 GitHub Container Registry（GHCR）和 Docker Hub — 相同的建置、相同的摘要、相同的 Cosign 簽章。

映像檔清單：

方法一：Docker Compose 一鍵部署（推薦）

docker compose up -d

此命令會啟動：

• Server：http://localhost:4747
• Web UI：http://localhost:4173

Web UI 會自動偵測本地伺服器，因為瀏覽器在主機上執行並透過映射的端口連接容器。

持久化儲存：命名卷（gitnexus-data）在伺服器容器內的 /data/gitnexus 持久化全域 Registry、索引和克隆的 Repo。

掛載主機 Repo：

# 使主機上的 Repo 可被索引
WORKSPACE_DIR=$HOME/code docker compose up -d

# 在容器內索引掛載的 Repo（以唯讀方式掛載於 /workspace）
docker compose exec gitnexus-server gitnexus index /workspace/my-repo

方法二：直接 docker run

# Server
docker run --rm -d \
  --name gitnexus-server \
  -p 4747:4747 \
  -v gitnexus-data:/data/gitnexus \
  ghcr.io/abhigyanpatwari/gitnexus:latest

# Web UI
docker run --rm -d \
  --name gitnexus-web \
  -p 4173:4173 \
  ghcr.io/abhigyanpatwari/gitnexus-web:latest

環境變數配置

cp .env.example .env
docker compose --env-file .env up -d

可覆寫映像標籤、容器名稱、端口和工作區掛載目錄。

映像版本鎖定與供應鏈保護

• 穩定映像僅從 vX.Y.Z Git 標籤發布（透過 docker.yml 觸發），工作流程拒絕建置除非標籤完全匹配 gitnexus/package.json 的版本
• RC 映像（如 :1.7.0-rc.1）與每個 RC npm 發布一同發布
• :latest 僅從非預發布標籤自動升級
• 所有映像使用 Cosign keyless signing 簽章，附帶建置出處證明和 SBOM 認證

驗證簽章：

cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.8 \
  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Kubernetes 部署

對於 Kubernetes 部署，可使用內建的 ClusterImagePolicy，搭配 Sigstore policy-controller 拒絕任何未經此 Repo 的 docker.yml 從 vX.Y.Z 標籤簽章的 GitNexus Pod。

# 1. 安裝 controller（一次性，叢集範圍）
helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
helm install policy-controller -n cosign-system --create-namespace \
  sigstore/policy-controller

# 2. 啟用命名空間
kubectl label namespace <your-ns> policy.sigstore.dev/include=true

# 3. 套用策略
kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml

Docker 相關檔案：

⚠️ 注意事項：

• 早期版本在 ghcr.io/abhigyanpatwari/gitnexus 下發布 Web UI。自引入綁定後端後，該 slug 現在託管 CLI/Server 映像，UI 已移至 ghcr.io/abhigyanpatwari/gitnexus-web
• 舊標籤仍可拉取，但新版本僅發布在新 slug 下

3.6 常見問題排除

⚠️ 注意事項：

• .gitnexus/ 資料夾已預設加入 .gitignore，不會被提交
• 全域 Registry 僅儲存路徑和 metadata，不含原始碼

第 4 章：基本操作教學

4.1 建立 Knowledge Graph

🎯 目的：學會索引一個 Repository 並建立知識圖譜。

🛠️ 操作步驟

# Step 1：切換到 Repo 根目錄
cd /path/to/your/repo

# Step 2：執行索引（一鍵完成）
npx gitnexus analyze

此指令會自動完成：

1. 掃描檔案樹結構
2. 使用 Tree-sitter 解析 AST
3. 解析跨檔 import / 呼叫 / 繼承關係（含 3-Tier Resolver）
4. 執行 Leiden 社群偵測（Clustering）
5. 追蹤執行流程（Process Detection）
6. 建構混合搜尋索引（BM25 + 語義 + RRF）
7. 安裝 Agent Skills（.claude/skills/gitnexus/）
8. 註冊 Claude Code Hooks（PreToolUse + PostToolUse）
9. 建立 AGENTS.md / CLAUDE.md 上下文檔案
10. 註冊到全域 Registry（~/.gitnexus/registry.json）

自動安裝的 4 個 Agent Skills：

進階選項：

# 強制完全重新索引
gitnexus analyze --force

# 生成 Repo 特定的 Skill 檔案（基於偵測到的社群）
gitnexus analyze --skills

# 跳過 Embedding 生成（更快）
gitnexus analyze --skip-embeddings

# 啟用 Embedding 生成（更慢，但搜尋更精確）
gitnexus analyze --embeddings

# 保留自訂的 AGENTS.md / CLAUDE.md 內容
gitnexus analyze --skip-agents-md

# 索引非 Git 儲存庫的資料夾
gitnexus analyze --skip-git

# 增加 worker 閒置逾時（適用於大型或複雜的 Repo）
gitnexus analyze --worker-timeout 60

# 設定 worker 池大小
gitnexus analyze --workers 8

# 僅重建 / 驗證 FTS 索引（快速修復路徑）
gitnexus analyze --repair-fts

# 控制 LadybugDB WAL 自動檢查點閾值（預設 64 MiB）
gitnexus analyze --wal-checkpoint-threshold 67108864

# 顯示跳過的檔案（當解析器不可用時）
gitnexus analyze --verbose

💡 最佳實務：

• 首次索引建議使用 --skip-embeddings 加速，確認基本功能正常後再啟用
• 使用 --skills 可為每個功能模組生成專屬的 SKILL.md（儲存於 .claude/skills/generated/）
• 使用 --skip-agents-md 可保留自訂的 AGENTS.md / CLAUDE.md 內容
• Skills 在每次 --skills 執行時會依據最新程式碼庫重新生成

Repo-Specific Skills：

執行 gitnexus analyze --skills 時，GitNexus 會透過 Leiden 社群偵測辨識程式碼庫的功能區域，並為每個區域在 .claude/skills/generated/ 下生成一個 SKILL.md。每個 Skill 描述該模組的關鍵檔案、入口點、執行流程和跨區域連結，讓 AI Agent 獲得精確的模組上下文。

4.2 CLI 常用指令

📘 完整指令一覽

# ===== 設定 =====
gitnexus setup                      # 設定 MCP 編輯器（一次性）

# ===== 索引 =====
gitnexus analyze [path]             # 索引 Repository（或更新過期索引）
gitnexus analyze --force            # 強制完全重新索引
gitnexus analyze --repair-fts       # 快速路徑：僅重建 / 驗證 FTS 索引
gitnexus analyze --skills           # 生成 Repo 特定 Skill 檔案
gitnexus analyze --skip-embeddings  # 跳過 Embedding（更快）
gitnexus analyze --embeddings       # 啟用 Embedding（更精確）
gitnexus analyze --skip-agents-md   # 保留自訂 AGENTS.md/CLAUDE.md 內容
gitnexus analyze --skip-git         # 索引非 Git 儲存庫的資料夾
gitnexus analyze --verbose          # 顯示跳過的檔案
gitnexus analyze --worker-timeout 60  # 增加 worker 閒置逾時（秒）
gitnexus analyze --workers <n>      # 解析 worker 池大小（預設：cores-1，上限 16；0 = 序列）
gitnexus analyze --wal-checkpoint-threshold 67108864  # LadybugDB WAL 自動檢查點閾值（預設 64 MiB）

# ===== 服務 =====
gitnexus mcp                        # 啟動 MCP Server（stdio）— 服務所有已索引 Repo
gitnexus serve                      # 啟動本地 HTTP Server（Multi-Repo）供 Web UI 連接

# ===== 狀態 =====
gitnexus list                       # 列出所有已索引 Repository
gitnexus status                     # 顯示當前 Repo 索引狀態

# ===== 清理 =====
gitnexus clean                      # 刪除當前 Repo 索引
gitnexus clean --all --force        # 刪除所有索引

# ===== Wiki =====
gitnexus wiki [path]                # 從知識圖譜生成 Wiki
gitnexus wiki --model gpt-4o        # 指定 LLM 模型
gitnexus wiki --base-url <url>      # 自訂 LLM API URL
gitnexus wiki --force               # 強制重新生成
gitnexus wiki --timeout <seconds>   # 每次嘗試的 LLM 請求逾時秒數（預設 60）
gitnexus wiki --retries <n>         # 最大 LLM 重試次數（預設 3）
gitnexus wiki --lang <lang>         # 輸出語言（如 english, chinese, spanish, japanese）

# ===== 解除安裝（v1.6.7+）=====
gitnexus uninstall                  # 完整移除：清除 Registry、Skills、MCP 配置、Hooks，引導 npm uninstall -g

# ===== 發布 =====
gitnexus publish                    # 通知 understand-quickly 登錄（opt-in）

# ===== Repository 群組 =====
gitnexus group create <name>                          # 建立群組
gitnexus group add <group> <groupPath> <registryName> # 加入 Repo 到群組（groupPath 為層級路徑，registryName 為 registry 中的名稱）
gitnexus group remove <group> <groupPath>             # 從群組依層級路徑移除 Repo
gitnexus group list [name]                            # 列出群組
gitnexus group sync <name>                            # 跨 Repo 契約同步
gitnexus group contracts <name>                       # 檢視跨 Repo 契約
gitnexus group query <name> <q>                       # 跨群組搜尋
gitnexus group status <name>                          # 檢查群組過期狀態

環境變數一覽

大多數 analyze 參數也可透過環境變數設定。CLI 旗標優先於環境變數，環境變數優先於內建預設值。

4.3 查詢程式碼關聯

🛠️ 操作步驟

透過 MCP 工具（在 AI Agent 中使用），GitNexus 提供以下查詢能力：

混合搜尋（query）

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

360 度符號檢視（context）

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)

4.4 視覺化圖譜操作

📘 說明

Web UI 使用 Sigma.js + Graphology（WebGL） 進行即時圖譜渲染。

操作方式：

1. 開啟 Web UI（gitnexus.vercel.app 或本地 gitnexus serve）
2. 載入 Repository（拖放 ZIP 或指定 GitHub URL）
3. 等待索引完成後，圖譜自動顯示
4. 互動操作：
   • 縮放：滾輪調整視角
   • 拖拽：移動畫布或節點
   • 點擊節點：檢視符號詳細資訊
   • 搜尋：在搜尋框輸入函式名或類別名
   • AI 對話：使用內建 Chat 功能詢問程式碼問題

💡 最佳實務：

• 大型 Repo 建議使用 Bridge Mode，避免瀏覽器記憶體不足
• 使用社群過濾器篩選特定功能模組

4.5 Repository 群組管理

🎯 目的：管理跨 Repo / 微服務的統一分析。

🛠️ 操作步驟

# 建立群組
gitnexus group create banking-platform

# 加入各服務 Repo（groupPath 為層級路徑，registryName 為 gitnexus list 中的名稱）
gitnexus group add banking-platform gateway/api api-gateway
gitnexus group add banking-platform services/user user-service
gitnexus group add banking-platform services/payment payment-service
gitnexus group add banking-platform batch/settlement batch-service

# 跨 Repo 契約同步（偵測 API 呼叫關係）
gitnexus group sync banking-platform

# 檢視跨服務契約
gitnexus group contracts banking-platform

# 跨服務搜尋
gitnexus group query banking-platform "轉帳流程"

# 檢查過期狀態
gitnexus group status banking-platform

⚠️ 注意事項：

• 每個 Repo 需先個別執行 gitnexus analyze
• 群組同步會提取各 Repo 的 API 契約並建立跨服務連結

第 5 章：進階應用

5.1 Graph RAG 使用方式

🎯 目的：掌握基於知識圖譜的 RAG 查詢，取得精確的程式碼分析結果。

📘 說明

GitNexus 的 Graph RAG 與傳統 RAG 的差異：

問答範例：

在 AI Agent（如 Claude Code）中直接提問：

# 範例 1：API 服務呼叫分析
「這個 UserController 呼叫了哪些服務？」

# 範例 2：資料庫依賴分析
「payment-service 依賴哪些 DB Table？」

# 範例 3：影響範圍評估
「如果我修改 AuthService.validate() 的回傳型別，會影響哪些功能？」

# 範例 4：執行流程追蹤
「從登入 API 到資料庫寫入的完整呼叫鏈是什麼？」

💡 最佳實務：

• 對於大型系統，建議先使用 query 找到相關模組，再用 context 深入分析特定符號
• 使用 impact 進行變更前評估是最高價值的使用場景

5.2 Impact Analysis（影響分析）

🎯 目的：在修改程式碼前，精確評估爆炸半徑。

🛠️ MCP 工具使用

impact({
  target: "UserService",
  direction: "upstream",      // upstream=誰依賴我, downstream=我依賴誰
  minConfidence: 0.8,         // 最低信心分數
  maxDepth: 3,                // 最大追蹤深度
  relationTypes: ["CALLS", "IMPORTS", "EXTENDS", "IMPLEMENTS", "METHOD_OVERRIDES", "METHOD_IMPLEMENTS"],
  includeTests: false,        // 是否包含測試
  limit: 100,                 // 每層最大符號數（預設 100）
  offset: 0,                  // 分頁起始位置
  summaryOnly: false          // 僅顯示計數與風險，省略符號列表
})

消歧義（Disambiguation）：

當多個符號共享相同名稱時，impact 會返回排名的 ambiguous 候選列表，而非猜測。可使用以下參數縮小範圍：

# CLI 範例
gitnexus impact get_embeddings                       # → ambiguous: 列出排名候選
gitnexus impact get_embeddings --file src/embed.py   # → 解析至該檔案中的符號
gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings"  # 精確指定

輸出範例：

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

實務應用情境：

5.3 Process-Grouped Search

📘 說明

搜尋結果不再是零散的符號列表，而是按**執行流程（Process）**分組。

query({query: "payment processing"})

回傳結構：

processes:
  - summary: "PaymentFlow"
    priority: 0.089
    symbol_count: 8
    process_type: cross_community
    step_count: 12

process_symbols:
  - name: processPayment
    type: Function
    filePath: src/payment/processor.ts
    process_id: proc_payment
    step_index: 1

  - name: validateAmount
    type: Function
    filePath: src/payment/validator.ts
    process_id: proc_payment
    step_index: 2

5.4 360 度 Symbol Context

📘 說明

取得一個符號的完整上下文 — 誰呼叫它、它呼叫誰、參與哪些流程。

context({name: "processPayment"})

symbol:
  uid: "Function:processPayment"
  kind: Function
  filePath: src/payment/processor.ts
  startLine: 42

incoming:
  calls: [PaymentController.create, BatchJobRunner.execute]
  imports: [paymentRouter]

outgoing:
  calls: [validateAmount, debitAccount, creditAccount, logTransaction]

processes:
  - name: PaymentFlow (step 1/12)
  - name: BatchSettlement (step 3/8)

5.5 Git-Diff 變更偵測

🎯 目的：在 commit 前分析變更的影響範圍。

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, ...]

💡 最佳實務：

• 在 PR 提交前執行 detect_changes，可作為 Code Review 的輔助資訊
• 可整合至 CI/CD Pipeline 自動執行

5.6 Multi-File Rename

📘 說明

基於圖譜的智慧重新命名 — 跨檔案協調更名。

rename({
  symbol_name: "validateUser",
  new_name: "verifyUser",
  dry_run: true   // 先預覽，不實際修改
})

輸出：

status: success
files_affected: 5
total_edits: 8
graph_edits: 6        # 高信心度（基於圖譜）
text_search_edits: 2  # 需人工檢查（基於文字搜尋）
changes: [...]

5.7 Cypher 原生查詢

📘 說明

直接使用 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

常用 Cypher 查詢範例：

-- 找出所有入口點
MATCH (n) WHERE n.isEntryPoint = true
RETURN n.name, n.kind, n.filePath

-- 找出某個類別的所有子類別
MATCH (child)-[:CodeRelation {type: 'EXTENDS'}]->(parent {name: 'BaseService'})
RETURN child.name, child.filePath

-- 找出某個介面的所有實作（METHOD_IMPLEMENTS）
MATCH (impl)-[:CodeRelation {type: 'METHOD_IMPLEMENTS'}]->(iface {name: 'PaymentGateway'})
RETURN impl.name, impl.filePath

-- 找出方法覆寫關係（METHOD_OVERRIDES）
MATCH (child_method)-[:CodeRelation {type: 'METHOD_OVERRIDES'}]->(parent_method)
RETURN child_method.name, child_method.filePath, parent_method.name, parent_method.filePath

-- 找出跨社群呼叫（潛在的架構邊界）
MATCH (a)-[:CodeRelation {type: 'MEMBER_OF'}]->(c1:Community),
      (b)-[:CodeRelation {type: 'MEMBER_OF'}]->(c2:Community),
      (a)-[:CodeRelation {type: 'CALLS'}]->(b)
WHERE c1 <> c2
RETURN a.name, c1.heuristicLabel, b.name, c2.heuristicLabel

-- 找出所有 HAS_METHOD 關係（類別的方法成員）
MATCH (cls)-[:CodeRelation {type: 'HAS_METHOD'}]->(method)
WHERE cls.name = 'UserService'
RETURN method.name, method.kind, method.startLine

-- 統計各社群的符號數量
MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
RETURN c.heuristicLabel, count(n) AS member_count
ORDER BY member_count DESC

5.8 Wiki 自動生成

🎯 目的：從知識圖譜自動產出 Repository 文件。

# 需要 LLM API Key（OPENAI_API_KEY 等）
gitnexus wiki

# 自訂 LLM 模型
gitnexus wiki --model gpt-4o

# 自訂 API 端點
gitnexus wiki --base-url https://api.anthropic.com/v1

# 強制重新生成
gitnexus wiki --force

# 指定輸出語言
gitnexus wiki --lang chinese

生成流程：

1. 讀取已索引的圖譜結構
2. 透過 LLM 將檔案分組為模組
3. 為每個模組生成文件頁面
4. 建立總覽頁面
5. 交叉引用知識圖譜

⚠️ 注意事項：

• Wiki 生成需要 LLM API 連線（如 OPENAI_API_KEY）
• 預設使用 gpt-4o-mini 模型
• 支援 Azure OpenAI — 使用簡化的 3 步驟互動設定（endpoint、deployment、key）
• v1.5.3 修復了 Wiki HTML 查看器中的 </script> 注入問題
• v1.6.4+ 新增 --timeout 和 --retries 旗標，適用於大型程式碼庫或慢速 LLM 供應商
• --lang 旗標可指定輸出語言（如 english、chinese、spanish、japanese）

企業版額外功能：

• Auto-updating Code Wiki — 文件自動保持最新（此功能 OSS 版本亦提供基礎支援）

5.9 Incremental Indexing（增量索引）

🎯 目的：僅重新索引變更的檔案，大幅縮短索引時間。

📘 說明

Incremental Indexing 是 GitNexus 近期完成的重要功能，透過 parse cache 和 DB writeback 機制，僅重新處理自上次索引以來變更的檔案。

運作機制：

1. Parse Cache — 首次索引後，每個檔案的 AST 解析結果被快取
2. 變更偵測 — 後續執行 gitnexus analyze 時，比較檔案的修改時間戳和雜湊值
3. 選擇性重新解析 — 僅對變更的檔案重新執行 Tree-sitter 解析
4. DB Writeback — 只更新圖譜資料庫中受影響的節點和邊
5. Scope-based 處理 — 限定重新計算的範圍（聚類、流程追蹤等）
6. Parse Cache 分片（Sharding） — 大型 Mono-repo（>50,000 檔案）自動將 parse cache 分片為多個 shard 檔案，避免單一快取檔案過大導致 I/O 瓶頸

使用方式：

# 自動偵測變更並增量更新（預設行為）
gitnexus analyze

# 如需強制完全重建（跳過增量邏輯）
gitnexus analyze --force

效能提升：

💡 最佳實務：

• 日常開發時直接使用 gitnexus analyze（自動增量）
• 大版本升級或索引格式變更時使用 --force
• Claude Code 的 PostToolUse Hook 會在 commit 後偵測過期索引並提示重新索引

5.10 PDG / 程式依賴圖分析

🎯 目的：透過 Program Dependence Graph（PDG）進行更精確的影響分析與資料流追蹤。

📘 說明

v1.6.8 引入完整的 PDG 基礎設施，包含：

• CFG（Control Flow Graph）：每個函式的基本區塊（BasicBlock）與控制流邊
• Reaching Definitions：追蹤變數定義到達使用點的路徑
• Control Dependence：標記哪些語句的執行取決於哪些條件分支

PDG 為 opt-in 功能，需在索引時啟用：

# 索引時啟用 PDG 建構
gitnexus analyze --pdg

# 使用 PDG-backed impact analysis
impact({symbol: "processPayment", mode: "pdg"})

PDG 邊類型：

PDG vs 傳統 Impact Analysis 差異：

5.11 Taint Analysis（污染分析）

🎯 目的：追蹤不受信任的資料（Taint Source）是否能流向敏感操作（Taint Sink），檢測潛在的安全漏洞。

📘 說明

v1.6.8 在 PDG 基礎上實作了 Taint Analysis，支援 intra-procedural（函式內）和 inter-procedural（跨函式）追蹤。

使用方式：

# 索引時需啟用 PDG
gitnexus analyze --pdg

# 在 MCP 工具中查詢污染路徑
impact({symbol: "getUserInput", mode: "pdg"})

預設 Source / Sink 模型（v1.6.8）：

污染傳播規則：

• 賦值傳播：x = tainted_value → x 被標記為 tainted
• 函式傳播（inter-procedural）：tainted 參數透過呼叫圖傳遞
• Sanitizer 中斷：通過已知的消毒函式後，taint 標記被清除

⚠️ 注意：Taint Analysis 為 v1.6.8 首次引入的功能，目前覆蓋 Java 和 Python 的常見 source/sink 模型。v1.6.9 計畫擴充更多語言和框架模型。

5.12 Trace（呼叫路徑追蹤）

🎯 目的：追蹤兩個符號之間的最短呼叫路徑，用於理解程式碼的執行流。

📘 說明

v1.6.8 新增 MCP trace 工具，使用 Directed BFS 在呼叫圖上搜尋最短路徑。

使用方式（MCP 工具）：

trace({from: "handleRequest", to: "saveToDatabase"})

回傳結果範例：

path:
  - handleRequest (src/api/handler.ts:42)
  - validateInput (src/api/validator.ts:15)
  - processData (src/service/processor.ts:88)
  - saveToDatabase (src/db/repository.ts:23)
hops: 3

典型應用場景：

• 理解 API 請求的完整處理流程
• 追蹤特定錯誤可能的傳播路徑
• 審查敏感操作的呼叫鏈（搭配 Taint Analysis）

5.13 Private Repos 與 Azure DevOps Server

🎯 目的：索引私有 GitHub Repository 或 Azure DevOps Server 上的程式碼。

📘 說明

v1.6.8 新增透過 Personal Access Token（PAT）存取私有 Repo 的能力，並支援 Azure DevOps Server（on-premises）。

GitHub Private Repo：

# 透過 PAT 索引私有 Repo
GITHUB_TOKEN=ghp_xxxx gitnexus analyze --repo https://github.com/myorg/private-repo

Azure DevOps Server：

# Azure DevOps Server（on-premises）
AZURE_DEVOPS_TOKEN=xxx gitnexus analyze --repo https://dev.azure.com/myorg/project/_git/repo

認證方式：

💡 企業最佳實務：在 CI/CD Pipeline 中使用 Service Account 的 PAT，並限定最小權限範圍（read-only）。Token 透過環境變數傳入，不應寫入配置檔。

5.14 HTTP Route Extraction（HTTP 路由提取）

🎯 目的：自動從程式碼中提取 HTTP API 路由定義，建立路由與處理函式的映射。

📘 說明

v1.6.8 新增對主流後端框架的 HTTP 路由自動提取：

提取結果會自動加入知識圖譜，建立以下關係：

• HTTP_ROUTE 節點 → 與處理函式的 HANDLES 邊
• 路由參數（path params、query params）的型別資訊

查詢範例：

# 搜尋所有 POST 路由
cypher({query: "MATCH (r:HTTP_ROUTE {method: 'POST'})-[:HANDLES]->(f:Function) RETURN r.path, f.name"})

5.15 DevContainer 開發環境

🎯 目的：使用預配置的開發容器快速建立一致的 GitNexus 開發環境。

📘 說明

v1.6.6 起 GitNexus Repo 內建 .devcontainer/ 配置，預裝：

• Node.js 20 LTS
• Claude Code CLI
• Codex CLI
• Cursor CLI
• 所有必要的 Tree-sitter 原生依賴

使用方式：

1. 在 VS Code 中開啟 GitNexus Repo
2. 點選 “Reopen in Container”
3. 容器自動安裝所有依賴並設定 MCP

💡 提示：DevContainer 同時適用於 GitHub Codespaces，可在瀏覽器中直接開發。

第 6 章：整合企業開發流程

6.1 與 GitHub / GitLab 整合

🎯 目的：將 GitNexus 嵌入日常 Git 工作流程。

PR Review 分析

場景：開發者提交 PR，需要評估變更影響。

作法：

# Step 1：在 PR 分支上重新索引
git checkout feature/update-auth
gitnexus analyze

# Step 2：使用 detect_changes 分析變更
# （在 AI Agent 中自動完成）

AI Agent 會自動執行：

1. detect_changes({scope: "all"}) 偵測變更
2. impact({target: "changed_symbol"}) 分析每個變更符號的影響
3. 產出影響報告

企業版功能：

• 自動化 PR Review — 自動產生爆炸半徑分析報告
• Auto-reindexing — 知識圖譜自動保持最新

Code Impact 分析

sequenceDiagram
    participant Dev as 開發者
    participant GH as GitHub PR
    participant GN as GitNexus
    participant AI as AI Agent

    Dev->>GH: 提交 PR
    GH->>GN: 觸發 analyze
    GN->>GN: 更新知識圖譜
    GN->>AI: detect_changes
    AI->>AI: impact analysis
    AI->>GH: 自動產出 Review 建議
    GH->>Dev: 變更影響報告

6.2 與 AI 工具整合

GitHub Copilot 整合

GitNexus 透過 MCP 提供上下文給 Copilot，使其在以下場景更精確：

• 程式碼生成：Copilot 了解現有架構，生成符合專案慣例的程式碼
• Bug 修復：Copilot 可追蹤完整呼叫鏈，定位根因
• 重構建議：Copilot 了解依賴關係，提出安全的重構方案

Claude Code 整合（最深度）

Claude Code 支援最完整的整合：

Cursor 整合

在 Cursor 中使用 GitNexus：

1. 設定 MCP（參見 3.4 節）
2. 在 Cursor Chat 中即可直接使用 GitNexus 工具
3. Cursor 會自動利用圖譜上下文改善回應品質

Antigravity (Google) 整合

Antigravity 是 Gemini CLI 的後繼產品，GitNexus 提供完整支援：

設定方式：執行 gitnexus setup 自動完成 MCP 配置和 Hook 安裝，或手動編輯 ~/.gemini/antigravity/mcp_config.json（參見 3.4 節）。

PR Reviewer Swarm Agents（v1.6.5+）

GitNexus v1.6.5 新增了 PR Reviewer Swarm Agents 功能，支援多 Agent 協作進行 PR 審查：

相關檔案：

• pr-swarm-review/ — PR Reviewer Swarm Agents 配置目錄
• .claude/ — Claude Code 審查 Agent 設定
• .cursor/ — Cursor 審查 Agent 設定

6.3 與開發架構整合

Spring Boot 微服務

實務應用：

# 索引整個微服務群
gitnexus group create my-platform
gitnexus group add my-platform gateway/api api-gateway
gitnexus group add my-platform services/user user-service
gitnexus group add my-platform services/order order-service
gitnexus group add my-platform services/payment payment-service

# 同步跨服務契約
gitnexus group sync my-platform

# 分析跨服務呼叫
gitnexus group query my-platform "訂單建立到付款完成的流程"

GitNexus 支援 Spring Boot 的 Framework Pattern Detection：

• 識別 @Controller、@Service、@Repository 註解
• 偵測 @GetMapping、@PostMapping 等 API 端點
• 追蹤 Service → Repository → Database 呼叫鏈

FastAPI 整合

GitNexus 對 Python 的支援同樣完整：

• 識別路由裝飾器（@app.get、@router.post）
• 追蹤依賴注入（Depends()）
• 解析 Pydantic 模型關係

Vue 微前端

• 解析 Vue SFC（Single File Component）
• 追蹤 Composable / Store 依賴
• 識別路由配置和元件關係

6.4 DevOps 整合

CI/CD 前分析

在 CI Pipeline 中加入 GitNexus 分析：

# GitHub Actions 範例
name: GitNexus Impact Analysis
on: pull_request

jobs:
  impact-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g gitnexus
      - run: gitnexus analyze --skip-embeddings
      - run: gitnexus status

自動化文件生成

# 定期自動更新 Wiki
name: Auto Wiki Update
on:
  schedule:
    - cron: '0 2 * * 1'  # 每週一凌晨 2 點

jobs:
  wiki:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g gitnexus
      - run: gitnexus analyze --skip-embeddings
      - run: gitnexus wiki --model gpt-4o-mini
      - run: |
          git add docs/wiki/
          git commit -m "docs: auto-update wiki"
          git push

⚠️ 注意事項：

• CI 環境中建議使用 --skip-embeddings 加速
• Wiki 生成需設定 OPENAI_API_KEY 環境變數

6.5 Community Integrations（社群整合）

📘 說明

以下為社群建構的整合專案 — 非官方維護，但值得參考：

💡 提示：如有基於 GitNexus 建構的專案，可至 GitHub 提交 PR 新增至此列表。

6.6 開發文件與貢獻指南

📘 說明

GitNexus 提供完善的開發者文件體系：

專案結構概覽：

6.7 understand-quickly 公開註冊

📘 說明

looptech-ai/understand-quickly 是一個公開的程式碼知識圖譜登錄處，將 gitnexus@1 列為第一級格式。

使用方式：

1. 註冊 Repo（一次性）：

   npx @understand-quickly/cli add

   或使用 線上精靈

2. 發布通知：

   gitnexus publish

   此命令發送一個 repository_dispatch 事件，讓登錄處按需重新同步您的條目，而非等待每日排程。

前提條件：

• 需要設定 UNDERSTAND_QUICKLY_TOKEN 環境變數 — 一個細粒度的 GitHub PAT，具有 Repository dispatches: write 權限
• 此功能為 opt-in（選擇加入），未設定 Token 時為 no-op
• 不會上傳任何圖譜檔案，僅觸發同步事件

📌 詳細規格：參見 protocol spec

第 7 章：銀行 / 大型系統應用案例

7.1 案例一：批次系統依賴分析

問題描述

某銀行核心系統有 200+ 個 Batch Job，每日排程執行。其中一個 Job DailySettlement 需要修改結算邏輯，但無人清楚該 Job 的完整依賴鏈。

使用 GitNexus 解法

# Step 1：索引批次系統 Repo
cd /path/to/batch-system
gitnexus analyze --skills

# Step 2：在 AI Agent 中分析

在 Claude Code 中執行：

# 查詢 DailySettlement 的完整上下文
context({name: "DailySettlement"})

# 影響分析 — 上游（誰依賴它）
impact({target: "DailySettlement", direction: "upstream", maxDepth: 5})

# 影響分析 — 下游（它依賴誰）
impact({target: "DailySettlement", direction: "downstream", maxDepth: 5})

分析結果

TARGET: Class DailySettlement (src/batch/settlement/DailySettlement.java)

DOWNSTREAM (dependencies):
  Depth 1:
    AccountRepository [CALLS 95%] -> src/repository/AccountRepository.java
    TransactionService [CALLS 90%] -> src/service/TransactionService.java
    SettlementCalculator [CALLS 88%] -> src/batch/settlement/Calculator.java
  Depth 2:
    OracleDataSource [CALLS 92%] -> src/config/DataSourceConfig.java
    AuditLogger [CALLS 85%] -> src/audit/AuditLogger.java

UPSTREAM (dependents):
  Depth 1:
    MonthlyReport [CALLS 90%] -> src/batch/report/MonthlyReport.java
    SettlementNotifier [CALLS 85%] -> src/notification/SettlementNotifier.java
  Depth 2:
    ReportScheduler [CALLS 80%] -> src/scheduler/ReportScheduler.java

帶來的效益

7.2 案例二：跨系統 API 呼叫分析

問題描述

銀行要升級「客戶資料服務」的 API 版本（v1 → v2），需要知道哪些系統呼叫了該 API。

使用 GitNexus 解法

# 建立跨服務群組
gitnexus group create customer-platform
gitnexus group add customer-platform customer-service
gitnexus group add customer-platform loan-service
gitnexus group add customer-platform card-service
gitnexus group add customer-platform mobile-app-bff

# 同步跨服務契約
gitnexus group sync customer-platform

# 查詢跨服務影響
gitnexus group query customer-platform "CustomerAPI v1"

分析結果

跨服務影響分析：

customer-service（API 提供者）：
  - GET /api/v1/customers/{id}  → 被 3 個服務呼叫
  - POST /api/v1/customers      → 被 2 個服務呼叫
  - PUT /api/v1/customers/{id}  → 被 1 個服務呼叫

loan-service（消費者）：
  - CustomerClient.getById()     → 呼叫 GET /api/v1/customers/{id}
  - CustomerClient.update()      → 呼叫 PUT /api/v1/customers/{id}

card-service（消費者）：
  - CustomerAdapter.fetch()      → 呼叫 GET /api/v1/customers/{id}

mobile-app-bff（消費者）：
  - CustomerProxy.getCustomer()  → 呼叫 GET /api/v1/customers/{id}
  - CustomerProxy.register()     → 呼叫 POST /api/v1/customers

帶來的效益

• 精確定位所有 API 消費者，無一遺漏
• 產出明確的遷移計畫：哪些服務需要優先修改
• 降低 API 升級導致的系統中斷風險

7.3 案例三：DB Schema 影響分析

問題描述

DBA 需要修改 ACCOUNT 表的欄位 balance 型別（從 DECIMAL(15,2) 改為 DECIMAL(18,4)），需評估程式碼端影響。

使用 GitNexus 解法

-- 使用 Cypher 查找所有引用 ACCOUNT 表或 balance 欄位的程式碼
MATCH (n)-[r:CodeRelation]->(m)
WHERE n.name CONTAINS 'Account' OR n.name CONTAINS 'balance'
RETURN n.name, n.kind, n.filePath, type(r), m.name
ORDER BY n.filePath

搭配 AI Agent 對話：

「找出所有讀寫 ACCOUNT 表 balance 欄位的程式碼，包含 Repository、Service、DTO 和 API」

分析結果

帶來的效益

• 變更前完整評估影響，避免精度遺失造成的金額計算錯誤
• 產出明確的修改清單，逐一追蹤修改進度

第 8 章：安全與隱私（SSDLC）

8.1 Zero-Server 優勢

🎯 目的：理解 GitNexus 的隱私保護機制。

8.2 原始碼保護

📘 說明

• 原始碼永遠不離開本地環境 — GitNexus 不會將任何程式碼傳送到外部伺服器
• .gitnexus/ 資料夾預設加入 .gitignore，不會被意外提交
• 全域 Registry（~/.gitnexus/registry.json）僅儲存 Repo 路徑和 metadata
• 開源專案，可自行審計程式碼

企業級建議：

# 確認 .gitignore 包含 .gitnexus/
echo ".gitnexus/" >> .gitignore

# 確認 Registry 不包含敏感資訊
cat ~/.gitnexus/registry.json

8.3 本地 AI 模型風險

8.4 權限控管建議

企業部署建議：

1. 開發者本機

   • 各開發者在自己的機器上執行 GitNexus
   • 索引資料不共享

2. 團隊共享環境

   • 使用企業版（akonlabs.com）的自託管部署
   • RBAC 控管 Repo 存取權限
   • 審計日誌追蹤使用行為

3. CI/CD 環境

   • 使用短暫的容器環境
   • 索引在 Pipeline 結束後自動清除
   • API Key 透過 Secret Manager 管理

4. API Key 管理

   • Wiki 生成所需的 LLM API Key 使用環境變數注入
   • 不在程式碼或配置檔中明文記錄 API Key
   • 設定 API Key 的使用限額

8.5 安全強化歷史與已知修復

📘 說明

GitNexus 團隊持續進行安全強化，以下為重要的安全修復記錄：

MCP Transport 安全架構：

GitNexus 的 CompatibleStdioServerTransport 採用雙框架（Dual-Framing）設計：

• 自動偵測 Content-Length（Codex / OpenCode）和換行分隔 JSON（Cursor / Claude Code）框架
• 於首條訊息偵測後以相同格式回應
• 13 個單元測試覆蓋傳輸框架、安全強化、緩衝區限制

8.6 Taint Analysis 安全審計應用

🎯 目的：利用 PDG / Taint Analysis 進行程式碼安全審計。

v1.6.8 的 Taint Analysis 可作為 SSDLC 的靜態分析工具：

SSDLC 整合建議：

# 在 CI Pipeline 中啟用 PDG 索引 + Taint 分析
gitnexus analyze --pdg
# 透過 Cypher 查詢 taint 路徑
cypher({query: "MATCH p=(s:TaintSource)-[:TAINT_FLOW*]->(k:TaintSink) RETURN p"})

企業安全建議：

8.7 供應鏈保護（Supply-Chain Protection）

🎯 目的：確保 GitNexus 映像檔和套件的真實性與完整性。

📘 說明

GitNexus 實施多層供應鏈保護措施：

Cosign Keyless 簽章

所有 Docker 映像使用 Cosign keyless signing 進行簽章，使用工作流程的 GitHub OIDC 身份。即使攻擊者在其他地方重新發布同名映像（或推送到拼寫錯誤的 Registry），也無法偽造與 abhigyanpatwari/GitNexus 的 docker.yml 綁定的 Cosign 簽章。

SBOM 與建置出處證明

每個映像附帶：

• SBOM（Software Bill of Materials） — 軟體物料清單
• SLSA Provenance v1 — 建置出處證明

# 檢查建置出處
cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.5 \
  --predicate-type https://slsa.dev/provenance/v1

OpenSSF Scorecard

GitNexus 已加入 OpenSSF Scorecard，定期評估專案的安全實踐。

npm 套件版本鎖定

Docker 映像版本鎖定至 npm 套件：ghcr.io/abhigyanpatwari/gitnexus:1.6.5 與 npm install gitnexus@1.6.5 是同一個版本 — 無漂移、無浮動建置。

Kubernetes Admission 控制

使用 Sigstore policy-controller 在 Kubernetes 叢集層級強制執行簽章驗證（詳見 3.5 節 Kubernetes 部署）。

企業安全建議（增訂）：

第 9 章：系統升級與維運

9.1 GitNexus 升級流程

🛠️ 操作步驟

# 檢查當前版本
gitnexus --version

# 升級到最新版本
npm update -g gitnexus

# 或使用 npx（始終使用最新版）
npx gitnexus@latest analyze

升級後建議：

# 重新索引所有 Repo（建議，但非必要 — 增量索引會自動處理）
gitnexus analyze --force

# 驗證 MCP 正常
gitnexus mcp

完整解除安裝（v1.6.7+）：

# 一鍵清除 Registry、Skills、MCP 配置、Hooks，並引導 npm uninstall -g
gitnexus uninstall

⚠️ 注意事項：

• 大版本升級可能變更索引格式，建議使用 --force 重新索引
• 參考 CHANGELOG.md 了解版本變更
• 參考 MIGRATION.md 了解遷移指南

9.2 Graph 重建策略

9.3 Repository 更新同步

📘 說明

GitNexus 目前的索引策略：

• gitnexus analyze（不帶 --force）支援 Incremental Indexing — 自動偵測變更的檔案並僅重新索引
• 透過 parse cache + DB writeback 機制，大幅縮短後續索引時間
• Claude Code 的 PostToolUse Hook 會在 commit 後偵測過期索引並提示 Agent 重新索引

建議的同步流程：

# 開發前：確認索引是最新的
gitnexus status

# 如果過期：重新索引
gitnexus analyze

# 大規模合併後：強制重建
gitnexus analyze --force

9.4 效能優化建議

9.5 LadybugDB 遷移指南

📘 說明

GitNexus 已從 KuzuDB 完成遷移至 LadybugDB（@ladybugdb/core、@ladybugdb/wasm-core）。

變更內容：

遷移步驟：

# 升級後，舊的 KuzuDB 索引將自動清理
# 只需執行強制重建即可
gitnexus analyze --force

注意事項：

• 從舊版升級後首次需要使用 --force 重新索引
• 舊的 KuzuDB 索引檔案會自動清除
• LadybugDB 需要顯式載入 VECTOR extension 才能使用語義搜尋

9.6 Edge Type 遷移（OVERRIDES → METHOD_OVERRIDES）

📘 說明

自 PR #642 起，OVERRIDES 關係類型已重新命名為 METHOD_OVERRIDES，以與新的 METHOD_IMPLEMENTS 邊類型保持一致。

是否需要手動遷移？

不需要。 向後相容性在執行時自動處理：

• local-backend.ts 在所有影響分析和上下文查詢中同時讀取 OVERRIDES 和 METHOD_OVERRIDES
• schema-constants.ts 中的 REL_TYPES 陣列包含兩個名稱，因此引用任一名稱的 Cypher 查詢都能正常運作
• 現有儲存圖譜中的 OVERRIDES 邊繼續返回正確結果，無需手動介入

重新索引後的行為：

執行 npx gitnexus analyze 將產生 METHOD_OVERRIDES 邊。舊的 OVERRIDES 邊將在正常的完整重新索引過程中被替換。

Legacy 別名移除時程：

OVERRIDES 相容別名將保留到未來的主要版本。移除前會在 MIGRATION.md 和 CHANGELOG 中公告。

第 10 章：最佳實務（Best Practices）

10.1 大型專案使用建議

1. 首次索引使用 --skip-embeddings，確認基本功能正常後再啟用
2. 大型 Repo（>50,000 檔案）使用 CLI，不要使用 Web UI 瀏覽器模式
3. 啟用 --skills 為每個功能模組生成專屬 Skill 檔案
4. 定期重新索引（建議每日或每次大規模合併後）
5. 使用 Repository Group 管理微服務架構
6. 使用 --workers <n> 根據 CPU 核心數調整並行 Worker 數量，提升大型 Repo 索引速度

Self-Healing Worker Pool（v1.6.5+）：

GitNexus v1.6.5 引入了自癒式 Worker 池機制，針對大型 Repo 索引時的穩定性進行強化：

10.2 Monorepo vs Multi-repo

10.3 團隊導入策略

graph TD
    A[Phase 1<br/>技術驗證 POC] --> B[Phase 2<br/>先導團隊]
    B --> C[Phase 3<br/>全面推廣]
    C --> D[Phase 4<br/>流程整合]

    A1[選擇 1-2 個 Repo<br/>安裝 CLI + MCP] --> A
    B1[3-5 人團隊使用<br/>建立內部最佳實務] --> B
    C1[全團隊安裝<br/>CI/CD 整合] --> C
    D1[PR Review 標準化<br/>Wiki 自動生成<br/>Impact Analysis 必做] --> D

導入步驟：

1. Phase 1（1 週）：選擇 1-2 個中型 Repo 進行 POC
2. Phase 2（2-4 週）：先導團隊使用，收集回饋
3. Phase 3（4-8 週）：全團隊推廣，建立 SOP
4. Phase 4（持續）：整合至 CI/CD、PR Review 流程

10.4 使用限制與風險

第 11 章：常見問題 FAQ

Q1：Graph 太大怎麼辦？

A：

1. 使用 --skip-embeddings 減少索引大小
2. 確認 .gitignore 排除 node_modules、build 等非程式碼目錄
3. 考慮使用 Repository Group 將 Monorepo 拆分為多個獨立索引
4. 增加機器記憶體（建議 16 GB+）

Q2：查詢速度慢？

A：

1. 確認使用 SSD 磁碟
2. 使用 --skip-embeddings 停用語義搜尋（改用 BM25）
3. 限制 maxDepth 參數避免深層遍歷
4. 對特定模組使用 --skills 生成 Skill 縮小查詢範圍

Q3：AI 回答不準？

A：

1. 確認索引是最新的：gitnexus status
2. 啟用 Embedding：gitnexus analyze --embeddings
3. 使用 --skills 生成模組 Skill，讓 AI 獲得更精確的上下文
4. 提供更具體的問題，而非泛泛而問

Q4：如何提升準確度？

A：

1. 使用 gitnexus analyze --skills --embeddings 完整索引
2. 為程式碼添加型別註解（尤其是 Python、JavaScript）
3. 使用 Cypher 進行精確查詢而非自然語言搜尋
4. 定期重新索引保持圖譜最新

Q5：Windows 環境有特殊設定嗎？

A：

• MCP 設定使用 cmd /c npx 前綴：

  claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

• 建議 Repo 路徑不含中文或空格
• 使用 PowerShell 或 Git Bash 執行 CLI

Q6：支援離線使用嗎？

A：

• CLI 索引和 MCP 查詢完全離線
• Embedding 模型首次使用需下載（之後快取在本地）
• Wiki 生成需要 LLM API 連線
• Web UI 線上版需要網路，本地版可離線

Q7：如何與企業 Proxy 搭配使用？

A：

• npm 設定 Proxy：npm config set proxy http://proxy:port
• 或預先安裝 gitnexus，之後完全離線使用
• Embedding 模型可手動下載放置到快取目錄

Q8：OVERRIDES 和 METHOD_OVERRIDES 的差異？

A：

• OVERRIDES 為舊版邊類型名稱，已在 PR #642 中重新命名為 METHOD_OVERRIDES
• 新命名是為了與新增的 METHOD_IMPLEMENTS 邊類型保持一致
• 向後相容性自動處理 — 現有圖譜中的 OVERRIDES 邊仍可正常查詢
• 重新索引後會自動使用新名稱
• 詳見 MIGRATION.md

Q9：如何處理動態語言（Python / JavaScript）的精確度問題？

A：

1. 為程式碼添加型別註解（Type Annotations）— GitNexus 的 Receiver-Constrained Resolution 會利用這些資訊
2. v1.4.0 的 3-Tier Resolver 已大幅提升精確度（精確 FQN → scope-walk → 受保護模糊回退）
3. 使用 Constructor Inference 自動推斷型別（包含 self/this 解析）
4. 對於無法自動解析的情況，使用 Cypher 手動補充查詢

Q10：GitNexus 和 GitHub Copilot 可以同時使用嗎？

A：

• 可以。GitNexus 透過 MCP 提供結構化的程式碼上下文，與 Copilot 的即時程式碼補全互補
• GitNexus 負責提供架構級理解（呼叫鏈、依賴圖），Copilot 負責程式碼生成
• 兩者同時使用可顯著提升 AI 輔助開發的準確性

Q11：LadybugDB 和 KuzuDB 的關係？

A：

• LadybugDB 是 GitNexus 目前使用的嵌入式圖譜資料庫（含向量支援）
• 前身為 KuzuDB，已完成遷移
• 儲存路徑從 .gitnexus/kuzu 變更為 .gitnexus/lbug
• 升級後執行 gitnexus analyze --force 即可自動遷移

Q12：Docker 部署和本地安裝有什麼差別？

A：

• Docker 部署適合團隊共享環境和生產部署，提供一鍵啟動 Server + Web UI
• 本地安裝（npm install -g gitnexus）適合個人開發，與 AI Agent 的 MCP 整合更直接
• Docker 映像附帶 Cosign 簽章和 SBOM，適合對供應鏈安全有要求的企業環境
• 兩者可並存：Docker 用於 Server + Web UI，本地 CLI 用於日常開發

Q13：什麼是 Incremental Indexing？

A：

• 增量索引是 v1.6.x 新增的功能，透過 parse cache 僅重新處理變更的檔案
• 直接執行 gitnexus analyze（不帶 --force）即自動啟用
• 可將索引時間從分鐘級降至秒級
• 使用 --force 可強制完全重建

Q14：如何索引非 Git 儲存庫的資料夾？

A：

• 使用 gitnexus analyze --skip-git 旗標
• 此選項會將當前工作目錄視為索引根目錄，而非向上查找 Git 根目錄

Q15：Antigravity（Google）和 Gemini CLI 有什麼不同？

A：

• Antigravity 是 Google Gemini CLI 的後繼產品，提供更完整的 Agent 體驗
• GitNexus 對 Antigravity 提供完整支援，包含 MCP Tools、Agent Skills 和 AfterTool Hooks
• 設定方式與 Gemini CLI 類似 — 配置檔位於 ~/.gemini/antigravity/mcp_config.json
• AfterTool Hooks 能在工具執行後自動附加圖譜上下文，並在 commit 後偵測過期索引

Q16：PR Reviewer Swarm Agents 是什麼？

A：

• v1.6.5 新增的多 Agent 協作 PR 審查功能
• 多個專業 Agent 各自負責不同面向（架構、安全、效能等）的審查
• 利用知識圖譜進行爆炸半徑分析，確保審查精確涵蓋影響範圍
• 配置檔位於 pr-swarm-review/、.claude/ 和 .cursor/ 目錄

Q17：Impact Analysis 出現 ambiguous 結果時該怎麼辦？

A：

• 當多個符號同名時，impact 工具會回傳排名的候選列表而非猜測
• 使用 --uid 精確指定目標符號（零歧義）
• 使用 --file 依檔案路徑縮小範圍
• 使用 --kind 依類型（Function、Class、Method 等）篩選

Q18：PDG 和 Taint Analysis 需要額外設定嗎？

A：

• PDG 和 Taint Analysis 為 opt-in 功能，需在索引時加上 --pdg 旗標
• 啟用後索引時間會增加（需建構 CFG + PDG），但後續的影響分析精確度大幅提升
• Taint Analysis 目前支援 Java 和 Python 的常見 source/sink 模型
• 使用 impact({symbol: "xxx", mode: "pdg"}) 啟用 PDG-backed 影響分析

Q19：MCP HTTP Server 和 stdio 模式有什麼差異？

A：

• stdio 模式（預設）：MCP Server 作為子行程透過標準輸入/輸出通訊，適合本機 Agent 整合
• HTTP 模式（v1.6.8+）：gitnexus mcp --http 啟動 Streamable HTTP 服務，適合遠端 Agent、多 Agent 共用、Docker/K8s 部署
• HTTP 模式預設使用 port 3100，可透過 --port 自訂
• 兩種模式提供完全相同的 17 個 MCP 工具

Q20：如何索引私有 GitHub Repository？

A：

• v1.6.8 起支援透過 Personal Access Token（PAT）存取私有 Repo
• 設定 GITHUB_TOKEN 環境變數後直接執行 gitnexus analyze --repo <url>
• PAT 需具備 repo scope 權限
• 同時支援 Azure DevOps Server（使用 AZURE_DEVOPS_TOKEN）

Q21：trace 工具和 impact 工具有什麼不同？

A：

• trace 追蹤兩個指定符號之間的最短呼叫路徑（A → … → B），回傳完整的呼叫鏈
• impact 分析單一符號變更的爆炸半徑（A → 所有受影響的符號）
• 兩者互補：先用 impact 確認影響範圍，再用 trace 理解特定路徑
• trace 使用 Directed BFS 演算法，impact 可選用 PDG 模式進行語句層級分析

Q22：npm 11.x 安裝 GitNexus 失敗怎麼辦？

A：

• npm 11 預設啟用 --omit=optional，導致 tree-sitter 原生綁定編譯失敗
• 解決方案一：降級至 npm 10（推薦）
• 解決方案二：執行 npm config set omit="" 後重新安裝
• 解決方案三：設定 GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 跳過可選語法（Dart/Proto/Swift 將不被解析）

第 12 章：未來發展與建議

12.1 Graph RAG 未來趨勢

目前 Roadmap（官方）：

企業版功能（akonlabs.com）：

💬 企業授權聯絡：Discord 或 Email: founders@akonlabs.com

12.2 與 Agent 系統整合

未來趨勢：

1. Multi-Agent Collaboration：多個 AI Agent 共享同一知識圖譜（v1.6.5 PR Reviewer Swarm Agents 已實現初步版本）
2. Agentic Workflow：AI Agent 自動化完成 analyze → impact → refactor → test 流程
3. Continuous Intelligence：知識圖譜隨程式碼變更即時更新（Claude Code PostToolUse Hook 已部分實現）
4. Cross-Organization Graph：跨組織的知識圖譜聯邦查詢
5. 全編輯器覆蓋：目前已支援 Claude Code、Cursor、Windsurf、Cline、Copilot、Roo Code、Codex、OpenCode、Antigravity 等 9+ 編輯器 / Agent，未來將持續擴展

12.3 企業導入 Roadmap

gantt
    title GitNexus 企業導入建議時程
    dateFormat  YYYY-MM
    section Phase 1 - 評估
    技術 POC              :a1, 2026-04, 2w
    安全審查              :a2, after a1, 1w
    授權確認              :a3, after a2, 1w
    section Phase 2 - 先導
    先導團隊（3-5人）     :b1, after a3, 4w
    建立內部 SOP          :b2, after b1, 2w
    section Phase 3 - 推廣
    全團隊推廣            :c1, after b2, 4w
    CI/CD 整合            :c2, after b2, 3w
    section Phase 4 - 優化
    PR Review 標準化      :d1, after c1, 4w
    Wiki 自動化           :d2, after c2, 4w
    持續優化              :d3, after d1, 8w

建議優先導入場景：

附錄 A：快速檢查清單（Checklist）

安裝與設定

• Node.js 18+ 已安裝
• npm install -g gitnexus 完成（或使用 Docker 部署）
• gitnexus --version 確認版本
• gitnexus setup 配置 MCP
• 驗證 AI Agent 可使用 GitNexus 工具

Docker 部署（選用）

• docker compose up -d 啟動服務
• 確認 http://localhost:4747 健康檢查通過
• 確認 http://localhost:4173 Web UI 可訪問
• 映像簽章已驗證（cosign verify）

首次索引

• 切換到 Repo 根目錄
• 執行 gitnexus analyze
• 執行 gitnexus status 確認索引狀態
• 在 AI Agent 中測試 query 工具
• 在 AI Agent 中測試 impact 工具

團隊導入

• 選定 POC Repo
• 先導團隊完成安裝
• 建立內部使用 SOP
• CI/CD Pipeline 加入 GitNexus
• PR Review 流程加入 Impact Analysis
• 定期重新索引排程設定

安全合規

• .gitnexus/ 已加入 .gitignore
• 確認無原始碼外洩風險
• LLM API Key 使用環境變數管理
• 企業授權確認（如需商業使用）
• Docker 映像使用 Cosign 簽章驗證（如使用 Docker）
• Kubernetes 部署已配置 ClusterImagePolicy（如使用 K8s）

日常使用

• 每日或合併後重新索引
• PR 提交前執行 Impact Analysis
• 定期更新 GitNexus 版本
• 定期重新生成 Wiki

版本升級

• 查閱 CHANGELOG.md
• 查閱 MIGRATION.md
• 執行 npm update -g gitnexus
• 執行 gitnexus analyze --force 重建索引
• 確認 MCP 正常運作

附錄 B：CLI 指令速查表

附錄 C：MCP 工具速查表

Per-Repo 工具（12 個）

Group 工具（5 個）

MCP Resources

MCP Prompts

Agent Skills（自動安裝）

提示：使用 gitnexus analyze --skills 可額外生成 Repo 專屬的模組 Skill。

附錄 D：語言能力詳細矩陣

以下為各語言支援的解析能力詳細對照：

註：OCaml 僅在企業版中支援。各欄位含義請參見第 2.2 節 Parser 能力說明。

各能力欄位說明：

附錄 E：Edge Type（關係類型）速查表

GitNexus 知識圖譜中使用的所有關係類型：

信心分數（Confidence Score）：

每個 CALLS 邊附帶信心分數（0.0 - 1.0），表示解析的確定程度：

附錄 F：Docker 部署速查表

端口對照：

環境變數：

附錄 G：.gitnexusrc 專案配置速查表

v1.6.6 起支援在專案根目錄放置 .gitnexusrc 檔案（JSON 格式），提供專案級配置：

{
  "skip": ["vendor/**", "dist/**", "*.generated.ts"],
  "skipEmbeddings": false,
  "pdg": true,
  "workers": 8,
  "maxFileSize": 1024,
  "ftsStemmer": "none",
  "skills": true
}

💡 提示：.gitnexusrc 的設定會被 CLI 旗標和環境變數覆蓋。優先順序：CLI 旗標 > 環境變數 > .gitnexusrc > 內建預設值。

附錄 H：PDG / Taint 邊類型速查表

PDG 節點類型：

文件維護：本手冊應隨 GitNexus 版本更新而同步更新，建議每季度或大版本發布時檢視內容。
官方 GitHub：https://github.com/abhigyanpatwari/GitNexus
企業版：akonlabs.com — SaaS 或自託管部署
Discord 社群：discord.gg/MgJrmsqr62
安全政策：SECURITY.md
企業授權聯絡：founders@akonlabs.com
最後更新：2026-06-30