指令用途

在複雜的大型系統中，一個核心方法（例如 ExecuteCommand）可能被分佈在不同目錄下的幾十個上游業務模組調用。如果僅僅依靠文字搜尋，我們很難理清一條端到端（End-to-End）的呼叫路徑。更糟糕的是，如果呼叫鏈中存在介面（Interface）與多型（Polymorphism），傳統的靜態文字搜尋根本無法感知具體的實作跳轉。

trace_path 透過知識圖譜的邊關係（Edges），專門用來追蹤 Symbol 的呼叫路徑與依賴關係：

• 入站追蹤 (Inbound Trace)：尋找「誰呼叫了我」（Who calls me）。
• 出站追蹤 (Outbound Trace)：尋找「我呼叫了誰」（Who do I call）。

這項工具是排查多執行緒卡死、連線洩漏與重構時影響評估（Impact Analysis）的終極利器。

運作流程

1. 參數輸入：接收 symbolName（目標 Symbol 名稱）與 direction（inbound 或 outbound，指定追蹤方向）。
2. 路徑尋索：在圖資料庫中以遍歷（Traversal）演算法沿着 CALLS 或 DEPENDS_ON 邊進行拓撲尋找。
3. 鏈條提煉：將複雜的網狀關係簡化為一條清晰的單向或樹狀路徑。
4. 輸出結果：回傳精確的呼叫關係路徑，並標明調用發生的精確行數與檔案位置。

實戰對話範例

範例：追蹤 PLC 讀取指令的入站呼叫鏈

• You:

  /opsx:explore "我想知道 PlcConnection 類別中的 ReadDeviceData 方法是被哪些 UI 按鈕或背景執行緒呼叫的。"

• AI:

  好的，我將呼叫 codebase-memory 的 trace_path 工具，進行 ReadDeviceData 方法的入站（inbound）呼叫鏈追蹤。

  CM 呼叫: trace_path(symbolName: "ReadDeviceData", direction: "inbound")
  CM 回傳:

  [
    {
      "caller": "ControlSystem.Core.Communication.PlcConnection.ReadDeviceData",
      "calledBy": [
        {
          "caller": "ControlSystem.Core.Jobs.PollPlcJob.Execute",
          "location": "/src/Core/Jobs/PollPlcJob.cs#L45",
          "calledBy": [
            {
              "caller": "ControlSystem.UI.FormMain.btnStart_Click",
              "location": "/src/UI/FormMain.cs#L102"
            }
          ]
        }
      ]
    }
  ]

  分析：
  呼叫路徑非常清晰：

  1. 最上游入口：FormMain.cs 中的 btnStart_Click 按鈕點擊事件（第 102 行）。
  2. 中游背景任務：調用了 PollPlcJob.Execute 非同步定時任務（第 45 行）。
  3. 底層執行者：最終驅動了 PlcConnection.ReadDeviceData。

  這意味著如果您修改了 ReadDeviceData 的參數，您必須同步調整 PollPlcJob.cs 的第 45 行。接下來需要為您讀取該呼叫處的原始碼嗎？