Graphify 教學手冊

版本：v0.9.2（2026-06-30）
適用對象：資深工程師、架構師、DevOps 團隊
定位：企業級知識圖譜建置與維運實戰手冊
授權：MIT License
Y Combinator：S26 批次

目錄

• 第 1 章：Graphify 概述
  • 1.1 什麼是 Graphify
  • 1.2 工具定位與比較
  • 1.3 使用情境
  • 1.4 與 AI Agent 的關係
  • 1.5 核心特色摘要
  • 1.6 多後端支援
  • 1.7 Penpax 與生態系統發展
• 第 2 章：系統架構設計
  • 2.1 整體架構圖
  • 2.2 三階段處理 Pipeline
  • 2.3 Pipeline 模組詳解
  • 2.4 模組職責對照表
  • 2.5 Graph 資料模型
  • 2.6 Confidence Labels（信賴標籤）
  • 2.7 實體去重 Pipeline
  • 2.8 與企業系統整合架構
  • 2.9 技術棧
• 第 3 章：安裝與環境建置
  • 3.1 環境需求
  • 3.2 安裝步驟（各平台）
  • 3.3 多平台支援
  • 3.4 選用安裝項目（Optional Extras）
  • 3.5 Docker 部署方式（企業推薦）
  • 3.6 安全性設定
  • 3.7 常見安裝問題排除
• 第 4 章：基本使用教學
  • 4.1 初始化專案
  • 4.2 建立知識圖譜
  • 4.3 指令完整說明
  • 4.4 輸出內容說明
  • 4.5 .graphifyignore 設定
  • 4.6 Always-On 模式設定
  • 4.7 查詢知識圖譜
• 第 5 章：進階使用（企業必備）
  • 5.1 全域知識圖譜（Global Graph）
  • 5.2 多 Repo 分析
  • 5.3 增量更新與 Watch 模式
  • 5.4 Git Hooks 與合併驅動器
  • 5.5 與 CI/CD 整合
  • 5.6 與 AI 助手整合
  • 5.7 MCP Server 模式
  • 5.8 知識圖譜查詢應用（RAG 強化）
  • 5.9 多格式匯出
  • 5.10 Wiki 生成
  • 5.11 記憶回饋迴圈（Memory Feedback Loop）
  • 5.12 Callflow HTML 匯出
  • 5.13 Docker MCP Toolkit
  • 5.14 PR Dashboard（圖譜感知 PR 管理）
  • 5.15 自訂 LLM Provider Registry
  • 5.16 循環匯入偵測（Import Cycle Detection）
  • 5.17 專案範圍安裝（Project-Scoped Install）
  • 5.18 Azure OpenAI 後端
  • 5.19 Terraform / HCL 支援
  • 5.20 Salesforce Apex 支援
  • 5.21 PostgreSQL Schema 內省
  • 5.22 FalkorDB 圖資料庫整合
  • 5.23 Cargo Workspace 映射
  • 5.24 CUDA / Metal Shader 支援
  • 5.25 WPF / XAML 支援
  • 5.26 Graph Health Gate
  • 5.27 Trigram Query 預過濾
  • 5.28 新增平台支援
• 第 6 章：實戰案例
  • 6.1 案例一：舊系統逆向工程（Java / Spring）
  • 6.2 案例二：微服務架構知識盤點
  • 6.3 案例三：新人 Onboarding 加速
  • 6.4 案例四：影音知識庫建構
• 第 7 章：系統升級與版本管理
  • 7.1 升級 Graphify
  • 7.2 Graph Schema 版本控制
  • 7.3 與 Git 版本同步策略
  • 7.4 v0.9.0 破壞性變更遷移指南
• 第 8 章：安全與隱私設計（SSDLC）
  • 8.1 安全模型總覽
  • 8.2 本地運算優勢
  • 8.3 威脅面與緩解措施
  • 8.4 敏感資料處理
  • 8.5 權限控管（RBAC）
  • 8.6 稽核與追蹤
  • 8.7 漏洞回報流程
  • 8.8 支援版本政策
• 第 9 章：最佳實務（Best Practices）
  • 9.1 大型專案使用建議
  • 9.2 Token 最佳化策略
  • 9.3 Graph 建模技巧
  • 9.4 團隊導入策略
  • 9.5 環境變數參考
• 第 10 章：常見問題（FAQ）
• 附錄 A：檢查清單（Checklist）
• 附錄 B：指令速查表
• 附錄 C：版本歷程摘要
• 附錄 D：官方基準測試結果（Worked Examples）
• 附錄 E：貢獻指南

第 1 章：Graphify 概述

1.1 什麼是 Graphify

Graphify 是由 AI 工程師 Safi Shamsi 開發的開源工具（GitHub 星數 74.4k+、貢獻者 100+、Releases 148+、Y Combinator S26 批次），能將任何資料夾（程式碼、PDF、圖片、影片、音訊、Markdown、Office 文件、Google Workspace、MCP 設定、Terraform/HCL、Salesforce Apex、XAML）自動轉化為可查詢的知識圖譜（Knowledge Graph）。

其核心靈感來自 Tesla 前 AI 主管 Andrej Karpathy 的 /raw 資料夾概念——將散亂的原始資料結構化，以圖譜形式呈現實體與關係，讓 AI 助手可以「看到結構」而非「暴力搜尋」。

核心價值主張：

• 完全多模態：支援 36+ 種程式語言 + PDF + 圖片 + 影片/音訊 + Office + Google Workspace + SQL Schema + YAML + .NET 專案檔 + MCP 設定檔 + Terraform/HCL + Salesforce Apex + CUDA/Metal + WPF/XAML
• Token 節省 71.5 倍（相較直接讀取原始檔案）
• 程式碼與影音完全本地運行，無資料外洩風險
• 100% Python，MIT 授權
• 支援 22+ 個 AI 平台（Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Amp、Devin、Kilo Code、CodeBuddy 等）
• 多後端推論：Claude、Gemini、OpenAI、Ollama（本地）、AWS Bedrock、Azure OpenAI、Kimi、DeepSeek、自訂 LLM Provider
• 自我改進記憶系統（Work Memory）：Q&A 結果自動回饋為 LESSONS.md，跨 session 持續學習

1.2 工具定位與比較

1.3 使用情境

1.4 與 AI Agent 的關係

Graphify 本質上是一個**「AI Coding Assistant Skill（技能）」**，設計為 AI 編程助手的擴充能力：

graph LR
    A[開發者] -->|提問| B[AI Coding Assistant]
    B -->|/graphify 指令| C[Graphify Skill]
    C -->|AST 解析| D[Tree-sitter]
    C -->|語義抽取| E[Claude Subagents]
    D --> F[Knowledge Graph]
    E --> F
    F -->|結構化回答| B
    B -->|精準回答| A

支援平台：

1.5 核心特色摘要

📌 實務建議：對於 50 個以上檔案的專案，Graphify 的 Token 節省效益最為顯著（71.5x+）。小型專案（< 10 檔案）的價值在於結構清晰度而非壓縮比。v0.8.12+ 將大型語料庫閘值由 200 提升至 500 個檔案，並在圖譜已存在時跳過提取直接進入查詢模式。v0.9.0+ 節點 ID 含完整路徑，解決同名檔案在不同目錄下靜默合併的問題。

1.6 多後端支援

Graphify v0.8+ 支援多種 LLM 後端，適用於不同企業環境與合規需求：

📌 自訂端點支援（v0.8.40+）：所有後端均支援 *_BASE_URL 環境變數指向自訂端點（如 OPENAI_BASE_URL、ANTHROPIC_BASE_URL、GEMINI_BASE_URL、KIMI_BASE_URL、DEEPSEEK_BASE_URL），可搭配企業內部代理、vLLM、llama.cpp 等自託管服務。

graph LR
    subgraph "Graphify 多後端架構"
        GF[Graphify Engine]
        GF -->|API| CL[Claude / Anthropic]
        GF -->|API| GM[Gemini / Google]
        GF -->|API| OA[OpenAI / Compatible]
        GF -->|Azure| AZ[Azure OpenAI<br>企業級]
        GF -->|Local| OL[Ollama<br>完全離線]
        GF -->|IAM| BD[AWS Bedrock<br>企業級]
        GF -->|API| KM[Kimi / Moonshot]
        GF -->|API| DS[DeepSeek]
        GF -->|CLI| CC[Claude CLI<br>訂閱額度]
        GF -->|Registry| CP[自訂 Provider<br>NVIDIA NIM / vLLM / OpenRouter]
    end

📌 企業建議：金融機構建議使用 Ollama（完全離線）、Azure OpenAI（企業級 IAM 認證）或 AWS Bedrock（IAM 認證），避免將程式碼結構資訊傳送至第三方 API。IDE 內建模式（/graphify）使用 IDE 提供的 LLM，無需額外設定 API Key。

1.7 Penpax 與生態系統發展

Graphify 定位為圖譜基礎層（Graph Layer）。專案團隊已獲得 Y Combinator S26 支持，並正基於 Graphify 構建 Penpax——一個裝置端數位分身（On-Device Digital Twin）：

graph TB
    subgraph "Graphify 生態系統"
        GF[Graphify<br>知識圖譜引擎]
        PP[Penpax<br>裝置端數位分身]
        AI[AI Coding Assistants<br>Claude Code / Codex / Trae]
    end

    GF -->|圖譜層| PP
    GF -->|Skill 整合| AI
    PP -->|連結會議/郵件/程式碼| USR[使用者]
    AI -->|結構化導航| DEV[開發者]

📌 企業關注：Penpax 的「無雲端」設計可能符合金融業與政府機構的資料在地化需求。建議持續關注其 waitlist 與發布動態。

第 2 章：系統架構設計

2.1 整體架構圖

