github-traffic

技能：GitHub Traffic

擷取並分析 GitHub 儲存庫流量資料 — 頁面瀏覽次數、Git 克隆次數、來源網站、熱門頁面以及星星成長趨勢。可選擇產生 PNG 格式的趨勢圖表。

前置需求：

• 必須安裝並驗證 gh CLI
• 需要目標儲存庫的推送（寫入）權限 — GitHub 的 Traffic API 不支援唯讀存取
• matplotlib 為選用（用於產生 PNG 圖表；若無則改以 ASCII 圖表替代）

---

使用時機

• 使用者詢問儲存庫流量、頁面瀏覽次數、克隆次數或訪客來源
• 使用者想查看流量隨時間的趨勢（每週、每月、每季）
• 使用者想產生流量報告圖表以便分享或放入文件
• 使用者想定期擷取流量快照以建立長期歷史記錄

---

重要：GitHub Traffic API 限制

GitHub 僅提供最近 14 天的流量資料。若要追蹤更長時間（30 天、90 天等）的趨勢，腳本會將每次擷取的資料儲存在本機歷史檔案中（~/.github-traffic/<repo>_traffic.json）。需要定期擷取快照才能累積歷史資料。

建議：設定 cron 工作或 CI 排程定期執行快照指令：

# 透過 cron 每日快照（無輸出，僅儲存資料）
0 9 * * * python /path/to/scripts/github_traffic.py owner/repo --snapshot

---

預設工作流程

python /path/to/skills/github-traffic/scripts/github_traffic.py <owner/repo>

此指令會：

1. 透過 gh api 擷取當前流量資料
2. 將快照儲存至 ~/.github-traffic/ 以利歷史追蹤
3. 顯示格式化摘要（瀏覽次數、克隆次數、來源網站、熱門頁面）

---

產生圖表

# 產生 PNG 趨勢圖表（預設最近 30 天）
python .../github_traffic.py owner/repo --chart

# 最近 7 天
python .../github_traffic.py owner/repo --chart --days 7

# 最近 90 天（需已累積歷史資料）
python .../github_traffic.py owner/repo --chart --days 90

# ASCII 圖表（不需 matplotlib）
python .../github_traffic.py owner/repo --ascii

PNG 圖表最多包含 3 個面板：

1. 頁面瀏覽次數 — 總瀏覽次數與不重複訪客（面積圖）
2. Git 克隆次數 — 總克隆次數與不重複克隆者（長條圖 + 折線圖）
3. 星星成長 — 星星數隨時間變化（折線圖，當有多個快照時顯示）

---

腳本選項

標記	預設值	說明
repo（位置參數）	必填	儲存庫，格式為 owner/name
--chart	關閉	產生 PNG 趨勢圖表
--ascii	關閉	強制輸出 ASCII 長條圖
--days	30	圖表涵蓋的天數
--history-dir	~/.github-traffic/	歷史資料儲存目錄
--output	<repo>_traffic.png	圖表圖片輸出路徑
--snapshot	關閉	僅擷取並儲存資料（不顯示）

---

範例

# 快速流量摘要
python .../github_traffic.py zilliztech/memsearch

# 每週趨勢圖表
python .../github_traffic.py zilliztech/memsearch --chart --days 7

# 每月趨勢圖表，自訂輸出路徑
python .../github_traffic.py zilliztech/memsearch --chart --days 30 --output ./reports/traffic.png

# 僅儲存快照（用於 cron 工作）
python .../github_traffic.py zilliztech/memsearch --snapshot

# 當 matplotlib 不可用時使用 ASCII 圖表
python .../github_traffic.py zilliztech/memsearch --ascii --days 14

---

歷史記錄與長期追蹤

每次執行會將當前 14 天視窗的資料合併至 ~/.github-traffic/<owner>_<repo>_traffic.json 的持久化 JSON 檔案中。該檔案包含：

• 每日瀏覽次數：日期 → {瀏覽次數, 不重複訪客}
• 每日克隆次數：日期 → {克隆次數, 不重複克隆者}
• 星星快照：日期 → 星星數
• 擷取中繼資料：時間戳記、14 天總計、星星數、分支數

若要建立有意義的 30/90 天圖表，請至少每 14 天執行一次腳本（每日執行為佳）。間隔超過 14 天會在圖表中顯示為缺失資料。

---

權限

GitHub Traffic API 需要儲存庫的推送權限。這表示：

• 儲存庫擁有者與管理員：完整存取
• 具有寫入/維護角色的協作者：完整存取
• 唯讀使用者與 fork 者：無法存取（API 回傳 403）

若遇到權限錯誤，請檢查 gh auth status 並確保您的 token 具有 repo 範圍。

---

疑難排解

問題	解決方案
「必須具有推送權限」錯誤	您需要對儲存庫有寫入權限。請檢查 gh auth status。
圖表僅顯示 14 天	GitHub 僅提供 14 天視窗。請定期執行 --snapshot 以累積歷史資料。
找不到 matplotlib	使用 pip install matplotlib 安裝。或使用 --ascii 以文字圖表替代。
某些日期沒有資料	GitHub 可能不會回報流量為零的日期。這些間隙是正常的。