【2026 最新】GitNexus 教學：Blast Radius 比 grep／LSP 準嗎？四題實測

你請 Coding Agent 改一個核心函式，它把目標檔改對、測試也變綠，兩天後另一條結帳流程卻壞了。問題往往不是 Agent 不會寫程式，而是它一開始就沒看見足夠的 Blast Radius（變更波及範圍）。這時候只用文字搜尋會不會漏掉呼叫路徑？LSP 的「尋找所有參照」又能不能跨過多層依賴？這正是這篇 GitNexus 教學要回答的問題。

這篇 GitNexus 教學會帶你在拋棄式 Repo 建立可判分的 Ground Truth，再讓 rg、LSP 與 GitNexus v1.6.10 跑同一組任務。你不必先懂 Graph RAG；只要會開終端機、知道要改哪個函式，就能跟著做。重點不是選出一個永遠最準的工具，而是知道每種工具看得見什麼、看不見什麼，以及最後該用什麼證據放行改版。

先說結論：GitNexus 不是 grep／LSP 的替代品

• rg適合先廣撒網：它找字串很快，能抓到註解、設定與動態字串，也會帶來同名雜訊；它不知道兩行程式碼是否真的有呼叫關係。
• LSP 適合查語言內的語意參照：在專案與型別資訊完整時，它能分清同名符號；但結果受語言伺服器、Workspace 邊界與動態派送影響。
• GitNexus 適合把多跳關係排成審查順序：impact、context與trace能沿預先建立的圖往上游追，但輸出可能是 lower-bound、截斷或模糊比對，圖上的邊也不等於「這個檔案一定會壞」。
• 可靠的放行條件仍是測試與人工驗收：本文的錨點是「Blast Radius 信心＝固定 Ground Truth × 三路搜尋 × Tests 驗收」。三路工具負責找候選，測試提供已覆蓋行為的證據。

截至 2026 年 8 月 30 日，npm 的穩定版是 GitNexus 1.6.10，本文固定在對應 Commit 6088d2e，不混用主分支上的候選功能。先固定版本，才有可能重跑同一個結果。

Graph RAG 到底多看見了什麼？

先把三種方法想成三張不同的地圖。rg像搜尋整座城市所有同名招牌；LSP 像戶政資料，知道某個名字實際指向哪個人；GitNexus 則把函式、類別、檔案、模組與執行流程畫成關係圖，再沿著邊找上游呼叫者。

GitNexus 的 v1.6.10 官方文件列出 17 個 MCP 工具；這篇只需要四個：query用自然語言找相關流程、context看單一符號的呼叫者與被呼叫者、impact沿依賴圖估算波及範圍、trace找兩個符號之間的最短有向路徑。Graph RAG 的價值不是把整個 Repo 塞進 Prompt，而是先用圖縮小「下一批值得讀的程式碼」。想先理解 Agent 為何需要這一層，可搭配 Context Repo 教學與 Graph Engineering 入門。

但圖不是執行時真相。靜態分析很難完整還原反射、字串拼接、依賴注入、事件匯流排與跨程序呼叫；官方工具本身也會用 exact或lower-bound標示證據強度。看到 LOW 風險或空結果時，正確反應不是直接刪除函式，而是回到文字搜尋、LSP 與測試補洞。

先設計考卷：沒有 Ground Truth，就沒有準確率

直接拿一個陌生大型 Repo 問「改這裡會影響哪裡」，再憑答案看起來像不像，不能叫準確率。你必須先知道正解。最實用的做法是把測試分成兩層：

1. 控制題：在拋棄式分支建立一條你完全知道的呼叫鏈，例如 API → Service → 計價函式 → 測試，再放入同名字串、同名函式與動態呼叫當干擾。這一層能算 Recall 與 Precision。
2. 真實題：挑一個已合併、已有測試與 Code Review 的歷史改版，切回改版前一個 Commit，讓三種工具預測應讀檔案。這一層檢查方法能否搬到真實 Repo，但不要把「當年實際修改的檔案」誤當唯一正解。

