運作原理 · codegraph 繁中教學站

一句話

CodeGraph 把「agent 慢慢 grep + Read 重建結構」的成本，變成一次性的索引建置：它用 tree-sitter 把整個專案解析成符號與邊，存進本機 SQLite（FTS5 全文搜尋），之後 agent 問結構問題就一次呼叫拿到答案。

英文原文（官方 docs · how-it-works）

CodeGraph hands the agent the exact code it needs in one call. It's a pre-built knowledge graph of every symbol, call edge, and dependency in your codebase — so instead of crawling files, the agent asks one question and gets back the relevant source, the call paths between those symbols (including dynamic-dispatch hops grep can't follow), and the blast radius of a change. Surgical context, not a file-by-file search.

四階段 Pipeline

原始碼 → ① 抽取 Extraction → ② 儲存 Storage → ③ 解析 Resolution → ④ 自動同步 Auto-Sync
              │                     │                   │
        Rust kernel (tree-sitter)  SQLite (.codegraph/)  ReferenceResolver
        20 語言原生編譯              WAL + FTS5            import + 名稱比對 + 框架模式

① 抽取（Extraction）

解析引擎是原生 Rust kernel：20 個語言（TypeScript、JavaScript、Java、Python、Go、C、C++、Rust、C#、Ruby、PHP、Swift、Kotlin、Scala、Dart、R、Lua、Luau…，Metal/CUDA 走 C++ 路徑）在編譯好的程式裡解析，每個檔案只跨界一次。抽取節點（function、class、method…）與邊（calls、imports、extends、implements…）。每個語言都要先在真實 repo 上證明與參考引擎逐位元組一致才出貨。

剩下的語言（Svelte、Vue、Astro、Liquid、Delphi…）與 per-file 回退用可攜引擎執行同一套抽取邏輯，產出相同的圖。

② 儲存（Storage）

一切進本機 SQLite（.codegraph/codegraph.db），node:sqlite + WAL 模式，附 FTS5 全文搜尋。Rust kernel 產出的邊都驗證過 byte-for-byte，且自動擴充到機器能力：worker pool、parallel resolution、analysis cache 依實際核心數（container-aware）、可用 RAM、與專案實際解析成本來決定。

③ 解析（Resolution）

抽取後把引用解析成真正的連結：function call → 定義、import → 來源檔、class 繼承、以及框架特定模式（Express route、Laravel controller、Spring annotation…）。dynamic-dispatch 跳躍（callback、React re-render、interface → impl）是 grep 追不到的，CodeGraph 補上。

④ 自動同步（Auto-Sync）

MCP server 用原生 OS 檔案事件（FSEvents / inotify / ReadDirectoryChangesW）watch 專案，debounce（預設 2 秒）後做增量同步。你改程式，圖就更新，不用手動 re-run。細節見自動同步機制。

資料模型

種類	內容
NodeKind	`file` `module` `class` `struct` `interface` `trait` `protocol` `function` `method` `property` `field` `variable` `constant` `enum` `enum_member` `type_alias` `namespace` `parameter` `import` `export` `route` `component` `union`
EdgeKind	`contains` `calls` `imports` `exports` `extends` `implements` `references` `type_of` `returns` `instantiates` `overrides` `decorates`

本站實測：真實數字

在 codegraph 自己的源碼上跑 codegraph init（v1.5.0）：

dogfooding 實測

◆  Indexed 570 files
●  12,733 nodes, 44,903 edges in 1.7s

$ codegraph status  （節錄）
  Backend:   node:sqlite — built-in (full WAL)
  Journal:   wal
Nodes by Kind:
  function        2,706
  import          2,304
  method          1,850
  class           206
  route           16

看到 route: 16——CodeGraph 在自己 repo 上也偵測到了 16 個框架路由節點。

看完這頁你應該能說出：四階段各自做什麼、為什麼 Rust kernel 是「逐位元組驗證」出貨、NodeKind/EdgeKind 各列一兩個例子、以及「索引建一次、之後自動同步」的設計如何把 agent 的成本從每次探索變成一次建置。