---
slug: codegraph-semantic-code-intelligence
status: published
title: CodeGraph 是什麼？用本地程式碼知識圖譜讓 AI agent 少走幾次冤枉路
excerpt: CodeGraph 把程式碼解析成可查詢的本地知識圖譜，透過 MCP 的 codegraph_explore 回傳符號、呼叫路徑與影響範圍，讓 AI coding agent 少用一輪 grep、glob 和逐檔閱讀。
category: AI
tags: [CodeGraph, AI agent, coding agent, MCP, static-analysis, developer-tools]
author: Seer
author_role: Author
read_time: 12 min
cover: "/static/codegraph-semantic-code-intelligence-cover.png"
published_at: "2026-08-07T00:00:00Z"
updated_at: "2026-08-09T02:59:44Z"
---

## 先講 CodeGraph 的定位

[CodeGraph](https://github.com/colbymchenry/codegraph) 是一款本地端運作的語意代碼分析（semantic code intelligence）工具。它能將 codebase 解析為包含 symbols、imports、calls、inheritance 及 framework routes 的知識圖譜，並透過 CLI 或 MCP 讓 AI coding agent 進行查詢。

在 agent 真正理解程式碼前，通常得花很多時間摸索結構。CodeGraph 處理的就是這段前置探索：釐清函式定義位置、呼叫來源、Request 導向資料庫的路由，以及修改特定 symbol 會波及哪些檔案和測試。

CodeGraph 本身並不扮演 coding agent，也不負責規劃需求、修改程式、跑測試或部署。它的定位是專門回答程式結構問題的本地資料層，理解需求、決定修改方式與驗證結果等工作，依然交給 agent 處理。

目前最新 Release 與官方 Repo 的 `package.json` 版本為 `1.5.0`；本文查核時 `main` 分支的 HEAD 為 `c6aaa20`。本文內容整理自官方 Repo、README、`package.json`、安裝腳本以及現行的 MCP/CLI 說明；Benchmark 數據則採用官方 README 揭露的結果，未於本機重新測試。

## 它解決哪一段工作？

當 AI agent 面對大型 codebase 時，常見流程是先找出檔案、搜尋關鍵字、打開好幾個檔案，再憑人腦拼湊呼叫關係。這套傳統流程不僅浪費工具呼叫次數，也極度消耗 Context 空間。一旦碰上跨檔案引用、動態 dispatch、Framework 路由或跨語言呼叫，還很容易遺漏關鍵線索。

CodeGraph 透過預先建立的索引，讓 agent 可以直接從結構化結果切入查詢：

| 問題 | CodeGraph 提供的結果 | 仍需要其他工具處理的部分 |
|---|---|---|
| 某個 symbol 在哪裡？ | symbol 定義、檔案與行號 | 閱讀產品需求與上下文 |
| 誰呼叫這個函式？ | callers、callees 與關係邊 | 判斷哪些呼叫是業務上重要的 |
| 一條流程怎麼走？ | 相關 symbols、呼叫路徑與來源片段 | 驗證 runtime 條件與外部服務行為 |
| 改某個 symbol 會影響什麼？ | impact radius、依賴與受影響範圍 | 執行測試、檢查資料與部署風險 |
| 哪些測試可能受影響？ | `codegraph affected` 找依賴的測試檔案 | 實際執行測試並解讀失敗原因 |
| 最近檔案有沒有跟上？ | watcher、auto-sync、pending sync 狀態 | 對仍在 debounce 期間的檔案直接讀取 |

它把「重新探索 Repo 結構」這類重複性的臨時工作，轉化為持續更新的本地索引，省去每次對話重新摸索的成本。

## 從安裝到 agent 使用

官方工作流可以歸納為三個動作：安裝 CLI、對接 agent、初始化專案。

### 1. 安裝 CLI

macOS 與 Linux 可直接執行官方 Shell 安裝指令：

```bash
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
```

Windows 使用者請執行 PowerShell 安裝腳本。若開發環境已有 Node.js，亦可透過 npm 安裝：

```bash
npm i -g @colbymchenry/codegraph
```

官方的獨立 standalone bundle 已內建 Node runtime，免去額外配置 Node.js 或編譯工具的麻煩。npm 套件則為另一種安裝途徑，適合習慣將 Node 工具整合進既有工作流的團隊。

### 2. 對接 AI coding agent

```bash
codegraph install
```

執行此指令會自動偵測並配置相容的 agent，包含 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 及 Kiro。安裝程式支援全域設定或套用至單一專案，也能搭配 `--target`、`--location`、`--yes` 或 `--print-config` 進行自動化非互動配置。

此步驟專注於打通 Agent 與工具間的連線，並未開始掃描專案或建立索引。

### 3. 初始化專案

```bash
cd your-project
codegraph init
```

在專案目錄下執行 `codegraph init`，會在目錄下建立 `.codegraph/` 資料夾並完成首次 Graph 建置。此時 agent 才有資料底層可供查詢。

簡單來說，流程就是：

```text
安裝 CLI → 用 codegraph install 對接 agent → 至各專案執行 codegraph init 建立索引
```

若誤將 `codegraph install` 當作專案初始化，雖然 agent 能識別 MCP server，但實際查詢時仍會因為缺少專案的 Graph 數據而無法運作。

## 實際使用需要啟動什麼？

答案可以先講白：**使用者不用手動開一個長駐的 MCP server，但不能只裝 MCP 設定就結束。** 正式工作流仍有三個前置步驟：安裝 CLI、把 MCP 接到 agent、在每個要查詢的專案執行一次 `codegraph init`。

```text
安裝 CLI
  → codegraph install：寫入 agent 的 MCP 設定與 instruction guidance
  → codegraph init：建立該專案的 .codegraph/ 索引
  → agent 啟動 codegraph serve --mcp：透過 stdio 提供查詢
```

`codegraph install` 寫入的 MCP 入口是 `codegraph serve --mcp`。這個命令是給 MCP host 透過管線啟動的，不是要開發者在另一個 Terminal 裡手動執行；官方 CLI 原始碼也特別把它標成 agent 自己啟動的 stdio entrypoint。現行程式還有依專案共用的 detached daemon 路徑，讓多個 MCP session 共用 watcher、SQLite 連線與 WAL writer，但這仍是 CodeGraph 自己管理的背景程序，不是使用者要另外部署的服務。

每個專案仍要有自己的 `.codegraph/`。`codegraph install` 只負責接線，不會掃描 codebase；`codegraph init` 才會建立初始 graph。完成設定後通常要重啟或 reload agent，讓新的 MCP 設定生效。之後檔案 watcher 預設會自動同步；只有關閉 watcher、檔案系統不適合監聽，或腳本需要 pre-flight 時，才需要手動執行 `codegraph sync`。

所以實際上有三種使用方式：

| 方式 | 需要什麼 | 適合情境 |
|---|---|---|
| MCP | CLI、agent 設定、該專案 `.codegraph/` | 日常讓 agent 自動查結構 |
| CLI | CLI、該專案 `.codegraph/` | 手動查詢、Subagent fallback、CI 或 Git hook |
| Library | 自己的 Node 程式與 CodeGraph API | 將索引查詢嵌入 Electron 或其他工具；需另外符合 README 的 Node runtime 條件 |

如果只有 MCP 設定、沒有 `codegraph init`，agent 可以看到工具，但沒有可查的專案 graph；CodeGraph 會提示回到一般的 `Read`、`grep` 或其他工具。這不是安裝失敗，而是「全域接線」和「專案索引」本來就是兩個不同階段。

## MCP 的核心是單一探索工具

目前 CodeGraph 預設只提供一個 MCP tool：`codegraph_explore`。

```text
codegraph_explore
  → relevant symbols
  → grouped source snippets
  → call paths
  → blast-radius summary
```

這個設計專門用來解答以下情境：

- 「這個功能是怎麼運作的？」
- 「Request 是如何一路進到資料庫？」
- 「這個 Class 的 Callers 與 Callees 有哪些？」
- 「如果修改這個 Symbol，會波及哪些檔案？」
- 「幫我找出這個檔案或 Symbol 目前的原始碼片段。」

官方 MCP 規範強烈建議 agent 直接呼叫 `codegraph_explore`，省去啟動子代理（sub-agent）進行 grep 搜尋或逐檔開啟的冗長過程。一次查詢就能直接帶回相關程式碼片段，並在關聯圖中整理好呼叫路徑與受影響範疇。

其餘查詢功能如 node、search、callers、callees、impact、files 和 status 依然存在，僅在預設狀態下隱藏於 MCP 選單外。若團隊需要更細粒度的工具調用，可藉由設定 `CODEGRAPH_MCP_TOOLS` 重新開啟，或在終端機直接執行對應的 CLI 指令。

## Agent 實際運作機制

### 釐清角色：Skill、MCP Tool 還是 CLI？

CodeGraph 與 coding agent 的核心整合管道為 MCP。透過 `codegraph install` 會將 CodeGraph MCP server 設定寫入指定的 agent 設定檔中，後續再由 agent 透過 `codegraph serve --mcp` 喚起該服務。對接完畢並重啟 agent 後，主 agent 便會在 MCP 的 `initialize` 階段接收到對應的使用指引（guidance）。

我們可以將各層級的分工梳理如下：

| 層級 | 實際角色 | 什麼時候用 |
|---|---|---|
| MCP server | 把 CodeGraph 接進主 agent 的 tool surface | 一般 agent 對話，讓 agent 自動呼叫 `codegraph_explore` |
| `codegraph_explore` | 預設唯一列出的 MCP tool，回傳來源、關係與影響範圍 | 問架構、流程、呼叫者、被呼叫者或變更影響時 |
| instruction／skill guidance | 告訴 agent 何時優先使用 CodeGraph，以及 subagent 的 CLI fallback | subagent、非 MCP harness、團隊共用 agent 指令 |
| CLI | `codegraph explore`、`node`、`impact`、`affected` 等命令 | 手動查詢、CI、腳本、MCP 尚未接通的 agent |

使用者無須在每次對話中手動輸入複雜的 skill 規則。MCP tool 本身即是實際執行查詢的介面，而 instruction 檔案或 skill 規則僅作為提示層，負責引導 agent 在正確時機呼叫工具。這些規則並不會自動建構圖譜，更無法取代 MCP server。

### `codegraph install` 做了什麼？

官方安裝程式會依據您的選擇處理以下事項：

1. 自動偵測 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 及 Kiro。
2. 將 `codegraph` MCP server 設定寫入對應的 agent 設定檔。
3. 針對 Claude Code，可選擇性寫入 CodeGraph MCP tools 的自動允許權限（auto-allow permission）。
4. 在 `CLAUDE.md`、`AGENTS.md` 或 `GEMINI.md` 寫入以 marker 框選的 CodeGraph 指引，確保 Subagent 以及無法讀取 MCP `initialize` 訊息的 harness 能得知 `codegraph explore` 的 CLI 同等入口。

此階段純粹完成對接，尚未對專案進行索引。設定完成後請重啟 agent，並前往個別專案目錄執行：

```bash
cd your-project
codegraph init
```

全域對接只需執行一次；而 `codegraph init` 則需在各專案分別執行。只要專案底下存有 `.codegraph/` 目錄，agent 就能在同個對話 Session 中發起查詢。此外，查詢時亦可傳入 `projectPath` 來讀取 Monorepo 下某個已初始化的 service，或是其他已完成圖譜建置的 Repo。

### Agent 如何進行呼叫？

在日常對話中，您不需要手動撰寫 MCP JSON。只要明確描述結構問題，agent 就會根據 MCP server 的指引自動呼叫 `codegraph_explore`：

```text
請先用 CodeGraph 查詢：
request 從 API route 進入後，如何一路走到資料庫？
請回傳相關檔案、主要 symbols、呼叫路徑，以及這條流程可能受影響的測試。
```

主 agent 接收到這類結構性問題時，典型工作路徑如下：

```text
使用者提問
  → 觸發 codegraph_explore
  → 獲取相關 symbols 的原始碼片段
  → grouped files
  → call paths
  → blast-radius summary
  → agent 評估修改範疇、讀取必要的最新檔案、執行對應測試
```

官方 MCP 指引建議 agent 優先檢索 CodeGraph，並將返回的程式碼內容當作已讀取的結構化 Context。此舉能有效防止 agent 啟動一個專門負責探索的 Sub-agent 去重複執行 grep、glob 或逐一讀檔。

Agent 不會將所有問題都交給 CodeGraph。面對業務需求說明、外部 API 回應、執行結果或尚未儲存的即時異動，依然需要仰賴內建的 `Read`、`Bash`、測試工具或其他 MCP。CodeGraph 的專長在於釐清「程式碼結構如何交互關聯」。

遇到未經 `codegraph init` 的專案（缺少 `.codegraph/`），CodeGraph 會向 agent 提供清晰的 fallback 指引以切換回傳統工具，確保使用者能彈性決定要對哪些專案建立索引。

### 手動進行 MCP 設定

多數情境下，執行 `codegraph install` 即可自動完成配置。若您希望手動管理，官方 README 提供了 Claude Code 的 stdio MCP 配置範例：

```json
{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}
```

若想讓 Claude Code 自動允許 CodeGraph 工具調用，可追加以下權限設定：

```json
{
  "permissions": {
    "allow": [
      "mcp__codegraph__*"
    ]
  }
}
```

該 Wildcard 規則除了涵蓋當前預設的 `codegraph_explore` 外，後續透過 `CODEGRAPH_MCP_TOOLS` 重新啟用的工具也同樣適用。是否啟用 auto-allow，建置時應視團隊的安全與權限規範而定。

### Subagent 的對接方式

主 Agent 能在 MCP server 的 `initialize` 階段取得引導訊息，但 Subagent 未必能共享同一份脈絡。為了解決這個問題，CodeGraph 安裝程式會將簡短指引寫入 Agent 的 Instruction 檔案，使 Subagent 能得知並呼叫對應指令：

```bash
codegraph explore "how does a request reach the database?"
```

此處的 `codegraph explore` 命令是 MCP `codegraph_explore` 工具在 CLI 的等同入口。這種設計非常適合以下情境：

- Subagent 無法直接存取 MCP tool surface；
- Agent framework 僅能讀取 `AGENTS.md`、`CLAUDE.md` 等 instruction 規則文件；
- 需在 CI 流程或自動化腳本中輸出結構化查詢結果；
- 開發者希望主動控制查詢行為，避免交由 agent 自行決定工具。

當 Subagent 具備直接連線同一個 MCP server 的能力時，呼叫 `codegraph_explore` 依舊是首選。多個代理共用同一個索引時，請務必留意 project path 的設定、併發修改的衝突以及各別 Agent 的權限邊界。

## 提升 Agent 效率的實戰建議

CodeGraph 能顯著提速，關鍵在於減少「重新摸索結構」的往返對話，無須將所有開發工作都交給圖譜。設計 Prompt 與工作流時，建議遵循以下脈絡：

| 階段 | 建議做法 | 提速原因 |
|---|---|---|
| 架構探索 | 一次把功能、入口、目標和想看的關係寫進 `codegraph_explore` 問題 | 讓結果直接帶回 symbols、source、call paths 和 blast radius |
| 來源確認 | 先採用 graph 回傳的來源；只有 staleness banner 或需要最新內容時再用 `Read` | 避免 grep／Read 重複查同一批檔案 |
| 修改前評估 | 先查 `impact` 或讓 `codegraph_explore` 回傳影響範圍 | 先知道可能影響哪些 callers、routes 和 tests |
| 修改後測試 | 用 `codegraph affected` 從 Git diff 篩選測試，再交給測試 runner | 減少不必要的測試範圍，但不跳過測試本身 |
| 日常同步 | 依賴 auto-sync；只有 sandbox、watcher 關閉或腳本 pre-flight 才手動 `sync` | 增量同步只處理變更檔案，不重建整棵 graph |
| 大型專案索引 | 使用預設排除規則，必要時在 `codegraph.json` 設定 `exclude` | 避免把 `node_modules`、build、cache、vendor 等雜訊放進 graph |

撰寫 Agent Prompt 時，若能將探索需求拆解為「入口 → 流程 → 影響範圍」，成效會更顯著：

```text
請先用 codegraph_explore 查詢以下資訊：
1. /api/orders 的 route handler；
2. 它呼叫的 service、repository 與外部 payment client；
3. 修改折扣計算邏輯後，可能波及的 callers 與測試檔案。
請先用查詢結果確認變更範圍，再讀取需修改的最新檔案，接著執行 affected tests。
```

相較於模糊的「幫我看看訂單系統」，這種具體結構的指令能引導 Agent 一次帶回完整且可用的上下文。

根據官方 README 在 2026-08-05 重新測量的 Benchmark，測試環境採用 Claude Opus 4.8，針對 7 個開源專案分別進行 4 次測試並取中位數（Median）。測試中利用 Hook 阻擋雙方的 `codegraph` CLI，避免控制組私下呼叫 CodeGraph。結果顯示：呼叫工具次數平均減少 88%、速度提升 53%、Token 消耗減少 62%、開發成本降低 44%；在有 CodeGraph 輔助的組別中，7 個專案均達到零檔案讀取（Zero file reads）。

要注意的是，這些數據由官方 Repo 維護者提供，本文並未在本機實地驗證。該測試主要評估解答特定架構問題時的 Throughput。README 同時指出，在多輪對話中，CodeGraph 的高密度資訊回傳會使殘留上下文（Residual retrieval context）增加約 80%；以 VS Code 專案為例，兩組的 Token 佔用分別約為 67k 對 18k。短期任務能換取極速探索，但面臨長對話或小 Context window 的 Agent 時，仍需額外監控 Context 的大小。

## CodeGraph、Agent Skill 與 CLI 的職責分工

核心架構與分工可以簡單用這張圖來理解：

```text
codegraph install
  → MCP server config + agent instruction guidance

codegraph init
  → 各專案的 .codegraph/codegraph.db

Agent 結構問題
  → codegraph_explore (MCP)
  → 獲取 source + call paths + blast radius

Subagent / CI / 非 MCP harness
  → codegraph explore (CLI)

修改與驗證
  → Read 最新檔案 + 編輯工具 + codegraph affected + test runner
```

Skill 與 Instruction 的主要作用在於提示 Agent 何時該求助 CodeGraph；MCP tool 扮演著實際的查詢通道；CLI 則是手動操作或 Subagent fallback 的安全備案。當三者協同運作，Agent 便能利用圖譜在短時間內理清代碼脈絡，隨後使用標準的讀檔、修改和測試工具完成後續開發。

## CLI 不僅用於配置 MCP

CodeGraph CLI 本身就是強大的輔助工具，能直接應用在 Code Review、除錯與測試範圍篩選：

| 指令 | 用途 |
|---|---|
| `codegraph status` | 查看檔案、nodes、edges、資料庫大小與索引狀態 |
| `codegraph query <search>` | 搜尋 symbols，可限制 kind、數量或輸出 JSON |
| `codegraph explore <query>` | 取得和 MCP `codegraph_explore` 相同方向的結構查詢 |
| `codegraph node <symbol\|file>` | 讀取 symbol、callers 或帶行號的檔案內容 |
| `codegraph callers <symbol>` | 找呼叫者 |
| `codegraph callees <symbol>` | 找被呼叫的函式 |
| `codegraph impact <symbol>` | 分析 symbol 的影響範圍 |
| `codegraph files [path]` | 查看檔案結構 |
| `codegraph affected [files...]` | 找出可能受變更影響的測試檔案 |
| `codegraph sync [path]` | 手動執行增量同步 |
| `codegraph upgrade [version]` | 更新或固定版本 |
| `codegraph telemetry [on\|off]` | 查看或切換匿名使用統計 |

其中 `affected` 指令特別適合搭配 Git diff：

```bash
git diff --name-only HEAD | codegraph affected --stdin --quiet
```

如此一來，便能將受波及的清單直接餵給測試 Runner，優先執行受影響的測試項目。這是 CodeGraph 提供的依賴關係分析功能，而實際測試依然交給 CI 或本地端的 Test runner 來執行。

## 如何保持索引即時更新？

為避免每次對話都要重新建構圖譜，CodeGraph 善用了作業系統底層的檔案監聽機制（例如 macOS 的 FSEvents、Linux 的 inotify，以及 Windows 的 ReadDirectoryChangesW）。偵測到檔案異動時，會先經過 Debounce 機制過濾。官方預設的 Debounce 時間為 `2000ms`，開發者可視需求透過 `CODEGRAPH_WATCH_DEBOUNCE_MS` 將其調整於 100ms 至 60s 之間。

官方 README 介紹了確保一致性的三項防護設計：

1. 監聽器（Watcher）會在檔案新增、編輯或刪除時，自動觸發增量同步。若有大量檔案連續異動，則會進行批次合併處理。
2. 在 Debounce 期間，若查詢範圍觸及尚未同步完畢的檔案，MCP 的回應中會加上 Staleness banner，提示 Agent 應改用 `Read` 讀取硬碟上的最新程式碼；其餘未被引入的 pending 變更檔案，則會列於 Footer。
3. 當 MCP server 斷線重啟，會以檔案大小、修改時間（mtime）及 Content hash 重新檢視 Working tree，進行 Reconciliation 以補齊離線期間發生的所有變更。

README 中也附上維護者的增量同步測量：在一個包含 4,400 個檔案的專案中，增量耗時約 0.3 秒；而在擁有 27,000 個檔案的 Swift 編譯器專案中，也僅需約 0.4 秒。這些數據為官方 Repo 提供的效能參考，沒有在本機實際跑過；其反映的是增量更新的工作量，不可直接視為所有專案的固定延遲。

在 Watcher 被關閉、Sandbox 限制了檔案監聽事件，或是自動化腳本需要 Pre-flight sync 的情況下，手動執行 `codegraph sync` 依然有其必要。正常的 Agent session 僅需依賴 auto-sync 機制，並可配合 `codegraph status` 確認 Pending sync 及檔案的同步狀態。

## 使用成本怎麼算？

CodeGraph 的費用不能只看「有沒有 API key」。目前本地 CLI／MCP 不需要外部模型，也沒有已公開的 hosted 方案價格；實際成本要拆成四層：

| 成本層 | 會付出什麼 | 目前能確認的邊界 |
|---|---|---|
| 安裝下載 | 網路流量與本機安裝空間 | 最新 `v1.5.0` Release 的 macOS arm64 壓縮包約 54.0 MiB、macOS x64 約 55.1 MiB；standalone bundle 已含 Node runtime，不必另裝 Node |
| 首次建索引 | CPU、記憶體、磁碟 I/O 與等待時間 | 會解析檔案、建立 nodes／edges／FTS5；官方沒有提供固定的最低 CPU、RAM、索引時間或每千檔案價格，不能用單一數字保證所有 repo |
| 日常同步 | watcher 常駐、變更檔案的增量解析與 SQLite 寫入 | 預設 watcher 依賴作業系統檔案事件與 debounce；只處理變更範圍，關閉 watcher 才需要手動 `sync` |
| Agent 使用 | agent 模型讀取 MCP 回傳、判斷下一步、修改與測試 | CodeGraph 本身不收模型費，但回傳內容會進 agent context；provider 的 token／時間／請求費用仍照原本模型方案計算 |

本機資源方面，官方 SQLite 連線設定包含 64 MiB page cache 與 256 MiB memory-mapped I/O 上限。這些是資料庫連線的設定值，不是「CodeGraph 最低需要 320 MiB RAM」的硬體需求；實際 resident memory 仍會受 repo 大小、同時索引檔案、語言 grammar、Node／Rust runtime 和 agent session 影響。`.codegraph/` 也可能包含 WAL sidecar，索引期間或非正常中止後的暫存大小不應直接當成永久資料庫大小。

最容易被忽略的是 agent 側成本：CodeGraph 能減少 grep、glob、Read 的探索輪次，官方 benchmark 也把 token 與美元支出列為結果；但同一份官方 README 同時指出，高密度 retrieval 會讓多輪對話殘留在 context 的內容變多。也就是說，**單題探索的模型成本可能下降，長對話的 context 壓力卻可能上升**，兩者不能只用「少幾次 tool call」互相替代。

至於 hosted CodeGraph Platform，官方 README 目前仍是 coming／beta waitlist；本輪沒有查到公開價格、用量單位或 SLA。因此現階段能做的是估本地 CPU、磁碟和 agent provider token，不能替 hosted 產品填一個看似精確的月費。

## 解析與圖譜建構原理

根據官方 README，程式碼轉換為圖譜的流程可以概括為四個階段：

```text
source files
  → Rust / tree-sitter extraction
  → symbols + edges
  → local SQLite + FTS5
  → MCP / CLI query
```

### 這不是內建小模型，而是確定性的靜態分析管線

CodeGraph 名稱裡的 `semantic` 容易讓人聯想到 embedding 或小型語言模型，但目前查核到的官方實作不是這條路。官方文件直接把 extraction 描述為 **deterministic**：結果來自 AST，不是由 LLM 摘要。`package.json` 的 runtime dependencies 也集中在 `tree-sitter-wasms`、`web-tree-sitter`、SQLite／CLI 與設定處理，沒有 embedding model、向量資料庫、ONNX runtime 或外部模型 API。

它的「語意」主要是把語法結構和可解析的關係命名出來，而不是理解自然語言意義：

```mermaid
flowchart TB
  S["Source files"] --> K{"Rust kernel 支援且解析成功？"}
  K -->|yes| R["Rust / Tree-sitter extraction"]
  K -->|no / parse error| W["WASM Tree-sitter fallback"]
  R --> G["Symbols, routes, unresolved references"]
  W --> G
  G --> E["Resolve calls, imports, inheritance, routes"]
  E --> D["SQLite graph + FTS5"]
  D --> Q["MCP / CLI query"]
```

現行版本的解析器有兩條實作路徑。通過等價性 gate 的語言會優先走 Rust native extraction kernel；其他語言、kernel 尚未支援的檔案，或解析結果含錯誤的檔案，會走內建的 WASM Tree-sitter extractor。原始碼中的 per-file fallback 是為了保留正確性，不是把錯誤交給模型猜測。Rust kernel 的角色比較接近「把 parse + extract 做得更快」，不是一個會自行推理程式碼的 AI 模型。

此外，CodeGraph 也不是把整份原始碼先轉成向量再做相似度搜尋。SQLite schema 裡的核心資料是 `nodes`、`edges`、`files` 和 `unresolved_refs`；FTS5 索引的欄位是 symbol `name`、`qualified_name`、`docstring` 與 `signature`。查詢回傳的 source range 則依 indexed node 的行號，從磁碟上的原始檔案讀出來。因此它的主要查找能力是「名稱／結構／關係／行號」的組合，不是自然語言 embedding 搜尋。

### 1. 語意提取（Extraction）

CodeGraph 採用 Tree-sitter grammar 解析原始碼；現行版本對部分語言使用 Rust 核心加速，並保留 WASM Tree-sitter 路徑作為支援與 fallback。圖譜節點（Nodes）類型涵蓋 Functions、Classes、Methods、Files 以及 Framework routes；節點之間的關聯（Edges）則用來表達 Calls、Imports、Extends、Implements、References 及特定框架路由的對應關係。

README 提及的支援名單涵蓋 TypeScript、JavaScript、ArkTS、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Objective-C、Metal、CUDA、Swift、Kotlin、Scala、Dart、Svelte、Vue、Astro、Lua、R、Terraform/OpenTofu 等多種語言與開發框架。

### 2. 本地儲存（Storage）

所有的圖譜索引資料都會存入專案目錄底下的 `.codegraph/codegraph.db`。資料庫選用 SQLite，並搭配 FTS5 索引 symbol 名稱、qualified name、docstring 和 signature；它不是把整個 source body 複製進全文索引。查詢需要展示程式碼時，再依節點的檔案路徑與行號讀取本機檔案。這套設計讓 graph、索引與程式碼都留在本機範圍內；但 agent 本身仍可能把查詢結果送進它所使用的模型 provider，這是 CodeGraph 與 agent 權限邊界要分開看的地方。

### 3. 關聯解析（Resolution）

完成語意提取後，CodeGraph 會開始連結 References 與 Definitions，並處理 Imports、Class inheritance 以及框架特有的 Pattern。官方甚至為 Swift 與 Objective-C、React Native、Expo 等混寫情境維護了跨語言的 Bridging 規則，讓呼叫關係鏈有機會跨越單一語言編譯器的限制。

需要留意的是，靜態分析的精準度高度取決於特定語言的語法特性、框架慣例、Reflection 依賴注入、動態 Dispatch 與程式寫法。圖譜雖然能接手大量的探索盲區，但無法將所有的 Runtime 執行期行為全數轉換為靜態結果。

## Framework-aware routes 的實用價值

傳統的代碼結構圖譜多半僅能識別函式與類別。但在 Web 開發中，常面臨另一種挑戰：URL Pattern 究竟對應到哪一個 Handler？

CodeGraph 的 Framework-aware routes 功能，會自動將部分的 Framework route 解析為 Route nodes，並將其與 Handler 進行串接。README 中列出的支援框架相當廣泛，包含 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、Rocket、ASP.NET、Vapor、React Router、SvelteKit、Vue Router、Nuxt 以及 Astro 等。

這使得「哪一個 API Endpoint 會觸發這個 Controller？」這類常見疑惑，能直接與 Callers、Impact analysis 合併在同一張關係圖上檢視。相較於大海撈針般搜尋函式名稱，這項設計無疑更貼近 Web 開發者的實際除錯需求。

## 如何解讀官方 Benchmark 數據？

CodeGraph README 最新的效能評測於 2026-08-05 進行，測試環境使用 Claude Code headless 搭配 Claude Opus 4.8，共測試 7 個不同語言的知名開源專案。每個專案在啟用與未啟用的對照組下各執行 4 次，並以中位數（Median）作為指標。為求公平，測試過程中使用 Hook 阻擋了兩組的 `codegraph` CLI 呼叫，以免控制組透過 Bash 偷吃步。

官方提供的評測摘要顯示：平均減少 88% 的工具呼叫次數、執行速度快 53%、消耗 Token 減少 62%、開發成本降低 44%，且啟用 CodeGraph 的組別在 7 個專案中的檔案讀取數皆為 0（Zero file reads）。要注意的是，這些數據由官方 Repo 維護者提供，本文並未在本機實地驗證。

| Codebase | Language | Tool calls | Time | File reads | Tokens | Cost |
|---|---|---:|---|---:|---:|---:|
| VS Code | TypeScript · 約 11k files | 2 / 28 | 2.2× faster | 0 / 12 | 少 77% | 低 71% |
| Excalidraw | TypeScript · 約 640 files | 2 / 43 | 3.6× faster | 0 / 18 | 少 84% | 低 78% |
| Django | Python · 約 3k files | 3 / 14 | 快 35% | 0 / 8.5 | 少 41% | 低 13% |
| Tokio | Rust · 約 790 files | 3 / 29 | 2.6× faster | 0 / 19 | 少 65% | 低 64% |
| OkHttp | Java · 約 645 files | 1 / 6 | 快 43% | 0 / 2 | 少 54% | 低 21% |
| Gin | Go · 約 110 files | 1 / 7 | 快 39% | 0 / 4 | 少 52% | 約略相同 |
| Alamofire | Swift · 約 110 files | 4 / 33 | 2.6× faster | 0 / 16.5 | 少 59% | 低 57% |

這項結果清楚展示了 CodeGraph 的優化邏輯：引導 Agent 進行精準的結構查詢，來取代傳統繁複的 find、grep、檔案閱讀與人工串接步驟。然而，這並不代表所有的開發任務都能達到相同的節省比例，亦無法保證取得圖譜資料後就能寫出完全無誤的程式碼。

此外，README 指出一個 Context 邊界限制：此測試測量的是解決特定問題所需的 throughput，並未將「後續殘留在 Context Window 中的歷史對話」納入同一評估指標。在多輪對話測試中，CodeGraph 帶來的高密度回傳資料會使殘留上下文（Residual retrieval context）增加約 80%；以 VS Code 為例，兩者分別佔用約 67k 與 18k tokens。如何在獲取快速結構檢索的優勢下，針對小 Context 的 Agent 或長對話妥善控制 Context 膨脹，是實務上需權衡的考量。

## 本地安全與 Telemetry 政策

CodeGraph 將資料庫與代碼索引全數存放於本機的 `.codegraph/` 目錄中，並以 100% 本地運行（100% local）為特色，無須 API 金鑰或聯網存取即可建構圖譜。對於嚴格禁止代碼外流至第三方伺服器的開發團隊而言，這是相當具吸引力的優勢。

即便如此，「本地運行」仍受限於 Agent 自身的權限配置。一旦 Agent 擁有專案的讀取權限，CodeGraph 便會將關聯的原始碼反饋給它。因此，針對 MCP wildcard auto-allow、共享 Workspace 以及跨 Agent 運作的 Instruction 規則，皆需遵循組織內部安全政策進行審查。

在遙測方面，CodeGraph 預設收集匿名的工具調用、指令與開發語言統計。官方聲明不會收集任何代碼、路徑、檔案名稱、Symbol 名稱、查詢語句或 IP 位址，且所有數據均會在本地聚合成每日摘要後才傳送。若有隱私疑慮，可透過以下方式關閉：

```bash
codegraph telemetry off
# 或設定 CODEGRAPH_TELEMETRY=0
# 或設定 DO_NOT_TRACK=1
```

在企業級部署前，建議先閱讀官方 Repo 底下的 [`TELEMETRY.md`](https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md)，以配合組織內部的遙測與合規政策。

## 授權與產品發展邊界

| 項目 | 截至目前的狀態 | 影響 |
|---|---|---|
| CLI / local index | 開源 repository，MIT | 可以自行安裝與管理本地 graph |
| standalone 安裝 | GitHub release bundle，內含 Node runtime | CLI／MCP 不需要額外安裝 Node |
| npm 套件 | `@colbymchenry/codegraph`，目前 `package.json` 為 `1.5.0` | 適合已有 Node 工具鏈的環境 |
| hosted CodeGraph Platform | README 寫為 coming、提供 beta waitlist | 目前不能依 README 推出 hosted 價格或 SLA |
| CLI／MCP runtime | 使用 bundled runtime | 與 library embedding 的 Node 條件不同 |
| library embedding | README 要求 Node `22.5+` 以使用 `node:sqlite` | Electron 或自有 Node 程式需另外核對 runtime |

另外，README 中提到 CodeGraph Platform 目前仍在 Beta 籌備階段，僅提供 Waitlist 登記。這項雲端服務與現行可自由下載的本地端 CLI/MCP 屬不同產品線，請避免將 Waitlist 預告誤讀為已對外開放的正式服務。

## 適合引進 CodeGraph 的工作流場景

### 1. 大型 Repository 的架構維護

在 Agent 需要爬梳跨檔案架構時，先透過 `codegraph_explore` 找出相關 Symbols、呼叫路徑與原始碼片段，隨後由 Agent 決定該讀取哪些特定檔案。此做法能大幅減少盲目摸索的對話往返，但在進行程式碼修改前，仍需讀取最新變更並完整理解業務需求。

### 2. 異動後的自動化測試範圍篩選

將 `git diff --name-only` 的結果導向 `codegraph affected` 指令，藉此找出與異動檔案高度關聯的測試項目，再交付測試 Runner 執行。這套做法適合作為縮小測試範圍的過濾器，無法直接當作測試成功的保證。

### 3. Web Route 與 Handler 的關聯追蹤

處理 API Endpoint、Controller、Middleware 或 Service 的呼叫依賴時，結合 Framework-aware route、Callers、Callees 以及 Impact analysis 能提供極大幫助。對於極度仰賴約定路由（Convention over configuration）的 Web 框架，這項功能比單純進行字串搜尋更能精確定位入口與下游節點。

### 4. 多代理共用專案索引

官方安裝程式允許多個 Agent 對接。由於 `.codegraph/` 屬於專案層級的索引，多個 Agent 可同步共享同一個圖譜，但開發時需特別留意同時編輯衝突、監聽器 Debounce 延遲、個別 MCP session 以及對應的權限範圍。

## 使用限制與注意事項

- **靜態圖譜與 Runtime 真實行為存在落差**：諸如 Reflection、依賴注入、動態字串生成的 Symbol、遠端配置以及資料庫即時狀態，仍需透過其他方式驗證。
- **圖譜結構與代碼修改的正確性無直接關聯**：Agent 依然必須深入閱讀需求、編寫邏輯、執行測試並進行人工 Diff 審查。
- **自動同步（Auto-sync）存在短暫的時間落差**：待同步的 pending 檔案雖有提示標記，但關鍵異動仍建議直接調用讀檔工具。
- **MCP 預設工具過於集中**：對於習慣將工具拆解得更細緻的團隊，需自行微調 `CODEGRAPH_MCP_TOOLS` 或多加利用 CLI 指令。
- **高密度資訊回傳（Dense retrieval）會加重 Context 負擔**：即便工具呼叫次數減少，長對話中殘留的 Context 體積並不一定會等比例縮小。
- **Node Library 與 CLI Standalone 運作環境有所區別**：程式庫內嵌所要求的 Node 版本規範，並不適用於獨立發行版。
- **難以透過 README 推估 Hosted 雲端版本計費**：目前 CodeGraph Platform 依然處於預告與等待名單（Waitlist）階段。
- **Moving branch 特性將隨時間持續更迭**：核心版本、語言支援矩陣、MCP Surface 與效能指標，在正式導入前均應以最新狀態重新核對。

## 總結：AI Agent 的代碼結構指南針

CodeGraph 的核心價值是將 codebase 結構整理為可供快速檢索的本地端資料層，它不負責代替 Agent 完成所有的代碼編寫。藉由 `codegraph_explore` 整合回傳 Symbol、原始碼、呼叫路徑與受波及範疇，配合 auto-sync 與檔案變更即時同步，並透過 `codegraph affected` 將依賴關聯引入測試階段。

若您的 Agent 經常陷入頻繁的 grep、glob 搜尋與逐檔閱讀的效能漩渦，CodeGraph 會是優化工作流的實用工具。導入時，建議先挑選單一大型專案做試點，重點觀察三項指標：Agent 能否順暢調用 `codegraph_explore`、查詢結果是否能有效收斂探索行為，以及 Dense context 對於長對話帶來的記憶體負擔。

完成這三項指標評估後，再決定是否將 MCP 配置推廣至團隊的其他開發代理中。結構圖譜能縮短定位代碼的時間，但需求的完整解讀、邏輯修改的正確性，乃至後續的測試與部署，依然是成熟工程流程中不可或缺的環節。

## 官方來源與查核範圍

- [CodeGraph 官方 repository](https://github.com/colbymchenry/codegraph)：README、CLI、MCP、語言支援、benchmark 與限制。
- [CodeGraph `package.json`](https://raw.githubusercontent.com/colbymchenry/codegraph/main/package.json)：目前 `1.5.0`、Node engines、npm scripts、MIT license。
- [CodeGraph `install.sh`](https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh)：standalone bundle、平台偵測、版本解析與安裝路徑。
- [CodeGraph `CLAUDE.md`](https://github.com/colbymchenry/codegraph/blob/main/CLAUDE.md)：repository layout、CLI、MCP server 與測試指令。
- [CodeGraph `TELEMETRY.md`](https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md)：匿名統計欄位與關閉方式。
- [CodeGraph 官方文件站](https://colbymchenry.github.io/codegraph/)：使用指南與 indexing 說明。
- [官方 Quickstart](https://colbymchenry.github.io/codegraph/getting-started/quickstart)：CLI、`codegraph install`、`codegraph init` 與 agent 啟動邊界。
- [官方 Introduction](https://colbymchenry.github.io/codegraph/getting-started/introduction)：deterministic AST extraction、SQLite graph 與 100% local 定位。
- [`src/db/schema.sql`](https://raw.githubusercontent.com/colbymchenry/codegraph/main/src/db/schema.sql)：nodes、edges、files、unresolved refs 與 FTS5 欄位。
- [`src/mcp/tools.ts`](https://raw.githubusercontent.com/colbymchenry/codegraph/main/src/mcp/tools.ts)：MCP tool surface、source range 讀取與 `projectPath`。
- [`src/bin/codegraph.ts`](https://raw.githubusercontent.com/colbymchenry/codegraph/main/src/bin/codegraph.ts)：`serve --mcp`、`init`、`sync` 與 CLI fallback。
- [`src/extraction/kernel/index.ts`](https://raw.githubusercontent.com/colbymchenry/codegraph/main/src/extraction/kernel/index.ts)：Rust kernel 路由與 WASM fallback。

本文查核日期：2026-08-09。`main` 為持續更新的分支；版本號、Release、語言支援度、Benchmark 數據及 MCP 支援工具可能隨時更迭。