實戰範例 009：從安裝到第一次 codegraph explore 的 Hello World · Codegraph

這個範例要解決的問題

你剛接手一個中型 Node.js Express 後端專案 shop-api/。前一位開發者離職，留下五十多個路由檔案與零散的工具函式。你想搞清楚一件事：「應用程式啟動時，到底是哪一支程式碼把所有路由掛載起來的？」

傳統做法會是 grep -r "app.use" .，看見十幾個命中，再 read_file 一個個翻。如果你今天特別累，可能 grep 到第三輪就忘了第一輪看到什麼。Codegraph 把這整個流程壓成單一工具呼叫。

這個範例帶你走完三件事：

安裝 Codegraph CLI
在專案裡跑 codegraph init 建立本地知識圖譜
用 codegraph explore 一次拿到入口函式原始碼、呼叫鏈與下游依賴

第一步：安裝 Codegraph

官方安裝指令是一行 shell 腳本：

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

裝完後，codegraph 指令會在 PATH 中可直接呼叫。

Codegraph v1.5.0 之後原生解析核心改用 Rust engine，20 種主流程式語言（TypeScript、JavaScript、Python、Go、Rust、Java 等）都能原生解析。沒有預編譯二進位檔的平台會自動回退到舊引擎，圖譜結果保持一致。

第二步：在專案中初始化知識圖譜

走進專案根目錄，執行：

cd shop-api
codegraph init

codegraph init 會做幾件事：

動作	結果
掃描專案檔案	辨識 20+ 種語言的原始碼
建構 AST 圖譜	把符號（symbol）、呼叫邊（call edge）、依賴邊寫進 `.codegraph/` 的 SQLite 資料庫

完成後專案根目錄會多出 .codegraph/ 資料夾。這就是你的本地知識圖譜，不會上傳任何 API、零金鑰。

中型 Node.js 專案（約 500 個檔案）通常在 10 秒內完成索引。要注意 init 本身只負責建出圖譜，不會持續監聽後續的檔案變更；要讓圖譜在開發過程中即時同步，再執行一次 codegraph watch 啟動背景監聽。

第三步：用 codegraph explore 一次看完入口

我們猜入口是 src/app.ts，但不確定實際的啟動函式是 createApp 還是 bootstrap。把這個問題直接交給 Codegraph：

codegraph explore "createApp bootstrap src/app.ts"

Codegraph 會回傳結構化區塊：

== Source (src/app.ts) ==
  12  export function createApp(): Express {
  13    const app = express();
  14    registerRoutes(app);
  15    return app;
  16  }

== Inbound Callers (誰呼叫了 createApp) ==
  - src/server.ts:8         const app = createApp();
  - tests/bootstrap.test.ts:14   const app = createApp();

== Outbound Dependencies (createApp 內部呼叫) ==
  - express()                vendor/express
  - registerRoutes(app)      src/routes/index.ts:4

一段輸出就回答了三個問題：

定義在哪：src/app.ts 第 12 行
誰會啟動它：src/server.ts 與測試檔，馬上知道實際進入點
它依賴誰：registerRoutes 在 src/routes/index.ts，繼續追下去就會看到所有路由掛載

v1.6.0 起，codegraph_explore 的排序進一步強化：結構訊號強的定義與主要呼叫端會排得更前面，generated files 與 test spec 這類低價值內容會被排除或降權，單次輸出更聚焦。

與傳統 grep 流程的對比

走傳統 grep 流程，同樣的問題會長這樣：

grep -rn "createApp" .
# 看到 5 個命中
read_file src/app.ts
read_file src/server.ts
read_file src/routes/index.ts
# 三次 read_file 才看完上游與下游

至少 4 次工具呼叫。Codegraph 用 1 次。這正是 v1.5.0 release notes 實測的 58% 更少工具呼叫、22% 更快的由來。對 AI 代理來說，每少一次工具呼叫，就少一次走偏上下文的機會。

第四步：框架感知幫你找到隱藏路由

Express 的路由常透過 app.use('/api/users', userRouter) 掛載。Codegraph 對 Express、Django、FastAPI 等 17 個框架具備路由感知。再用一次 explore：

codegraph explore "registerRoutes src/routes/index.ts"

輸出會自動附帶框架感知資訊：

== Framework Routes (Express) ==
  GET    /api/users       -> src/routes/users.ts:8    listUsers
  POST   /api/users       -> src/routes/users.ts:24   createUser
  GET    /api/users/:id   -> src/routes/users.ts:42   getUser

你看見的不是字串 /api/users，而是「HTTP 方法、路徑、處理函式、檔案位置」的強型別對應。這對後續重構（例如把 REST 改 GraphQL）極關鍵，因為你不會再漏掉任何一條路由。

常見新手陷阱

忘記在專案根目錄執行 `codegraph init`

Codegraph 找不到 .codegraph/ 時會明確報告 no index found。回到專案根目錄重跑即可。

以為 `codegraph explore` 需要完整路徑

給符號名或檔名片段就夠了。Codegraph 會做模糊比對。codegraph explore "createApp" 跟 codegraph explore "src/app.ts" 都會回傳 createApp 的上下文。

懷疑圖譜過期

v1.5.0 的 watcher 在 300ms 靜默後只同步變動路徑，4,400 個 Java 檔案大約 0.3 秒同步完成。如果還是擔心，v1.6.0 起可以先跑 codegraph status 檢查圖譜的索引狀態，或用 codegraph index 手動觸發一次重新索引；重跑 codegraph init 強制重建整個圖譜的做法依然可用。

關鍵學習點

一條 curl ... | sh 安裝、一行 codegraph init 索引，就能把任意 20+ 語言專案變成可查詢的本地知識圖譜，全程零 API 金鑰。
codegraph explore 用單次呼叫同時回傳「定義、入站呼叫者、出站依賴」，直接取代 grep 加多次 read_file 的線性增長流程。
框架感知（Express、Django、FastAPI 等）把字串路由對應回真實處理函式，重構時不會再漏路由。
v1.5.0 的 Rust engine 加上 300ms watcher 同步，讓中型專案的探索接近即時，不必為了重新索引中斷工作流。