graph TB
    subgraph "輸入層"
        CODE[程式碼<br>33+ 種語言]
        DOC[文件<br>.md .mdx .qmd .txt .rst .html .yaml .yml]
        OFFICE[Office<br>.docx .xlsx]
        GOOGLE[Google Workspace<br>.gdoc .gsheet .gslides]
        PDF[論文<br>.pdf]
        IMG[圖片<br>.png .jpg .webp .gif]
        VID[影片/音訊<br>.mp4 .mp3 .wav .mov]
        SQL_F[SQL Schema<br>.sql]
        DOTNET[.NET 專案<br>.sln .csproj .slnx .razor .cshtml]
        MCP_CFG[MCP 設定<br>.mcp.json mcp.json]
        TERRA[Terraform/HCL<br>.tf .tfvars .hcl]
        APEX[Salesforce Apex<br>.cls .trigger]
        GPU[CUDA/Metal<br>.cu .cuh .metal]
        XAML_F[WPF/XAML<br>.xaml]
        URL[URL / YouTube<br>論文 / 影片連結]
    end

    subgraph "處理層"
        DETECT[detect.py<br>檔案收集與過濾]
        
        subgraph "三階段提取引擎"
            AST[Pass 1: AST 解析<br>Tree-sitter + SQL<br>零 Token・本地]
            WHISPER[Pass 2: 影音轉錄<br>faster-whisper<br>零 Token・本地]
            SEM[Pass 3: 語義抽取<br>多後端 LLM 並行<br>消耗 Token]
        end
        
        DEDUP[deduplicate.py<br>MinHash/LSH 實體去重]
        VALIDATE[validate.py<br>Schema 驗證]
        BUILD[build.py<br>Graph 建構]
        CLUSTER[cluster.py<br>Leiden 社區偵測<br>確定性種子]
        ANALYZE[analyze.py<br>God Nodes / Surprises]
    end

    subgraph "輸出層"
        REPORT[GRAPH_REPORT.md<br>分析報告]
        HTML[graph.html<br>互動式圖譜]
        JSON[graph.json<br>持久化圖譜<br>含 built_at_commit]
        OBSIDIAN[Obsidian Vault<br>Wikilinks]
        WIKI[Wiki<br>Agent 導航]
        CALLFLOW[Callflow HTML<br>Mermaid 架構圖]
        TREE[D3 Tree<br>可折疊樹狀圖]
        EXPORT[SVG / GraphML / Neo4j / FalkorDB]
        MCP[MCP Server<br>stdio + HTTP]
        GLOBAL[Global Graph<br>~/.graphify/global.json]
        LESSONS[LESSONS.md<br>自我改進記憶]
    end

    subgraph "快取層"
        CACHE[cache.py<br>SHA256 語義快取<br>ast/ + semantic/ 分離]
    end

    CODE --> DETECT
    DOC --> DETECT
    OFFICE --> DETECT
    GOOGLE --> DETECT
    PDF --> DETECT
    IMG --> DETECT
    VID --> DETECT
    SQL_F --> DETECT
    DOTNET --> DETECT
    MCP_CFG --> DETECT
    TERRA --> DETECT
    APEX --> DETECT
    GPU --> DETECT
    XAML_F --> DETECT
    URL --> DETECT

    DETECT --> AST
    DETECT --> WHISPER
    DETECT --> SEM
    AST --> VALIDATE
    WHISPER --> SEM
    SEM --> VALIDATE
    CACHE -.->|跳過未變更| SEM
    VALIDATE --> DEDUP
    DEDUP --> BUILD
    BUILD --> CLUSTER
    CLUSTER --> ANALYZE
    ANALYZE --> REPORT
    ANALYZE --> HTML
    ANALYZE --> JSON
    ANALYZE --> OBSIDIAN
    ANALYZE --> WIKI
    ANALYZE --> CALLFLOW
    ANALYZE --> TREE
    ANALYZE --> EXPORT
    ANALYZE --> LESSONS
    JSON --> MCP
    JSON --> GLOBAL

2.2 三階段處理 Pipeline

Graphify 採用三階段提取流程，最大化本地處理、最小化 API 成本：

flowchart LR
    subgraph "Pass 1: 程式碼結構（免費）"
        A1[Tree-sitter AST]
        A2[SQL DDL 解析]
        A3[call-graph 建構]
    end
    subgraph "Pass 2: 影音轉錄（本地）"
        B1[faster-whisper]
        B2[領域感知提示<br>God Nodes 種子]
    end
    subgraph "Pass 3: 語義抽取（消耗 Token）"
        C1[多後端 LLM 並行]
        C2[文件/PDF/圖片/轉錄稿]
    end
    
    A1 --> A3
    A2 --> A3
    A3 --> B2
    B1 --> B2
    B2 --> C2
    C1 --> C2
    
    style A1 fill:#e1f5fe
    style A2 fill:#e1f5fe
    style B1 fill:#fff3e0
    style C1 fill:#fce4ec

📌 成本控制：Pass 1 與 Pass 2 完全免費。Pass 3 可使用 Ollama 後端（--backend ollama）達成零成本全流程，適合對外部 API 有限制的環境。

2.3 Pipeline 模組詳解

Graphify 的核心處理流程為 7 個純函數階段，無共享狀態：

detect() → extract() → build_graph() → cluster() → analyze() → report() → export()

flowchart LR
    A[detect<br>目錄掃描] --> B[extract<br>三階段提取]
    B --> C[dedup<br>實體去重]
    C --> D[build_graph<br>NetworkX圖]
    D --> E[cluster<br>Leiden社區]
    E --> F[analyze<br>分析結果]
    F --> G[report<br>GRAPH_REPORT]
    G --> H[export<br>多格式輸出]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style E fill:#fce4ec
    style F fill:#f3e5f5
    style G fill:#fff8e1
    style H fill:#e0f2f1

階段詳解

2.4 模組職責對照表

2.5 Graph 資料模型

每個提取器產出的標準 Schema：

{
  "nodes": [
    {
      "id": "unique_string",
      "label": "human readable name",
      "source_file": "path/to/file.java",
      "source_location": "L42",
      "file_type": "code|doc|paper|image|rationale|concept"
    }
  ],
  "edges": [
    {
      "source": "id_a",
      "target": "id_b",
      "relation": "calls|imports|uses|inherits|implements|semantically_similar_to|rationale_for",
      "confidence": "EXTRACTED|INFERRED|AMBIGUOUS",
      "confidence_score": 0.85,
      "source_file": "path/to/file.java",
      "source_location": "L42"
    }
  ]
}

Schema 驗證：validate.py 在 build_graph() 消費提取結果前會強制驗證此 Schema，不符合規格的資料會被拒絕並拋出錯誤。

合法 file_type 值：code、doc、paper、image、rationale、concept（v0.7+ 新增，用於抽象概念與設計模式節點）。

特殊節點/邊類型：

Hyperedges（超邊）詳解

傳統圖譜僅支援兩兩配對的邊（pairwise edges），無法精確表達 3 個以上節點的群組關係。Graphify 的 Hyperedges 解決此問題：

{
  "hyperedges": [
    {
      "nodes": ["StripeProcessor", "PayPalProcessor", "BankTransferProcessor"],
      "relation": "implements",
      "target": "PaymentProcessor",
      "confidence": "EXTRACTED",
      "source_file": "src/main/java/com/payment/"
    }
  ]
}

📌 實務建議：在 Neo4j 中，Hyperedges 可透過中間節點（Intermediate Node）模式表達，便於進行群組查詢與影響分析。

2.6 Confidence Labels（信賴標籤）

INFERRED 離散信賴分數等級（v0.7+ 新增）：

📌 企業實務：在銀行系統分析中，建議設定 CI 管線告警：當 AMBIGUOUS 邊佔比超過 15% 時，應安排人工審查。INFERRED 邊建議以 0.75 為閾值進行分級處理。

2.7 實體去重 Pipeline

Graphify v0.7+ 引入自動實體去重機制，解決大型專案中同一概念以不同名稱出現的問題：

flowchart LR
    A[所有提取實體] --> B[MinHash/LSH<br>候選對篩選]
    B --> C[Jaro-Winkler<br>字串相似度計算]
    C --> D{相似度 ≥ 閾值?}
    D -->|是| E[自動合併]
    D -->|否| F[保留為獨立實體]
    E --> G[合併後圖譜]
    F --> G
    
    style B fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#fce4ec

# 基本去重（純啟發式，免費）
graphify --dedup

# LLM 輔助去重（消耗少量 Token，精確度更高）
graphify --dedup-llm

📌 實務建議：對於 500+ 節點的大型圖譜，建議啟用 --dedup 以減少 10–30% 的冗餘節點。--dedup-llm 在企業級分析場景中可進一步提升 5–10% 的合併精確度。

2.8 與企業系統整合架構

graph TB
    subgraph "版本控制"
        GH[GitHub / GitLab]
    end

    subgraph "CI/CD Pipeline"
        CI[GitHub Actions / Jenkins]
        HOOK[Git Hooks<br>post-commit]
        MERGE[Git 合併驅動器<br>graph.json 聯合合併]
    end

    subgraph "Graphify"
        GF[Graphify CLI]
        GR[graph.json<br>含 built_at_commit]
        REP[GRAPH_REPORT.md]
        WIKI_OUT[Wiki 文件]
        CF[Callflow HTML]
        GLB[Global Graph<br>~/.graphify/global.json]
    end

    subgraph "知識平台"
        OBS[Obsidian]
        NEO[Neo4j]
        CONF[Confluence]
    end

    subgraph "AI Agent 系統"
        CLAUDE[Claude Code]
        COPILOT[GitHub Copilot]
        CURSOR[Cursor]
        GEMINI[Gemini CLI]
        MCP_S[MCP Server]
    end

    GH -->|push| CI
    CI -->|觸發| GF
    HOOK -->|commit| GF
    MERGE -->|merge| GR
    GF --> GR
    GF --> REP
    GF --> WIKI_OUT
    GF --> CF
    GR --> MCP_S
    GR --> NEO
    GR --> GLB
    REP --> OBS
    WIKI_OUT --> CONF
    MCP_S --> CLAUDE
    MCP_S --> CURSOR
    MCP_S --> GEMINI
    REP --> COPILOT

2.9 技術棧

📌 注意：不需要 Neo4j 伺服器即可運行。Neo4j 僅為可選的匯出目標。

第 3 章：安裝與環境建置

3.1 環境需求

3.2 安裝步驟（各平台）

推薦安裝方式（uv）

# uv 是目前推薦的安裝方式（速度最快、隔離性最佳）
uv tool install graphifyy

替代安裝方式（pip / pipx）

# pip 安裝
pip install graphifyy

# pipx 安裝（隔離虛擬環境）
pipx install graphifyy

Windows

# 1. 確認 Python 版本
python --version   # 需 3.10+