令正解集合為 G，工具回報集合為 P。Recall 是 |P ∩ G| ÷ |G|，回答「該找的有找到多少」；Precision 是 |P ∩ G| ÷ |P|，回答「找回來的候選有多少真的相關」。重構前通常先守 Recall，因為漏掉一個呼叫者可能造成事故；Repo 很大、Context 很貴時，再用 Precision 控制閱讀量。若你想把這套方法接到 Agent 評測，可延伸讀 AI Evals 新手教學。

GitNexus 教學第 1 步：只在拋棄式副本建索引

先建立獨立 Clone，固定 Repo Commit，並記錄版本。不要在唯一工作副本直接跑快速安裝；也不要先執行 setup。以下命令不會替你刪除任何資料：

git clone <REPO_URL> repo-gitnexus-lab
cd repo-gitnexus-lab
git switch --detach <BASE_SHA>

node --version
git --version
git rev-parse HEAD
git status --short
npx -y gitnexus@1.6.10 --version

GitNexus 1.6.10 的 npm 套件要求 Node ^22.18.0或>=24.11.0。接著使用 --index-only；在這個版本中，Embeddings 預設關閉，所以不用加不存在的 --skip-embeddings旗標。

npx -y gitnexus@1.6.10 analyze --index-only --name blast-radius-lab
npx -y gitnexus@1.6.10 status --json
git status --short
find .gitnexus -maxdepth 2 -type f -print

--index-only的精確承諾，是跳過 AGENTS.md、CLAUDE.md 與 Skills 等 AI Context 注入；它仍會在 Repo 建立 .gitnexus/索引，並使用使用者層的 GitNexus 登錄資訊。範例同時用 --name blast-radius-lab固定登錄名稱，避免帳號已登錄多個 Repo 時查錯目標。因此它是「縮小寫入範圍」，不是「完全零寫入」。若公司 Repo 對工具安裝有管制，先在隔離 VM、容器或專用測試帳號完成這一步。

官方快速流程的 setup會寫入 Coding Agent 的 MCP 設定；一般 analyze還可能注入規則與 Skills。本文刻意分開：先用 CLI 完成 A/B，確認值得留下，再決定是否接 MCP。這也符合 大型 Repo 安全重構流程的原則：先建立可回滾邊界，再讓 Agent 擴大權限。

GitNexus 教學第 2 步：讓三路工具回答同一題

A 路：用 rg 建立文字搜尋 Baseline

ripgrep 官方指南把它定位為遞迴、逐行的 Regex 搜尋器。先搜完整符號名，再搜 import 路徑、事件名與設定鍵；把註解、文件、測試與產生檔分開計數，避免把雜訊當命中。

rg -n --hidden --glob '!node_modules' --glob '!.git' \
  'calculatePrice|pricing/calculatePrice|PRICE_UPDATED' .

記錄「命中的檔案集合」而不只記行數。同一檔案出現十次，對檔案層 Precision 仍只算一個候選。

B 路：用 LSP 找語意參照

在 VS Code 把游標放到目標符號，執行「Find All References」（預設 Shift+F12），匯出檔案清單。LSP 本身是編輯器與語言伺服器之間的協定；實際準確度取決於背後的語言伺服器與它載入的 Project。LSP 3.18 規格定義了 References 請求，卻不保證每種語言、反射或多 Repo Workspace 都能得到同樣結果。

測試時要記錄語言伺服器版本、Workspace Root、是否載入所有 package，以及測試檔是否包含在專案設定。若同一個 Monorepo 有多個語言，請分語言跑，不要把某一個 LSP 的空結果外推成全 Repo 無影響。

C 路：用 GitNexus 查 Context、Impact、Trace

npx -y gitnexus@1.6.10 context calculatePrice \
  --repo blast-radius-lab \
  --file src/pricing/calculatePrice.ts --limit 200

