Understand-Anything — 深度教學

對應 gh-save metadata 報告：inbox/2026-05-28-github-Lum1104-Understand-Anything.md 對應 repo: https://github.com/Lum1104/Understand-Anything（v2.7.3, 42.3k stars, MIT）

1. 專案定位

一句話： 給 AI coding agent（Claude Code / Codex / Cursor / Copilot / Gemini CLI 等）用的 codebase 知識化 plugin — 把整個 repo 跑一次 multi-agent pipeline，輸出 .understand-anything/knowledge-graph.json，再透過 React + React Flow + ELK 自動 layout 的 dashboard 視覺化探索。

它解決的問題：

• 新人 onboarding 一個 200K LOC repo，不知道從哪個檔開始讀
• PM / 主管想了解 codebase 高層架構但不想 grep
• PR review 想看「這次改動會影響哪些下游」
• 把 Karpathy-pattern LLM wiki 變成可互動 knowledge graph（/understand-knowledge）

它不是什麼：

• 不是 LSP / IDE plugin — 它是 slash command driven
• 不是 vector DB — graph 是 JSON、可 commit 進 git，靠 tree-sitter 抽 deterministic 結構 + LLM 補語義
• 不是「跑一次永遠不變」— 內建 --auto-update post-commit hook，可 incremental

為什麼值得學：

1. v2.5.0 之後 dashboard 用 ELK + lazy container，處理 3000+ node 大型 graph 仍可互動 — 是 React Flow 大 graph 渲染的實戰案例
2. Tree-sitter + LLM 雙軌設計是 codebase 分析工具的近年共識，本專案實作完整
3. Multi-agent pipeline + intermediate file 架構（不把中介結果送回 LLM context）— pipeline 設計值得借鏡
4. v2.7.x 系列正在修「大型 repo token 燒爆」與「incremental 破口」— 對 production AI agent 系統的工程挑戰具參考價值

對 AI-Knowledge Template 的相關性：

• 與本專案 Layer 4 (graphify) / Layer 6 (gitnexus) 同為 codebase → 知識圖類工具，但走 LLM-heavy + 跨平台 plugin 路線，與 graphify (AST-heavy, 增量無 API cost) 形成互補。

2. 安裝指南

2.1 系統需求

• Node.js >= 22（developed on v24）
• pnpm >= 10（root package.json 已 pin packageManager）
• macOS / Linux / Windows 11（Windows 須注意 PowerShell 環境變數語法 — 見 §6 / §7 FAQ）

2.2 一鍵安裝（推薦）

1# Claude Code 內建 plugin marketplace
2/plugin marketplace add Lum1104/Understand-Anything
3/plugin install understand-anything

2.3 跨平台 CLI 安裝（curl pipe）

🟡 資安提醒： curl | bash 模式請先看 §6 風險評估再決定是否信任。

1# macOS / Linux
2curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash
3
4# 指定平台（例：codex）
5curl -fsSL .../install.sh | bash -s codex
6
7# Windows PowerShell
8iwr -useb https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.ps1 | iex

支援平台 id：claude / codex / cursor / copilot / gemini / opencode / vibe / trae。

2.4 開發者本地安裝（contributing）

1git clone https://github.com/Lum1104/Understand-Anything
2cd Understand-Anything
3pnpm install
4pnpm --filter @understand-anything/core build
5pnpm --filter @understand-anything/skill build
6pnpm test                                # 跑 root vitest.config.ts，含 tests/skill/
7pnpm dev:dashboard                       # 啟動 dashboard dev server

2.5 本地 plugin 覆寫測試

Claude Code 會把 marketplace plugin 快取到 ~/.claude/plugins/cache/understand-anything/understand-anything/<version>/，symlink 無效（Search/Glob 不跟隨）。改用 cp -R：

1ls ~/.claude/plugins/cache/understand-anything/understand-anything/   # 查 <VERSION>
2rm -rf ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>
3cp -R ./understand-anything-plugin ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>
4# 重啟 Claude Code session，跑 /understand --full 驗證

3. 核心架構解析