# 2. 安裝 Graphify（推薦 uv）
uv tool install graphifyy

# 3. 安裝 Skill（自動偵測 Windows）
graphify install

# 4. 驗證安裝
graphify --version

Linux / macOS

# 1. 確認 Python 版本
python3 --version   # 需 3.10+

# 2. 安裝 Graphify（推薦 uv）
uv tool install graphifyy

# 3. 安裝 Skill
graphify install

# 4. 驗證安裝
graphify --version

手動安裝（curl）

# 適用於無法使用 pip 的環境
curl -sSL https://raw.githubusercontent.com/safishamsi/graphify/v3/install.sh | bash

專案範圍安裝（Project-Scoped Install）

# 安裝 Skill 至專案目錄（而非全域 ~/）
graphify install --project

# 效果：將 skill 安裝至 .claude/skills/、.agents/skills/ 等專案本地目錄
# 適合 monorepo 或多專案環境，避免全域設定互相干擾

3.3 多平台支援

Graphify 支援 22+ 種 AI 開發平台：

Codex 額外設定：

# ~/.codex/config.toml
[features]
multi_agent = true   # 啟用並行提取

3.4 選用安裝項目（Optional Extras）

# PDF 支援
uv tool install graphifyy --with "graphifyy[pdf]"

# 影片/音訊支援（.mp4 / .mp3 / .wav 等）
uv tool install graphifyy --with "graphifyy[video]"

# SQL Schema 提取
uv tool install graphifyy --with "graphifyy[sql]"

# 中文查詢分詞
uv tool install graphifyy --with "graphifyy[chinese]"

# 全部安裝
uv tool install graphifyy --with "graphifyy[all]"

3.5 Docker 部署方式（企業推薦）

# Dockerfile
FROM python:3.12-slim

