BIGboss248/nextjs-wordpress

程式碼記憶體與圖譜智能（codebase-memory）

此技能定義了使用 codebase-memory MCP 知識圖譜 來探索、搜尋和理解程式碼的工程標準、操作程序及工具使用合約。

---

核心不變規則：索引優先協定

[!CRITICAL] 索引優先不變性： 背景監控重新索引在此工作區中已永久停用（auto_watch = false），以防止在主動編輯檔案時發生磁碟震顫、zstd 序列化開銷和系統卡頓。

因此，代理在對程式碼知識圖譜執行搜尋之前，必須始終驗證索引的新鮮度，或觸發按需重新索引（index_repository）。

每當你需要尋找符號、理解模組、調查錯誤或準備重構時，請在進行搜尋呼叫之前執行索引優先閘門。

---

工具層級：圖譜優先，Grep 其次

在發現、導航或審查程式碼時，嚴格遵守此優先順序層級：

flowchart TD
    Task[程式碼發現 / 調查任務] --> Freshness{索引新鮮嗎？}
    Freshness -->|否 / 未知 / 編輯後| Sync[index_repository 模式: 'fast' 或 'moderate']
    Freshness -->|是| Strategy{查詢類型}
    Sync --> Strategy

    Strategy -->|符號 / 函式 / 介面| SearchGraph[search_graph BM25 或 semantic_query]
    Strategy -->|呼叫者 / 被呼叫者 / 依賴項| TracePath[trace_path 呼叫者 / 被呼叫者]
    Strategy -->|變更的影響範圍| DetectChanges[detect_changes diff 到影響集合]
    Strategy -->|確切原始碼| GetSnippet[get_code_snippet 精確行數]
    Strategy -->|系統層級與樞紐模組| GetArch[get_architecture 高中心性節點]
    Strategy -->|文字字串 / 非程式碼 / 靜態資源| GrepFallback[search_code 或 run_command grep]

1. search_graph > 文字 grep：BM25 排名結構化搜尋，支援駝峰式拆分、標籤加權（函式 +10，路由 +8，介面 +5）和向量嵌入。
2. trace_path > 手動檔案跳躍：即時多跳呼叫者和被呼叫者圖譜解析。
3. get_code_snippet > 在大型檔案上使用 view_file：使用開始/結束行和呼叫者計數檢索符號的確切宣告和主體，而不會膨脹代理上下文。
4. detect_changes > 手動 diff 檢查：將 git diff（since: "HEAD~1"、base_branch: "main"）直接映射到其傳遞影響範圍。
5. Grep 備用方案：僅在以下情況使用 search_code 或 run_command（git grep、rg）：
   • 在 Markdown（.md）、設定檔（.json）或樣式表（.css）中的文字文字。
   • 在 index_status 中明確標記為 parse_partial 下的行範圍。
   • 透過設計經由 .cbmignore 排除的檔案。

---

標準操作工作流程

步驟 1：索引同步閘門（強制第一步操作）

在發出搜尋查詢之前，請確定專案名稱並確保圖譜反映最近的檔案系統編輯。

1. 識別專案名稱： 如果專案識別碼未知，請呼叫 list_projects：

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   （在此工作區中，衍生的專案名稱是 "D-Scripts-aminwebsite"）。

2. 檢查狀態或重新整理索引： 如果在工作階段期間建立或修改了檔案，請呼叫 index_repository：

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • 模式選擇：
     • mode: "fast"：增量解析、過濾檔案、無語意向量嵌入。適用於進行中開發，快速且輕量。
     • mode: "moderate"：增量解析 + 向量相似性嵌入，用於自然語言概念橋接。
   • 涵蓋範圍檢查：檢查回應中的：
     • parse_partial：某些行範圍發生解析錯誤的檔案。
     • skipped：完全跳過的檔案（例如二進位或過大檔案）。

---

步驟 2：符號與結構發現（search_graph）

尋找函式、介面、型別、元件和路由定義。

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• 自然語言發現： 使用 query 進行關鍵字 / BM25 搜尋（例如 "theme toggle transition"、"locale routing"）。
• 確切名稱模式： 使用 name_pattern 進行正則表達式過濾（例如 ".*Provider.*"、".*Skeleton.*"）。
• 語意概念搜尋： 使用 semantic_query: ["i18n", "language", "switch"]（需要字串陣列）來橋接詞彙落差。
• 處理截斷（has_more）： 如果回應傳回 "has_more": true，請透過新增 "offset": <current_offset + limit> 來進行分頁。

---

步驟 3：關係追蹤與影響範圍

在未檢查其依賴項目之前，絕不修改函式或介面。

1. 追蹤呼叫者與被呼叫者（trace_path）：

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound"：識別所有依賴此函式的呼叫者（影響範圍）。
   • direction: "outbound"：識別由此符號呼叫的下游函式。
   • direction: "both"：完整的雙向呼叫鏈。

2. 映射 Git Diff 影響集合（detect_changes）： 在提交或完成變更之前，評估影響範圍：

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

步驟 4：精準程式碼檢索（get_code_snippet）

與其透過 view_file 檢視整個檔案來消耗上下文，不如檢索確切的符號實作：

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

回應包括：

• 確切的 start_line 和 end_line
• 符號的乾淨原始碼
• 直接呼叫者和被呼叫者計數

---

步驟 5：高階架構探索（get_architecture）

在熟悉新的子系統或了解系統拓撲時：

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

識別頂層架構樞紐元件、中央依賴項和層級階層。

---

MCP 便捷工具參考矩陣

能力	工具名稱	必要參數	關鍵可選參數
驗證狀態	index_status	project	無
觸發索引	index_repository	repo_path	mode（"fast"、"moderate"、"full"）、persistence
列出專案	list_projects	無	無
搜尋符號	search_graph	project	query、name_pattern、semantic_query、limit、offset
追蹤呼叫鏈	trace_path	project、function_name	direction（"inbound"、"outbound"、"both"）、depth、mode
檢索原始碼	get_code_snippet	project、qualified_name	include_neighbors
影響範圍	detect_changes	project	base_branch、since、scope（"impact"、"files"）、depth
架構	get_architecture	project	aspects（["hub_nodes"]、["layers"]、["all"]）
文字搜尋	search_code	project、query	file_pattern、case_sensitive、limit

---

護欄與常見反模式

反模式	正確操作標準
未檢查索引新鮮度就進行搜尋	由於背景自動監控已停用，請始終先呼叫 index_repository(mode: "fast") 或透過 index_status 驗證。
使用 grep 尋找函式定義	呼叫 search_graph 並傳入符號名稱；它會傳回完整名稱、確切檔案路徑、行範圍和呼叫者計數。
讀取 1000 行檔案只為了看 1 個函式	使用符號的 qualified_name 呼叫 get_code_snippet。
手動讀取每個檔案以尋找呼叫者	使用 direction: "inbound" 呼叫 trace_path。
假設圖譜 100% 完整	圖譜是盡力而為。如果 index_status 在 parse_partial 下列出檔案，請對那些特定標記的行範圍使用文字 grep。
啟用 auto_watch	絕不啟用 auto_watch；保持其為 false 以維持尖峰互動式開發效能。