From ca5baccd8de53ae293ff804d2c89a9fbd87b0421 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Apr 2026 02:44:34 +0000 Subject: [PATCH 1/2] Initial plan From 74b0a78321f5481e073d386c5ebd0ecd2e543237 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Apr 2026 03:05:18 +0000 Subject: [PATCH 2/2] Add Traditional Chinese README (README.zh-TW.md) and update language nav links Agent-Logs-Url: https://github.com/hondayaya123/graphify/sessions/eb7fd9e9-3028-41e9-8526-c831c7ed4d3f Co-authored-by: hondayaya123 <50391999+hondayaya123@users.noreply.github.com> --- README.ja-JP.md | 2 +- README.md | 2 +- README.zh-CN.md | 2 +- README.zh-TW.md | 254 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 257 insertions(+), 3 deletions(-) create mode 100644 README.zh-TW.md diff --git a/README.ja-JP.md b/README.ja-JP.md index 9924b4629..f598e9a22 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -1,6 +1,6 @@ # graphify -[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja-JP.md) +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja-JP.md) [![CI](https://github.com/safishamsi/graphify/actions/workflows/ci.yml/badge.svg?branch=v3)](https://github.com/safishamsi/graphify/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/graphifyy)](https://pypi.org/project/graphifyy/) diff --git a/README.md b/README.md index d9b624e3f..c771fea60 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # graphify -[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja-JP.md) +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja-JP.md) [![CI](https://github.com/safishamsi/graphify/actions/workflows/ci.yml/badge.svg?branch=v3)](https://github.com/safishamsi/graphify/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/graphifyy)](https://pypi.org/project/graphifyy/) diff --git a/README.zh-CN.md b/README.zh-CN.md index d2a07f371..dd17b3088 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,6 +1,6 @@ # graphify -[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja-JP.md) +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja-JP.md) [![CI](https://github.com/safishamsi/graphify/actions/workflows/ci.yml/badge.svg?branch=v3)](https://github.com/safishamsi/graphify/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/graphifyy)](https://pypi.org/project/graphifyy/) diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 000000000..c9fc2aef8 --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,254 @@ +# graphify + +[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja-JP.md) + +[![CI](https://github.com/safishamsi/graphify/actions/workflows/ci.yml/badge.svg?branch=v3)](https://github.com/safishamsi/graphify/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/pypi/v/graphifyy)](https://pypi.org/project/graphifyy/) +[![Sponsor](https://img.shields.io/badge/sponsor-safishamsi-ea4aaa?logo=github-sponsors)](https://github.com/sponsors/safishamsi) + +**一個面向 AI 編碼助手的技能。** 在 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中輸入 `/graphify`，它會讀取你的檔案、建立知識圖譜，並把原本不明顯的結構關係還給你。更快理解程式碼庫，找到架構決策背後的「為什麼」。 + +完全多模態。你可以直接丟進去程式碼、PDF、Markdown、截圖、流程圖、白板照片，甚至其他語言的圖片——graphify 會用 Claude vision 從這些內容中提取概念和關係，並把它們連接到同一張圖裡。透過 tree-sitter AST 支援 20 種語言（Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia）。 + +> Andrej Karpathy 會維護一個 `/raw` 資料夾，把論文、推文、截圖和筆記都丟進去。graphify 就是在解決這類問題——相比直接讀取原始檔案，每次查詢的 token 消耗可降低 **71.5 倍**，結果還能跨會話持久保存，並且會明確區分哪些內容是實際發現的，哪些只是合理推斷。 + +``` +/graphify . # 可用於任意目錄：程式碼庫、筆記、論文都可以 +``` + +``` +graphify-out/ +├── graph.html 可互動圖譜：可點節點、搜尋、按社群過濾 +├── GRAPH_REPORT.md God nodes、意外連接、建議提問 +├── graph.json 持久化圖譜：數週後仍可查詢，無需重新讀原始檔案 +└── cache/ SHA256 快取：重複執行時只處理變更過的檔案 +``` + +新增 `.graphifyignore` 檔案，以排除你不想納入圖譜的資料夾： + +``` +# .graphifyignore +vendor/ +node_modules/ +dist/ +*.generated.py +``` + +語法與 `.gitignore` 相同。樣式會比對相對於 graphify 執行目錄的檔案路徑。 + +## 運作原理 + +graphify 分兩輪執行。第一輪是確定性的 AST 提取，對程式碼檔案做結構分析（類別、函式、匯入、呼叫圖、docstring、解釋性注釋），這一輪不需要 LLM。第二輪會並行呼叫 Claude 子代理處理文件、論文和圖片，從中提取概念、關係和設計動機。最後把兩邊結果合併到一個 NetworkX 圖裡，用 Leiden 社群發現演算法做聚類，並匯出成可互動 HTML、可查詢 JSON，以及一份人類可讀的稽核報告。 + +**聚類是基於圖拓撲完成的，不依賴 embeddings。** Leiden 按邊密度發現社群。Claude 抽取出的語義相似邊（`semantically_similar_to`，標記為 `INFERRED`）本來就存在於圖中，所以會直接影響社群劃分。圖結構本身就是相似性訊號，不需要額外的 embedding 步驟，也不需要向量資料庫。 + +每條關係都會被標記為 `EXTRACTED`（直接在源材料中找到）、`INFERRED`（合理推斷，並附帶信心分數）或 `AMBIGUOUS`（有歧義，需要複核）。所以你始終知道哪些是實際發現的，哪些是模型猜出來的。 + +## 安裝 + +**需求：** Python 3.10+，並且使用以下平台之一：[Claude Code](https://claude.ai/code)、[Codex](https://openai.com/codex)、[OpenCode](https://opencode.ai)、[OpenClaw](https://openclaw.ai)、[Factory Droid](https://factory.ai) 或 [Trae](https://trae.com) + +```bash +pip install graphifyy && graphify install +``` + +> PyPI 套件當前暫時叫 `graphifyy`，因為 `graphify` 這個名字還在回收中。CLI 命令和 skill 命令仍然都是 `graphify`。 + +### 平台支援 + +| 平台 | 安裝命令 | +|------|----------| +| Claude Code (Linux/Mac) | `graphify install` | +| Claude Code (Windows) | `graphify install`（自動偵測）或 `graphify install --platform windows` | +| Codex | `graphify install --platform codex` | +| OpenCode | `graphify install --platform opencode` | +| OpenClaw | `graphify install --platform claw` | +| Factory Droid | `graphify install --platform droid` | +| Trae | `graphify install --platform trae` | +| Trae CN | `graphify install --platform trae-cn` | + +Codex 用戶還需要在 `~/.codex/config.toml` 的 `[features]` 下打開 `multi_agent = true`，這樣才能並行提取。Factory Droid 使用 `Task` 工具進行並行子代理調度。OpenClaw 目前的並行 agent 支援還比較早期，所以使用順序提取。Trae 使用 Agent 工具進行並行子代理調度，**不支援** PreToolUse hook，因此 AGENTS.md 是其常駐機制。 + +然後開啟你的 AI 編碼助手，輸入： + +``` +/graphify . +``` + +注意：Codex 使用 `$` 而非 `/` 來呼叫技能，所以請輸入 `$graphify .`。 + +### 讓助手始終優先使用圖譜（建議） + +圖建立完成後，在專案裡執行一次： + +| 平台 | 命令 | +|------|------| +| Claude Code | `graphify claude install` | +| Codex | `graphify codex install` | +| OpenCode | `graphify opencode install` | +| OpenClaw | `graphify claw install` | +| Factory Droid | `graphify droid install` | +| Trae | `graphify trae install` | +| Trae CN | `graphify trae-cn install` | + +**Claude Code** 會做兩件事： +1. 在 `CLAUDE.md` 中寫入一段規則，告訴 Claude 在回答架構問題前先讀 `graphify-out/GRAPH_REPORT.md` +2. 安裝一個 **PreToolUse hook**（寫入 `settings.json`），在每次 `Glob` 和 `Grep` 前觸發 + +如果知識圖譜存在，Claude 會先看到：_"graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes and community structure before searching raw files."_——這樣 Claude 會優先按圖譜導覽，而不是一上來就 grep 整個專案。 + +**Codex、OpenCode、OpenClaw、Factory Droid、Trae** 會把同樣的規則寫進專案根目錄的 `AGENTS.md`。這些平台沒有 PreToolUse hook，所以 `AGENTS.md` 是它們的常駐機制。 + +卸載時使用對應平台的 uninstall 命令即可（例如 `graphify claude uninstall`）。 + +**常駐模式和顯式觸發有什麼區別？** + +常駐 hook 會優先暴露 `GRAPH_REPORT.md`——這是一頁式總結，包含 god nodes、社群結構和意外連接。你的助手在搜尋檔案前會先讀它，因此會按結構導覽，而不是按關鍵字亂搜。這已經能涵蓋大部分日常問題。 + +`/graphify query`、`/graphify path` 和 `/graphify explain` 會更深入：它們會逐跳遍歷底層 `graph.json`，追蹤節點之間的精確路徑，並展示邊級別細節（關係類型、信心分數、源位置）。當你想從圖譜裡精確回答某個問題，而不僅僅是獲得整體感知時，就該用這些命令。 + +可以這樣理解：常駐 hook 是先給助手一張地圖，`/graphify` 這幾個命令則是讓它沿著地圖精確導覽。 + +
+手動安裝（curl） + +```bash +mkdir -p ~/.claude/skills/graphify +curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v3/graphify/skill.md \ + > ~/.claude/skills/graphify/SKILL.md +``` + +把下面內容加到 `~/.claude/CLAUDE.md`： + +``` +- **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify` +When the user types `/graphify`, invoke the Skill tool with `skill: "graphify"` before doing anything else. +``` + +
+ +## 用法 + +``` +/graphify # 對目前目錄執行 +/graphify ./raw # 對指定目錄執行 +/graphify ./raw --mode deep # 更積極地抽取 INFERRED 邊 +/graphify ./raw --update # 只重新提取變更檔案，並合併到已有圖譜 +/graphify ./raw --cluster-only # 只重新聚類已有圖譜，不重新提取 +/graphify ./raw --no-viz # 跳過 HTML，只產生 report + JSON +/graphify ./raw --obsidian # 額外產生 Obsidian vault（可選） +/graphify ./raw --obsidian --obsidian-dir ~/vaults/myproject # 將 vault 寫入指定目錄 + +/graphify add https://arxiv.org/abs/1706.03762 # 抓取論文、儲存並更新圖譜 +/graphify add https://x.com/karpathy/status/... # 抓取推文 +/graphify add https://... --author "Name" # 標記原作者 +/graphify add https://... --contributor "Name" # 標記是誰把它加入語料庫的 + +/graphify query "attention 和 optimizer 之間有什麼連接？" +/graphify query "attention 和 optimizer 之間有什麼連接？" --dfs # 追蹤一條具體路徑 +/graphify query "attention 和 optimizer 之間有什麼連接？" --budget 1500 # 把預算限制在 N tokens +/graphify path "DigestAuth" "Response" +/graphify explain "SwinTransformer" + +/graphify ./raw --watch # 檔案變更時自動同步圖譜（程式碼：立即更新；文件：提醒你） +/graphify ./raw --wiki # 建立可供 agent 抓取的 wiki（index.md + 每個 community 一篇文章） +/graphify ./raw --svg # 匯出 graph.svg +/graphify ./raw --graphml # 匯出 graph.graphml（Gephi、yEd） +/graphify ./raw --neo4j # 產生給 Neo4j 用的 cypher.txt +/graphify ./raw --neo4j-push bolt://localhost:7687 # 直接推送到執行中的 Neo4j +/graphify ./raw --mcp # 啟動 MCP stdio server + +# git hooks - 跨平台，在 commit 和切分支後重建圖譜 +graphify hook install +graphify hook uninstall +graphify hook status + +# 常駐助手規則 - 按平台區分 +graphify claude install # CLAUDE.md + PreToolUse hook（Claude Code） +graphify claude uninstall +graphify codex install # AGENTS.md（Codex） +graphify opencode install # AGENTS.md（OpenCode） +graphify claw install # AGENTS.md（OpenClaw） +graphify droid install # AGENTS.md（Factory Droid） +graphify trae install # AGENTS.md（Trae） +graphify trae uninstall +graphify trae-cn install # AGENTS.md（Trae CN） +graphify trae-cn uninstall + +# 直接從終端機查詢圖譜（不需要 AI 助手） +graphify query "attention 和 optimizer 之間有什麼連接？" +graphify query "顯示認證流程" --dfs +graphify query "CfgNode 是什麼？" --budget 500 +graphify query "..." --graph path/to/graph.json +``` + +支援混合檔案類型： + +| 類型 | 副檔名 | 提取方式 | +|------|--------|----------| +| 程式碼 | `.py .ts .js .jsx .tsx .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .exs .m .mm .jl` | tree-sitter AST + 呼叫圖 + docstring / 注釋中的 rationale | +| 文件 | `.md .txt .rst` | 透過 Claude 提取概念、關係和設計動機 | +| Office | `.docx .xlsx` | 轉換成 Markdown 後透過 Claude 提取（需要 `pip install graphifyy[office]`） | +| 論文 | `.pdf` | 引文挖掘 + 概念提取 | +| 圖片 | `.png .jpg .webp .gif` | Claude vision——截圖、圖表、任意語言都可以 | + +## 你會得到什麼 + +**God nodes**——度最高的概念節點（整個系統最容易匯聚到的地方） + +**意外連接**——按綜合得分排序。程式碼-論文之間的邊會比程式碼-程式碼邊權重更高。每條結果都會附帶一段人話解釋。 + +**建議提問**——圖譜特別擅長回答的 4 到 5 個問題。 + +**「為什麼」**——docstring、行內注釋（`# NOTE:`、`# IMPORTANT:`、`# HACK:`、`# WHY:`）以及文件裡的設計動機都會被抽取成 `rationale_for` 節點。不只是知道程式碼「做了什麼」，還能知道「為什麼要這麼寫」。 + +**信心分數**——每條 `INFERRED` 邊都有 `confidence_score`（0.0-1.0）。你不只知道哪些是猜出來的，還知道模型對這個猜測有多有把握。`EXTRACTED` 邊恒為 1.0。 + +**語義相似邊**——跨檔案的概念連接，即使結構上沒有直接依賴也能建立關聯。比如兩個函式做的是同一類問題但彼此沒有呼叫，或者某個程式碼類別和某篇論文裡的演算法概念本質相同。 + +**超邊（Hyperedges）**——用來表達 3 個以上節點的群組關係，這是普通兩兩邊表達不出來的。比如：一組類別共同實作一個協定、認證鏈路裡的一組函式、同一篇論文某一節裡的多個概念共同組成一個想法。 + +**Token 基準**——每次執行後都會自動印出。對混合語料（Karpathy 的儲存庫 + 論文 + 圖片），每次查詢的 token 消耗可以比直接讀原始檔案少 **71.5 倍**。第一次執行需要先提取並建圖，這一步會花 token；後續查詢直接讀取壓縮後的圖譜，節省會越來越明顯。SHA256 快取保證重複執行時只重新處理變更檔案。 + +**自動同步**（`--watch`）——在背景終端機裡跑著，程式碼庫一變化，圖譜就會跟著更新。程式碼檔案儲存會立刻觸發重建（只走 AST，不用 LLM）；文件/圖片變更則會提醒你跑 `--update` 進行 LLM 再提取。 + +**Git hooks**（`graphify hook install`）——安裝 `post-commit` 和 `post-checkout` hook。每次 commit 後、每次切分支後都會自動重建圖譜。如果重建失敗，hook 會以非零碼退出，讓 git 顯示錯誤而非靜默繼續。不需要額外開一個背景程序。 + +**Wiki**（`--wiki`）——為每個 community 和 god node 產生類似維基百科的 Markdown 文章，並提供 `index.md` 作為入口。任何 agent 只要讀 `index.md`，就能透過普通檔案導覽整個知識庫，而不必直接解析 JSON。 + +## 實作範例 + +| 語料 | 檔案數 | 壓縮比 | 輸出 | +|------|--------|--------|------| +| Karpathy 的儲存庫 + 5 篇論文 + 4 張圖片 | 52 | **71.5x** | [`worked/karpathy-repos/`](worked/karpathy-repos/) | +| graphify 原始碼 + Transformer 論文 | 4 | **5.4x** | [`worked/mixed-corpus/`](worked/mixed-corpus/) | +| httpx（合成 Python 函式庫） | 6 | ~1x | [`worked/httpx/`](worked/httpx/) | + +Token 壓縮效果會隨著語料規模增大而更明顯。6 個檔案本來就塞得進上下文視窗，所以 graphify 在這種場景裡的價值更多是結構清晰度，而不是 token 壓縮。到了 52 個檔案（程式碼 + 論文 + 圖片）這種規模，就能做到 71x+。每個 `worked/` 目錄裡都帶了原始輸入和真實輸出（`GRAPH_REPORT.md`、`graph.json`），你可以自己跑一遍核對數字。 + +## 隱私 + +graphify 會把文件、論文和圖片的內容發送給你所用 AI 編碼助手背後的模型 API 來做語義提取——可能是 Anthropic（Claude Code）、OpenAI（Codex），或者你當前平台使用的其他提供方。程式碼檔案則完全在本地透過 tree-sitter AST 處理，不會把程式碼內容發出去。專案本身沒有任何遙測、使用追蹤或分析。唯一的網路請求就是語義提取階段呼叫你平台自己的模型 API，使用的也是你自己的 API key。 + +## 技術堆疊 + +NetworkX + Leiden（graspologic）+ tree-sitter + vis.js。語義提取由 Claude（Claude Code）、GPT-4（Codex）或你當前平台所執行的模型完成。不需要 Neo4j，不需要 server，整體是純本地執行。 + +## 下一步計劃 + +graphify 是圖層。我們正在它之上建立 [Penpax](https://safishamsi.github.io/penpax.ai)——一個在裝置上的數位孿生，將你的會議、瀏覽器歷史、檔案、電子郵件和程式碼連接成一個持續更新的知識圖譜。不上雲端，不用你的資料訓練。[加入等候名單。](https://safishamsi.github.io/penpax.ai) + +## Star 歷史 + +[![Star History Chart](https://starchart.cc/safishamsi/graphify.svg)](https://starchart.cc/safishamsi/graphify) + +
+貢獻 + +**實作範例**是最能建立信任的貢獻方式。對一個真實語料跑 `/graphify`，把輸出儲存到 `worked/{slug}/`，再寫一份誠實的 `review.md`，評價圖譜哪些地方做得對、哪些地方做得不對，然後提交 PR。 + +**提取 bug**——提 issue 時請附上輸入檔案、對應的快取項目（`graphify-out/cache/`）以及它漏提取或瞎編了什麼。 + +模組職責和新增語言的方法見 [ARCHITECTURE.md](ARCHITECTURE.md)。 + +