npx -y gitnexus@1.6.10 impact calculatePrice \
  --repo blast-radius-lab \
  --file src/pricing/calculatePrice.ts \
  --direction upstream --depth 3 --include-tests --limit 200

npx -y gitnexus@1.6.10 trace CheckoutController calculatePrice \
  --repo blast-radius-lab \
  --from-file src/checkout/CheckoutController.ts \
  --to-file src/pricing/calculatePrice.ts --depth 10 --include-tests

請先把範例裡的函式名與路徑換成自己的目標。用 context確認選到正確符號；同名函式很多時，加 --file或改用工具回傳的 UID。再用 impact取得上游候選，最後用 trace驗證你關心的兩個端點之間是否存在圖路徑。自然語言 query適合找流程，不適合直接拿來算檔案 Precision，因為它的任務本來就是排名與摘要。

本文比較的是 v1.6.10 的本機 CLI／索引結果，不把 Web UI 的同名 impact混進分數。穩定版原始碼中，Web 與 MCP／CLI 的查詢深度、上限與失敗回報並不完全相同；同樣寫著 depth 3，也不該當成同一份考卷。

三路結果：受控題能回答什麼？

AlphaLab 在隔離目錄鎖定 Hono Commit e2740d5，掃到 360 個受追蹤 TypeScript 檔、84,319 行 TypeScript。GitNexus 1.6.10 的 --index-only在這台 Apple Silicon 主機回報 54.4 秒完成，建立 7,293 個 Nodes、22,124 條 Edges、430 個 Clusters 與 624 條 Flows；同一次索引也明確警告部分 Flow 因預算截斷，因此本文沒有把流程數當完整真相。

四題分別把匯出的 compose、mergePath、createNullObject與getRuntimeKey定義改成 *_MUTATED，每題都在獨立 Worktree 比較 TypeScript 5.9.3 的修改前後診斷。Hono 依賴沒有另外安裝，基準版本本來就有診斷；本文只把「Mutation 新增、基準沒有」的診斷檔案當 Ground Truth，共有 18 個 case×file 正例。接著用精確符號字串的 rg、TypeScript Language Service References、GitNexus impact --depth 1與--depth 3對同一集合判分。所有 Patch、原始輸出、時間紀錄與評分檔都保留在本次工作目錄。

這裡測的是預先建立的 Code Graph 遍歷，不是完整的 Graph RAG 系統分數。本輪沒有開啟 Embeddings，也沒有把自然語言 query納入 Precision／Recall；因此結果只回答 impact在這四題找直接與多跳候選的表現，不能拿來證明向量檢索或 Agent 最終答案品質。

這組直接參照題的答案很清楚：TypeScript LSP 的 Recall／Precision 都是 100%；GitNexus depth 1 的 Recall 是 94.4%、Precision 是 100%，漏掉 mergePath所在檔案內的一個參照；rg的 Recall 是 100%、Precision 是 75%。把 GitNexus 擴到 depth 3 沒有補回那一漏，case×file 候選卻從 17 增到 40。

這不代表 depth 3 多出的 23 個 case×file 候選都「錯」：它們是圖上的間接審查候選，只是定義改名後沒有產生本文定義的直接 TypeScript 診斷。若改看不重複檔案，depth 1 是 16 檔、depth 3 是 37 檔，增加 21 檔。因為這份 Oracle 沒有判定所有間接行為，本文不替 depth 3 硬算通用 Precision；若只看直接正例密度，17/40 是 42.5%，但那不等於 23 個額外 case×file 候選皆為 False Positive。反過來，GitNexus 確實用 trace找出 verifying → importPublicKey → isCryptoKey → getRuntimeKey的三跳路徑，這是單純 References 清單沒有整理出的流程資訊。最合理的用法是：LSP 守直接參照，GitNexus 排多跳閱讀順序，rg補圖與型別系統外的字串。

