為什麼 Cursor 跨檔案改程式，總是漏掉一半呼叫端？

如果你用 Cursor 或 Claude Code 做過跨檔案改程式（改介面、重新命名函式、抽模組——往往要動十幾個甚至上百個檔案），多半遇過：漏改呼叫端、改錯檔案、誤傷共用模組——模型「讀懂片段」，卻看不懂系統。2026 年各類 Agent 已能自動跑測試、開 PR，但團隊越大、倉庫越老，這個失敗模式依然沒變。根因往往不是模型不夠聰明，而是缺少一張可查詢、可增量、可共享的程式碼知識圖譜（Code Knowledge Graph）。本文說明這張圖是什麼、為何向量 RAG 與超長上下文仍不夠，以及工程團隊該如何為 Agent 建構結構化的「倉庫記憶」。

Agent 的盲區：上下文視窗不是「地圖」

當代 AI 程式設計 Agent 的典型流水線是：使用者提問 → 檢索相關檔案 → 塞進上下文 → 產生 diff。檢索手段包括 @ 檔案、ripgrep、embedding 相似度，或產品內建的 codebase index。它們在回答「哪段文字像答案」時表現不錯，卻在回答「改這裡會波及誰」時系統性失手，原因包括：

• 文字區塊沒有拓撲：chunk 切分破壞呼叫鏈；註解相似的兩個函式可能被一起召回，而真正呼叫關係在另一個 chunk 裡。
• grep 只有字串，沒有型別：多載、泛型、巨集生成程式碼、Swift extension 讓「同名」不等於「同一符號」。
• 上下文預算是零和遊戲：塞進 200 個檔案，模型仍不知道哪 5 個是必經路徑上的樞紐節點。
• 工作階段無狀態：上次重構拆掉的模組邊界，下次對話要從頭猜。

資深工程師靠的不是「背下全庫」，而是腦中的分層地圖：模組邊界、依賴方向、誰依賴誰、測試在哪。程式碼知識圖譜，就是把這張地圖外置、機器可讀、可版本化。

程式碼知識圖譜是什麼

狹義上，它是面向軟體工程的屬性圖（Property Graph）或異構圖：節點表示程式碼實體，邊表示可驗證的關係。與通用「知識圖譜」不同，它的邊大多可由靜態分析或建置日誌確定性推導，而非靠 LLM 幻覺補全。

圖譜的價值不在節點數量，而在多跳推理的可重現性：「從使用者點擊事件到落庫 SQL」可以是一條固定路徑，而不是每次讓模型重新「猜」一遍。

對比向量 RAG：語意相似 ≠ 結構相關

向量檢索把程式碼當自然語言段落，適合「找一段像支付處理的邏輯」。但下列任務天然是圖遍歷：

• 刪除廢棄 flag 前，列舉所有 if (featureX) 的真實引用點（含巨集與生成程式碼）。
• 將介面從 sync 改 async，列出全倉庫呼叫堆疊與測試替身。
• 拆分 God class，識別內聚子圖與對外扇出。

業界常見做法是混合檢索（Hybrid Retrieval）：意圖分類後，結構型問題走圖譜工具，探索型問題走向量；結果按「圖譜路徑上的節點優先」排序，再截斷進上下文。只堆 embedding、不建邊，Agent 在檔案多、依賴雜的大型程式碼庫（monorepo）上的 PR 合併率往往會觸頂。

對比 LSP / IDE 索引：工作階段內 vs 組織級

Language Server 為編輯器提供跳轉、引用、重新命名——與圖譜節點高度重疊。差異在生命週期與消費方：

• LSP 通常綁定目前開啟的工作區，Agent 在 CI 或遠端 Runner 上往往沒有同一 LSP 實例。
• 重新命名 API 是互動式的；Agent 需要批次、可腳本化的 get_callers(symbol_id)。
• 圖譜可掛載業務元資料：服務 owner、deprecated 日期、合規標籤——LSP 不會建模這些邊。
• 多分支比對（main vs feature）在圖譜裡可以是兩張子圖 diff，而不是兩次人工點跳轉。

務實路線是：用 LSP / compiler 前端做事實來源，用圖譜做持久化與 Agent 協定層，避免重複造輪子。

推薦架構：三層記憶，圖譜居中

把 Agent 的「倉庫理解」拆成三層，可減少概念混亂：

結構層（程式碼知識圖譜）

回答：程式碼是什麼、如何連接。 由靜態分析、建置圖（Bazel/Gradle/Xcode project graph）、OpenAPI/Proto 生成。更新觸發：merge、定時全量、或 watch 檔案變更。儲存：圖資料庫或帶鄰接索引的 SQLite；對外暴露 MCP tools。

語意層（向量索引）

回答：哪段實作「像」使用者描述的行為。 對函式本體、註解、ADR、Issue 做 embedding。注意與圖譜共享同一 symbol_id，避免「檢索到 chunk 卻找不到符號」。

情境層（任務與設計記憶）

回答：我們上次為什麼這樣改。 對應 PR 摘要、Runbook，或 OpenHuman 類 Memory OS 中的 Topic 節點。它不替代圖譜，而是給邊打上「已討論」「已廢棄」等權重。

圖譜直接改善的五類 Agent 任務

