github-traffic

技能：GitHub 流量

获取并分析 GitHub 仓库流量数据——页面浏览量、Git 克隆量、引荐来源、热门页面和星标增长。也可选择生成 PNG 趋势图表。

前置条件：

• 必须安装并完成身份验证的 gh CLI
• 必须对目标仓库拥有推送（写入）权限——GitHub 流量 API 不支持只读访问
• matplotlib 为可选项（用于生成 PNG 图表；不可用时会改用 ASCII 图表）

---

使用场景

• 用户询问仓库流量、页面浏览量、克隆量或访客来源
• 用户想查看一段时间内的流量趋势（每周、每月、每季度）
• 用户想生成流量报告图表，以便分享或用于文档
• 用户想定期保存流量数据快照，以建立长期历史记录

---

重要提示：GitHub 流量 API 的限制

GitHub 只提供最近 14 天的流量数据。要跟踪更长时间的趋势（30 天、90 天等），脚本会将每次获取的数据保存到本地历史文件（~/.github-traffic/<repo>_traffic.json）。必须定期保存快照，才能逐步积累历史数据。

建议：设置 cron 任务或 CI 定时任务，定期运行快照命令：

# Daily snapshot via cron (no output, just stores data)
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. 显示格式化的摘要（浏览量、克隆量、引荐来源、热门页面）

---

生成图表

# Generate PNG trend chart (last 30 days, default)
python .../github_traffic.py owner/repo --chart

# Last 7 days
python .../github_traffic.py owner/repo --chart --days 7

# Last 90 days (needs accumulated history)
python .../github_traffic.py owner/repo --chart --days 90

# ASCII chart (no matplotlib needed)
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	关闭	仅获取并保存数据（不显示）

---

示例

# Quick traffic summary
python .../github_traffic.py zilliztech/memsearch

# Weekly trend chart
python .../github_traffic.py zilliztech/memsearch --chart --days 7

# Monthly trend chart, custom output path
python .../github_traffic.py zilliztech/memsearch --chart --days 30 --output ./reports/traffic.png

# Just store a snapshot (for cron jobs)
python .../github_traffic.py zilliztech/memsearch --snapshot

# ASCII chart when matplotlib is not available
python .../github_traffic.py zilliztech/memsearch --ascii --days 14

---

历史记录与长期跟踪

每次运行都会将当前 14 天时间窗口的数据合并到 ~/.github-traffic/<owner>_<repo>_traffic.json 中的持久 JSON 文件。该文件包含：

• 每日浏览量：日期 → {浏览量，独立访客数}
• 每日克隆量：日期 → {克隆量，独立克隆者数量}
• 星标快照：日期 → 星标数量
• 获取元数据：时间戳、14 天总量、星标数、复刻数

若要生成有参考价值的 30/90 天图表，至少每 14 天运行一次脚本（理想情况下每天运行）。超过 14 天的数据间隔会在图表中显示为缺失数据。

---

权限

GitHub 流量 API 要求对仓库拥有推送权限。这意味着：

• 仓库所有者和管理员：拥有完整访问权限
• 拥有写入/维护角色的协作者：拥有完整访问权限
• 只读用户和复刻者：无访问权限（API 返回 403）

如果遇到权限错误，请检查 gh auth status，并确保令牌具有 repo 作用域。

---

故障排除

问题	解决方案
出现 “Must have push access” 错误	你需要对仓库拥有写入权限。请检查 gh auth status。
图表只显示 14 天	GitHub 只提供 14 天时间窗口的数据。请定期运行 --snapshot，以累积历史记录。
找不到 matplotlib	使用 pip install matplotlib 安装，或使用 --ascii 生成文本图表。
部分日期没有数据	GitHub 可能不会报告流量为零的日期。这些数据缺口属于正常情况。