還有一個重要細節：漏掉同檔案參照的 GitNexus 結果仍標成 epistemic: exact。這裡的 exact 只能讀成「對目前索引圖的遍歷是精確的」，不能讀成「對真實程式所有影響都完整」。同樣地，compose被評為 LOW，定義改名後仍新增 3 個檔案診斷；Risk 是排序 Heuristic，不是故障機率。

成本也要一起看：這些數字來自 2026 年 8 月 30 日的一台 arm64 Mac mini（macOS 26.1、Node 24.15.0），索引用 4 個 Workers、略過可選 Grammars、停用 Ladybug Extension 自動安裝，也沒有 Embeddings；初次 FTS 不可用，修復後的查詢是 BM25。每個題目保留一次執行，不是多輪效能基準。rg每題掃 360 個 TypeScript 檔、約 2.63 MB，牆鐘時間 0.07～0.15 秒；TypeScript Language Service 冷啟動讀 361 份 Source Snapshot，四題共 4.21 秒。GitNexus 把成本前置：初次索引牆鐘 77.51 秒、最高 RSS 約 1.17 GB，結構索引回報約 89 MiB；之後每次 depth 1 impact約 0.92～1.21 秒，原始輸出約 1.8～6.2 KB。depth 3 的 createNullObject輸出膨脹到約 26 KB。本文保留 Bytes，不把它硬換算成某個模型的 Token。

這個結果只能描述固定版本、固定 Fixture 與固定判分規則，不能外推成「GitNexus 在所有大型 Repo 都比 LSP 準」。真正可搬走的是測法：把 Ground Truth、命令、版本、原始輸出與判分程式一起保存；換 Repo、語言或索引參數時重新跑。

最容易踩的兩個坑：舊索引與「會壞」的誤讀

坑 1：Commit 沒變，不代表工作樹沒變

v1.6.10 的本機 gitnexus status實作會檢查索引 Commit、Analyzer Identity、不完整原因與 Dirty Tree；但 MCP 的 Staleness 路徑主要比較已存 Commit 與 HEAD，同一個 HEAD 下的未提交修改可能沒有舊索引警告。每次把 LOW 風險或零結果用在刪除、改名、權限與金流路徑前，先同時跑 git status --short與gitnexus status --json，再刷新索引：

git status --short
npx -y gitnexus@1.6.10 analyze --index-only
npx -y gitnexus@1.6.10 status --json

本文也做了 Dirty Index 題：在同一個 Hono Commit 新增 runtime-label.ts，讓它直接呼叫 getRuntimeKey。TypeScript References 已看到第 9 個檔案，CLI status --json也顯示 stale；但重建索引前的 impact仍回傳原本 8 個檔案，而且標示 epistemic: exact。重新執行 analyze --index-only後，GitNexus 才把第 9 個檔案納入。這再次說明 exact 是「舊圖內精確」，不是「工作樹必然完整」。

如果 CLI 已刷新、長駐 MCP Session 卻仍回傳舊資料，先重啟該 Agent Session，再以 CLI 與原始碼搜尋交叉確認。這是故障排除順序，不是宣稱 v1.6.10 每次都會快取錯誤。

坑 2：圖上的上游邊，是審查線索，不是故障證明

impact找到 A 呼叫 B，只能證明靜態圖存在一條關係；若你對 B 做向後相容的修改，A 可能完全不必改。反過來，動態派送沒被解析時，真正會受影響的 A 也可能不在圖上。因此把輸出分成三層：必讀候選、需要測試確認、工具已標示 lower-bound／未知，不要把所有上游檔案直接改成任務清單。

v1.6.10 的 官方工具說明把第一層標成「WILL BREAK」，同一段卻也要求把零呼叫者視為 UNKNOWN，並揭露 lower-bound。前者比靜態圖實際能證明的事情更強；本文採保守讀法，把每條邊當 Review lead，直到測試或介面契約證明它真的會壞。

