← 文件教學

版本演進摘要

CHANGELOG 1709 行的精簡導覽——只看里程碑，不逐字翻
來源：CHANGELOG.md（0.1.0 → 0.9.34）· 本站對齊 v8 @ 9f25a3a

發展節奏

Graphify 從 2026-04-03 的 0.1.0 到 2026-08-05 的 0.9.34，約四個月出了 100+ 個版本。早期每天多版，中期轉為穩定修 bug。這頁只挑「改變產品方向的里程碑」。

里程碑時間軸

  1. 0.1.0（2026-04-03）— 誕生最初版本就有完整骨架：13 語言 tree-sitter AST 抽取（Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP）、Leiden 社群偵測、SHA256 語意快取、MCP stdio server（query_graph/get_node/shortest_path/god_nodes）、記憶回饋迴路。
  2. 0.2.2（2026-04-06）— 開始整合開發工作流加入 graphify claude install（CLAUDE.md + PreToolUse hook）、git hook（post-commit/post-checkout）、benchmark 指令。
  3. 0.3.0（2026-04-06）— 多平台化支援 Codex、OpenCode、OpenClaw；install --platform 路由到各平台設定目錄；加 MIT license。也是這版把 extract.py 從 2527 行瘦身到 1588 行（用 LanguageConfig dataclass 取代 12 份複製貼上的語言抽取器）。
  4. 0.4.0（2026-04-10）— v4：影音時代支援影片/音訊語料（faster-whisper 本機轉錄）、YouTube/URL 下載（yt-dlp）、領域感知 Whisper prompt、transcripts 快取。
  5. 0.5.0（2026-04-24）— 跨 repo 與安全更新graphify clone、merge-graphs、shrink guard（不讓更小的圖覆蓋）、build_merge() 安全增量更新、deduplicate_by_label()。
  6. 0.6.0（2026-05-01）— SQL 時代SQL AST 抽取器（tables、views、FK、FROM/JOIN reads_from 邊），xlsx 結構抽取。
  7. 0.7.0（2026-05-03）— 多人開發支援git merge driver（graph.json 自動 union-merge，不再衝突）、Leiden seed=42 確定性分群、built_at_commit 嵌入、內容式 file hash（改名沿用快取）。
  8. 0.8.x（2026-05~06）— 品質與擴充FalkorDB export、ghost duplicate 自動合併、內建型別註解雜訊過濾、自訂 OpenAI/Anthropic 相容端點、PowerShell 模組、Swift import 修復、runbook 崩潰修復等。
  9. 0.9.0（2026-06-28）— Breaking：節點 ID 全面重造節點 ID 改含完整 repo-relative 路徑（docs_v1_api_readme vs docs_v2_api_readme），修掉「不同目錄同名檔被併成一個節點」的資料流失問題。既有圖下次 build/update 自動遷移。
  10. 0.9.x（2026-07~08）— 持續修復C# partial class、path 邊方向、hyperedge、incremental 跨檔呼叫保留等精密修復；目前最新 0.9.34（2026-08-05）。

主線趨勢

維度演進
語言支援13 種 → 36 種 tree-sitter 文法（含 SQL、Terraform、Pascal、DM…）+ Apex regex 抽取
輸入類型程式碼 → +文件/PDF → +影音/YouTube → +SQL/Office/Google Workspace
平台Claude Code → Codex/OpenCode/OpenClaw → 20+ 平台
團隊工作流個人工具 → merge driver、確定性分群、built_at_commit（多人協作）
工程品質extract.py 2500+ 行 → LanguageConfig 抽象；效能修復（遞迴→迭代、平行化）；ghost 合併
透明度信任標籤（EXTRACTED/INFERRED/AMBIGUOUS）始終如一，愈來愈嚴格

看完整記錄

這頁只是摘要。完整的 1709 行 CHANGELOG 在上游 repo 的 CHANGELOG.md——每個版本都有詳細的 issue 編號與 contributor 感謝。

教學角度：這份 CHANGELOG 是很好的「開源專案成長史」教材——看它怎麼從單一平台的個人工具，演進到多平台、多語料、多人協作的產品。特別值得注意 0.9.0 的 breaking change：節點 ID 是資料，改 ID 格式會影響所有下游（Neo4j、GraphML、MCP）。

教學解說

這份 CHANGELOG 摘要展示了「開源專案成長史」。從 0.1.0 到 0.9.34，約四個月出了 100+ 個版本。關鍵里程碑包括：0.3.0 的多平台化、0.4.0 的影音支援、0.6.0 的 SQL 抽取、0.9.0 的節點 ID 重造。

主線趨勢很清晰：語言支援從 13 種擴展到 36 種、輸入類型從程式碼擴展到影音/SQL/Office、平台從 Claude Code 擴展到 20+ 平台。這反映了「從個人工具到多平台產品」的演進路徑。

特別值得注意 0.9.0 的 breaking change：節點 ID 改含完整 repo-relative 路徑。這修掉了「不同目錄同名檔被併成一個節點」的資料流失問題，但也代表所有下游（Neo4j、GraphML、MCP）都需要適配。

Worked Example：追蹤一個功能的演進

  1. 選擇功能：選擇一個功能（例如 SQL 抽取），從 CHANGELOG 中找到它首次出現的版本（0.6.0）。
  2. 查看原始實作：在對應版本的 commit 中找到 extract.py 的 SQL 抽取器實作。
  3. 追蹤後續修復：在後續版本中找到 SQL 相關的 bug fix（例如 0.9.x 的精密修復）。
  4. 比較前後：比較 0.6.0 與最新版本的 SQL 抽取器差異。
關鍵觀察：每個版本都有詳細的 issue 編號與 contributor 感謝，這是開源專案透明度的體現。

常見錯誤與診斷

錯誤訊息原因解決方式
version mismatch使用了不同版本的 graphify執行 graphify --version 確認版本
breaking change: node ID format0.9.0 的節點 ID 重造執行 graphify extract --migrate 自動遷移
deprecated: old API使用了已廢棄的 API查看 CHANGELOG 找到替代 API

練習與驗收清單