davidw-philips/cgraph

CodeGraph (codegraph)

codegraph 建立並維護一個本地、自動同步的知識圖譜（SQLite），涵蓋程式碼庫中的每個符號、呼叫邊緣與相依性。初始化完成後，您的代理可以直接透過 codegraph_explore 這個 MCP 工具，從圖譜中回答結構性問題——僅需一次呼叫，無需任何檔案讀取——取代傳統的 grep/read 迴圈。

使用時機

• 回答「X 如何運作？」、「X 如何到達 Y？」或快速熟悉當前活躍儲存庫中不熟悉的區域。
• 尋找某個函式的呼叫者/被呼叫者、追蹤呼叫路徑，或評估變更的影響範圍。
• 啟動、管理或停止 CodeGraph 背景常駐程式與環境程序。
• 跨 Git 分支、rebase 和 Git 工作樹，導覽與維護圖譜索引。
• 任何您原本會透過 grep 或讀取多個檔案來手動重建結構的問題。

請勿將其用於尚未擁有 .codegraph/ 索引的儲存庫（請先執行 codegraph init），或用於您尚未在本地索引的外部/公開儲存庫——這類情況請優先使用 deepwiki 技能。

前置檢查

command -v codegraph || Get-Command codegraph

如果缺少，請參閱 INSTALL.md，或直接透過以下方式安裝：

# macOS / Linux — 無需 Node.js，自帶執行環境
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell) — 無需 Node.js
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

這是大多數環境所需的全部步驟——請直接跳至下方的工作流程與啟動。僅當您特別需要 npm 安裝路徑或 CodeGraph 的 Node 函式庫 API 時，才使用隨附的 scripts/（請參閱 INSTALL.md）。

工作流程與啟動

1. 每台機器的一次性設定

將 CodeGraph 接入此代理（變更前會先確認）：

codegraph install

2. 每個專案的首次設定

為當前活躍專案建立圖譜（建立 .codegraph/codegraph.db；執行完整初始索引）：

cd your-project
codegraph init

3. 日常工作啟動（開始工作時）

您不需要在開始工作前手動啟動常駐程式或背景服務：

• 代理工作階段（MCP）：您的 AI 主機（VS Code Copilot、Claude Code 等）會透過 codegraph serve --mcp 自動啟動 MCP 伺服器。該伺服器會依需求連線或生成一個背景常駐程式，並附帶作業系統檔案系統監看器。
• 檢查健康狀態：執行 codegraph status 以驗證索引健康度、符號/邊緣計數以及待同步項目。
• 追趕同步：如果代理關閉時檔案已變更（例如拉取了提交），請執行 codegraph sync 以進行快速的增量更新。

4. 查詢結構

一旦連線完畢，您的代理會自行呼叫 codegraph_explore 這個 MCP 工具。同樣的功能也可從 shell 中使用：

codegraph explore "X 如何到達 Y"
codegraph callers someFunction
codegraph callees someFunction
codegraph impact someSymbol

環境與常駐程式生命週期

預設情況下，CodeGraph 會執行一個背景常駐程式（daemon mode），以便多個客戶端工作階段共用一個監看器、快取和 SQLite 控制代碼。

關閉常駐程式

• 互動式停止：執行 codegraph daemon（或 codegraph daemons）。選擇專案的常駐程式（會浮到頂部），或選擇停止所有常駐程式。
• 腳本化 / 非互動式停止：常駐程式會將其 PID 記錄在 <專案根目錄>/.codegraph/daemon.pid 中。直接終止該程序 ID（或檢查 ~/.codegraph/daemons/<雜湊>.json）。
• 清除過時鎖定：如果程序崩潰或突然終止，請使用以下命令清除過時鎖定與孤立的常駐程式工件：

  codegraph unlock
  

環境設定開關（常駐程式與監看器）