要不要接 MCP？先過這張決策樹

• 只想做一次影響分析：停在 CLI；不要跑 setup，索引完成後直接查 context／impact。
• 每天都要讓 Coding Agent 查圖：先確認 A/B 對你的主要語言有增益，再執行 gitnexus setup -c codex或對應 Agent；避免 MCP 與外掛重複註冊。MCP 的唯讀模式預設沒有開啟；若 Agent 只需查詢，可在 MCP 啟動環境設定 GITNEXUS_MCP_READ_ONLY=1，並用 GITNEXUS_MCP_ALLOWED_REPOS限制可見 Repo。
• Repo 有大量反射、事件或跨服務呼叫：把 GitNexus 當候選排序器，保留 rg、LSP、契約測試與整合測試，不能讓圖單獨決定改版範圍。
• Repo 含商業機密或受控資料：先審 npm 安裝、套件供應鏈、可選 Embeddings 與網路政策；不要只靠「Local」一句話完成資安審查。

若你正比較不同 Coding Agent 的 Repo 理解方式，可接著讀 Claude Code vs Codex；若想看 BM25、Embedding 與混合檢索為何會得到不同候選，則讀 混合搜尋教學。

完整移除怎麼驗？uninstall 不等於 clean

GitNexus 把不同類型的資料交給不同命令處理。uninstall是反轉 setup建立的 MCP、Hooks 與 Skills；預設只預覽，加入 --force才套用。Repo 內的索引要用 clean，全域 npm 套件則由 npm 自己移除。

本次隔離驗收中，setup -c codex新增 1 個 MCP、12 個 Skills 與 2 個 Hooks，共 36 個檔案、約 608 KiB；第一次 uninstall只列出預覽，檔案沒有改變，--force才移除 GitNexus 內容。移除後仍留下約 4 KiB 的 Config／Hooks 骨架與空目錄，而且原本約 88 MiB 的 Repo 索引仍可查詢。這正是為什麼「看到 Removed」後還要分層驗收。

# 若曾執行 setup：先看預覽，再決定是否套用
npx -y gitnexus@1.6.10 uninstall
npx -y gitnexus@1.6.10 uninstall --force

# 在這個拋棄式 Repo 內移除索引
npx -y gitnexus@1.6.10 clean -f

# 只有曾全域安裝才需要這一步；npx 不等於全域安裝
npm uninstall -g gitnexus

# 驗收，而不是只相信成功訊息
git status --short
find . -maxdepth 3 -name '.gitnexus' -print
rg -n '^\.gitnexus/?$' .git/info/exclude
git status --short -- AGENTS.md CLAUDE.md .claude/skills .agents/skills
find .claude/skills .agents/skills -maxdepth 1 -type d \
  -name 'gitnexus-*' -print 2>/dev/null
npx -y gitnexus@1.6.10 list

若你從頭到尾只跑 analyze --index-only，就沒有 setup 建立的 MCP／Hook 要回滾；仍要檢查 Repo 索引、使用者層登錄，以及 .git/info/exclude裡殘留的 .gitnexus/規則。clean與uninstall都不會移除一般 analyze寫進 Repo 的 AGENTS.md／CLAUDE.md GitNexus 區塊、.claude/skills/gitnexus-*、可能鏡像的 .agents/skills/gitnexus-*，或 --skills產生的 .claude/skills/gitnexus-area-*；.git/info/exclude裡的 .gitnexus/規則也會留下。先檢查 Diff 與自訂內容，再精準移除，不要整個刪掉可能已被人工修改的檔案。單看 git status也看不到 Ignore 規則，所以驗收命令要同時檢查實際目錄與 Ignore 來源。

成本、資安與授權：上線前要看的真實邊界

