SuperAPI AI 工具集

github-traffic

通用与其它

查看项目

更新于 10-16 07:22

技能介绍

用途:获取并分析 GitHub 仓库流量数据,包括页面浏览量、git 克隆量、引荐来源、热门页面和星标增长,可选生成 PNG 趋势图。

前提条件:已安装并认证 gh CLI;需要对目标仓库有推送(写入)权限,GitHub 流量 API 不支持只读访问;matplotlib 为可选项,用于生成 PNG 图表,缺失时回退为 ASCII 图表。

适用场景:用户询问仓库流量、页面浏览量、克隆数或访客来源;想查看按周、月、季度的流量趋势;想生成流量报告图表用于分享或文档;想定期快照流量数据以建立长期历史。

重要限制:GitHub 仅提供最近 14 天的流量数据。要跟踪更长周期(30 天、90 天等),脚本会将每次抓取存入本地历史文件(~/.github-traffic/<repo>_traffic.json),因此需要定期快照。建议设置 cron 或 CI 定时运行快照命令,如:0 9 * * * python /path/to/scripts/github_traffic.py owner/repo --snapshot。

默认工作流:运行 python /path/to/skills/github-traffic/scripts/github_traffic.py <owner/repo>,会通过 gh api 抓取当前流量、保存快照到 ~/.github-traffic/,并显示格式化摘要(浏览量、克隆量、引荐来源、热门页面)。

生成图表:使用 --chart 生成 PNG 趋势图(默认最近 30 天),可用 --days 7 指定 7 天、--days 90 指定 90 天(需已积累历史),或用 --ascii 生成无需 matplotlib 的 ASCII 图。PNG 图表最多含 3 个面板:页面浏览量(总量与独立访客,面积图)、Git 克隆量(总量与独立克隆者,柱状加折线图)、星标增长(随时间变化的星标数折线图,存在多个快照时显示)。

脚本选项:repo(位置参数,必填,owner/name 格式);--chart(默认关闭,生成 PNG 趋势图);--ascii(默认关闭,强制 ASCII 柱状图);--days(默认 30,图表包含天数);--history-dir(默认 ~/.github-traffic/,历史数据存储目录);--output(默认 <repo>_traffic.png,图表输出路径);--snapshot(默认关闭,仅抓取并存储数据,不显示)。

历史与长期跟踪:每次运行将当前 14 天窗口合并到 ~/.github-traffic/<owner>_<repo>_traffic.json 持久文件,包含每日浏览量、每日克隆量、星标快照及抓取元数据。要构建有意义的 30/90 天图表,至少每 14 天运行一次(每日最佳),间隔超过 14 天会在图表中显示为缺失数据。

权限:GitHub 流量 API 需要仓库推送权限。仓库所有者和管理员完全可用;具有 write/maintain 角色的协作者完全可用;只读用户和 fork 者无访问权限(API 返回 403)。如遇权限错误,检查 gh auth status 并确保 token 具有 repo scope。

故障排除:出现“Must have push access”错误说明需要写入权限,检查 gh auth status;图表仅显示 14 天是因为 GitHub 只提供 14 天窗口,需定期运行 --snapshot;未找到 matplotlib 可用 pip install matplotlib 安装,或使用 --ascii;某些日期无数据属正常,GitHub 可能不报告零流量日期。