把 GitNexus 接進 Codex：安裝、索引、Web UI 和專案分析實作

AI 編碼工具讀檔案沒問題，但遇到「專案怎麼分層」「這個介面後面呼叫了誰」「改一個類別會影響哪些流程」時，只靠搜尋檔名和關鍵字就不夠了。GitNexus 的思路是先把專案索引成程式碼知識圖譜，再把這份圖譜提供給 CLI、Web UI 和 MCP。接入 Codex 之後，Codex 可以直接讀取 GitNexus 的專案上下文、功能叢集和執行流程。

這次操作基於一個多模組 Java 專案 bo-camunda-flow。過程裡包含安裝、Codex MCP 設定、一次目錄錯誤、專案索引、Web UI 查看圖譜，以及最後讓 Codex 基於 GitNexus 做架構分析。

環境和安裝

先確認本機 Node 和 npm。實際環境是 Node v22.12.0，npm 10.9.0。

GitNexus 的 CLI 會載入本地解析和圖資料庫相關依賴，版本過低時容易在安裝或執行階段出問題。這裡保留環境資訊，不是為了湊步驟，而是後面遇到安裝失敗、native dependency 建置失敗時能快速判斷是不是執行環境引起的。

全域安裝 GitNexus：

bash 体验AI代码助手 代码解读复制代码npm install -g gitnexus@latest
gitnexus --version

安裝完成後，版本回傳 1.6.5。中間出現 deprecated 警告不影響使用。

如果安裝時卡在可選語法包建置，可以跳過部分可選 grammar：

bash 体验AI代码助手 代码解读复制代码GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 npm install -g gitnexus@latest

設定到 Codex

GitNexus 最值得用的地方不是單獨跑 CLI，而是接到 Codex 這類支援 MCP 的工具裡。這裡使用全域安裝後的命令註冊 MCP：

bash 体验AI代码助手 代码解读复制代码codex mcp add gitnexus -- gitnexus mcp

終端回傳 Added global MCP server 'gitnexus'.，說明 Codex 已經能啟動 GitNexus MCP 服務。

也可以用 npx 寫法：

bash 体验AI代码助手 代码解读复制代码codex mcp add gitnexus -- npx -y gitnexus@latest mcp

兩種方式都可以。全域安裝後使用 gitnexus mcp，啟動會更直接一些。

GitNexus 也提供了通用設定命令：

bash 体验AI代码助手 代码解读复制代码gitnexus setup

它會嘗試自動偵測本機安裝的編輯器並寫入 MCP 設定。手動執行 codex mcp add 的好處是更明確，只改 Codex；gitnexus setup 適合同時設定 Claude Code、Cursor、Codex 等多個工具。文章裡如果只講 Codex，保留 codex mcp add 這條命令更清楚。

gitnexus analyze 是核心命令

GitNexus 的入口命令是：

bash 体验AI代码助手 代码解读复制代码gitnexus analyze

這個命令會掃描目前 Git 倉庫，解析程式碼，生成 .gitnexus 本地索引，並把倉庫註冊到全域 registry。後面的 Web UI 和 MCP 都依賴這個索引。

這次使用的是：

bash 体验AI代码助手 代码解读复制代码gitnexus analyze --embeddings --skills --verbose

三個參數的意思分別是：

參數作用是否必須--embeddings生成語意搜尋向量，後續 query/search 更適合自然語言檢索，但會更慢、更吃資源可選--skills根據專案功能叢集生成 repo-specific skills，方便 AI 工具獲得更具體的模組上下文可選--verbose輸出更詳細的分析日誌，適合第一次安裝、排查跳過檔案或解析問題可選不加這些參數也可以：

bash 体验AI代码助手 代码解读复制代码gitnexus analyze

第一次體驗只想快速看圖譜，可以先跑預設命令。需要更好的語意搜尋和 AI 上下文時，再加 --embeddings --skills。

這裡可以按目標選擇命令。只想生成基礎圖譜，用 gitnexus analyze；準備接給 Codex 做自然語言查詢，用 gitnexus analyze --embeddings；希望 AI 工具拿到更細的模組上下文，用 --skills；第一次排錯或者想看跳過了哪些檔案，再加 --verbose。這些參數是增強項，不是必填項。

