# GitHub架構透視器：讓隱藏的架構可視化
**作者**：Neo K.
**機構**：一言諾科技有限公司 (EveMissLab)
**日期**：2025年1月
------------------------------------------------------------------------
#### 引言：一個被忽視的事實
當我們打開GitHub瀏覽一個陌生的開源專案時，面對的往往是這樣的場景：
github.com/django/django
django/
├── django/
│ ├── contrib/
│ ├── core/
│ ├── db/
│ ├── forms/
│ ├── http/
│ ├── middleware/
│ ├── template/
│ ├── utils/
│ ├── views/
│ └── ... (共50+個資料夾)
├── tests/
├── docs/
└── README.md
即使Django是全球最流行的Python Web框架之一，即使它擁有詳盡的文檔，大多數開發者在第一次看到這個資料夾樹時仍然感到困惑：**這些資料夾之間是什麼關係？哪些是核心邏輯？我該從哪裡開始閱讀？**
這種困惑揭示了一個根本性的問題：**GitHub頁面展示的是原始的資料夾結構，而開發者需要的是架構理解**。資料夾是「語法」，架構是「語義」。GitHub只給了我們語法，卻讓我們自己去猜測語義。
更深刻的洞察是：**GitHub頁面實際上已經是一種「資料夾語言的介面」，只是它是未經詮釋的、盲目的**。每個開源專案的資料夾結構都在「說話」——告訴我們系統如何組織、模組如何劃分、依賴如何流動——但GitHub沒有提供「翻譯器」，讓這些資訊停留在隱性狀態。
本文提出**GitHub架構透視器**（GitHub Architecture Visualizer）的概念：一個能自動解析GitHub專案、生成互動式架構圖、提供層次化導航的工具。它不是替代GitHub，而是增強GitHub——讓已經存在於資料夾結構中的架構知識顯現出來。
------------------------------------------------------------------------
## 第一章：GitHub的「架構盲點」
### 1.1 資料夾結構≠架構理解
GitHub在展示專案方面做得很好：
- 清晰的資料夾樹
- 程式碼語法高亮
- Blame、History等版本追蹤功能
- README的渲染
但它有一個根本性的缺失：**缺乏架構層次的理解與呈現**。
讓我們看一個實際案例。當你打開Flask框架的倉庫：
github.com/pallets/flask
flask/
├── src/
│ └── flask/
│ ├── app.py
│ ├── blueprints.py
│ ├── cli.py
│ ├── config.py
│ ├── ctx.py
│ ├── helpers.py
│ ├── json/
│ ├── sessions.py
│ ├── templating.py
│ ├── testing.py
│ └── views.py
├── tests/
└── docs/
作為一個新接觸Flask的開發者，你看到這個列表會有以下疑問：
1. **職責疑問**：app.py和ctx.py有什麼區別？為什麼需要兩個？
2. **依賴疑問**：blueprints.py依賴哪些其他模組？
3. **重要性疑問**：哪些是核心檔案（不能刪除），哪些是可選功能？
4. **入口疑問**：如果我想理解Flask的請求處理流程，該從哪個檔案開始看？
5. **演化疑問**：這個結構是一開始就這樣，還是演化而來？背後的設計邏輯是什麼？
這些問題的答案都隱藏在程式碼與文檔中，但**沒有直接的視覺化呈現**。GitHub頁面給你一個平鋪的列表，你需要自己去建構系統的心智模型。
### 1.2 現有解決方案的不足
開發者社群已經意識到這個問題，並產生了一些應對策略：
#### 策略一：詳細的README
優秀的專案會在README中描述架構，如：
markdown
\## Architecture
Flask is organized into several core components:
\- \`app.py\`: The Flask application object
\- \`blueprints.py\`: Modular application components
\- \`ctx.py\`: Request and application contexts
...
\`\`\`
\*\*局限\*\*：這是靜態文字描述，無法互動探索。當專案有50個模組時，README要麼過於簡略（只提核心），要麼過於冗長（列出全部但無人讀完）。
\*\*策略二：docs/目錄的架構文檔\*\*
大型專案會建立獨立的架構文檔，如\`docs/architecture.md\`。
\*\*局限\*\*：文檔與程式碼分離，容易過時。當資料夾結構演化時，文檔往往滯後更新。
\*\*策略三：第三方架構圖\*\*
社群成員手動繪製架構圖並分享（如部落格文章、YouTube影片）。
\*\*局限\*\*：這些是「二手知識」，可能包含理解偏差，且無法保證時效性。
\*\*根本問題\*\*：現有方案都是「外部描述」（描述專案的架構），而非「內在顯現」（從專案本身提取架構）。
\### 1.3 認知科學的視角
為什麼資料夾列表不足以理解架構？認知科學提供了答案。
\*\*工作記憶的限制\*\*
當看到50個資料夾名稱時，大腦無法一次性處理全部資訊。George Miller的「7±2法則」指出，人類工作記憶容量約為5-9個資訊單元。超過這個容量，我們必須進行「分批處理」——先記住一部分，處理完後再記住下一部分，這導致理解的碎片化。
\*\*缺乏層次結構的視覺提示\*\*
資料夾列表是平鋪的（即使有縮排，仍是線性的）。但人類大腦更擅長處理\*\*空間化的層次結構\*\*——就像組織架構圖、地鐵路線圖、思維導圖那樣。當資訊被組織為「中心-外圍」、「上層-下層」的空間關係時，理解效率會提升60%以上（Tversky, 2011）。
\*\*缺乏語義標註\*\*
資料夾名稱\`contrib/\`告訴我們什麼？字面意思是「貢獻的」，但這是核心邏輯還是可選功能？是穩定的還是實驗性的？純粹的名稱無法傳達這些語義資訊。
\*\*缺乏關係呈現\*\*
資料夾列表無法顯示依賴關係。你不知道\`forms.py\`依賴\`validators.py\`，也不知道\`admin.py\`依賴整個\`auth\`子系統。這些關係只能通過閱讀import語句來推斷，但這需要逐一打開每個檔案——認知成本極高。
---
\## 第二章：GitHub架構透視器的設計理念
\### 2.1 核心概念：從「資料夾樹」到「架構圖」
GitHub架構透視器的核心任務是：\*\*將線性的資料夾列表轉換為結構化的架構視覺化\*\*。
轉換前（GitHub原生介面）：
\`\`\`
一個扁平的資料夾列表
├── folder_a/
├── folder_b/
├── folder_c/
├── ... (50個)
└── folder_z/
\`\`\`
轉換後（架構透視器）：
\`\`\`
一個分層的、帶語義標註的架構圖
┌─────────────┐
│ 專案全景 │
│ 架構模式：X │
└──────┬──────┘
│
┌──────────┼──────────┐
│ │ │
┌───▼──┐ ┌──▼──┐ ┌──▼──┐
│核心A │ │核心B │ │核心C │
│(紅色)│ │(紅色)│ │(紅色)│
└──────┘ └──────┘ └──────┘
│
┌───▼──────────────┐
│ 可選功能D、E、F │
│ (綠色) │
└──────────────────┘
\`\`\`
這不是簡單的「把資料夾畫成圖」，而是\*\*語義的提取與重組\*\*：
\- 識別哪些資料夾屬於「核心邏輯」（SMS），哪些是「可選功能」（TMS）
\- 提取資料夾之間的依賴關係
\- 標註穩定性（core/stable/evolving/experimental）
\- 提供職責描述（每個模組做什麼）
\### 2.2 設計原則
\*\*原則一：非侵入性\*\*
透視器是Chrome擴展或網頁服務，\*\*不需要專案方做任何改動\*\*。它直接分析GitHub上的公開資訊（資料夾結構、README、程式碼）。這確保了即使是10年前的舊專案，也能被分析。
\*\*原則二：互動式探索\*\*
不是靜態生成一張大圖，而是提供\*\*層次化的逐步展開\*\*：
\- 第一層：專案全景（5-10個主要模組）
\- 點擊模組 → 展開內部結構
\- 再點擊 → 深入到具體檔案
這符合人類的認知習慣：先理解整體，再深入細節。
\*\*原則三：雙向連結\*\*
架構圖中的每個節點都超連結到對應的GitHub資料夾。用戶可以：
\- 看圖理解架構
\- 點擊跳轉到程式碼
\- 無縫切換「架構視圖」與「程式碼視圖」
\*\*原則四：AI驅動的語義理解\*\*
不是簡單的「資料夾名稱映射」，而是用AI（Claude/GPT-4）真正理解：
\- 閱讀README與文檔
\- 分析程式碼的import關係
\- 推斷架構模式（Layered/Hexagonal/Microservices）
\- 提取設計意圖
\### 2.3 視覺化設計
\*\*顏色編碼\*\*
\- 🔴 紅色：核心模組（SMS），不可移除
\- 🟡 黃色：穩定模組，變更頻率低
\- 🟢 綠色：可選功能（TMS），可插拔
\- 🔵 藍色：實驗性功能，可能變動
\*\*節點大小\*\*
\- 依賴越廣泛（被引用次數越多），節點越大
\- 視覺上凸顯「關鍵節點」
\*\*箭頭樣式\*\*
\- 實線箭頭：強依賴（直接import）
\- 虛線箭頭：弱依賴（間接調用）
\- 箭頭粗細：依賴頻率
\*\*佈局演算法\*\*
\- 核心模組居中
\- 可選模組環繞在外圍
\- 依賴關係決定節點距離（依賴多的靠得近）
\### 2.4 互動功能
\*\*功能一：懶人式資料夾導航\*\*
\`\`\`
用戶看到架構圖中的「ORM」節點
↓
滑鼠懸停，顯示tooltip：
「負責資料庫抽象層，核心模組，穩定性：core」
↓
點擊節點，展開子圖：
顯示ORM內部的QueryBuilder、ConnectionManager等
↓
再點擊「QueryBuilder」，跳轉到GitHub該檔案
\`\`\`
\*\*功能二：依賴追蹤\*\*
\`\`\`
用戶點擊「顯示依賴」按鈕
↓
高亮顯示選中模組的：
\- 上游依賴（它依賴誰）— 藍色高亮
\- 下游依賴（誰依賴它）— 綠色高亮
↓
清晰看到模組在系統中的位置
\`\`\`
\*\*功能三：路徑查詢\*\*
\`\`\`
用戶輸入：「我想找表單驗證的程式碼」
↓
AI搜尋架構，高亮「Forms」模組
↓
顯示路徑：Forms → Validators → 具體檔案forms/validators.py
\`\`\`
\*\*功能四：架構對比\*\*
\`\`\`
用戶同時打開兩個專案：Flask vs Django
↓
並排顯示兩者的架構圖
↓
一眼看出設計差異：
\- Flask更輕量（核心模組少）
\- Django更全功能（內建Admin、Auth等）
\`\`\`
---
\## 第三章：技術實現路徑
\### 3.1 系統架構
\`\`\`
┌──────────────────────────────────────┐
│ 前端：Chrome擴展 / Web應用 │
│ - 注入GitHub頁面 │
│ - 渲染架構圖（Mermaid/D3.js） │
│ - 處理用戶互動 │
└─────────────┬────────────────────────┘
│ REST API
┌─────────────▼────────────────────────┐
│ 後端：分析引擎（Python FastAPI） │
│ - GitHub API整合 │
│ - AI語義分析（Claude API） │
│ - 快取與資料庫 │
└─────────────┬────────────────────────┘
│
┌─────────────▼────────────────────────┐
│ 資料層 │
│ - PostgreSQL（分析結果） │
│ - Redis（快取） │
└──────────────────────────────────────┘
### 3.2 核心演算法
#### 階段一：資料夾結構掃描
python
import requests
def fetch_repo_structure(repo_url):
"""使用GitHub API獲取完整資料夾樹"""
*\# GitHub API: GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1*
owner, repo = parse_repo_url(repo_url)
api_url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/main?recursive=1"
response = requests.get(api_url, headers={"Authorization": f"token {GITHUB_TOKEN}"})
tree = response.json()\['tree'\]
*\# 過濾出資料夾（type='tree'）*
folders = \[item for item in tree if item\['type'\] == 'tree'\]
*\# 構建層次結構*
folder_tree = build_hierarchy(folders)
return folder_tree
#### 階段二：關鍵文件讀取
python
def fetch_key_files(repo_url):
"""讀取README、setup.py等關鍵文件"""
key_files = {}
*\# README*
readme = fetch_file_content(repo_url, 'README.md')
key_files\['readme'\] = readme
*\# 配置文件（偵測語言）*
if file_exists(repo_url, 'setup.py'):
key_files\['setup'\] = fetch_file_content(repo_url, 'setup.py')
elif file_exists(repo_url, 'package.json'):
key_files\['package'\] = fetch_file_content(repo_url, 'package.json')
elif file_exists(repo_url, 'Cargo.toml'):
key_files\['cargo'\] = fetch_file_content(repo_url, 'Cargo.toml')
*\# 架構文檔（如果有）*
if file_exists(repo_url, 'docs/architecture.md'):
key_files\['arch_doc'\] = fetch_file_content(repo_url, 'docs/architecture.md')
return key_files
#### 階段三：AI語義分析
python
import anthropic
def analyze_architecture(folder_tree, key_files):
"""使用Claude分析架構"""
prompt = f"""
你是軟體架構分析專家。請分析以下GitHub專案：
\## 資料夾結構
{format_tree(folder_tree)}
\## README摘要
{key_files\['readme'\]\[:2000\]}
請以JSON格式回答：
{{
"name": "專案名稱",
"purpose": "專案目的（一句話）",
"pattern": "架構模式（layered/hexagonal/microservices/...）",
"core_modules": \[
{{
"path": "資料夾路徑",
"name": "模組名稱",
"description": "職責描述",
"stability": "core/stable/evolving/experimental"
}}
\],
"optional_modules": \[...\],
"dependencies": \[
{{"from": "module_a", "to": "module_b", "reason": "依賴原因"}}
\]
}}
分析原則：
1\. 核心模組（core）：移除後系統無法運行
2\. 穩定模組（stable）：介面穩定，變更頻率低
3\. 演化模組（evolving）：正在開發，可能調整
4\. 實驗模組（experimental）：試驗性功能
"""
client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)
message = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=4000,
messages=\[{"role": "user", "content": prompt}\]
)
result = json.loads(message.content\[0\].text)
return result
#### 階段四：依賴關係提取
python
def extract_dependencies(repo_url, folder_tree):
"""掃描import語句，構建依賴圖"""
dependencies = \[\]
for folder in folder_tree:
*\# 獲取該資料夾下的所有Python檔案*
py_files = get_python_files(repo_url, folder\['path'\])
for file in py_files:
content = fetch_file_content(repo_url, file)
imports = parse_imports(content) *\# 使用AST解析import*
for imp in imports:
*\# 判斷是否為專案內部import*
if is_internal_import(imp, folder_tree):
target_folder = resolve_import_path(imp, folder_tree)
dependencies.append({
'from': folder\['path'\],
'to': target_folder,
'file': file
})
return dependencies
#### 階段五：架構圖生成
python
def generate_mermaid_diagram(analysis):
"""生成Mermaid格式的架構圖"""
mermaid = "graph TD\n"
*\# 定義節點*
for module in analysis\['core_modules'\]:
node_id = sanitize_id(module\['name'\])
label = f"{module\['name'\]}\
\{module\['description'\]}\"
mermaid += f" {node_id}\[{label}\]\n"
*\# 根據穩定性設置顏色*
color = {
'core': '#FF6B6B',
'stable': '#FFD93D',
'evolving': '#6BCB77',
'experimental': '#4D96FF'
}\[module\['stability'\]\]
mermaid += f" style {node_id} fill:{color}\n"
for module in analysis\['optional_modules'\]:
node_id = sanitize_id(module\['name'\])
mermaid += f" {node_id}\[{module\['name'\]}\]\n"
mermaid += f" style {node_id} fill:#B8E6B8\n"
*\# 定義依賴關係*
for dep in analysis\['dependencies'\]:
from_id = sanitize_id(dep\['from'\])
to_id = sanitize_id(dep\['to'\])
reason = dep.get('reason', '')
mermaid += f" {from_id} --\>\|{reason}\| {to_id}\n"
return mermaid
### 3.3 前端實現（Chrome擴展）
javascript
*// content.js - 注入到GitHub頁面*
class ArchitectureVisualizerUI {
constructor() {
this.overlay = null;
this.analysis = null;
}
async init() {
*// 在GitHub頁面添加「顯示架構」按鈕*
const button = this.createButton();
document.querySelector('.repository-content').prepend(button);
button.addEventListener('click', () =\> this.show());
}
createButton() {
const btn = document.createElement('button');
btn.className = 'btn btn-sm';
btn.innerHTML = '🔍 顯示架構';
btn.style.cssText = 'position: fixed; top: 80px; right: 20px; z-index: 1000;';
return btn;
}
async show() {
if (this.overlay) {
this.overlay.style.display = 'block';
return;
}
*// 顯示載入動畫*
this.showLoading();
*// 呼叫後端API分析*
const repoUrl = this.getRepoUrl();
const response = await fetch(\`https://api.arch-visualizer.com/analyze?repo=\${repoUrl}\`);
this.analysis = await response.json();
*// 渲染架構圖*
this.renderOverlay();
}
renderOverlay() {
*// 創建側邊欄*
this.overlay = document.createElement('div');
this.overlay.className = 'arch-visualizer-overlay';
this.overlay.innerHTML = \`
\