• 索引成本：大型 Repo 會消耗 CPU、記憶體與磁碟；v1.6.10 預設略過超過 512 KB 的檔案，產生檔與 Ignore 規則也會改變可見範圍。
• 網路邊界：圖索引儲存在本機不代表整個安裝流程離線。首次使用且 Cache 未命中時，npx需要從 Registry 取得套件；v1.6.10 在 Ladybug Extension 載入失敗時也可能嘗試安裝，套件安裝流程另含 Scarf Analytics。要測離線邊界，可先設 GITNEXUS_LBUG_EXTENSION_INSTALL=never與SCARF_ANALYTICS=false；Embeddings 雖預設關閉，開啟後仍要另外審模型與端點設定。
• 語言覆蓋：官方文件列出多種語言，但每種語言的解析深度不同；CFG／PDG 要用 analyze --pdg額外開啟，不能把 TypeScript 的結果直接外推到所有語言。
• 授權：v1.6.10 的 npm metadata 與 LICENSE標示 PolyForm Noncommercial 1.0.0。要放進商業開發流程的團隊，應先依實際用途完成授權審查，而不是把 GitHub Stars 當使用許可。

GitNexus 教學 FAQ

1. GitNexus 比 grep 準嗎？

沒有脫離 Repo 與任務的單一答案。GitNexus 能沿關係圖排出多跳呼叫者，通常比純字串更有結構；rg卻可能抓到圖沒解析出的動態字串與設定。用本文的 Ground Truth 分別算 Recall、Precision，才知道你的任務哪個更合適。

2. GitNexus 可以取代 LSP 嗎？

不建議。LSP 的語意參照、即時診斷與編輯器整合仍很重要；GitNexus 的優勢是預先建立跨檔案、多跳的圖與流程視角。兩者輸出不一致時，那個差異本身就是最值得人工閱讀的區域。

3. 為什麼本文不直接用 GitHub Stars 證明準確率？

Stars 只能當關注度與人氣的 proxy，不能換算成 Recall 或 Precision。準確率需要固定資料集、Ground Truth、版本與判分規則；人氣數字沒有回答它找到哪些正確檔案。

4. 一定要開 Embeddings 才能用嗎？

不用。在 v1.6.10，analyze的 Embeddings 預設關閉；context、impact與trace的圖分析不以開啟 Embeddings 為前提。自然語言搜尋是否值得加 Embeddings，應另做成本與隱私評估。

5. impact 顯示 HIGH，就代表改了必壞嗎？

不代表。它代表圖上有較大的上游波及候選；相容修改可能讓呼叫者完全不用變。把 HIGH 當審查優先級，再用型別檢查、單元測試、契約測試與整合測試確認實際行為。

6. status 顯示最新，為什麼答案還可能舊？

先檢查未提交工作樹。v1.6.10 的 CLI status會檢查 Dirty Tree，但 MCP 的舊索引提示主要比較 Commit；未提交變更不會讓 HEAD改變。關鍵決策前同時看 git status --short與gitnexus status --json、重跑 analyze --index-only，若 MCP 與 CLI 不一致再重啟 Session。

7. 跑 analyze 會改 AGENTS.md 或 CLAUDE.md 嗎？

一般流程可能會；本文指定的 --index-only會跳過這類檔案注入。但它仍建立 .gitnexus索引與登錄資訊，所以要在拋棄式副本執行並保存前後清單。

8. 最小可行的導入方式是什麼？

挑一個高連接度符號，建立 5～10 個已知受影響檔案的 Ground Truth。在副本只跑 analyze --index-only，用三路方法算一次 Recall、Precision 與閱讀檔數；只有當它確實改善你的審查流程，再考慮接 MCP。

給新手的 6 個重點

1. 先固定 GitNexus 版本與 Repo Commit。
2. 沒有 Ground Truth，就不要談準確率。
3. rg、LSP、Graph 各自找不同類型的漏網。
4. 把 impact當審查候選，不當故障判決。
5. 零結果前先刷新索引並檢查 Dirty Tree。
6. 最後由測試與介面契約放行，不由任何一個搜尋工具放行。