簡介

本 Harness 驗證 graphify 的核心建圖功能是否正常運作。graphify 跑 /graphify .（或 graphify extract .）後會在 graphify-out/ 目錄下產出三個檔案：

• graph.json — 完整圖譜（可直接查詢，不需重新讀檔）
• graph.html — 互動式 force-directed 視覺化（瀏覽器開啟即可點節點、過濾、搜尋）
• GRAPH_REPORT.md — 報告：god nodes、surprising connections、設計理由、建議問題

程式碼部分使用 tree-sitter AST 本地解析（零 LLM、零 token），只有 docs/PDF/圖片/video 才會呼叫 LLM。

前置條件

• 已完成 Graphify 安裝驗證：graphify --version 可正常輸出
• 準備一個小型測試專案（任一含 10~50 個 Python/TS/JS 原始檔的 codebase 即可；以下會建立一個極小範例）

驗證步驟

第一步：建立測試 corpus（純 AST，不需 API key）

# 建立測試目錄
mkdir -p graphify-test
cd graphify-test

# 準備 Python 測試檔
cat > auth.py << 'EOF'
def login(user, password):
    """使用者登入。"""
    if verify_password(user, password):
        return create_session(user)
    return None

def verify_password(user, password):
    return user.password == hash(password)

def create_session(user):
    return Session(user_id=user.id)
EOF

cat > session.py << 'EOF'
class Session:
    def __init__(self, user_id):
        self.user_id = user_id
        self.token = generate_token()

def generate_token():
    import secrets
    return secrets.token_hex(16)
EOF

這個 corpus 純粹是程式碼，不需要任何 LLM API key，graphify 跑出來的圖譜是 AST 解析的結果。

第二步：執行建圖

在 AI 助理中（Claude Code / Cursor 等）：

/graphify .

或在 headless 終端：

graphify extract .

預期輸出（終端會印出階段性進度）：

Detecting files...
Parsing AST (Python, 2 files)...
Building graph...
Detecting communities (Leiden)...
Writing graphify-out/...

第三步：驗證產出檔案

ls graphify-out/

預期結果：至少看到三個檔案

graph.html
GRAPH_REPORT.md
graph.json

通過條件：

• ✅ graph.json 存在且非空（大於 0 bytes）
• ✅ GRAPH_REPORT.md 存在且包含 # 開頭的報告
• ✅ graph.html 可在瀏覽器開啟並看到 force-directed 圖

第四步：驗證邊關係與信心標籤

# 用 jq 檢查 graph.json 中的邊
cat graphify-out/graph.json | jq '.edges[0:3]'

預期結果：邊物件應包含下面幾個欄位中的多數

• relation：calls、imports、inherits、references、re_exports、contains 其中之一
• source、target：節點 id
• source_file、source_location：來源檔案與行號
• 信心屬性（標記 EXTRACTED 或 INFERRED）

通過條件：

• ✅ 至少看到一條 calls 邊（例如 login → verify_password）
• ✅ 至少看到一條 imports 邊（session.py 引用 Session）
• ✅ 至少有一條邊標 EXTRACTED（原始碼直接出現）

graphify 官方設計與 spec 對齊：¹

第五步：驗證社群偵測

# 報告中應列出 god nodes（最連結的節點）與社群
head -50 graphify-out/GRAPH_REPORT.md

預期結果：報告至少包含

• 🌟 God nodes 列表（degree 最高的節點）
• 🎨 Communities 列表（Leiden 演算法分群，含自動命名）
• 💡 Suggested questions（4-5 個建議查詢）

通過條件：

• ✅ 報告可正常輸出（不是空檔案）
• ✅ 至少列出 1 個 god node
• ✅ 至少列出 1 個 community

第六步（可選）：加入 docs/PDF 後驗證 LLM 語意層

要驗證 LLM 提取功能，需要設定 API key：

# 二選一
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

# 在 corpus 中新增一份測試 markdown docs
cat > README.md << 'EOF'
# Graphify Test

這個專案展示使用者登入流程。`login` 函式會呼叫 `verify_password` 驗證密碼，
然後透過 `create_session` 建立 session token。
EOF

# 重新建圖
graphify extract . --mode deep

通過條件：

• ✅ graph.json 中除了 AST 邊之外，多了從 README.md 提取出的 rationale / concept 節點
• ✅ 這些節點的 source_file 指向 README.md
• ✅ 設定 --mode deep 後，LLM 提取更豐富（比對 jq '.nodes | length' graph.json 前後差異）

驗證清單

結論

若步驟 1-5 通過 🟢，graphify 的核心建圖與報告產出運作正常，可繼續 查詢效能測試。

若 LLM 語意層（步驟 6）失敗，先檢查 API key 是否設定正確；純 AST 路徑（步驟 1-5）不需要任何 key，是 graphify 的主路徑。

下一步

1. 查詢效能測試
2. graphify build 指令詳解
3. graphify query 指令詳解