Ganger

🚀 Ganger - GitHub Ranger

Ganger是一款受ranger啟發的基於終端的GitHub starred倉庫文件管理器。藉助類似Vim的快捷鍵和多面板界面，你可以輕鬆地對GitHub starred倉庫進行導航、組織和管理。

🚀 快速開始

認證

Ganger支持兩種認證方式：

1. OAuth設備流程（推薦）：

   ganger auth
   # 按照提示通過瀏覽器進行認證
   

2. 個人訪問令牌：

   export GITHUB_TOKEN=your_token_here
   ganger tui
   

MCP服務器

MCP服務器允許大語言模型（LLM）代理編排GitHub starred倉庫管理：

# 啟動MCP服務器
ganger mcp

# 服務器提供的工具如下：
# - list_starred_repos
# - create_virtual_folder
# - move_repo_to_folder
# - star_repository
# - get_repo_details

✨ 主要特性

• 雙界面：TUI（文本用戶界面）和MCP（模型上下文協議）服務器
• 米勒列視圖：三列的ranger風格視圖（文件夾 | 倉庫 | 預覽）
• 虛擬文件夾：使用基於標籤的虛擬文件夾來組織starred倉庫
• 自動分類：根據語言、主題和活躍度自動對倉庫進行分類
• Vim快捷鍵：支持hjkl導航、可視模式、剪切/複製/粘貼操作
• 智能緩存：使用SQLite緩存，支持離線瀏覽並減少API調用
• 雙重認證：支持OAuth設備流程或個人訪問令牌認證

📦 安裝指南

前提條件

• Python 3.10 或更高版本
• Poetry（用於依賴管理）
• GitHub賬戶

使用Poetry安裝

# 克隆倉庫
git clone https://github.com/synapticsage/ganger.git
cd ganger

# 安裝依賴
poetry install

# 激活虛擬環境
poetry shell

# 運行認證設置
ganger auth

# 啟動TUI
ganger tui

# 或者啟動MCP服務器
ganger mcp

📚 詳細文檔

配置

配置文件：~/.config/ganger/config.yaml

有關默認設置和可用選項，請參閱config/config.yaml。

項目狀態

階段1（進行中）：核心基礎

• [x] 項目結構和依賴
• [ ] 核心數據模型
• [ ] GitHub認證（OAuth + PAT）
• [ ] GitHub API客戶端（REST + GraphQL）
• [ ] SQLite緩存
• [ ] 支持自動分類的文件夾管理器
• [ ] MCP服務器
• [ ] 配置系統
• [ ] 單元測試

階段2（計劃中）：TUI界面 階段3（計劃中）：高級功能

架構

Ganger採用了清晰的服務層架構，TUI和MCP界面均可使用該架構：

ganger/
├── core/          # 業務邏輯（共享）
│   ├── models.py
│   ├── github_client.py
│   ├── cache.py
│   ├── auth.py
│   └── folder_manager.py
├── mcp/           # MCP服務器界面
│   ├── server.py
│   └── tools.py
└── tui/           # TUI界面（階段2）
    └── app.py

開發

運行測試

poetry run pytest

代碼質量

# 格式化代碼
poetry run black src/ tests/

# 代碼檢查
poetry run ruff check src/ tests/

# 類型檢查
poetry run mypy src/

📄 許可證

本項目採用MIT許可證。

致謝

• 靈感來源於 ranger 文件管理器
• 架構模式借鑑自 yanger
• 基於 Textual 和 MCP 構建