指令用途
/graphify .（在 AI 助理中）或 graphify extract <root>（headless）是 graphify 的核心指令：掃描一個目錄，把程式碼、文件、PDF、圖片、video 全部解析進單一 JSON 知識圖譜 graphify-out/graph.json。
⚠️ 重要觀念：graphify 沒有
init這個指令。graphify init/graphify init --backend=neo4j都是上一版作者虛構，不要使用。直接跑/graphify .即可。
graphify 的解析分兩層：
- AST 層（本地、零 LLM、零 token） — 程式碼（36+ 種語言）用 tree-sitter 本地解析成
calls/imports/inherits/references/re_exports/contains六類邊。 - LLM 語意層（可選） — docs/PDF/圖片/video 才會呼叫 LLM（用 IDE session 的 model，或
--backend指定）。
基本用法
在 AI 助理中（最常見）
/graphify .等價於「在當前目錄建圖」。建完後助理會自動讀 GRAPH_REPORT.md 找線索。
Headless / CI
# 在終端機跑（不依賴 IDE）
graphify extract .
# 指定 corpus 目錄
graphify extract ./my-project
# 加入 docs/PDF 但跳過 HTML 視覺化
graphify extract . --no-viz純 AST 模式（不需 API key）
graphify extract . --code-only--code-only 只解析程式碼，完全跳過 docs / PDF / 圖片，所以不需要任何 LLM key。對 CI / 大型 monorepo 友善。
輸出
graphify 跑完會在 graphify-out/ 產出三個檔案：
| 檔案 | 用途 |
|---|---|
graph.json |
完整 JSON 圖譜，供 graphify query / path / explain 直接查詢 |
graph.html |
互動式 force-directed 視覺化（瀏覽器打開可點節點、過濾、搜尋） |
GRAPH_REPORT.md |
god nodes / surprising connections / 設計理由 / 建議問題 |
另可能有 manifest.json（增量同步用）、cache/（AST & 語意 cache）跟 cost.json（LLM 用量），這幾個通常應該被 .gitignore 排除。
常用選項
| 選項 | 用途 | 範例 |
|---|---|---|
--update |
只重抓有變動的檔案（增量重建） | graphify extract . --update |
--mode deep |
更豐富的 LLM 語意提取（消耗 token 更多） | graphify extract . --mode deep |
--code-only |
只 AST，跳過 docs/PDF/圖片 | graphify extract . --code-only |
--no-viz |
跳過 graph.html 生成（大圖譜友善） |
graphify extract . --no-viz |
--no-cluster |
跳過 Leiden 社群偵測（raw dump） | graphify extract . --no-cluster |
--force |
強制覆寫 graph.json（refactor 後清理幽靈節點） | graphify extract . --force |
--backend <provider> |
指定 LLM backend（gemini/claude/openai/kimi/ollama/bedrock/azure/claude-cli） | graphify extract . --backend ollama |
--token-budget N |
縮小語意 chunk（本地小模型友善） | graphify extract . --token-budget 4000 |
--no-gitignore |
把 .gitignore 排除的檔案也納入 |
graphify extract . --no-gitignore |
--out DIR |
把產出寫到自訂目錄 | graphify extract . --out ../shared-graph |
--cluster-only |
只重跑社群偵測，不重建 | graphify extract . --cluster-only |
自動重建：hook + watch
單次 build 之外，graphify 還提供兩種持續同步：
git hook 自動重建
graphify hook install會在 post-commit / post-checkout 自動 AST-only 重建（零 API 成本），並設定 graph.json 的 git merge driver，避免兩人同時 commit graphify-out/ 時留下 conflict marker。
Watch 模式
graphify watch ./src檔案一變動就觸發增量 AST 解析。適合開發中即時更新圖譜。
進階情境
加入 PDF / 圖片 / video / YouTube
# 把外部 PDF 抓進來並建圖
/graphify add https://arxiv.org/abs/1706.03762
# YouTube 影片 → Whisper 轉譯 → 加入圖譜
/graphify add https://youtu.be/xxxxxxxxadd 子指令負責從 URL 抓資源並加入 corpus，後續 /graphify . 會自動納入。
整合外部資料庫 schema
# 直接 introspect PostgreSQL schema
graphify extract --postgres "postgresql://user:pass@host/db"
# Cargo workspace 依賴
graphify extract . --cargo範例
純 AST 快速 scan（30 秒）
mkdir demo && cd demo
echo 'def f(): return g()' > a.py
echo 'def g(): return 1' > b.py
graphify extract . --code-only
ls graphify-out/
# => graph.html GRAPH_REPORT.md graph.json完整 docs + code build
# 設 LLM key
export ANTHROPIC_API_KEY=sk-ant-...
# 深度 build
graphify extract . --mode deep內部連結與外部參考
- 官方 README「Get started (30 seconds)」
- 官方 README「Common commands」
- 官方 README「Full command reference」
- 下一章：graphify query 指令詳解
下一步
- graphify query 指令詳解：自然語言問題 → 子圖
- graphify path-explain 指令詳解：節點關係探索
- graphify install 指令詳解：對 20+ AI 平台註冊