3.1 Monorepo 結構

 1Understand-Anything/
 2├── install.sh / install.ps1            # 跨平台安裝（8 個目標 IDE）
 3├── README.md / READMEs/<lang>          # 8 語言 README
 4├── scripts/generate-large-graph.mjs    # 3000-node 假 graph 性能測試用
 5└── understand-anything-plugin/          # ← 真正的 plugin 本體
 6    ├── .claude-plugin/plugin.json
 7    ├── packages/
 8    │   ├── core/         # 共享分析引擎（tree-sitter / search / schema / tours）
 9    │   └── dashboard/    # React + React Flow + Zustand + Tailwind v4
10    ├── src/              # /understand-chat /understand-diff /understand-explain /understand-onboard
11    ├── skills/           # /understand /understand-dashboard /understand-domain /understand-knowledge ...
12    ├── agents/           # 7 個專門 agent（見 §3.3）
13    └── hooks/            # auto-update post-commit hook

3.2 Mermaid 架構圖（主資料流）

flowchart TD
    subgraph User["User / AI Agent"]
        U1[/understand cmd/]
        U2[/understand-dashboard cmd/]
    end

    subgraph Pipeline["Multi-Agent Pipeline"]
        A1[project-scanner]
        A2[file-analyzer x N parallel]
        A3[architecture-analyzer]
        A4[tour-builder]
        A5[graph-reviewer]
    end

    subgraph Static["Static Analysis"]
        S1[web-tree-sitter WASM]
        S2[scan-project.mjs]
        S3[extract-import-map.mjs]
        S4[build-fingerprints.mjs]
        S5[compute-batches.mjs]
    end

    subgraph Storage[".understand-anything/"]
        D1[intermediate/]
        D2[knowledge-graph.json]
        D3[meta.json]
        D4[config.json]
    end

    subgraph UI["React Dashboard"]
        V1[React Flow + ELK layout]
        V2[Zustand store]
        V3[NodeInfo / FileExplorer / Tour]
    end

    U1 --> A1
    A1 --> S2
    S2 --> S3
    S3 --> S5
    A1 --> A2
    A2 --> S1
    A2 --> D1
    A3 --> D1
    A4 --> D1
    D1 --> A5
    A5 --> D2
    A5 --> D3

    U2 --> V1
    V1 --> D2
    V2 --> V3
    V1 --> V2

    H1[post-commit hook] --> S4
    S4 -->|structural delta?| A2
    S4 -->|no change| D3

3.3 7 個 Agent 的職責切分

關鍵設計：agent 中介結果寫到 .understand-anything/intermediate/，不丟回 Claude context — 避免 conversational LLM 的 context window 爆掉。

3.4 Tree-sitter + LLM 混合分工

• Tree-sitter（deterministic）：抽 imports / exports / function&class definitions / call sites / inheritance。Pre-resolve 成 importMap，傳給 file-analyzer，避免 LLM 重新從原始碼推 imports。
• LLM（semantic）：plain-English summaries、tags、architectural layer 判斷、business domain、tour 步驟、language concept callouts。

副產出：fingerprint（檔案結構 hash）— 之後 --auto-update 的 incremental 基礎。

3.5 Dashboard 設計重點（v2.5.0+）

• 75% graph + 360px 右側 sidebar（Info / Files tab）
• 暗色奢華主題（#0a0a0a + #d4a574 gold + DM Serif Display）
• 點檔案 node → prism-react-renderer code viewer 從下方滑出，展開可全螢幕
• Code 內容透過 dev server /file-content.json 取得，access token + graph-derived path allowlist 雙閘
• Schema validation 失敗會顯示 error banner（不靜默吃掉）

4. Helper Scripts 詳細用法

4.1 scripts/generate-large-graph.mjs（性能測試）

1node scripts/generate-large-graph.mjs              # 預設 3000 node
2node scripts/generate-large-graph.mjs 10000        # 自訂 node 數
3# 寫到 .understand-anything/knowledge-graph.json，給 dashboard 跑壓力測試用

