graphify query 指令詳解 · Graphify

指令用途

graphify query "<自然語言問題>" 對一個已建好的 graphify 圖譜（graphify-out/graph.json）執行自然語言查詢。graphify 為你的問題計算 BFS seeds（找出最相關的關鍵字命中），然後回傳一個子圖（subgraph）含相關節點與邊。

📌 與傳統圖譜資料庫的差異：你不需要寫 Cypher 或 GraphQL；只要打中文 / 英文的問題，graphify 會自動挑關鍵字（過濾 stop-words）→ BFS 找子圖。

基本用法

graphify query "認證流程怎麼運作的？"

在 AI 助理內則是：

graphify query "auth 在哪裡用到的？"

預期輸出

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]
  create_session -[imports]-> Session [INFERRED]
  ...

每個節點都標 Source（檔案與行號）與 Community（Leiden 分群），每條邊都標 relation 與信心標籤 EXTRACTED / INFERRED。

常用選項

選項	用途	範例
`--dfs`	用 DFS 走法（深度優先）而非 BFS	`graphify query "..." --dfs`
`--budget N`	限制 token / 節點預算（大圖友善）	`graphify query "..." --budget 1500`
`--graph PATH`	指定 graph.json 位置（預設 `graphify-out/graph.json`）	`graphify query "..." --graph other/graph.json`

子圖 vs 完整圖

graphify query 不會一次倒整份 JSON 給助理；它只回傳「relevance-ranked subgraph」，所以助理拿到的是精挑過的相關片段。這對降低 token 消耗非常關鍵。

為什麼要 budget 控制？

對「god node」（degree 極高的節點）一次倒出全部連結可能塞爆 context window。--budget 可以控制輸出大小。

範例對話

讓 AI 助理示範一次完整查詢：

使用者：這個專案的認證邏輯寫在哪？

助理：我先查 graphify 圖譜。
> graphify query "認證在哪裡實作？"

圖譜命中 4 個節點：
- login (auth.py:1) — 主登入入口
- verify_password (auth.py:6) — 密碼驗證
- create_session (session.py:14) — session 建立
- Session (session.py:1) — session 類別

邊關係：
login calls verify_password   [EXTRACTED]
login calls create_session    [EXTRACTED]
create_session instantiates Session [INFERRED]

→ 認證流程在 `auth.py` 的 login() 與 verify_password() 裡；session token 由 `session.py` 的 generate_token() 產生。

內部連結與外部參考

上一章：graphify build 指令詳解
同類指令：graphify path-explain 指令詳解
官方 README「See it in action」章節有 graphify query 的真實輸出範例

下一步

v0.9.56：Leaf node 查 callers 不再掉資料

MCP query_graph 在 v0.9.56 修正一個很典型的圖譜查詢問題：如果 seed node 只有 incoming edges，例如「被很多人呼叫、但自己不再呼叫其他函式」的 leaf function，舊行為可能無法往 caller 方向擴張。新版對這種 seed 會做 undirected traversal，與 CLI 行為一致。

因此這類問題現在更可靠：

「誰呼叫 SaveResult()？」
「這個 DTO 被哪些 handler 使用？」
「這個 leaf validator 的上游路徑是什麼？」

另外，query scorer 從 v0.9.54 起把 rationale 命中視為獨立 ranking tier；只有設計理由文字命中的節點，不再與一般 source-path match 混在一起。