• 直接模式（無常駐程式）：設定 CODEGRAPH_NO_DAEMON=1，強制每個 MCP 和 CLI 工作階段以獨立、自包含的程序執行，而非連線到共享的常駐程式。
• 停用檔案監看器：設定 CODEGRAPH_NO_WATCH=1（或使用 --no-watch 旗標）來停用即時檔案系統監看器。建議在慢速檔案系統（WSL2 /mnt/ 磁碟機、網路掛載）或電池受限的設定上使用。

退役 / 取消初始化

• 從專案中移除：執行 codegraph uninit 以刪除 .codegraph/ 索引並移除 Git 同步鉤子（加上 --force 可跳過提示）。
• 從機器中移除：執行 codegraph uninstall（或 codegraph uninstall --keep-cli 以保留 CLI 二進位檔）。

使用 Git 分支與工作樹

Git 分支切換（單一工作樹）

• 基於檔案系統的同步：CodeGraph 在 SQLite 中追蹤檔案路徑與內容雜湊，而非 git status。切換分支（git switch <branch> 或 git checkout <branch>）會修改磁碟上的檔案；檔案監看器會自動偵測變更，並在大約 2 秒內增量同步索引。
• 手動同步：如果在切換期間監看器已停用或未運行，請執行 codegraph sync 以進行快速的增量追趕。
• 重大 Rebase / 重建：在大量的 rebase 或合併衝突嚴重的分支合併之後，使用以下命令強制進行乾淨的索引重建：

  codegraph index --force
  

• Git 同步鉤子（當監看器關閉時）：如果設定了 CODEGRAPH_NO_WATCH=1，CodeGraph 可以安裝 post-commit、post-merge 和 post-checkout 鉤子，在分支切換後自動在背景執行 codegraph sync。

Git 工作樹與「借用索引」的風險

• 索引發現：CodeGraph 透過從目前工作目錄向上遍歷父目錄來發現 .codegraph/。
• 風險：使用 Git 工作樹時（例如 git worktree add ../feature-worktree feature），如果該工作樹缺乏自己的 .codegraph/ 目錄，CodeGraph 會向上遍歷並繫結到主要簽出項目的 .codegraph/ 索引。從工作樹中查詢時，將回傳主要簽出分支的符號和原始碼，從而遺漏工作樹專屬的變更！
• 不匹配偵測：CodeGraph 會透過比較 git rev-parse --show-toplevel 與 indexRoot（使用 git rev-parse --git-common-dir）來執行 detectWorktreeIndexMismatch。當工作樹借用主要索引時，CodeGraph 會在 codegraph status 和 MCP 查詢工具中發出警告。
• 工作樹的黃金法則：請務必在每個工作樹目錄中執行 codegraph init（或 codegraph init -i）。每個工作樹必須擁有自己專屬的 .codegraph/ 目錄，才能獨立地為其分支建立索引。
• 自訂目錄隔離：如果需要自訂索引資料夾命名或隔離（例如區分 Windows 和 WSL2 簽出），請設定 CODEGRAPH_DIR（例如 export CODEGRAPH_DIR=.codegraph-worktree）。

規則

• 信任圖譜的結果——它透過檔案監看器保持同步（儲存後有 2 秒去抖）；無需用 grep 重新驗證。
• 將 codegraph_explore 回傳的原始碼視為已讀取；請勿使用 Read 工具重新開啟相同檔案。
• 僅查詢擁有 .codegraph/ 索引的專案。若路徑沒有索引，會回傳清晰的指引，建議改用內建工具——建立索引應是一個審慎的決定，而非自動行為。
• 在 Git 工作樹中，請使用 codegraph status 驗證該工作樹擁有自己的本地索引，而非借用主要樹的索引。
• 優先使用 codegraph_explore（或 CLI 中的 codegraph explore），而非較狹隘的隱藏工具（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）——它們回傳的所有資訊都已內嵌在 codegraph_explore 的結果中。

關於安裝選項，請參閱 INSTALL.md，包括 scripts/ 中隨附的 Node.js 檢查器/安裝程式腳本，僅在需要 npm 安裝路徑或函式庫嵌入時才需要使用。