指令用途

雖然 search_graph 與 trace_path 可以解決 80% 的日常搜尋需求，但在面臨更為複雜的架構審查時，它們的功能就顯得力不從心。例如，當你想尋找：

• 「所有繼承自 IConnection 且被 UI 專案直接相依的 Class，且這些 Class 還沒有被任何單元測試覆蓋」
• 「存在循環相依（Circular Dependency）的類別環」

這類涉及多節點類型（Classes, Interfaces, Projects）與多重關係條件的查詢，普通的搜尋工具完全無能為力。

query_graph 允許開發者直接向本地知識圖譜資料庫發送 Cypher 查詢語句。這給予了 AI 助手與架構師極致強大的程式碼分析與依賴挖掘能力。

運作流程

1. 語句輸入：接收一段符合 W3C 標準的 Cypher 圖查詢語句（如 MATCH (n)... RETURN n）。
2. 圖引擎執行：在本地嵌入式圖資料庫（或記憶體圖模型）中執行 Cypher 語法解析與匹配。
3. 安全過濾：自動防止任何非唯讀的寫入操作，確保資料庫絕對安全。
4. 輸出結果：以 JSON 格式回傳匹配的節點、關係邊及屬性欄位。

實戰對話範例

範例：利用 Cypher 語句查找未被測試覆蓋的通訊方法

• You:

  /opsx:explore "請幫我用 Cypher 語句查詢，專案中所有繼承自 IConnection 且沒有任何 Test 方法調用它的類別方法。"

• AI:

  好的，為了找出未被單元測試覆蓋的通訊實作方法，我將呼叫 query_graph 工具執行一段精準的 Cypher 圖查詢。

  CM 呼叫:

  query_graph(cypher: "MATCH (c:Class)-[:IMPLEMENTS]->(i:Interface {name: 'IConnection'}) MATCH (c)-[:CONTAINS]->(m:Method) WHERE NOT ()-[:CALLS]->(m) RETURN c.name, m.name")

  CM 回傳:

  [
    { "c.name": "PlcConnection", "m.name": "ForceResetRegister" },
    { "c.name": "PlcConnection", "m.name": "UpdateBaudRate" }
  ]

  分析：
  查詢結果顯示，在 PlcConnection 類別中，有兩個繼承自 IConnection 的方法完全沒有被外部呼叫（意味著極大可能缺少單元測試覆蓋）：

  1. ForceResetRegister：強制重置暫存器。
  2. UpdateBaudRate：更新鮑率。

  這為我們補齊單元測試指明了精確的目標。您需要為您建立補齊這兩個方法測試的變更提案嗎？