簡介

本 Harness 驗證 graphify 的三大查詢指令能否正確回傳

• graphify query "<自然語言問題>" — 用白話問問題，回傳子圖
• graphify path A B — 找出兩個節點之間的最短路徑
• graphify explain <節點名稱> — 列出某個節點的所有連結與脈絡

這三個指令都不需要 LLM API key（純圖譜查詢）。

前置條件

• 已完成 知識提取驗證：graphify-out/graph.json 存在且非空

驗證步驟

第一步：query — 自然語言查詢

# 用白話問問題
graphify query "認證流程怎麼運作的？"

預期輸出：

Showing 8 of 8 nodes (ranked by relevance)

Node: login
  Source: auth.py:1
  Community: 1

Node: verify_password
  Source: auth.py:6
  ...

Edges (5):
  login -[calls]-> verify_password  [EXTRACTED]
  login -[calls]-> create_session   [EXTRACTED]
  ...

通過條件：

• ✅ 回傳結構包含節點（Node）與邊（Edges）
• ✅ 至少一條邊帶信心標籤（EXTRACTED 或 INFERRED）
• ✅ 每個節點有 Source（檔案與行號）

測試 --dfs 與 --budget 選項：

# 限制 budget 控制輸出大小
graphify query "session token 怎麼來的？" --budget 1500

# 用 DFS 走法
graphify query "..." --dfs

第二步：path — 找兩節點間最短路徑

graphify path "login" "generate_token"

預期輸出：

Shortest path (3 hops):
  login --calls--> create_session
  create_session --calls--> generate_token
  (Session.__init__ references generate_token)

通過條件：

• ✅ 回傳含 Shortest path (N hops) 字樣
• ✅ 每一跳（hop）標示真實 relation（從 v0.9.23 起 deterministic 且標真實 relation，見 release notes）¹
• ✅ 兩端點是輸入指定的節點

第三步：explain — 解釋單一節點

graphify explain "login"

預期輸出：

Node: login
  Source:    auth.py:1
  Community: 1
  Degree:    3

Connections (3):
  --> verify_password  [calls]  [EXTRACTED]
  --> create_session   [calls]  [EXTRACTED]
  <-- auth.py          [contains]  [EXTRACTED]
  ...

通過條件：

• ✅ 列出節點的 Source、Community、Degree
• ✅ 列出所有連結（in/out），每條包含 relation 與信心標籤
• ✅ 高 degree 節點（如 god node）的輸出會按檔案分組（v0.9.24 起）²

第四步：MCP server 的工具呼叫

如果你把圖譜暴露成 MCP server:

python -m graphify.serve graphify-out/graph.json

則 MCP client 可呼叫六個工具：

可在 MCP host 端（例如 Claude Desktop MCP 設定）驗證 query_graph / get_neighbors / shortest_path 回傳的 node / edge 格式與 CLI 一致。

第五步：延遲基本檢查

# 用 time 量延遲
time graphify query "auth" >/dev/null
time graphify path "login" "generate_token" >/dev/null
time graphify explain "login" >/dev/null

通過條件：

• ✅ 三個指令在 small corpus（< 100 nodes）下都應 < 1 秒
• ✅ 在大 corpus 上，query 已自 0.9.17 起改為單次 scoring pass（每查詢 1 次遍歷而非 T+1 次）³

驗證清單

結論

若所有測試通過 🟢，graphify 的查詢層運作正常。若 path 顯示的 relation 看起來怪怪的（例如 related），可能是圖譜是舊版（< v0.9.23）建置，請跑 graphify extract . --force 重置。

下一步

1. graphify query 指令詳解
2. graphify path-explain 指令詳解
3. graphify prs 指令詳解