有 GitHub 仓库 push 权限并已认证 gh…

适用于查询或长期跟踪 GitHub 仓库浏览量、克隆量、来源和 Star 增长，并输出摘要或趋势图的场景。

适用场景

解决思路

1. 运行 gh auth status 检查认证状态，并确保 token 具备 repo scope 且对目标仓库有 push 权限；只读用户和 forker 无权访问 Traffic API，会返回 403。
2. 如需要生成 PNG 图表，可选安装 matplotlib：pip install matplotlib；未安装时改用 --ascii 输出文本图表。
3. 运行默认命令 python /path/to/skills/github-traffic/scripts/github_traffic.py <owner/repo>：通过 gh api 获取当前流量数据，保存快照到 ~/.github-traffic/，并显示 views、clones、referrers、popular pages 的格式化摘要。
4. 生成 PNG 趋势图：python .../github_traffic.py owner/repo --chart，默认包含最近 30 天。
5. 查看最近 7 天：python .../github_traffic.py owner/repo --chart --days 7。
6. 查看最近 90 天：python .../github_traffic.py owner/repo --chart --days 90，需要已累积历史。
7. 无需 matplotlib 时生成 ASCII 图表：python .../github_traffic.py owner/repo --ascii。
8. PNG 图表最多包含 3 个面板：Page Views（总浏览量和唯一访客，面积图）。
9. PNG 图表第 2 个面板：Git Clones（总克隆量和唯一克隆者，柱状图+折线图）。
10. PNG 图表第 3 个面板：Star Growth（Star 数随时间变化，折线图，仅在存在多个快照时显示）。
11. repo 位置参数必填，格式为 owner/name。
12. --chart 默认关闭，生成 PNG 趋势图。
13. --ascii 默认关闭，强制输出 ASCII 柱状图。
14. --days 默认 30，指定图表包含的天数。
15. --history-dir 默认 ~/.github-traffic/，指定历史数据存储目录。
16. --output 默认 <repo>_traffic.png，指定图表图片输出路径。
17. --snapshot 默认关闭，仅抓取并存储数据、不显示。
18. 快速摘要示例：python .../github_traffic.py zilliztech/memsearch。
19. 每周趋势图示例：python .../github_traffic.py zilliztech/memsearch --chart --days 7。
20. 每月趋势图并自定义输出路径示例：python .../github_traffic.py zilliztech/memsearch --chart --days 30 --output ./reports/traffic.png。
21. 仅存储快照供 cron 使用示例：python .../github_traffic.py zilliztech/memsearch --snapshot。
22. matplotlib 不可用时 ASCII 图表示例：python .../github_traffic.py zilliztech/memsearch --ascii --days 14。
23. GitHub Traffic API 只提供最近 14 天数据；要跟踪 30 天、90 天等更长周期，必须把每次抓取存入本地历史文件 ~/.github-traffic/<repo>_traffic.json。
24. 定期快照是建立历史的关键；推荐用 cron 或 CI 定时运行：0 9 * * * python /path/to/scripts/github_traffic.py owner/repo --snapshot。
25. 每次运行会把当前 14 天窗口合并进持久 JSON 文件 ~/.github-traffic/<owner>_<repo>_traffic.json。
26. 历史文件包含 daily views：date -> {views, unique}。
27. 历史文件包含 daily clones：date -> {clones, unique}。
28. 历史文件包含 star snapshots：date -> star count。
29. 历史文件包含 fetch metadata：timestamp、14-day totals、stars、forks。
30. 要生成有意义的 30/90 天图表，至少每 14 天运行一次脚本，每日运行最理想；超过 14 天的间隔会在图表中显示为缺失数据。
31. 权限规则：仓库 owner 和 admin 有完整访问权。
32. 权限规则：具有 write/maintain 角色的 collaborator 有完整访问权。
33. 权限规则：只读用户和 forker 无访问权，API 返回 403。
34. 如果遇到权限错误，检查 gh auth status 并确保 token 具有 repo scope。
35. 故障处理：遇到 Must have push access 错误，需要目标仓库的写权限，并检查 gh auth status。
36. 故障处理：图表只显示 14 天，是因为 GitHub 只提供 14 天窗口；定期运行 --snapshot 累积历史。
37. 故障处理：matplotlib not found，安装 pip install matplotlib，或使用 --ascii 输出文本图表。
38. 故障处理：某些日期没有数据，GitHub 可能不报告零流量日期，这些间隙是正常的。

适用边界 · 注意事项

• 没有目标仓库 push 写权限时不要使用，只读用户和 forker 会得到 403。
• 未安装并认证 gh CLI，或 token 没有 repo scope 时不要使用。
• 只依赖 GitHub 原生 14 天窗口却需要 30/90 天趋势、又不愿定期运行快照时不要使用，图表会缺失历史。