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 调度定期运行快照命令：

# 通过 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 天窗口的数据合并到持久化 JSON 文件 ~/.github-traffic/<owner>_<repo>_traffic.json 中。该文件包含：

• 每日浏览量：日期 → {views, unique}
• 每日克隆量：日期 → {clones, unique}
• 星标快照：日期 → 星标数
• 获取元数据：时间戳、14 天总计、星标数、复刻数

要构建有意义的 30/90 天图表，请至少每 14 天运行一次脚本（每天运行最理想）。超过 14 天的间隔会在图表中显示为缺失数据。

---

权限

GitHub 流量 API 需要仓库的推送权限。这意味着：

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

如果遇到权限错误，请检查 gh auth status 并确保你的令牌具有 repo 范围。

---

故障排除

问题	解决方案
“必须具有推送权限”错误	你需要仓库的写入权限。检查 gh auth status。
图表仅显示 14 天	GitHub 仅提供 14 天窗口。定期运行 --snapshot 以积累历史数据。
未找到 matplotlib	使用 pip install matplotlib 安装。或使用 --ascii 生成文本图表。
某些日期无数据	GitHub 可能不报告零流量的日期。这些缺失是正常的。