架構總覽 · codegraph 繁中教學站

分層 Pipeline

files → ExtractionOrchestrator (tree-sitter) → DB (nodes/edges/files)
               ↓
        ReferenceResolver (imports, name-matching, framework patterns)
               ↓
        GraphQueryManager / GraphTraverser (callers, callees, impact)
               ↓
        ContextBuilder (markdown/JSON for AI consumption)

公開 API 面是 src/index.ts 的 CodeGraph class——把各層接起來並 re-export 型別。Library 使用者只碰這支檔案；MCP server 與 CLI 也驅動同一支。詳見程式碼對照 · CodeGraph class。

模組職責表

模組	職責	教學頁
`src/index.ts`	`CodeGraph` class：init/open/close、indexAll、sync、searchNodes、getCallers/Callees、getImpactRadius、buildContext、watch/unwatch	main
`src/db/`	`DatabaseConnection`、`QueryBuilder`（prepared statements）、schema.sql、sqlite-adapter；Node 內建 `node:sqlite`（DatabaseSync）+ WAL + FTS5，無原生 build	db
`src/extraction/`	`ExtractionOrchestrator`、tree-sitter 包裝、per-language extractors（`languages/`）、Svelte/Vue/Liquid/DFM 等獨立 extractor；`parse-worker.ts` 主執行緒外解析	extraction
`codegraph-kernel/`	Rust 原生解析 kernel（20 語言），逐位元組驗證對齊參考引擎；無 prebuilt 平台或語法錯誤自動 per-file 回退	extraction
`src/resolution/`	`ReferenceResolver` 調度 import-resolver（含 tsconfig path aliases + cargo workspace）、name-matcher、`frameworks/`（Express、Laravel、Rails、FastAPI、Django、Flask、Spring、Gin、Axum…）產 `route` 節點與 `references` 邊	resolution
`src/graph/`	`GraphTraverser`（BFS/DFS、影響半徑、路徑搜尋）與 `GraphQueryManager`（高階查詢）	graph
`src/context/`	`ContextBuilder` + markdown/JSON 格式化輸出	context
`src/search/`	FTS5 全文搜尋的查詢解析與 helper	db
`src/sync/`	`FileWatcher`（原生 FSEvents/inotify/RDCW）debounce + filter、git-hook helpers	auto-sync
`src/mcp/`	MCP server（MCPServer、tools、transport）；`server-instructions.ts` 是 initialize response 的指引來源	mcp
`src/installer/`	多 agent 安裝器；`targets/registry.ts` 列全部 agent，新增一個 agent = 一個新檔案 + registry 一列	installer
`src/bin/codegraph.ts`	CLI（commander）：install、init、uninit、index、sync、status、query、files、context、affected、serve --mcp	cli
`src/telemetry/`	匿名使用統計（聚合、可關）	security

安裝器架構

安裝器是 codegraph install（以及裸 codegraph / npx @colbymchenry/codegraph）的入口。目前 targets：claude.ts、cursor.ts、codex.ts、opencode.ts 等 9 個（含 Copilot 三種 surface）。opencode 讀 opencode.jsonc（偏好既有 .jsonc，fallback .json，greenfield 建 .jsonc）；編輯用 jsonc-parser 做到 surgical，使用者註解與排版在 re-install/uninstall round-trip 後保留。

設計要點

單一入口：CLI、MCP server、library 全部驅動同一個 CodeGraph class。
零設定：語言支援依副檔名自動；不寫 codegraph.json 也能用（見設定）。
確定性：抽取由 AST 決定，不是 LLM 摘要。
Rust 邊界：一個檔案只跨界一次，20 語言原生解析。

看完這頁你應該能說出：分層 pipeline 的四層、CodeGraph class 是唯一公開入口、新增一個 agent target 只需「一個新檔案 + registry 一列」、以及 Rust kernel 與可攜引擎的關係。