實際使用時可以分兩輪跑。第一輪先執行 gitnexus analyze，確認專案能被正常解析、gitnexus list 能看到倉庫、gitnexus status 是 up-to-date。第二輪再按需要補 --embeddings 和 --skills。這樣做更穩：如果基礎索引都沒生成，就沒必要先花時間生成向量；如果只是想讓 Web UI 畫出關係圖，預設 analyze 已經夠用；如果準備讓 Codex 做自然語言問答和模組分析，再上增強參數更合適。

--verbose 不建議長期預設開啟。它適合第一次接入或排查階段，能看到更詳細的解析過程；等命令穩定後，日常只保留需要的參數即可。大專案生成 embeddings 的時間會更長，最好在機器空閒時跑。

如果專案改動頻繁，提交前重新執行一次 gitnexus analyze，再讓 Codex 查詢，會比拿舊索引分析更可靠。

多人協作專案裡，也要先確認目前分支和本地改動狀態。這樣結果更容易穩定重現。

一個常見錯誤：目前目錄不是 Git 倉庫

第一次直接執行 analyze 時，終端提示：

text 体验AI代码助手 代码解读复制代码Not inside a git repository.
Tip: pass --skip-git to index any folder without a .git directory.

原因很簡單：命令跑在了非 Git 目錄裡。GitNexus 預設需要在 Git 倉庫裡分析，因為它要記錄專案路徑、commit 和索引狀態。

正確做法是進入專案根目錄：

bash 体验AI代码助手 代码解读复制代码cd /Users/xiaobo/huawei-code/bo-camunda-flow
gitnexus analyze --embeddings --skills --verbose

如果確實要分析一般資料夾，可以加：

bash 体验AI代码助手 代码解读复制代码gitnexus analyze --skip-git

索引專案並驗證狀態

在 bo-camunda-flow 目錄下重新執行後，GitNexus 完成索引：

text 体验AI代码助手 代码解读复制代码105 files
863 symbols
1844 edges
28 clusters
32 processes

這些統計分別對應檔案、程式碼符號、關係邊、功能叢集和執行流程。對於後續分析來說，edges、clusters、processes 比檔案數更關鍵，因為它們才是呼叫關係和模組邊界的來源。

索引完成後，建議順手檢查：

bash 体验AI代码助手 代码解读复制代码gitnexus list
gitnexus status

gitnexus list 可以看到已註冊倉庫，gitnexus status 用來確認目前 commit 和 indexed commit 是否一致。圖裡顯示 Status: up-to-date，說明目前索引沒有過期。

啟動 Web UI

本地啟動服務：

bash 体验AI代码助手 代码解读复制代码gitnexus serve

輸出裡能看到：

text 体验AI代码助手 代码解读复制代码MCP HTTP endpoints mounted at /api/mcp
GitNexus server running on http://localhost:4747

瀏覽器打開：

text 体验AI代码助手 代码解读复制代码http://localhost:4747

頁面會列出已經索引的 camunda-flow，並顯示 105 files、863 symbols、32 flows。

gitnexus serve 啟動後，終端要保持執行。Web 頁面只是前端入口，真正提供倉庫列表、圖譜資料和 MCP HTTP endpoint 的是這個本地服務。頁面裡顯示的檔案數、符號數和流程數來自前面生成的 .gitnexus 索引，不需要重新上傳程式碼。

進入專案後，左側是檔案樹，右側是知識圖譜。flow-common、flow-config、flow-service、flow-web 這些模組能在左側直接看到；右側圖譜展示了 863 個節點和 1844 條邊。

圖譜的作用不是取代 IDE，而是先給出關係視角。比如 flow-service 附近關係密度更高，Controller、CommonFlowServiceImpl、SysWorkFlowServiceImpl 等節點集中在主幹區域，說明業務邏輯主要圍繞這些類別展開。

對業務專案來說，檔案樹只回答「程式碼放在哪」，圖譜回答「程式碼之間怎麼連」。這兩個視角放在一起比較好用：左側能看到 Maven 模組拆分，右側能看到哪些類別處在關係中心。初次接手專案時，可以先從高連接節點下手，再回到原始碼確認職責。

點擊某個節點後，左側會打開 Code Inspector，並定位到原始碼。這裡選中的是 ProcessDetailInfoRespVO，能直接看到 Java 檔案內容、註解和欄位。