1. 跨檔案重構：重新命名、提取介面、遷移套件名——按呼叫邊批次改，減少漏網檔案。
2. 缺陷定位：從堆疊頂端沿 calls 邊向上找共用中間層，而不是全文搜尋錯誤字串。
3. 新成員 onboarding：「支付模組的入口」= 從 UI route 到 service 的子圖，比閱讀 README 更快。
4. 測試選擇：根據改動節點的 covers 邊跑最小測試集，縮短 CI 回饋——可與 TestFlight 驗證流水線 同機編排。
5. 安全與合規掃描：敏感 API 的 reachable_from 查詢比正則更準。

如何建構：增量、可失敗、語言感知

最小可行流水線（與文首 HowTo schema 一致）：

• 解析：tree-sitter（多語言）、SourceKit（Swift）、rust-analyzer（Rust）等匯出 AST 符號表。
• 建邊：呼叫解析可用保守近似（漏報優於誤報）；繼承與實作必須精確。
• 增量：以檔案為粒度 hash；變更檔案局部失效上下游兩跳鄰居。
• 版本：圖譜帶 commit_sha；Agent 工具參數裡強制傳入，防止跨分支混用。
• 工具面：固定 6～10 個高階 API（get_callers、get_module_graph…），禁止模型寫 ad-hoc Cypher 注入風險。

{
  "symbol": "PaymentService.charge",
  "callers": [
    {"id": "CheckoutViewModel.submit", "file": "ios/Checkout/VM.swift", "line": 88},
    {"id": "SubscriptionRenewalJob.run", "file": "jobs/renewal.ts", "line": 41}
  ],
  "graph_version": "a3f9c2e"
}

Apple / iOS 大型程式碼庫的特殊性

Swift、Objective-C、SPM、Xcode project 的組合讓「純文字 RAG」尤其吃虧：extension、conditional compilation、@objc 橋接都會產生靜態上不可見、執行時才顯現的邊。圖譜建置應：

• 在與 Xcode 同構的 macOS 環境解析（本機 Mac 或 Mac mini M4 雲端主機），避免 Linux CI 上解析失敗卻靜默跳過。
• 把 .xcodeproj / SPM target 依賴建成 Module 級邊，再下鑽到符號級。
• 與 Flutter iOS 混合倉 的 Dart ↔ Platform Channel 建立跨語言邊（手工標註 + 生成程式碼掃描）。

索引任務 CPU/磁碟密集、耗時長，適合放在獨享 Cloud Mac 上 7×24 增量跑；開發者本機 Cursor 透過 SSH/MCP 消費遠端圖譜 API，筆電只保留輕量用戶端。這與 Mac VPS vs Cloud Mac 中「算力與磁碟隔離」的結論一致：圖譜服務不應與超售 VPS 搶 I/O。

與 OpenClaw、agentmemory 的分工

OpenClaw 等多通道 Agent 擅長編排定時任務、Webhook 與外部工具；程式碼知識圖譜則是其中「讀倉庫」那一類的結構化後端。個人記憶產品（如 OpenHuman 的 Memory Tree）記錄的是決策與對話脈絡，不應試圖用自然語言摘要替代呼叫圖。

推薦整合方式：OpenClaw / Cursor MCP 註冊 code_graph_* 工具；Memory OS 僅存「本次重構已通知團隊 X」類元資料，並在檢索時把圖譜版本號寫入稽核日誌。

常見坑與反模式

• 用 LLM 自動「猜」呼叫關係：無法回歸測試，合併後圖譜腐爛。
• 圖譜與原始碼不同步：比沒有圖譜更危險——Agent 會過度自信地改錯檔案。
• 只有檔案級節點：與 @folder 無異，無法支撐 rename/refactor。
• 把圖譜全文塞進 prompt：應走工具呼叫 + 多跳裁剪，而非 dump 全圖 JSON。
• 忽略生成程式碼與 lockfile：Protobuf、GraphQL codegen、Swift macro 需納入建置掛鉤。

常見問題 (FAQ)

和向量 RAG 二選一嗎？ 不。圖譜管結構，向量管語意；用同一 symbol_id 串聯。

LSP 夠嗎？ 對單人單工作階段夠，對組織級 Agent 不夠；應用 LSP 產出餵給圖譜。

小專案要不要做？ 出現「Agent 總漏改呼叫端」再做；維護成本可用託管索引服務攤薄。

更新頻率？ 主分支每次 merge 增量更新；長任務前校驗 graph_version。

產品自帶索引還要自建嗎？ 要，若你需要 CI 整合、合規稽核、跨工具統一事實源。

雲端 Mac 有何用？ 持久圖譜庫、Swift/ObjC 解析、與 Xcode 同機、SSH 遠端供本機 IDE 消費。

安全？ 圖譜含模組結構與符號名，權限與原始碼同級；勿寫入公有 LLM 日誌。

和 Memory OS？ 圖譜 = 結構事實；記憶 = 決策與偏好；介面層組合。

結論

AI 程式設計 Agent 的上限， increasingly 由倉庫結構理解決定，而非由單次 prompt 技巧決定。程式碼知識圖譜把呼叫鏈、模組邊界與測試對應外置為可查詢、可版本、可稽核的資料，與向量檢索、個人記憶 OS 形成三層互補。2026 年仍只靠「更大上下文 + 檔案搜尋」的團隊，會在跨檔案改動多的 monorepo 與 Apple 工具鏈專案上反覆支付漏改成本。把索引建在正確的環境（含 macOS 解析與持久磁碟）上，是讓 Agent 從「會寫程式」走向「會改系統」的最低工程投資。