# 安裝系統依賴
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    && rm -rf /var/lib/apt/lists/*

# 安裝 Graphify（含所有 extras）
RUN pip install --no-cache-dir "graphifyy[all]"

# 設定工作目錄
WORKDIR /workspace

# 預設指令
ENTRYPOINT ["graphify"]
CMD ["--help"]

# 建置 Docker Image
docker build -t graphify:latest .

# 執行分析（掛載本地專案目錄）
docker run --rm \
  -v /path/to/project:/workspace \
  -v /path/to/output:/workspace/graphify-out \
  graphify:latest /workspace --no-viz

Docker Compose（企業 CI 整合）：

# docker-compose.yml
version: '3.8'
services:
  graphify:
    build: .
    volumes:
      - ./src:/workspace/src:ro
      - ./graphify-out:/workspace/graphify-out
    command: ["/workspace/src", "--no-viz"]
    environment:
      - PYTHONUNBUFFERED=1

3.6 安全性設定

Graphify 的安全機制為預設啟用，無需額外設定：

3.7 常見安裝問題排除

📌 企業建議：使用 Docker 部署可避免大多數環境相容性問題，並確保團隊一致的執行環境。建議使用 uv 取代 pip，安裝速度快 10–100x 且自動隔離。Mac 與 Windows 使用者強烈建議避免 pip install，改用 uv tool install，以避免 Python 環境不匹配導致的 ModuleNotFoundError。macOS 安裝後若找不到指令，執行 uv tool update-shell 重新載入 PATH。

第 4 章：基本使用教學

4.1 初始化專案

在專案根目錄開啟 AI Coding Assistant（以 Claude Code 為例）：

# 進入專案目錄
cd /path/to/your-project

# 在 Claude Code 中輸入
/graphify .

首次執行會：

1. 掃描目錄中所有支援的檔案
2. Pass 1：使用 Tree-sitter 進行 AST 解析（程式碼，零 Token）
3. Pass 2：使用 faster-whisper 轉錄影音檔案（本地，零 Token）
4. Pass 3：使用 LLM 進行語義抽取（文件/圖片/轉錄稿）
5. 執行實體去重（MinHash/LSH）
6. 建構 NetworkX 圖譜（支援有向圖）
7. 執行 Leiden 社區偵測（確定性種子）
8. 產出報告與匯出檔案

4.2 建立知識圖譜

# 基本使用 - 分析當前目錄
/graphify .

# 分析指定資料夾
/graphify ./src

# 深度模式 - 更積極的 INFERRED 邊提取
/graphify ./src --mode deep

# 僅重新聚類（已有圖譜時）
/graphify ./src --cluster-only

# 不產生 HTML 視覺化（CI 環境推薦）
/graphify ./src --no-viz

執行結果目錄結構：

graphify-out/
├── graph.html          # 互動式圖譜（vis.js）- 點擊節點、搜尋、社區篩選
├── GRAPH_REPORT.md     # God Nodes、Surprising Connections、建議問題
├── graph.json          # 持久化圖譜（含 built_at_commit）
├── callflow.html       # Callflow 互動式架構頁面（--callflow 時產出）
├── tree.html           # D3 可折疊樹狀圖（--tree 時產出）
├── obsidian/           # Obsidian Vault（--obsidian 時產出）
├── wiki/               # Wikipedia 風格文章（--wiki 時產出）
├── memory/             # Q&A 記憶回饋（自動累積）
├── reflections/        # LESSONS.md 自我改進記憶（v0.8.47+）
└── cache/              # SHA256 快取 - ast/ + semantic/ 分離
    ├── ast/            # AST 提取快取（Pass 1）
    └── semantic/       # 語義提取快取（Pass 3，v0.9.2+ 自動清理孤兒條目）

graph.html 互動功能

graph.html 使用 vis.js 渲染，提供以下互動能力：

支援檔案類型完整列表

4.3 指令完整說明

核心指令

新增內容

查詢指令

匯出指令

圖譜管理指令（v0.7+ 新增）

Git Hooks 管理

Always-On 助手設定

4.4 輸出內容說明

GRAPH_REPORT.md 包含

graph.json 使用方式

# 不要一次性貼到 prompt —— 使用 query 提取子圖
graphify query "show the auth flow" --graph graphify-out/graph.json
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json

輸出包含：節點標籤、邊類型、信賴標籤、來源檔案、來源位置。

4.5 .graphifyignore 設定

在專案根目錄建立 .graphifyignore，語法與 .gitignore 相同：

# .graphifyignore
vendor/
node_modules/
dist/
target/
*.generated.py
*.min.js
__pycache__/
.git/

📌 企業建議：務必排除 node_modules/、target/、dist/ 等建置產物，以避免圖譜被大量無關節點淹沒。

4.6 Always-On 模式設定

安裝 Always-On 後，AI 助手在每次 Glob / Grep 呼叫前都會自動讀取 GRAPH_REPORT.md：

# 安裝（以 Claude Code 為例）
graphify claude install

運作原理：

1. 寫入 CLAUDE.md 區段，告知 Claude 先讀 graphify-out/GRAPH_REPORT.md
2. 安裝 PreToolUse hook（.claude/settings.json），在每次 Glob/Grep 前觸發
3. Claude 看到提示：「Knowledge graph exists. Read GRAPH_REPORT.md for god nodes and community structure before searching raw files.」

類比：Always-On hook = 給 AI 一張地圖。/graphify 指令 = 讓 AI 精確導航地圖。

4.7 查詢知識圖譜

# 從終端機直接查詢（不需 AI 助手）
graphify query "what connects attention to the optimizer?"
graphify query "show the auth flow" --dfs
graphify query "what is CfgNode?" --budget 500
graphify query "..." --graph path/to/graph.json

# 在 AI 助手中使用
/graphify query "這個 API 呼叫了哪些服務？"
/graphify path "UserController" "DatabaseService"
/graphify explain "AuthenticationFilter"

📌 實務建議：先用 GRAPH_REPORT.md 了解整體結構，再用 query / path / explain 深入細節。

第 5 章：進階使用（企業必備）

5.1 全域知識圖譜（Global Graph）

v0.7+ 引入全域圖譜，可跨專案統一查詢：

# 建構後自動更新全域圖譜
/graphify ./project-a
/graphify ./project-b

# 全域圖譜位置
~/.graphify/global.json

# 跨專案查詢
graphify query "authentication" --graph ~/.graphify/global.json

全域圖譜特色：

• 自動合併所有已分析專案的圖譜
• 跨專案關係保留完整的社區結構
• 適用於微服務架構的統一知識查詢
• 以 home 目錄為根，不受 workspace 限制

📌 企業建議：將 ~/.graphify/global.json 透過共享儲存或定期同步機制分享給團隊，實現跨團隊知識查詢。

5.2 多 Repo 分析

對於微服務或 Monorepo 架構，可分別建圖後合併：

# 方法一：直接分析包含多個子專案的目錄
/graphify ./microservices/

# 方法二：使用 merge-graphs 合併（v0.7+ 新增）
/graphify ./service-a
/graphify ./service-b
graphify merge-graphs ./service-a/graphify-out ./service-b/graphify-out

# 方法三：使用 clone + 自動建圖（v0.7+ 新增）
graphify clone https://github.com/org/service-a
graphify clone https://github.com/org/service-b
graphify merge-graphs ./service-a/graphify-out ./service-b/graphify-out

# 方法四：逐一推送至 Neo4j
/graphify ./service-a --neo4j-push bolt://localhost:7687
/graphify ./service-b --neo4j-push bolt://localhost:7687

5.3 增量更新與 Watch 模式

# 增量更新 - 僅重新提取有變更的檔案（SHA256 快取，ast/ + semantic/ 分離）
/graphify ./src --update

# Watch 模式 - 背景持續同步
/graphify ./src --watch

Watch 模式行為：

• 程式碼變更：立即觸發 AST 重建（無 LLM 成本）
• 影音變更：觸發 faster-whisper 重新轉錄（本地，無 API 成本）
• 文件/圖片變更：通知使用者執行 --update 進行 LLM 重新分析
• 適用場景：多 Agent 並行開發時，圖譜自動保持最新

增量更新注意事項：

• 快取分為 ast/ 和 semantic/ 兩層，可獨立清除
• v0.3.14+ 已修復刪除檔案的幽靈節點問題（--update 會先清理再合併）
• v0.3.17+ 語義提取按目錄分組，跨 chunk 關係更精確
• 內容雜湊（SHA256 of content），重命名不觸發重提取

5.4 Git Hooks 與合併驅動器

# 安裝 git hooks（平台無關）
graphify hook install

# 檢查狀態
graphify hook status

# 移除
graphify hook uninstall

安裝後行為：

• post-commit：每次 commit 後自動重建圖譜
• post-checkout：切換分支後自動重建
• 失敗處理：hook 失敗會以非零退出碼通知 git
• pipx 相容：v0.3.15+ 正確偵測 pipx 安裝的 graphify
• 路徑驗證：v0.7.10+ hooks 路徑不可逃逸 workspace

Git 合併驅動器（v0.7+ 新增）

Graphify 提供 graph.json 專用的 Git 合併驅動器，解決多人協作時的圖譜合併衝突：

# .gitattributes
graphify-out/graph.json merge=graphify-union

# 設定合併驅動器
git config merge.graphify-union.name "Graphify union merge"
git config merge.graphify-union.driver "graphify merge-driver %O %A %B"

運作原理：

• 對 graph.json 中的 nodes 和 edges 進行聯合合併（union merge）
• 避免 <<<<<<< / >>>>>>> 衝突標記
• 保留兩個分支的所有新增實體
• 重複 ID 自動去重

5.5 與 CI/CD 整合

GitHub Actions 範例

# .github/workflows/graphify.yml
name: Build Knowledge Graph

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  graphify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      
      - name: Install Graphify
        run: pip install "graphifyy[all]"
      
      - name: Build Knowledge Graph（Headless）
        run: |
          graphify extract /github/workspace/src --no-viz
          # 使用 graphify extract（headless 模式，無需 IDE）
      
      - name: Upload Graph Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: knowledge-graph
          path: graphify-out/
      
      - name: Check AMBIGUOUS edges ratio
        run: |
          python -c "
          import json
          with open('graphify-out/graph.json') as f:
              data = json.load(f)
          edges = data.get('links', [])
          ambiguous = sum(1 for e in edges if e.get('confidence') == 'AMBIGUOUS')
          total = len(edges)
          ratio = ambiguous / total if total > 0 else 0
          print(f'AMBIGUOUS edges: {ambiguous}/{total} ({ratio:.1%})')
          if ratio > 0.15:
              print('::warning::AMBIGUOUS edge ratio exceeds 15%')
          "

flowchart LR
    A[git push] --> B[GitHub Actions]
    B --> C[Install Graphify]
    C --> D[Build Graph<br>--no-viz]
    D --> E[Upload Artifacts]
    D --> F[Quality Gate<br>AMBIGUOUS < 15%]
    E --> G[團隊下載<br>GRAPH_REPORT.md]
    F -->|Pass| H[PR Approved]
    F -->|Fail| I[需人工審查]

5.6 與 AI 助手整合

Claude Code（原生支援）

# 安裝 Always-On
graphify claude install

# 在 Claude Code 中使用
/graphify .                      # 建立圖譜
/graphify query "核心 API 流程"   # 查詢

Cursor（MCP 整合）

graphify cursor install
# Cursor 透過 MCP 協議與 graph.json 互動

Gemini CLI

graphify gemini install

GitHub Copilot CLI / VS Code Copilot Chat

# CLI 版本
graphify copilot install

# VS Code Copilot Chat（MCP 整合）
graphify vscode install

Codex

graphify install --platform codex
graphify codex install

# Codex 使用 $ 而非 /
$graphify .

搭配 MCP Server

# 啟動 MCP 伺服器
python -m graphify.serve graphify-out/graph.json

# 提供以下工具給 AI 助手
# - query_graph: 查詢圖譜
# - get_node: 取得節點詳情
# - get_neighbors: 取得鄰居節點
# - shortest_path: 最短路徑
# - god_nodes: God Nodes 列表

5.7 MCP Server 模式

# 啟動 MCP stdio 伺服器（預設）
graphify ./src --mcp

# 或從已建好的圖譜啟動
python -m graphify.serve graphify-out/graph.json

# 使用 graphify-mcp console script（v0.8.36+）
graphify-mcp graphify-out/graph.json

# HTTP transport（團隊共享，v0.8.34+）
python -m graphify.serve graphify-out/graph.json --transport http --port 8080 --api-key "$SECRET"

MCP 工具列表：

HTTP Transport 部署（v0.8.34+ 新增）：

# Docker 部署 MCP HTTP 伺服器
docker run --rm -p 8080:8080 \
  -v ./graphify-out:/data \
  -e GRAPHIFY_API_KEY="$SECRET" \
  graphify-mcp:latest --transport http

📌 注意：stdio 模式不開啟網路監聽。HTTP transport 需搭配 --api-key 認證，適合團隊共享場景。HTTP transport 依賴 starlette >= 1.3.1（已修復 CVE-2026-48818、CVE-2026-54283）。

5.8 知識圖譜查詢應用（RAG 強化）

Graphify 的 graph.json 不適合一次性貼入 prompt。正確的工作流程：

flowchart TD
    A[開始] --> B[閱讀 GRAPH_REPORT.md<br>了解整體結構]
    B --> C{需要深入?}
    C -->|是| D[graphify query<br>提取子圖]
    C -->|否| E[直接回答]
    D --> F[將子圖輸出<br>作為上下文]
    F --> G[提交給 LLM]
    G --> H[取得精準回答]

Graph RAG Prompt 範例：

使用以下圖譜查詢輸出來回答問題。優先依據圖譜結構，
引用來源檔案路徑。

[graphify query 輸出結果]

問題：AuthenticationFilter 的完整呼叫鏈是什麼？

5.9 多格式匯出

5.10 Wiki 生成

/graphify ./src --wiki

產出結構：

graphify-out/wiki/
├── index.md              # 入口頁面，社區總覽
├── community_0.md        # 社區文章，含內部節點與跨社區連結
├── community_1.md
├── god_node_UserService.md  # God Node 專屬文章
└── ...

特色：

• Wikipedia 風格的 Markdown 文章
• 跨社區 Wikilinks
• Cohesion scores
• 審計追蹤
• 導航頁腳

📌 企業應用：將 Wiki 輸出同步至 Confluence 或內部文件系統，作為「系統知識庫」供全團隊瀏覽。

5.11 記憶回饋迴圈（Memory Feedback Loop）

Graphify 自 v0.1.0 起內建記憶回饋機制：將使用者與圖譜的 Q&A 互動結果持久化，在後續更新時自動融入圖譜。v0.8.47+ 新增 Work Memory 層，提供結構化的學習回饋與知識聚合。

運作流程：

flowchart LR
    A[使用者提問] --> B[graphify query]
    B --> C[圖譜走訪<br>產出答案]
    C --> D[答案儲存至<br>graphify-out/memory/]
    C --> E[save-result<br>標記 outcome]
    D --> F[下次 --update]
    E --> F
    F --> G[memory/ 中的 Q&A<br>作為新輸入提取]
    G --> H[圖譜更新<br>新邊/新節點]
    H --> B
    D --> I[graphify reflect]
    I --> J[LESSONS.md<br>聚合學習摘要]
    J --> F

檔案結構：

graphify-out/
├── memory/
│   ├── qa_2026-04-08_001.json    # Q&A 記錄
│   ├── qa_2026-04-08_002.json
│   └── ...
├── LESSONS.md                     # 聚合學習摘要（v0.8.47+）
├── graph.json
└── GRAPH_REPORT.md

使用方式：

# 正常查詢 — Q&A 結果自動儲存至 memory/
/graphify query "核心認證流程是什麼？"

# 標記 Q&A 結果（v0.8.47+）
graphify save-result --outcome useful      # 標記為有用
graphify save-result --outcome dead_end    # 標記為無效
graphify save-result --outcome corrected   # 標記為需修正
graphify save-result --answer-file ans.md  # 多行答案從檔案讀取（v0.9.2+）

# 聚合學習摘要（v0.8.47+）
graphify reflect                           # 產出 LESSONS.md
graphify reflect --if-stale                # 僅過期時重建

# 下次增量更新時，memory/ + LESSONS.md 自動納入提取
/graphify ./src --update

Work Memory 三層架構（v0.8.47+）：

企業價值：

📌 注意：Memory 檔案隨 graphify-out/ 一同管理。建議在 .gitignore 中決定是否追蹤 graphify-out/memory/——追蹤可讓團隊共享累積知識，不追蹤則保持個人查詢隱私。LESSONS.md 建議提交版控。

5.12 Callflow HTML 匯出

v0.7+ 新增 Callflow HTML 匯出，自動產生含 Mermaid 架構圖的互動式呼叫流程頁面：

/graphify ./src --callflow

產出：

graphify-out/
├── callflow.html       # 互動式呼叫流程頁面
└── callflow/
    ├── index.html      # 入口（含全域架構 Mermaid 圖）
    ├── module_auth.html
    └── module_payment.html

特色：

• 自動產生 Mermaid flowchart 與 classDiagram
• 可展開/折疊的模組呼叫流程
• 按社區分組的模組導航
• 支援深層呼叫鏈追蹤

📌 企業應用：將 Callflow HTML 部署至內部 Web Server，作為「活的架構文件」供全團隊瀏覽。

5.13 Docker MCP Toolkit

v0.7+ 支援透過 Docker Desktop MCP Toolkit 整合，提供容器化的 MCP 伺服器：

# 使用 Docker MCP Toolkit 啟動
docker run --rm -i \
  -v ./graphify-out:/data \
  graphify-mcp:latest

# 或搭配 SQLite 持久化
docker run --rm -i \
  -v ./graphify-out:/data \
  -v ./db:/db \
  graphify-mcp-sqlite:latest

適用場景：

• 企業環境中需要隔離執行的 MCP 伺服器
• 與 Docker Desktop AI 助手整合
• 無需在主機安裝 Python/Graphify

5.14 PR Dashboard（v0.8.22+ 新增）

Graphify v0.8.22+ 引入圖譜感知 PR 分析，結合知識圖譜與 Git 差異，自動評估 PR 影響範圍：

# 基本 PR Dashboard
graphify prs

# AI Triage — 自動分類 PR 風險等級
graphify prs --triage

# 偵測語義衝突（跨 PR 的間接影響）
graphify prs --conflicts

# 多 worktree 環境下的 PR 分析
graphify prs --worktrees

MCP 工具（PR Dashboard 同時提供 MCP 介面）：

輸出範例（graphify prs --triage）：

PR #42: "Refactor AuthService"
  Risk: HIGH — touches God Node "AuthService" (degree 34)
  Cross-community: YES — affects 3 communities
  Files changed: 8 → Transitive impact: 23 files
  Suggested reviewers: @alice (auth domain), @bob (security)

PR #43: "Fix typo in README"
  Risk: LOW — no graph impact
  Cross-community: NO
  Files changed: 1 → Transitive impact: 0 files

📌 企業應用：在 CI 中執行 graphify prs --triage，自動將高風險 PR 標記為需要額外審查，低風險 PR 可自動合併。

5.15 自訂 LLM Provider Registry（v0.8.24+ 新增）

v0.8.24+ 支援註冊自訂 LLM Provider，可整合企業內部部署的推論端點。v0.8.30+ 新增 *_BASE_URL 環境變數支援，v0.8.32+ 新增 Azure OpenAI 後端。

# 註冊自訂 Provider
graphify provider add nvidia-nim \
  --base-url https://internal.example.com/v1 \
  --model meta/llama3-70b-instruct \
  --api-key-env NVIDIA_API_KEY

# 列出所有已註冊 Provider
graphify provider list

# 檢視特定 Provider 設定
graphify provider show nvidia-nim

# 移除 Provider
graphify provider remove nvidia-nim

# 使用自訂 Provider 進行提取
graphify extract ./src --backend nvidia-nim

# 使用 BASE_URL 環境變數（v0.8.30+）
export OPENAI_BASE_URL=https://my-proxy.example.com/v1
graphify extract ./src --backend openai

# Azure OpenAI 後端（v0.8.32+）
export AZURE_OPENAI_ENDPOINT=https://my-instance.openai.azure.com/
export AZURE_OPENAI_API_KEY=<key>
export AZURE_OPENAI_API_VERSION=2025-01-21-preview
graphify extract ./src --backend azure

已驗證的相容 Provider：

BASE_URL 環境變數對照（v0.8.30+）：

設定檔位置：~/.graphify/providers.json

{
  "nvidia-nim": {
    "base_url": "https://internal.example.com/v1",
    "model": "meta/llama3-70b-instruct",
    "api_key_env": "NVIDIA_API_KEY"
  }
}

📌 企業應用：可將企業內部的 GPU 叢集透過 vLLM / NVIDIA NIM 提供推論服務，搭配 graphify provider add 註冊後即可使用，資料完全不離開內網。Azure OpenAI 後端特別適合已有 Azure 企業合約的組織。

5.16 Import Cycle Detection（v0.8.15+ 新增）

v0.8.15+ 新增檔案級循環匯入偵測，使用 Johnson’s algorithm 自動發現 import cycles：

# 建構圖譜時自動偵測
/graphify ./src

# 偵測結果會出現在 GRAPH_REPORT.md 的 "## Import Cycles" 段落

GRAPH_REPORT.md 輸出範例：

## Import Cycles

Found 2 import cycles:

### Cycle 1 (length 3)

src/auth/service.py → src/auth/middleware.py → src/auth/utils.py → src/auth/service.py

### Cycle 2 (length 2)

src/models/user.py → src/models/profile.py → src/models/user.py

技術細節：

• 使用 find_import_cycles(G) 函數（analyze.py）
• 基於 Johnson’s algorithm 偵測有向圖中所有簡單環
• 僅分析 imports 邊（非 calls 或 uses）
• 對大型圖譜自動限制搜尋深度以避免效能問題

📌 企業應用：在 CI 中設定品質門檻：若偵測到新增的循環匯入，CI 應發出警告或阻擋合併。

5.17 Project-Scoped Install（v0.8.26+ 新增）

v0.8.26+ 支援專案範圍安裝，將 Skill 安裝至專案目錄而非全域 ~/ 路徑：

# 專案範圍安裝
graphify install --project

# 效果：
# - Claude Code → .claude/skills/graphify.md（而非 ~/CLAUDE.md）
# - Cursor → .cursor/skills/graphify.md
# - VS Code → .vscode/skills/graphify.md
# - 其他平台 → .agents/skills/graphify.md

適用場景：

📌 企業建議：搭配 .gitignore 策略，將 .claude/skills/ 等目錄納入版本控制，讓團隊成員 clone 專案後即獲得一致的 Graphify Skill 設定。

5.18 Azure OpenAI 後端（v0.8.32+ 新增）

v0.8.32+ 新增原生 Azure OpenAI 後端支援，適合有 Azure 企業合約的組織：

# 設定 Azure OpenAI 環境變數
export AZURE_OPENAI_ENDPOINT=https://my-instance.openai.azure.com/
export AZURE_OPENAI_API_KEY=<your-key>
export AZURE_OPENAI_API_VERSION=2025-01-21-preview

# 使用 Azure 後端建構圖譜
graphify extract ./src --backend azure

# 指定部署名稱（若非預設）
export AZURE_OPENAI_DEPLOYMENT=gpt-4o-deployment
graphify extract ./src --backend azure

與標準 OpenAI 的差異：

📌 企業應用：Azure OpenAI 可確保資料駐留在指定區域，搭配 Azure VNET 私有端點，資料完全不離開企業網路。

5.19 Terraform / HCL 支援（v0.8.30+ 新增）

v0.8.30+ 新增 Terraform / HCL 基礎設施即程式碼的圖譜建構支援：

# 建構 Terraform 知識圖譜
graphify extract ./infra --include "*.tf,*.tfvars"

# 查詢資源依賴
/graphify query "哪些資源依賴 aws_vpc.main？"

支援範圍：

產出範例（GRAPH_REPORT.md 摘錄）：

## God Nodes
1. aws_vpc.main (degree: 47) — 所有子網路、安全群組均依賴此 VPC
2. module.eks_cluster (degree: 32) — K8s 叢集為核心基礎設施

## Import Cycles
⚠ aws_security_group.api → aws_security_group.db → aws_security_group.api

5.20 Salesforce Apex 支援（v0.8.31+ 新增）

v0.8.31+ 支援 Salesforce Apex 語言，涵蓋 Trigger、Custom Object、Flow 等 Salesforce 特有結構：

# 建構 Salesforce 專案圖譜
graphify extract ./force-app --include "*.cls,*.trigger,*.xml"

# 查詢物件間關係
/graphify query "Account 觸發器的完整流程"

支援範圍：

5.21 PostgreSQL Schema 內省（v0.8.34+ 新增）

v0.8.34+ 支援連接 PostgreSQL 資料庫，即時擷取 Schema 結構並納入圖譜：

# 連接 PostgreSQL 擷取 Schema
graphify extract --postgres "postgresql://user:pass@localhost:5432/mydb"

# 合併程式碼 + DB Schema
graphify extract ./src --postgres "postgresql://user:pass@localhost:5432/mydb"

擷取範圍：

📌 安全注意：連線字串包含密碼，建議使用環境變數 GRAPHIFY_POSTGRES_DSN 替代命令列明碼。連線僅用於 information_schema / pg_catalog 讀取，不會修改資料。

5.22 FalkorDB 圖資料庫整合（v0.8.39+ 新增）

v0.8.39+ 新增 FalkorDB 圖資料庫支援，提供比 Neo4j 更輕量的圖儲存方案：

# 推送圖譜至 FalkorDB
graphify extract ./src --falkordb

# 指定 FalkorDB 連線
export FALKORDB_URL=redis://localhost:6379
graphify extract ./src --falkordb

與 Neo4j 比較：

5.23 Cargo Workspace 映射（v0.8.38+ 新增）

v0.8.38+ 支援 Rust Cargo workspace 的多 crate 結構映射：

# Cargo workspace 映射
graphify extract ./my-workspace --cargo

# 結合深度分析
graphify extract ./my-workspace --cargo --mode deep

支援範圍：

• Cargo.toml workspace members → 子 crate 節點
• crate 間 dependencies → DEPENDS_ON 邊
• [features] 條件依賴 → 條件邊
• build.rs → 建置腳本節點
• extern crate / use → 模組引用邊

5.24 CUDA / Metal Shader 支援（v0.8.40+ 新增）

v0.8.40+ 新增 GPU Shader 語言支援，涵蓋 CUDA 與 Metal：

# CUDA 核心程式碼圖譜
graphify extract ./cuda-kernels --include "*.cu,*.cuh"

# Metal Shader 圖譜
graphify extract ./shaders --include "*.metal"

支援範圍：

5.25 WPF / XAML 支援（v0.8.41+ 新增）

v0.8.41+ 支援 WPF / XAML 應用程式的 UI 層圖譜建構：

# WPF 專案圖譜（含 XAML）
graphify extract ./WpfApp --include "*.xaml,*.cs"

支援範圍：

5.26 Graph Health Gate（v0.8.44+ 新增）

v0.8.44+ 新增 Graph Health Gate — 圖譜品質閘門，可在 CI/CD 中自動驗證圖譜品質：

# 執行健康檢查
graphify extract ./src --health-gate

# CI/CD 整合 — 失敗則中斷 pipeline
graphify extract ./src --health-gate --fail-on-warning

檢查項目：

CI 整合範例（GitHub Actions）：

- name: Graph Health Gate
  run: |
    graphify extract ./src --health-gate --fail-on-warning
    echo "Graph quality passed ✅"

產出報告：graphify-out/HEALTH_REPORT.md

5.27 Trigram Query 預過濾（v0.8.45+ 新增）

v0.8.45+ 新增 Trigram 預過濾，使用純 NumPy trigram 索引加速圖譜查詢，取代原先的 datasketch MinHash：

# 查詢自動使用 trigram 預過濾（無需額外設定）
/graphify query "認證模組的依賴關係"

效能改善：

📌 注意：datasketch 與 scipy 已從 v0.8.45+ 的依賴中移除，改用純 NumPy 實作。升級後 pip install graphifyy 會自動清理舊依賴。

5.28 新增平台支援（v0.8.27+ 持續擴充）

v0.8.27 之後持續擴充 AI 平台整合：

Always-On 指令對照（各平台語法差異）：

第 6 章：實戰案例

6.1 案例一：舊系統逆向工程（Java / Spring）

問題背景

某銀行核心系統已運行 15 年，技術棧為 Java 8 + Spring Framework 4.x + Oracle DB。原始團隊已全數離職，僅剩程式碼與使用手冊，無設計文件。新團隊需要在 3 個月內完成現代化評估。

解法

# Step 1: 建立知識圖譜
/graphify ./legacy-banking-system --mode deep

# Step 2: 檢視 God Nodes 找出核心元件
cat graphify-out/GRAPH_REPORT.md

# Step 3: 查詢特定流程
/graphify query "交易處理流程"
/graphify path "TransactionController" "OracleDAO"
/graphify explain "TransactionService"

# Step 4: 建立 Wiki 供團隊瀏覽
/graphify ./legacy-banking-system --wiki

# Step 5: 匯出至 Neo4j 進行深度分析
/graphify ./legacy-banking-system --neo4j-push bolt://localhost:7687

Graphify 介入效果

成果

• 自動識別 12 個 God Nodes（核心服務類）
• 發現 3 個未記錄的跨模組循環依賴
• 從 # HACK: 和 # WHY: 註解中提取 47 個設計決策
• 產出完整系統文件，Token 消耗僅為直接閱讀的 1/71

6.2 案例二：微服務架構知識盤點

問題背景

金融平台包含 28 個微服務，分散在多個 GitHub Repository。跨服務 API 呼叫關係不明，每次變更都擔心影響未知服務。

解法

# Step 1: 逐一建圖並推送至 Neo4j
for service in service-auth service-account service-payment service-notification; do
  git clone https://github.com/org/$service /tmp/$service
  cd /tmp/$service
  /graphify . --neo4j-push bolt://localhost:7687
done

# Step 2: 在 Neo4j 中查詢跨服務依賴
# MATCH (a)-[r:calls]->(b) WHERE a.source_file CONTAINS 'service-payment' RETURN a, r, b

# Step 3: 對關鍵服務做影響分析
/graphify path "PaymentGateway" "NotificationService"

成果

6.3 案例三：新人 Onboarding 加速

問題背景

大型 Java Web 專案，新進工程師平均需要 4-6 週才能獨立開發。

解法

# Step 1: 建立圖譜與 Wiki
/graphify ./project --wiki

# Step 2: 安裝 Always-On 讓新人的 AI 助手自動引導
graphify claude install

# Step 3: 新人直接對 Claude 提問
# "系統中核心的身份驗證流程是什麼？"
# Claude 自動參考 GRAPH_REPORT.md 回答

成果

• Onboarding 時間從 4-6 週縮短至 1-2 週
• 新人的第一個 PR 提交時間提前 60%
• 資深工程師回答重複問題的時間減少 70%

📌 實務建議：將 graphify-out/wiki/ 加入專案的標準文件結構，每次 release 時自動更新。

6.4 案例四：影音知識庫建構

問題背景

某技術團隊累積了 200+ 小時的內部技術分享影片（.mp4），散佈在共享磁碟中，無人整理索引。新人無法快速找到相關主題的影片。

解法

# Step 1: 安裝影音支援
uv tool install graphifyy[video]

# Step 2: 建立影音知識圖譜
/graphify ./tech-talks --mode deep

# Step 3: 查詢特定主題
/graphify query "Kubernetes 部署最佳實務"
/graphify query "資料庫效能調校"

# Step 4: 產出 Wiki 索引
/graphify ./tech-talks --wiki

Graphify 介入效果

成果

• 200+ 小時影片在 ~4 小時內完成轉錄與圖譜建構（Pass 2 本地、Pass 3 LLM）
• 自動識別 45 個技術主題社區
• 發現 12 個跨主題的知識關聯（如「微服務設計」與「Kafka 事件驅動」的連結）

📌 實務建議：影音檔案的 Pass 2（faster-whisper）完全在本地執行，適合含機密內容的內部影片。

第 7 章：系統升級與版本管理

7.1 升級 Graphify

# 升級至最新版本（推薦 uv）
uv tool install --upgrade graphifyy

# 或使用 pip
pip install --upgrade graphifyy

# 確認版本
graphify --version

# 重新安裝 Skill（建議每次升級後執行）
graphify install

# 重新安裝 Always-On（如果有使用）
graphify claude install    # 或對應平台

版本陳舊偵測：v0.3.10+ 會自動檢查已安裝的 Skill 版本是否過期，並顯示警告。

7.2 Graph Schema 版本控制

# 建議的 .gitignore 策略
graphify-out/cache/
graphify-out/graph.html
graphify-out/callflow.html
graphify-out/tree.html
graphify-out/*.svg

# 追蹤以下檔案（納入版本控制）
# graphify-out/GRAPH_REPORT.md
# graphify-out/graph.json        ← 含 built_at_commit 追蹤
# graphify-out/wiki/

# 建議的 .gitattributes（啟用合併驅動器）
# graphify-out/graph.json merge=graphify-union

built_at_commit 追蹤（v0.7+ 新增）：

• graph.json 自動記錄建構時的 git commit hash
• 可用於判斷圖譜新鮮度與程式碼同步狀態
• GRAPH_REPORT.md 顯示新鮮度檢查結果

Graph 重建策略：

7.3 與 Git 版本同步策略

flowchart TD
    A[開發者 commit] --> B{Git Hook<br>已安裝?}
    B -->|是| C[自動重建圖譜]
    B -->|否| D[手動 --update]
    C --> E[graphify-out/ 更新]
    D --> E
    E --> F{納入版本控制?}
    F -->|GRAPH_REPORT + graph.json| G[git add & commit]
    F -->|cache + html| H[.gitignore 排除]

    I[分支切換] --> J{post-checkout<br>hook?}
    J -->|是| K[自動重建]
    J -->|否| L[手動重建]

📌 企業建議：在 CI 管線中為每個 release tag 建立圖譜快照，方便日後版本間架構比較。

7.4 v0.9.0 破壞性變更遷移指南

v0.9.0 引入節點 ID 格式變更——最重要的破壞性更新。此變更解決了長期存在的同名檔案靜默碰撞問題。

變更內容

影響範圍

1. graph.json：節點 ID 會從短檔名變為完整路徑——下次 graphify extract 或 --update 時自動遷移
2. GraphML 匯出：舊 .graphml 檔案的節點 ID 不再對應——需重新匯出
3. Neo4j 資料：已推送的 Cypher 節點 ID 不匹配——需重新匯入
4. FalkorDB：同 Neo4j，需重新匯入
5. Obsidian Vault：筆記檔名可能因路徑前綴而改變——建議重新產生
6. memory/ Q&A：引用舊 ID 的記錄可能查無節點——可安全保留，不影響功能

遷移步驟

# Step 1: 升級至 v0.9.0+
pip install --upgrade graphifyy

# Step 2: 重建圖譜（自動遷移 ID 格式）
graphify extract ./src --force

# Step 3: 驗證先前碰撞的同名檔案是否已正確分離
graphify extract ./src --timing
# 檢查 GRAPH_REPORT.md 中的節點數 — 應比舊版多（因碰撞節點已分離）

# Step 4: 重新匯出外部格式
graphify extract ./src --graphml    # 重新匯出 GraphML
graphify extract ./src --neo4j-push bolt://localhost:7687  # 重新推送 Neo4j

# Step 5:（可選）復原先前因碰撞而遺失的節點
graphify extract --force
# --force 會完全重建，確保所有先前碰撞的節點都被正確提取

查詢語法調整

# 舊版（v0.8.x）— 使用短檔名
/graphify query "utils.py 的功能"

# 新版（v0.9.0+）— 建議使用 label 查詢
/graphify query "label:authentication 的功能"
# 或使用完整路徑
/graphify query "src/auth/utils.py 的功能"

📌 注意：現有 graphify-out/ 目錄在 v0.9.0+ 首次建構時會自動遷移，無需手動操作。但外部系統（Neo4j、FalkorDB、Gephi）中的資料需要重新匯入。

第 8 章：安全與隱私設計（SSDLC）

8.1 安全模型總覽

Graphify 是本地開發工具，設計原則為「最小權限」：

• 圖譜分析期間不進行任何網路呼叫
• 僅在 ingest 指令時存取使用者明確指定的 URL
• MCP 伺服器預設透過 stdio 通訊，不開啟網路監聽
• HTTP transport（v0.8.34+）需明確啟用，且強制要求 --api-key 認證
• 不執行原始碼（Tree-sitter 只解析 AST，不 eval/exec）
• 不使用 shell=True
• 不儲存憑證或 API Key
• 依賴 starlette >= 1.3.1（已修復 CVE-2026-48818 路徑穿越、CVE-2026-54283 DoS）

8.2 本地運算優勢

網路呼叫範圍：

• 程式碼：100% 本地（Tree-sitter AST）
• 文件/圖片：透過所屬 AI 平台的 API（Anthropic / OpenAI），使用使用者自己的 API Key
• ingest <URL>：根據使用者明確指定的 URL 進行擷取

8.3 威脅面與緩解措施

8.4 敏感資料處理

建議的 .graphifyignore 安全性排除清單：

# 敏感檔案排除
*.key
*.pem
*.env
*.credentials
*.secret
config/secrets/
passwords.properties

企業建議：

1. 在 CI 管線中加入敏感資料掃描步驟（如 git-secrets），確保 graph.json 不含敏感資料
2. 若分析包含客戶資料的系統，建議在隔離環境中運行
3. graph.json 包含原始碼結構資訊（類別名、函數名），應視為內部機密文件

8.5 權限控管（RBAC）

Graphify 本身不內建 RBAC，但可透過以下方式實現：

8.6 稽核與追蹤

📌 合規建議：對於金融系統，建議將圖譜建置流程加入 SSDLC 的「程式碼分析」階段，並保留 6 個月以上的圖譜快照。

8.7 漏洞回報流程

根據官方 SECURITY.md，Graphify 有明確的漏洞回報機制：

回報方式：

回報內容應包含：

1. 漏洞描述
2. 重現步驟
3. 潛在影響範圍
4. 建議修復方式（如有）

回應承諾：

📌 企業建議：內部安全團隊應將 Graphify 的 SECURITY.md 納入第三方元件安全評估範圍，並訂閱 GitHub Release Notifications 追蹤安全更新。

8.8 支援版本政策

升級建議：

• 使用 0.7.x 的用戶應升級至 0.8.x 以獲得 XML DoS 防護、NAT64 阻擋、敏感目錄封鎖等安全修復
• 每次升級後重新安裝 Skill（graphify install），確保平台整合一致
• v0.3.10+ 內建版本陳舊偵測，會在 Skill 版本過期時自動警告

📌 企業政策：建議在內部套件管理中設定版本下限為 graphifyy >= 0.8.12，確保包含所有已知安全修復。

第 9 章：最佳實務（Best Practices）

9.1 大型專案使用建議

1. 分層建圖：對 Monorepo，按模組分別建圖再合併至 Neo4j
2. CI 自動化：在 CI 中使用 --no-viz 減少建置時間
3. 增量優先：日常開發使用 --update，Release 時全新建圖
4. 排除噪音：設定完善的 .graphifyignore
5. Watch 模式：多 Agent 並行開發時啟用自動同步
6. 定期清理：清除過期的快取（graphify-out/cache/）

9.2 Token 最佳化策略

9.3 Graph 建模技巧

1. 活用 --mode deep：對關鍵模組使用深度模式，取得更多 INFERRED 邊
2. 關注 God Nodes：度數最高的節點通常是系統核心
3. 審查 AMBIGUOUS：定期審查不確定的邊，確認或刪除
4. 利用 Hyperedges：關注群組關係（如所有實作同一介面的類別）
5. 追蹤 rationale_for：從 # WHY: / # HACK: 註解中提取設計決策
6. 語義相似度邊：關注 semantically_similar_to 邊，找出未直接連結但功能相似的模組

9.4 團隊導入策略

flowchart LR
    A[Phase 1<br>概念驗證] --> B[Phase 2<br>標準化]
    B --> C[Phase 3<br>全面導入]
    
    A1[選擇 1 個專案<br>試運行] --> A
    B1[建立 .graphifyignore<br>模板] --> B
    B2[整合 CI/CD] --> B
    C1[所有專案<br>Always-On] --> C
    C2[Neo4j 集中管理] --> C

Phase 1：概念驗證（1-2 週）

• 選擇一個中型專案（20-50 檔案）試運行
• 評估 GRAPH_REPORT.md 的實用性
• 團隊成員試用 query 功能

Phase 2：標準化（2-4 週）

• 建立團隊統一的 .graphifyignore 模板
• 整合 CI/CD 自動建圖
• 制定圖譜品質規範（AMBIGUOUS 比例上限）

Phase 3：全面導入（持續）

• 所有專案啟用 Always-On 模式
• 部署 Neo4j 集中管理多專案圖譜
• 定期圖譜品質審查與優化

9.5 環境變數參考

📌 實務建議：在 CI 環境中使用 GRAPHIFY_OUT 自訂輸出路徑，避免與其他 pipeline 步驟衝突。GRAPHIFY_API_TIMEOUT 自 v0.8.36+ 預設值已從 60 秒提升至 600 秒，避免大型專案逾時。

第 10 章：常見問題（FAQ）

效能問題

Q：大型專案（1000+ 檔案）執行很慢？

• 使用 .graphifyignore 排除不必要的檔案
• 使用 --no-viz 跳過 HTML 產生
• 使用 --update 增量更新而非全新建圖
• v0.3.17+ 每 100 個檔案會顯示進度，不會看起來像是當機

Q：Watch 模式佔用太多資源？

• 程式碼變更的 AST 重建非常輕量（無 LLM）
• 文件/圖片變更僅發出通知，不自動觸發 LLM

Q：Louvain fallback 導致無限迴圈？

• v0.3.11+ 已增加 max_level=10, threshold=1e-4 防止大型稀疏圖的無限迴圈

Token 使用

Q：Token 節省 71.5 倍是怎麼算的？

• 首次執行需消耗 Token 建圖（語義提取階段）
• 後續每次查詢都從壓縮的圖譜讀取，這是節省累計的地方
• 基準測試在 52 檔案混合語料（程式碼 + 論文 + 圖片）上測得

Q：程式碼更新語義提取耗費多少 Token？

• SHA256 快取確保僅重新提取有變更的檔案
• 程式碼檔案的 AST 提取完全本地，零 Token
• 僅文件和圖片需要 LLM Token

語意錯誤

Q：圖譜中出現錯誤的 INFERRED 邊？

• 檢查 confidence_score（0.0-1.0），低分邊可能不準確
• 使用 --cluster-only 重新聚類而不重新提取
• 人工審查 AMBIGUOUS 邊並提供回饋

Q：跨檔案關係遺漏？

• v0.3.17 改善了 chunk 分組策略（按目錄分組）
• 考慮使用 --mode deep 進行更積極的推論

多語言支援問題

Q：支援哪些語言？

• 程式碼（33+ 種 Tree-sitter 語言）：Python, JS, TS, JSX, TSX, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Fortran, Pascal/Delphi, Verilog/SystemVerilog, Dart, Groovy, Vue, Svelte, Astro, Bash, JSON, BYOND DreamMaker, ArkTS
• .NET 專案：.sln, .csproj, .fsproj, .vbproj, .razor, .cshtml
• WPF / XAML：.xaml（v0.8.41+）
• Terraform / HCL：.tf, .tfvars（v0.8.30+）
• Salesforce Apex：.cls, .trigger（v0.8.31+）
• GPU Shader：.cu, .cuh（CUDA）, .metal（Metal）（v0.8.40+）
• 文件：.md, .mdx, .qmd, .txt, .rst, .html
• 結構化資料：.yaml, .yml, .json, .sql
• MCP 設定：.mcp.json
• Office：.docx, .xlsx（需 [office] extra）
• Google Workspace：.gdoc, .gsheet, .gslides
• 論文：.pdf（需 [pdf] extra）
• 圖片：.png, .jpg, .webp, .gif（Vision LLM）
• 影片/音訊：.mp4, .mp3, .wav, .mov 等（需 [video] extra）
• 無副檔名腳本：透過 shebang 偵測

Q：Julia 支援包含哪些？

• v0.3.17+ 新增，涵蓋 modules、structs、abstract types、functions、short functions、using/import、call edges、inherits edges
• 透過 tree-sitter-julia 實作

Q：影片/音訊如何處理？

• 使用 faster-whisper 本地轉錄（Pass 2），完全離線、零 API 成本
• 轉錄稿在 Pass 3 中由 LLM 提取概念和關係
• 需安裝 [video] extra：uv tool install graphifyy[video]

Q：圖片中的非英文文字可以辨識嗎？

• 可以。Graphify 使用 Vision LLM（Claude Vision / Gemini Vision / OpenAI Vision），支援多語言圖片內容抽取。

平台與相容性問題

Q：支援哪些 LLM 後端？

• Claude（Anthropic）、Claude CLI、Gemini（Google）、OpenAI、Azure OpenAI（v0.8.32+）、Ollama（本地）、AWS Bedrock、Kimi（Moonshot）、DeepSeek、自訂 Provider（OpenAI 相容端點）
• 使用 --backend <name> 指定，或設定 GRAPHIFY_BACKEND 環境變數
• 自訂 Provider 可透過 graphify provider add 註冊（v0.8.24+）

Q：可以完全離線使用嗎？

• 可以。使用 --backend ollama 搭配本地 Ollama 服務，全流程零 API 成本、零網路需求。

Q：PyPI 套件名為什麼是 graphifyy 而非 graphify？

• 這是暫時性命名，graphify 名稱正在回收中。CLI 和 Skill 指令仍然是 graphify。

Q：NetworkX 版本相容性問題？

• v0.3.16+ 已加入 node_link_graph() 版本安全墊片，支援 NetworkX < 3.4

Q：可以在沒有 AI 助手的情況下使用嗎？

• 可以。graphify query CLI 指令可直接在終端機查詢 graph.json，不需要 AI 助手
• MCP Server 模式也可獨立運行：python -m graphify.serve graphify-out/graph.json

Q：可以同時使用多個匯出格式嗎？

• 可以。多個旗標可組合使用：

  /graphify ./src --obsidian --wiki --svg --neo4j

v0.9.0 遷移問題

Q：升級到 v0.9.0 後圖譜會壞掉嗎？

• 不會。現有 graphify-out/ 會在首次建構時自動遷移至新的完整路徑 Node ID 格式。
• 但外部系統（Neo4j、FalkorDB、Gephi）中的資料需要重新匯入。

Q：升級後節點數量變多了？

• 正常現象。v0.9.0 之前同名檔案會靜默碰撞合併為單一節點。升級後每個檔案都有獨立的完整路徑 ID，先前碰撞的節點會被正確分離。
• 使用 graphify extract --force 確保完全重建。

Q：查詢時找不到原本存在的節點？

• v0.9.0 Node ID 格式從短檔名改為完整路徑。建議改用 label 查詢：

  /graphify query "label:authentication 的依賴關係"

新語言 / 新功能問題

Q：如何啟用 Terraform / HCL 支援？

• 無需額外設定，v0.8.30+ 自動偵測 .tf / .tfvars 檔案。
• 或明確指定：graphify extract ./infra --include "*.tf,*.tfvars"

Q：如何連接 PostgreSQL 擷取 Schema？

• 使用 --postgres 參數搭配連線字串：

  graphify extract --postgres "postgresql://user:pass@host:5432/db"

• 建議使用環境變數 GRAPHIFY_POSTGRES_DSN 避免密碼明碼。

Q：CUDA / Metal Shader 支援的限制？

• v0.8.40+ 支援基本的 kernel/function 節點和呼叫關係。
• 不支援 PTX assembly 或 SPIR-V 中間碼。

Q：macOS 安裝後 graphify 指令找不到？

• uv tool install 安裝路徑可能未在 PATH 中。執行：

  export PATH="$HOME/.local/bin:$PATH"

• 或加入 ~/.zshrc（macOS 預設 shell）。

Q：如何使用 Azure OpenAI 後端？

• 設定三個環境變數後使用 --backend azure：

  export AZURE_OPENAI_ENDPOINT=https://my-instance.openai.azure.com/
  export AZURE_OPENAI_API_KEY=<key>
  export AZURE_OPENAI_API_VERSION=2025-01-21-preview
  graphify extract ./src --backend azure

附錄 A：檢查清單（Checklist）

初次安裝

• Python 3.10+ 已安裝
• uv tool install graphifyy 或 pip install graphifyy 執行成功
• graphify --version 顯示 v0.8.26+
• graphify install 安裝對應平台 Skill
• AI Coding Assistant 可正常執行 /graphify .

專案設定

• .graphifyignore 已設定（排除 node_modules/、target/、dist/ 等）
• 首次 /graphify . 執行成功
• graphify-out/GRAPH_REPORT.md 可正常閱讀
• graphify-out/graph.html 可在瀏覽器中開啟
• 敏感檔案已加入 .graphifyignore

Always-On 設定

• graphify claude install（或對應平台 install）已執行
• AI 助手在搜尋前會自動參考 GRAPH_REPORT.md
• 測試查詢：AI 能從圖譜結構回答架構問題

Git Hooks

• graphify hook install 已執行
• graphify hook status 顯示正常
• commit 後圖譜自動更新

CI/CD 整合

• GitHub Actions / Jenkins 設定 Graphify 步驟
• 使用 --no-viz 減少 CI 建置時間
• AMBIGUOUS 邊比例品質門檻已設定
• 圖譜產物已設定上傳/歸檔

安全性

• .graphifyignore 排除 *.key, *.pem, *.env 等敏感檔案
• graphify-out/ 存取權限已設定
• graph.json 被視為內部機密文件處理
• 定期審查 AMBIGUOUS 邊

團隊導入

• 團隊統一的 .graphifyignore 模板已建立
• Onboarding 文件包含 Graphify 使用說明
• Wiki 輸出已同步至內部知識庫
• 定期圖譜品質審查排程已建立

附錄 B：指令速查表

# === 基本操作 ===
/graphify .                                    # 分析當前目錄
/graphify ./src                                # 分析指定目錄
/graphify ./src --mode deep                    # 深度模式
/graphify ./src --update                       # 增量更新
/graphify ./src --cluster-only                 # 僅重新聚類
/graphify ./src --no-viz                       # 不產生 HTML
/graphify ./src --watch                        # 背景自動同步
/graphify ./src --dedup                        # 啟用實體去重
/graphify ./src --dedup-llm                    # LLM 輔助去重
/graphify ./src --backend ollama               # 指定 LLM 後端
/graphify ./src --backend azure                # Azure OpenAI（v0.8.32+）
/graphify ./src --directed                     # 有向圖模式
/graphify ./src --exclude "test*"              # 排除匹配模式
/graphify ./src --affected                     # 僅 git diff 影響的檔案
/graphify ./src --import-resolution            # 啟用匯入路徑解析
/graphify ./src --resolution 1.5               # 自訂 Leiden 解析度
/graphify ./src --exclude-hubs 95              # 排除 degree > 95% 的 hub
/graphify ./src --timing                       # 顯示每階段耗時（v0.9.0+）
/graphify ./src --max-concurrency 4            # LLM 並行數上限（v0.9.1+）
/graphify ./src --no-label                     # 跳過社群命名（v0.8.27+）
/graphify ./src --health-gate                  # 圖譜品質閘門（v0.8.44+）

# === 新增內容 ===
/graphify add <URL>                            # 擷取 URL 內容（含 YouTube 影片）
/graphify add <URL> --author "Name"            # 標記作者
/graphify add <URL> --contributor "Name"       # 標記貢獻者

# === 查詢 ===
/graphify query "問題"                         # BFS 查詢
/graphify query "問題" --dfs                   # DFS 路徑追蹤
/graphify query "問題" --budget 1500           # 限制 Token
/graphify path "NodeA" "NodeB"                 # 兩點路徑
/graphify explain "NodeName"                   # 解釋節點

# === 匯出 ===
/graphify ./src --obsidian                     # Obsidian Vault
/graphify ./src --wiki                         # Agent Wiki
/graphify ./src --callflow                     # Callflow HTML（Mermaid）
/graphify ./src --tree                         # D3 可折疊樹狀圖
/graphify ./src --svg                          # SVG
/graphify ./src --graphml                      # GraphML
/graphify ./src --neo4j                        # Cypher 語句
/graphify ./src --neo4j-push bolt://host:7687  # 推送 Neo4j
/graphify ./src --falkordb                     # FalkorDB（v0.8.39+）
/graphify ./src --mcp                          # MCP Server（stdio）

# === MCP Server ===
python -m graphify.serve graphify-out/graph.json                     # stdio
graphify-mcp graphify-out/graph.json                                 # console script（v0.8.36+）
python -m graphify.serve graph.json --transport http --port 8080     # HTTP transport（v0.8.34+）

# === 圖譜管理（v0.7+）===
graphify clone <repo-url>                      # Clone + 自動建圖
graphify merge-graphs <dir1> <dir2>            # 合併多專案圖譜
graphify extract                               # Headless CI 提取
graphify extract --mode deep                   # 深度 Headless 提取
graphify extract --timing                      # 顯示耗時（v0.9.0+）
graphify extract --cargo                       # Cargo workspace（v0.8.38+）
graphify extract --postgres "dsn"              # PostgreSQL Schema（v0.8.34+）
graphify extract --force                       # 完全重建（忽略所有快取）
graphify uninstall                             # 完整移除所有設定

# === 社群命名 / Work Memory（v0.8.27+）===
graphify label <path>                          # 獨立社群命名
graphify label --missing-only                  # 僅命名未命名社群（v0.8.50+）
graphify reflect                               # 聚合 Q&A → LESSONS.md（v0.8.47+）
graphify reflect --if-stale                    # 僅過期時重建
graphify save-result --outcome useful          # 標記結果（v0.8.47+）
graphify save-result --answer-file ans.md      # 多行答案（v0.9.2+）

# === PR Dashboard（v0.8.22+）===
graphify prs                                   # PR 影響分析
graphify prs --triage                          # AI triage 風險排序
graphify prs --conflicts                       # 語義衝突偵測
graphify prs --worktrees                       # 多 worktree PR 分析

# === 自訂 LLM Provider（v0.8.24+）===
graphify provider add <name>                   # 註冊自訂 Provider
graphify provider list                         # 列出所有 Provider
graphify provider show <name>                  # 檢視 Provider 設定
graphify provider remove <name>                # 移除 Provider

# === Git Hooks ===
graphify hook install                          # 安裝 hooks
graphify hook uninstall                        # 移除 hooks
graphify hook status                           # 檢查狀態

# === Always-On 平台安裝 ===
graphify claude install                        # Claude Code
graphify cursor install                        # Cursor
graphify gemini install                        # Gemini CLI
graphify copilot install                       # GitHub Copilot CLI
graphify vscode install                        # VS Code Copilot Chat
graphify codex install                         # Codex
graphify aider install                         # Aider
graphify opencode install                      # OpenCode
graphify claw install                          # OpenClaw
graphify droid install                         # Factory Droid
graphify trae install                          # Trae
graphify trae-cn install                       # Trae CN
graphify kimi install                          # Kimi Code
graphify kiro install                          # Kiro
graphify amp install                           # Amp
graphify devin install                         # Devin CLI
graphify antigravity install                   # Google Antigravity
graphify install --platform kilo               # Kilo Code（v0.8.27+）
graphify install --platform codebuddy          # CodeBuddy（v0.8.28+）
graphify install --platform agents             # 通用代理（v0.8.29+）
graphify install --project                     # 專案範圍安裝

# === CLI 直接查詢 ===
graphify query "問題"                          # 不需 AI 助手
graphify query "問題" --graph path/to/graph.json

附錄 C：版本歷程摘要

附錄 D：官方基準測試結果（Worked Examples）

Graphify 官方 Repository 的 worked/ 目錄提供可驗證的基準測試結果。每個測試案例包含原始輸入檔案與完整輸出（GRAPH_REPORT.md、graph.json），可自行運行驗證。

測試案例總覽

Token 節省效益分析

graph LR
    subgraph "Token 節省與語料規模的關係"
        A[6 檔案<br>~1x 節省<br>價值：結構清晰] --> B[4 檔案<br>5.4x 節省<br>價值：壓縮 + 結構]
        B --> C[52 檔案<br>71.5x 節省<br>價值：顯著壓縮]
        C --> D[100+ 檔案<br>預期 100x+<br>企業級效益]
    end

關鍵洞察：

• Token 節省與語料規模正相關：6 個檔案可直接放入 context window，圖譜價值在於結構化；52 檔案時壓縮效益達 71.5 倍
• 首次執行消耗 Token：語義提取階段需 LLM Token，這是一次性成本
• 後續查詢零成本：SHA256 快取確保相同檔案不重複提取，所有查詢從壓縮圖譜讀取
• 效益隨時間複利累積：團隊成員每次查詢都從圖譜獲益，而非每人各自閱讀原始檔案

📌 驗證方式：可 clone 官方 repo 後進入 worked/ 目錄，對照原始檔案與 GRAPH_REPORT.md 輸出，自行驗證數據準確性。

附錄 E：貢獻指南

專案資訊

新增語言擴充器（Extractor）

根據官方 ARCHITECTURE.md，新增語言支援的標準流程：

1. 新增提取函數：自 v0.8.27+ 提取器已模組化至 extractors/ 目錄。在 extractors/ 中建立 <lang>.py，實作 extract_<lang>(path: Path) -> dict，遵循既有模式
   • 使用 Tree-sitter 解析 → 走訪節點 → 收集 nodes 和 edges → call-graph 二次掃描
2. 註冊至 resolver-registry：在 extractors/__init__.py 中註冊副檔名與提取器的映射
3. 更新 detect.py：將副檔名加入 CODE_EXTENSIONS 和 _WATCHED_EXTENSIONS（watch.py）
4. 新增 Tree-sitter 依賴：在 pyproject.toml 中加入對應的 tree-sitter 語言套件
5. 撰寫測試：在 tests/fixtures/ 新增測試檔案，在 tests/test_languages.py 撰寫測試

測試規範

# 執行所有測試
pytest tests/ -q

# 測試特性
# - 每個模組一個測試檔案
# - 純單元測試：無網路呼叫、無檔案系統副作用（僅使用 tmp_path）
# - 目前共計 367+ 個測試案例

程式碼品質要點

📌 參與建議：提交 PR 前確認 pytest tests/ -q 全部通過。對於安全相關修改，請額外閱讀 SECURITY.md 了解威脅模型。

文件最後更新日期：2026-05-30
Graphify 版本：v0.8.26
專案 Repository：https://github.com/safishamsi/graphify
授權：MIT License
貢獻者：70+ 人（含 Claude AI）
GitHub Stars：57.1k+
加速器：Y Combinator S26（Penpax）