這一步比較實用：先在圖上找到節點，再回原始碼確認。圖譜負責告訴你「它和誰有關」，原始碼負責確認「它到底做什麼」。

讓 Codex 調 GitNexus 分析專案

設定 MCP 後，Codex 可以直接呼叫 GitNexus 工具。實際分析時，先讓 Codex 分析專案架構，它呼叫了：

text 体验AI代码助手 代码解读复制代码gitnexus.query
gitnexus.read_mcp_resource

讀取的資源包括：

text 体验AI代码助手 代码解读复制代码gitnexus://repo/camunda-flow/context
gitnexus://repo/camunda-flow/clusters
gitnexus://repo/camunda-flow/processes

context 給專案概覽，clusters 給功能叢集，processes 給執行流程。相比直接讓 Codex 掃目錄，這種方式更快建立專案地圖。

這一步相當於讓 Codex 先讀「索引摘要」，而不是從零開始搜尋。query 適合按概念找執行流程，read_mcp_resource 適合讀取固定資源，例如專案概覽、功能區、流程列表和圖 schema。對一個陌生專案來說，先拿這些資訊再展開原始碼分析，方向會更準。

繼續分析時，Codex 又結合本地檔案和 GitNexus 上下文確認專案結構。它先看 pom.xml 和 Java 檔案，再圍繞關鍵類別呼叫 gitnexus.context，例如 CommonFlowServiceImpl、CommonFlowController、SysWorkFlowServiceImpl。

這裡可以看出 GitNexus 和一般 grep 的差別。grep 能找到包含關鍵字的檔案，但不會主動告訴你這些類別處在什麼流程裡。context 會圍繞一個符號回傳呼叫方、被呼叫方、流程參與情況和相關關係，適合繼續追 Controller 到 Service、Service 到 Camunda Runtime 的路徑。

最後得出的結論是：這是一個多模組 Maven 的 Spring Boot + Camunda 7 工作流程後端。模組關係大致是：

text 体验AI代码助手 代码解读复制代码flow-web
  -> flow-service
      -> flow-common
      -> flow-config

flow-web 負責應用入口、REST Controller 和 Web 設定；flow-service 負責業務實作；flow-common 放模型、VO、列舉、例外和 BPMN 生成工具；flow-config 放 MyBatis、Camunda、Sa-Token、日誌和應用設定。

這類結論不是單靠目錄名猜出來的。GitNexus 提供了功能叢集和執行流程，Codex 再結合本地原始碼確認關鍵路徑。比如流程部署鏈路被整理為：

text 体验AI代码助手 代码解读复制代码POST /sys/flow/deploy
-> SysWorkFlowController.definition
-> SysWorkFlowServiceImpl.processDeploy
-> Bpmn.createEmptyModel
-> BpmnElementFactory / BpmnModelUtil
-> CamundaProcessUtil
-> repositoryService.createDeployment().deploy()

流程啟動鏈路被整理為：

text 体验AI代码助手 代码解读复制代码POST /flow/start
-> CommonFlowController.start
-> CommonFlowServiceImpl.processStart
-> runtimeService.startProcessInstanceById

審批鏈路被整理為：

text 体验AI代码助手 代码解读复制代码POST /flow/approve
-> CommonFlowServiceImpl.processApproval
-> taskService.complete / delegateTask
-> runtimeService.createProcessInstanceModification

這就是 GitNexus 接入 Codex 後最直接的好處：不是只回答「某個類別在哪裡」，而是能把類別、模組、介面和業務流程串起來。

常用命令整理

安裝和設定：

bash 体验AI代码助手 代码解读复制代码npm install -g gitnexus@latest
gitnexus --version
codex mcp add gitnexus -- gitnexus mcp

索引專案：

bash 体验AI代码助手 代码解读复制代码gitnexus analyze
gitnexus analyze --embeddings
gitnexus analyze --skills
gitnexus analyze --embeddings --skills --verbose
gitnexus analyze --force
gitnexus analyze --skip-git

索引狀態：

bash 体验AI代码助手 代码解读复制代码gitnexus list
gitnexus status

啟動服務和 MCP：

bash 体验AI代码助手 代码解读复制代码gitnexus serve
gitnexus mcp

直接查詢圖譜：

