背景

範例 001 假設你已經裝好 graphify,直接拿來探索陌生 codebase。但很多人卡在更前面:

• uv tool install 跟 graphify install 到底差在哪?
• 裝完後要打什麼才會「看到圖譜」?
• 三個輸出檔(graph.json、graph.html、GRAPH_REPORT.md)各代表什麼?

這個範例給完全沒用過 graphify 的人:用一個 5 個檔的小玩具專案,跑通安裝 → 第一次 build → 第一個 query → 第一個 path的最短路徑。不談進階語意層、不談 PR 分析,只確認你能從零走到「助理會用 graphify 回答問題」這一步。

適用情境

• 第一次接觸 graphify
• 想先在小專案驗證安裝無誤,再上大 codebase
• 教學/工作坊開場的 quickstart

事前準備

不需要 API key。本範例全程 --code-only,只走 AST 本地解析,零 token、零網路。

完整流程

步驟 1:建立玩具專案

隨便找一個目錄,放五個檔。這是後面要建圖的 corpus:

mkdir hello-graphify && cd hello-graphify

cat > user.py << 'EOF'
class User:
    def __init__(self, name):
        self.name = name

    def greet(self):
        return f"Hi, I am {self.name}"
EOF

cat > auth.py << 'EOF'
from user import User

def login(name):
    user = User(name)
    return user.greet()
EOF

cat > main.py << 'EOF'
from auth import login

if __name__ == "__main__":
    print(login("Alice"))
EOF

三個檔、三個 class/function、兩條 import 邊、一條 calls 邊。夠小,輸出看得清楚。

步驟 2:安裝 graphify

一條指令搞定。注意 PyPI 套件名是 graphifyy(雙 y),CLI 名才是 graphify:

uv tool install graphifyy

裝完驗證:

graphify --version

看到版本號(v0.9.41 或更新)就代表 CLI 可用。

步驟 3:對 AI 助理註冊 graphify

graphify install 會把 graphify 的工具描述寫進你目前 AI 助理的設定檔,讓助理「知道」有 graphify query、graphify path 這些指令可用。

# 在專案目錄下,裝到「此專案」層級
graphify install --project

graphify 支援 20+ 平台(Claude Code、Cursor、Codex、Gemini CLI 等),install 會自動偵測你目前的助理。若要明確指定平台,例如 Claude Code:

graphify claude install --project

--project 代表設定寫進當前 repo(可 commit 給團隊共用),不加則寫進個人全域設定。

步驟 4:第一次 build(純 AST)

graphify extract . --code-only

--code-only 是新手好朋友:完全跳過 LLM 語意層,只跑 tree-sitter AST,零 token、零網路。玩具專案一秒內跑完。

輸出會在 graphify-out/:

graphify-out/
├── graph.json         # 完整 JSON 圖譜
├── graph.html         # 互動式 force-directed 視覺化
└── GRAPH_REPORT.md    # god nodes、communities、建議問題

步驟 5:看圖譜長相

直接讀 GRAPH_REPORT.md:

cat graphify-out/GRAPH_REPORT.md

預期看到:

• 🌟 God nodes — User、login(連結數最高的節點,這個迷你 codebase 的核心)
• 🎨 Communities — 只有一個 community(檔案太少,Leiden 不會切)
• 💡 Suggested questions — graphify 建議你問的問題

想看視覺化,瀏覽器開 graphify-out/graph.html 即可。

步驟 6:第一個 query

對圖譜問問題。中文也行,graphify 會做 stop-words 處理:

graphify query "login 是怎麼運作的?"

graphify BFS 出子圖,把 5 到 8 個相關節點加邊回傳。在這個迷你專案,你會看到 login → User → greet 這條呼叫鏈被標出來。

步驟 7:第一個 path

問兩個概念的連結:

graphify path "login" "greet"

輸出類似:

Shortest path (2 hops):
  login --calls--> User.__init__
  User.__init__ --calls--> greet

graphify 用 BFS 找最短路徑,你立刻看到 login 跟 greet 在呼叫鏈上的相對位置。

步驟 8:把圖譜交給助理

build 完之後,你的 AI 助理(步驟 3 註冊過的)就能讀 graphify-out/GRAPH_REPORT.md,並呼叫 graphify query、graphify path 回答問題。

在助理裡問:「這個專案的 login 流程是什麼?」助理不會再 grep 原始碼,而是讀圖譜 + 跑 query,回答更精準。

對比傳統做法

失敗處理

內部連結

• graphify install 指令詳解
• graphify build 指令詳解
• graphify query 指令詳解
• graphify path-explain 指令詳解
• 快速入門工作流

下一步

1. 探索陌生 codebase 範例(把這套流程上大型 repo)
2. 增量重建工作流範例(日常開發維持圖譜新鮮)

關鍵學習點

• uv tool install graphifyy 裝 CLI,graphify install 對助理註冊工具;兩件事不要搞混。
• --code-only 是新手預設值:純 AST、零 token、零網路,跑完 80% 價值就拿到了。
• 三個輸出檔分工:graph.json 給程式讀、graph.html 給人看、GRAPH_REPORT.md 給助理讀。
• query 問「怎麼運作」,path 問「兩個概念怎麼連」;前者開放、後者收斂。