# Top Github Users Ref

> gayanvoice/top-github-users 架構參考指南。當需要了解 GitHub 使用者排行榜的資料抓取管線、國家設定、排行計算邏輯、已知問題、或社群需求時使用。

- Skill: `recca0120/top-github-users-ref` (Agent Skill)
- Install (CLI): `npx skillmds@latest add recca0120/top-github-users-ref`
- Raw SKILL.md: https://api.skillmd.com/api/skills/recca0120/top-github-users-ref/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: recca0120 (https://skillmd.com/u/recca0120)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/recca0120/top-github-users-ref

---


# top-github-users 架構參考 + 社群回饋

## 資料抓取管線（從原始碼分析）

### 搜尋策略
- **GraphQL Search API**（非 REST）— 使用 `search(type: USER)` 查詢
- **所有 locations 合併成一個 query** — `location:Taiwan location:Taipei sort:followers-desc`
- **Cursor-based 分頁** — 用 `hasNextPage` + `endCursor` 遍歷所有結果，不限固定頁數
- **每頁 10 筆**（`first: 10`），透過 cursor 持續取得直到沒有下一頁

### 單次 GraphQL 取得所有欄位
一次查詢即取得：`login`、`avatarUrl`、`name`、`location`、`company`、`twitterUsername`、`followers.totalCount`、`contributionsCollection.contributionCalendar.totalContributions`、`contributionsCollection.restrictedContributionsCount`

**重點**：不需要逐人打 REST API 取 profile，效率遠高於 REST Search + 逐人 REST profile + 逐人 GraphQL contributions 的三步驟做法。

### Rate Limit 策略
- **隨機延遲 1-5 秒** — 每頁請求之間加入 `randomIntFromInterval(1000, 5000)` 延遲
- **錯誤重試** — 失敗時等待 60 秒，最多容許 4 次錯誤（`MAXIMUM_ERROR_ITERATIONS`）後停止
- **Checkpoint 機制** — 每次 cron 只處理一個國家（checkpoint），避免一次跑完所有國家撞 rate limit

### 資料保護
- **最低 750 筆保護** — 如果新抓的結果比快取少，且低於 750 筆，視為 API 錯誤，不覆蓋快取
- **快取機制** — 每個國家有獨立 cache 檔案，只在確認資料品質後才覆蓋

### 排序與排名
- 搜尋時依 `followers-desc` 排序
- 產出三種排名：Public Contributions、Total Contributions、Followers

## 與我們的差異比較

| 面向 | gayanvoice | CodeAtlas（目前） |
|------|-----------|------------------|
| 搜尋 API | GraphQL `search(type: USER)` | REST `search/users` |
| 每人 API calls | 1（GraphQL 包含全部欄位） | 3（REST search + REST profile + GraphQL contributions） |
| 分頁 | Cursor-based，無上限 | Page-based，上限 10 頁 × 100 = 1000 |
| Rate limit | 隨機延遲 1-5s + 錯誤等待 60s | Octokit throttle plugin |
| 處理單位 | 一次 cron 跑一個國家（checkpoint） | 一次 cron 跑所有國家（逐國 commit） |
| 快取保護 | 有（750 筆最低門檻） | 無 |

## 已知問題（從 Issues 學到的）

### Location 歧義問題（最嚴重）
- **Georgia（美國州）vs Georgia（國家）** — #291
- **Granada（西班牙城市）vs Granada（尼加拉瓜）** — #287
- **解決方案**：搜尋時加排除條件，如 `location:Georgia NOT location:"Georgia, US"` 或事後用 country code 過濾

### Emoji Flag Location — #279
- 有些使用者的 location 設為 flag emoji 如 🇹🇼
- **解決方案**：regex 偵測 flag emoji 並 mapping 到國家

### Contribution 計算不準 — #281 #295
- GraphQL `totalContributions` 和使用者看到的數字可能不同
- 原因：private repo contributions 計算差異
- **接受此限制**，清楚說明我們的計算方法

### Username 變更 — #123
- 使用者改名後舊資料不更新
- **解決方案**：每次 cron 重新抓取，不依賴快取的 username

### 使用者遺漏 — #222 #198
- 不理解為何沒被列入
- **解決方案**：建立 FAQ 頁面說明：需要設定 location、需要有足夠 followers/contributions

## 社群最想要的功能

1. **更頻繁更新**（weekly 以上）— 他們的 pipeline 壞了導致資料非常舊
2. **Profile info + top repos** — 目前只有 table，沒有個人資訊
3. **Star-based ranking** — 依總 star 數排名
4. **GitHub Pages 呈現** — 不只是 markdown 檔案
5. **容易新增國家/城市** — 目前需要 PR 改 config.json

## 我們的優勢

| 面向 | top-github-users | CodeAtlas |
|------|-------------------|---------|
| 呈現 | Markdown 表格 | GitHub Pages 網站 |
| 個人資料 | 無 | 語言、repos、bio、social |
| 搜尋/過濾 | 無 | 語言/城市/搜尋 |
| 更新頻率 | 壞了（~195 天一輪） | 每週 cron |
| 新增國家 | 需 PR 改 config.json | 加一個 JSON 檔 |
| Theme | 無 | Dark/Light toggle |
| 分享 | 有社群按鈕 | 有社群按鈕 + OG image |
| 3D | 無 | Globe 地球 |