bash 体验AI代码助手 代码解读复制代码gitnexus query "authentication flow"
gitnexus context CommonFlowServiceImpl
gitnexus impact CommonFlowServiceImpl --direction upstream
gitnexus detect-changes
gitnexus cypher "MATCH (n) RETURN count(n) AS count"

這幾個命令可以對應不同場景：

命令適合場景query按自然語言或關鍵字找相關執行流程context看一個類別、方法、函式的上下游關係impact改動前看影響面，尤其是共用 Service、工具類、介面 DTOdetect-changes已經有本地改動時，分析目前 diff 影響了哪些符號和流程cypher直接查底層圖資料庫，適合做更精確的結構查詢除錯和改動分析怎麼用

GitNexus 自己的定位並不只是「畫圖」。分析它的專案實作後，可以看到它圍繞 MCP 暴露了一批面向 AI Agent 的工具：query 用來按概念找流程，context 用來查看單個符號的上下游，impact 用來分析變更影響，detect_changes 用來把目前 Git diff 映射到受影響符號和流程，cypher 則保留了底層圖查詢能力。這些工具組合起來，比較適合 debugging 和重構前檢查。

比如線上某個流程啟動介面異常，普通排查通常是先搜介面路徑，再進 Controller，再進 Service，然後手動追 RuntimeService、RepositoryService、TaskService 等呼叫。接入 GitNexus 後，可以先問：

bash 体验AI代码助手 代码解读复制代码gitnexus query "start workflow process"

找到相關流程後，再看核心類別：

bash 体验AI代码助手 代码解读复制代码gitnexus context CommonFlowServiceImpl

如果準備修改 CommonFlowServiceImpl，再跑：

bash 体验AI代码助手 代码解读复制代码gitnexus impact CommonFlowServiceImpl --direction upstream

這樣能先知道哪些 Controller、流程節點或其他服務依賴它。程式碼已經改完但還沒提交時，用：

bash 体验AI代码助手 代码解读复制代码gitnexus detect-changes

它會根據目前 Git diff 反查受影響的符號和流程。這個能力比單純看 git diff 更接近實際開發場景，因為很多問題不是「改了哪一行」，而是「這行被哪些入口和流程使用」。

在 Codex 裡，這套流程可以直接透過 MCP 完成。先讓 Codex 用 query 找問題相關流程，再用 context 深挖關鍵類別，最後用 impact 或 detect_changes 做改動前後的風險判斷。GitNexus 的好處不是取代除錯器，而是把排查入口提前縮窄，讓人不用從整個專案目錄裡盲找。

維護命令：

bash 体验AI代码助手 代码解读复制代码gitnexus clean
gitnexus clean --all --force
gitnexus wiki

多倉庫或多服務場景還可以用 group 命令：

bash 体验AI代码助手 代码解读复制代码gitnexus group create <name>
gitnexus group add <group> <groupPath> <registryName>
gitnexus group sync <name>
gitnexus group query <name> "<query>"
gitnexus group status <name>

GitNexus 適合做什麼

從這次使用看，GitNexus 的好處主要在四個地方。

第一，專案接手更快。query、context、clusters、processes 能先給出模組和流程視角，不用從目錄開始盲翻。

第二，除錯更有方向。遇到 bug 時，可以先用 query 找相關流程，再用 context 看某個類別的呼叫方和被呼叫方，最後回原始碼確認邏輯。GitNexus 自己也把 debugging 作為典型使用場景，因為它擅長沿呼叫鏈追蹤問題。

第三，改程式碼前能看影響面。impact <symbol> --direction upstream 可以看哪些呼叫方、模組或流程可能受影響，比只靠 IDE 的引用搜尋更貼近「業務流程會不會斷」。

第四，Codex 的專案分析不再只靠 grep。MCP 讓 Codex 直接讀 GitNexus 的圖譜資源，回答架構、流程、模組職責時更容易落到真實檔案和真實呼叫關係上。

它不是執行時監控，也不能保證覆蓋反射、動態呼叫和所有框架魔法。更合理的用法是：用 GitNexus 快速建立結構判斷，再回原始碼驗證關鍵路徑。對於 bo-camunda-flow 這種多模組 Spring Boot + Camunda 專案，這個組合已經足夠把架構梳理、流程追蹤和改動影響分析做得更快。

原文出處：https://juejin.cn/post/7649633479534182436