本地初始化與圖譜同步 · Codegraph

建立本地圖譜：`codegraph init`

要在本地專案中使用 Codegraph，首先需要對專案目錄進行初始化，解析原始碼並建立圖譜資料庫。

請切換到你的專案根目錄（通常是包含 package.json、.git/ 或 .sln 的資料夾），執行：

codegraph init

這項命令會在背景引導以下初始化流程：

建立 .codegraph/ 資料夾：在專案根目錄下建立隱藏配置目錄，用來儲存圖譜的本地資料庫及快取檔案。
生成預設配置文件：產生 .codegraph/config.yaml 檔案，你可以在其中調整排除清單、包含路徑與框架配置。
首次 AST 全域分析：自動遍歷專案檔案，利用 AST 解析器在本地構建最初的程式碼圖譜。對於普通規模的專案，這僅需數秒時間。

排除規則與效能配置

預設情況下，Codegraph 會自動讀取專案的 .gitignore 配置，自動忽略被 Git 排除的檔案（如 bin/、obj/ 等）。

但為防止第三方依賴包（如龐大的 node_modules、dist、build 等）或大型靜態媒體資源被寫入圖譜資料庫，造成查詢效能下降，我們強烈建議編輯 .codegraph/config.yaml 來精確排除不需要的資源：

# .codegraph/config.yaml 詳細配置文件說明
project:
  name: "PhysioMonitoringApp"
  version: "1.2.0"
  framework: "react-native" # 指定框架以啟用特定感知路由

indexing:
  # 強制索引的檔案副檔名
  include:
    - "**/*.{ts,tsx,js,jsx,swift,m,h,kt,java}"
  
  # 排除規則（使用標準 glob 匹配）
  exclude:
    - "**/node_modules/**"
    - "**/ios/build/**"
    - "**/android/app/build/**"
    - "**/dist/**"
    - "**/.expo/**"
    - "**/public/assets/**"
    - "**/tests/**" # 可選：排除測試程式碼以使業務圖譜更乾淨

database:
  driver: "sqlite"
  path: "./.codegraph/graph.db"

[!NOTE] 設定良好的排除規則，能使後續圖譜更新在一瞬間完成，且能有效限制 .codegraph/graph.db 檔案的大小在數 MB 以內。

自動同步機制 (FsWatcher Watch)

代碼變更在日常開發中是非常頻繁的。如果圖譜的依賴關係滯後於你的實際代碼修改，AI 助手就會基於舊版的代碼心智圖給出不當的重構建議。

Codegraph 通過 本地檔案監聽 (File-Watching) 技術來解決這一同步問題：

1. 啟動背景監聽

在啟動開發伺服器的同時，您可以在終端機執行監聽指令：

codegraph watch

此命令會使 Codegraph 在背景執行，並註冊作業系統級別的檔案變更通知（如 macOS 的 FSEvents 或 Windows 的 ReadDirectoryChangesW）。

2. 增量 AST 更新流程 (Incremental Updates)

當你儲存某個被修改的檔案時：

觸發變更：watch 捕捉到檔案修改事件。
局部分析：Codegraph 僅針對該檔案再次運行 tree-sitter 解析出最新的 AST。
圖譜差異對比 (AST Diff)：它會比對新舊 AST，找出該檔案中哪些 Symbol 被新增、修改或刪除，並精準更新圖譜資料庫中對應的節點與關係（CALLS、DEPENDS_ON 等）。
即時同步：當你下一次在 AI Chat 中執行代碼修改或呼叫 codegraph_explore 時，AI 讀取到的就是已經增量同步好的最新圖譜，保證了協作的絕對正確性，且此同步流程 100% 在本地完成，零 token 消耗。

3. 手動索引與狀態檢查（v1.6.0 新增）

並非每個情境都適合讓背景常駐監聽（例如在 CI 或批次腳本中更新圖譜）。v1.6.0 因此補上了明確的手動操作：

codegraph index：手動觸發一次索引，讓圖譜對齊目前的程式碼狀態。
codegraph status：查看圖譜的索引狀態，確認資料是否為最新。

兩者可以搭配使用：先用 status 檢查圖譜是否過期，必要時用 index 手動補一次同步，不必依賴常駐的 watch 進程。

建立本地圖譜：codegraph init