不是 production pipeline 的一部分 — 純粹用來驗證 dashboard ELK + lazy container 在大型 graph 是否還可互動。

4.2 Plugin 內部 scripts（understand-anything-plugin/skills/understand/*.mjs）

設計觀察：merge 用 Python 而非 Node — 推測是因為 Python 處理大型 JSON merge 更直覺、且 plugin 在發布時可假設使用者有 python3（macOS / Linux default）。

4.3 Hook：hooks/hooks.json + hooks/auto-update-prompt.md

兩個 hook 觸發點：

1. PreToolUse on git：若 commit 偵測到、且 autoUpdate=true、且 knowledge-graph.json 存在，提示 Claude 讀 auto-update-prompt.md 並執行
2. SessionStart：若 meta.json 的 gitCommitHash ≠ 當前 HEAD，提示 graph 已 stale

auto-update 流程：先 build-fingerprints.mjs 跑 deterministic compare → 若無結構變動 → 只更新 meta.json（0 token）；若有 → 只重跑變動檔的 file-analyzer。

5. 應用場景

對 Apotek 的可能應用：

• 不過注意 §6 資安提醒 — 機密 / pre-IND 程式碼不要送進雲端 LLM，建議改用本專案 Layer 4 graphify（local AST-only 增量）。

6. 資安掃描報告

紅黃綠燈總評：🟡 中等風險（社群熱門 + active maintain，但跨平台 install 模式 + LLM 上傳整 codebase 屬中等風險）

🟢 低風險點

1. MIT 授權、open source、active maintain（過去 7 天有 daily commit）
2. 無硬編 secret / API key（grep 全 repo 未發現 hardcoded credentials）
3. Tree-sitter 用 WASM 版本（web-tree-sitter） — 避開 native binding 在 darwin/arm64 + Node 24 的編譯漏洞風險
4. Dashboard code viewer 雙閘：access token + graph-derived path allowlist — 不讓 dev server 變成任意檔案讀取後門
5. Schema validation 在 graph load 時主動驗證（見 #288 詳細 diagnose）— 不靜默吃錯誤 graph

🟡 中等風險點

1. curl ... | bash install 模式（install.sh L12-13）
   • 風險：MITM / 上游 repo 被 compromise → 直接 shell 注入
   • 緩解：建議改成「先 curl -o 下載 → 看完內容 → 再 bash install.sh」分兩步
2. /understand 會把整個 codebase 內容上傳到 LLM
   • 緩解：機密專案改用 local-only 工具（如本專案 Layer 4 graphify AST-only 模式）
3. Phase 7 cleanup 用 rm -rf（issue #301 已報）
   • 風險：在 hardened host（destructive-action policy 受限環境）會卡住
   • 緩解：等 v2.7.4+ 修補；或改成 rm -rf allowlist
4. Auto-update hook 包含「Do not ask the user for confirmation — just do it」字串（hooks.json）
   • 風險：每次 commit 都自動觸發 LLM agent，token cost 不透明
   • 緩解：config.json 設 autoUpdate=false 改成手動觸發
5. 8 個目標 IDE 的 install script 走相同 binary copy 邏輯 — 任一平台 plugin 被植入後門，其它平台一起受害

🔴 高風險點

無立即發現的 critical 漏洞。

建議

7. FAQ

Q1：為什麼 file-analyzer 結果不送回 Claude context？ A：避免 conversational 流程 context window 爆掉。中介結果寫 intermediate/，最後 graph-reviewer 統合 → 只送 final graph 給 user。

Q2：tree-sitter 為什麼用 WASM 不用 native？ A：native bindings 在 darwin/arm64 + Node 24 編譯失敗。WASM 版本（web-tree-sitter）跨平台、不需 native build chain。

Q3：incremental update 真的 0 token 嗎？ A：只在無結構變動時 0 token。build-fingerprints.mjs 跑 Node script 比對 hash → 若 fingerprint 不變 → 只更新 meta.json。任何 function / class / import 變動 → 觸發該檔的 file-analyzer（其它檔仍 skip）。

Q4：為什麼大型 java repo 跑不動？（issue #284 / #300） A：file-analyzer 並行 5、每 batch 20-30 檔 — 50K 檔 repo 仍會跑數百 batch、燒大量 token。目前社群建議 scope 到子模組：/understand src/feature-x。

Q5：Windows 跑 dashboard 抓不到 graph 怎麼辦？（issue #288） A：PowerShell 環境變數語法不同，必須：

1$env:GRAPH_DIR='C:\path\to\project'
2$env:UNDERSTAND_ACCESS_TOKEN='claudeteam-local'
3pnpm exec vite --host 127.0.0.1

不是 bash 風格的 GRAPH_DIR=... npx vite。

Q6：commit .understand-anything/ 進 git 安全嗎？ A：commit 內容只含 graph structure + summary，不含原始碼。但若 LLM 在 summary 寫出敏感邏輯 → 仍可能洩漏。建議 review 一遍再 commit，並把 intermediate/ 與 diff-overlay.json 加進 .gitignore。

Q7：能不能完全離線？ A：tree-sitter / static analysis 階段是離線的；LLM agent 階段必須能呼叫 LLM。若要完全離線，需把 agent 換成 self-hosted LLM endpoint（理論可行、官方未提供 config flag）。

Q8：與本專案 Layer 4 graphify 的差異？ A：

• graphify：local AST-only，增量無 API cost，給 codebase 架構探索用
• Understand-Anything：cloud LLM heavy，semantic 標記更豐富，跨平台 plugin
• 互補：graphify 適合 daily 增量、機密專案；Understand-Anything 適合一次性深度梳理 + 跨團隊分享。

8. 進階技巧

1. 大型 monorepo 拆 scope 跑：/understand src/frontend && /understand src/backend && /understand src/shared — 三個獨立 graph 比一次全跑省 token，又能 reload merge
2. commit graph 進 git + git-lfs：.understand-anything/*.json track lfs，10 MB+ graph 也能版控
3. post-commit auto-update：config.json 設 autoUpdate=true，每次 commit 自動 fingerprint 比對 → 結構不變 0 token
4. 客製 dashboard 主題：fork → 改 understand-anything-plugin/packages/dashboard/src/App.tsx 的色票常量
5. 整合 CI：在 CI runner 跑 /understand --full → 把 graph commit 到 docs branch → 同事永遠看到最新 graph
6. 與 graph-reviewer --review 配合：跑完 /understand 後 /understand --review 觸發 LLM full review，可抓出 cross-batch dangling edges（#303 類型問題）

9. 整合進其他工作流（AI-Knowledge Template 19 Layer）

10. 重點摘要 Checklist

• 是什麼：codebase → multi-agent pipeline → knowledge graph → React dashboard 的 Claude Code plugin
• 為什麼：新人 onboarding / PR review / 跨團隊分享，比 grep + LSP 高層、比 IDE 全圖更語意化
• 怎麼跑：/plugin marketplace add Lum1104/Understand-Anything → /understand → /understand-dashboard
• 架構亮點：tree-sitter WASM + LLM 雙軌 / 7 agent 中介寫檔不回 context / ELK lazy container 撐大 graph
• 資安等級：🟡 個人 / open source ok / 企業內部 / 機密研發 不建議直接用
• 典型痛點：大型 repo token 燒爆（#284, #300）/ incremental phase 7 cleanup bug（#293, #301）/ Windows PowerShell env var（#288）

11. 進一步閱讀

• 官方 repo：https://github.com/Lum1104/Understand-Anything
• Homepage + Live Demo：https://understand-anything.com
• Better Stack 社群 walkthrough（YouTube）：https://www.youtube.com/watch?v=VmIUXVlt7_I
• Karpathy LLM wiki 規範（/understand-knowledge 對應）：https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
• 範例：committed graph repo — https://github.com/Lum1104/microservices-demo
• 內部對應文件：本專案 inbox/2026-05-28-github-Lum1104-Understand-Anything.md（gh-save metadata）
• 互補工具：本專案 Layer 4 graphify（local AST-only）/ Layer 6 gitnexus（local 符號圖）