大型專案的全域對應與探索工作流 · Codebase Memory

工作流的設計核心：自頂向下探索

當開發者或 AI 代理接手一個完全陌生的超大型專案時，如果直接去逐個閱讀原始碼檔案，很容易陷入細節泥潭。全域對應工作流 (Codebase Mapping Flow) 提供了一套系統化的探索路線，它要求我們從宏觀架構出發，逐步收斂到微觀的程式碼實作。

探索流程漏斗模型

  ┌─────────────────────────────────────────┐
  │         list_projects (專案定位)        │
  └───────────────────┬─────────────────────┘
                      │ 
                      ▼
  ┌─────────────────────────────────────────┐
  │       get_architecture (架構心智圖)     │
  └───────────────────┬─────────────────────┘
                      │
                      ▼
  ┌─────────────────────────────────────────┐
  │       search_graph (關鍵節點定位)        │
  └───────────────────┬─────────────────────┘
                      │
                      ▼
  ┌─────────────────────────────────────────┐
  │       trace_path (入站/出站呼叫追蹤)     │
  └───────────────────┬─────────────────────┘
                      │
                      ▼
  ┌─────────────────────────────────────────┐
  │      get_code_snippet (目標代碼精讀)    │
  └─────────────────────────────────────────┘

步驟詳解與工具參數規範

步驟 1：專案發現 (Discover Project)

確認目標專案是否已成功被 Codebase Memory 索引，並取得其在圖譜中的唯一專案識別名稱。

MCP 工具：list_projects
輸入參數：無

回傳結構：

[
  {
    "name": "PlcControlSystem",
    "path": "D:/Repo/PlcSystem",
    "file_count": 482,
    "indexed_at": "2026-07-16T18:00:00Z"
  }
]

步驟 2：獲取高階架構 (Get Project Architecture)

自頂向下地獲取整個專案的模組邊界、主要元件與外部依賴。這能幫助 AI 建立最初步的架構心智模型。

MCP 工具：get_architecture
輸入參數：project_name: "PlcControlSystem"
回傳內容：包含專案的三層架構說明、主要的進入點（Entrypoints）以及關鍵的第三方相依套件。

步驟 3：定位關鍵業務 Symbol (Search Graph)

當我們對架構有了輪廓後，針對具體功能模組（例如藍牙、資料庫、PLC）進行模糊或正則搜尋，定位關鍵的 Class 或 Interface 節點。

MCP 工具：search_graph
輸入參數：query: "PlcConnection", type: "class"
回傳結構：返回匹配的節點 ID、所在檔案路徑、以及其直接宣告的成員方法列表（如 Connect、WriteRegister）。

步驟 4：追蹤跨檔案呼叫關係 (Trace Paths)

這是圖譜發揮最大價值的核心步驟。我們需要分析這個關鍵 Symbol 被哪些上游呼叫者存取（Inbound），或者它往下呼叫了哪些底層方法（Outbound）。

MCP 工具：trace_path
輸入參數：
- node_id: "PlcConnection:WriteRegister"
- direction: "inbound" （分析改動影響範圍時使用）或 "outbound"（分析實現細節時使用）
回傳內容：一條或多條有向路徑，展示所有跨檔案、跨模組的呼叫鏈結。

步驟 5：讀取關鍵程式碼片段 (Get Snippet)

有了上述精準的呼叫路徑，AI 與開發者即可跳過所有無關的檔案，直接調取目標函式所在行數的 Verbatim 程式碼進行精讀。

MCP 工具：get_code_snippet
輸入參數：
- file_path: "Services/PlcConnection.cs"
- start_line: 120
- end_line: 160
回傳內容：該區間的原始程式碼。

循序圖

以下是 AI 助手在收到一個涉及「 PLC 斷線 bug」的模糊任務時，如何利用此工作流與 Codebase Memory 進行多輪工具呼叫以定位問題的循序歷程：

sequenceDiagram
    actor Developer as 開發者
    participant AI as AI Assistant
    participant CM as Codebase Memory MCP

    Developer->>AI: 幫我查一下 PLC 連線模組是怎麼跟 UI 互動的？
    Note over AI: 判斷需要先獲取 PlcControlSystem 架構
    AI->>CM: get_architecture(project_name: "PlcControlSystem")
    CM-->>AI: 返回三層架構與 PlcConnection 元件路徑
    
    Note over AI: 定位 PlcConnection 類別下的成員方法
    AI->>CM: search_graph(query: "PlcConnection")
    CM-->>AI: 返回類別成員與 Connect()、WriteRegister() 節點 ID
    
    Note over AI: 追蹤是哪些 UI 元件呼叫了 WriteRegister()
    AI->>CM: trace_path(node_id: "PlcConnection:WriteRegister", direction: "inbound")
    CM-->>AI: 返回呼叫鏈: MainForm.btnWrite_Click -> PlcConnection.WriteRegister
    
    Note over AI: 讀取具體按鈕事件的實作細節
    AI->>CM: get_code_snippet(file_path: "UI/MainForm.cs", start_line: 45, end_line: 75)
    CM-->>AI: 返回 btnWrite_Click 的 C# 原始碼
    
    AI->>Developer: 報告呼叫鏈，並展示 btnWrite_Click 與 PlcConnection 互動的實作