剛接手一個陌生 repository，最花時間的通常不是寫 code，而是搞懂 code 到底在幹嘛。

「索引從哪裡開始？」「改了這個 function 會壞哪裡？」「PR 影響到的下游測試跑過了嗎？」這些問題用全文搜尋或 IDE 只能找到零散線索，真正的呼叫關係與影響範圍，還是得自己拼湊。

這個系列要做的不是另一個只會聊天的 Copilot，而是一個「拿得出程式碼證據」的 Codebase 專家。它回答時必須附上相對路徑、行號與推導依據；查不到就說查不到，絕不把模型猜測包裝成事實。

先看未來的 Demo

傳統 grep 找不到別名（alias）或動態關聯，而一般的 Chatbot 又容易出現幻覺。我們期望未來的互動是這樣：

User: 修改了 src/rag_common.py 的 format_chunk()，哪些下游元件會受影響？需要測哪裡？

Agent:
根據 AST 呼叫分析，以下檔案直接呼叫了 `format_chunk`：
- src/build_index.py:42 (呼叫點：chunking pipeline)
- src/chat_reranker.py:108 (呼叫點：preview 格式化)

建議優先回歸測試：
- tests/test_indexer.py:15 (覆蓋 build_index.py 邏輯)

輸出看似樸素，但每一行都是確定性的程式碼依據，讓你可以直接點擊跳轉驗證，而不是聽模型瞎猜。

系統運作架構

要讓 LLM 不講幹話，核心關鍵是「把運算交給確定性工具，LLM 只負責意圖理解與整合」：

┌────────────────────────────────────────────────────────┐
│                      開發者提問                         │
└──────────────────────────┬─────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────┐
│       LLM (Local / Ollama) : 意圖識別 + 工具調度        │
└──────────────────────────┬─────────────────────────────┘
                           │ 呼叫確定性工具 (Deterministic Tools)
                           ▼
┌────────────────────────────────────────────────────────┐
│            Codebase Intelligence 分析引擎              │
│  ├─ 語法樹解析 (AST / Symbol Indexer)                  │
│  ├─ 依賴關聯圖 (Import & Direct Call Graph)            │
│  └─ 變更影響分析 (Git Diff Impact Analyzer)            │
└──────────────────────────┬─────────────────────────────┘
                           │ 附帶真實檔案路徑、行號 (Ground Truth)
                           ▼
┌────────────────────────────────────────────────────────┐
│                  附帶驗證依據的結構化回覆                │
└────────────────────────────────────────────────────────┘

這個 Agent 會做什麼？（以及它不會做什麼）

第一版我們專注在 Python 專案，核心引擎基於原生 ast 模組與 Git 介面建構，鎖定三件事：

1. 精準 Symbol 檢索：不僅是關鍵字比對，而是利用語法樹提取 class、function、module 的定義與實際位置。
2. 依賴關係解析：跨越 import as 等別名混淆，精準解析檔案與 symbol 間的直接相依性。
3. 變更影響候選分析：解析 Git diff 改動的 AST 節點，向上逆推可能被波及的模組與候選測試案例。

邊界宣告：Python 具備高度動態特性（反射、動態 import 等），第一版以靜態分析為準，定義為「候選影響範圍」，絕不聲稱 100% 捕獲所有動態行為。

為什麼不先接 LLM？

因為 LLM 太擅長把錯誤答案講得煞有介事。要讓回答可靠，底層必須先有扎實、可驗證的資料來源。

這就是本系列的開發原則：先做確定性的 Codebase Intelligence 工具，最後才掛上 Agent。 就算把 LLM 拔掉，前面打造的靜態分析索引器依舊是一套能在本機獨立運作的 CLI 開發利器。

下一篇，我們會先從 Agent 的權限控制與系統邊界談起，把執行安全與職責劃分清楚。