GitHub Topics Trending

追踪 GitHub 话题下的热门项目，AI 智能分析，每日趋势报告邮件

目录

• 项目简介
• 功能特性
• 系统架构
• 快速开始
• 配置说明
• 使用方法
• GitHub Actions
• 数据模型
• 开发指南
• 常见问题

项目简介

GitHub Topics Trending 是一个自动化仓库趋势追踪系统。它每天通过 GitHub API 获取指定话题下的热门仓库，使用 Claude AI 对仓库进行智能分析和分类，计算星标变化趋势，并通过 Resend 发送专业的 HTML 邮件报告，同时生成 GitHub Pages 静态网站。

为什么需要这个项目？

1. 开发者视角 - 快速了解特定话题下的热门项目
2. 趋势洞察 - 捕捉新兴项目和工具的崛起
3. 智能总结 - AI 帮你理解每个项目解决什么问题
4. 自动化 - 无需手动查看网站，每天自动推送

功能特性

核心功能

邮件报告内容

GitHub Topics Daily - 2026-01-27
├── Top 20 经典榜单（含 AI 总结）
│   ├── 仓库名称（可点击跳转）、排名、星标数
│   ├── AI 一句话摘要
│   ├── 详细说明
│   └── 解决的问题标签
├── 星标增长 Top 5
├── 新晋项目
├── 活跃项目
└── 趋势统计

仓库分类

系统架构

┌─────────────────────────────────────────────────────────────────┐
│                     GitHub Topics Trending                      │
└─────────────────────────────────────────────────────────────────┘

  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
  │   GitHub     │      │   GitHub     │      │    Claude    │
  │   Actions    │ ──▶ │   Fetcher    │ ──▶ │  Summarizer │
  │  (Cron Daily)│      │  (API)       │      │     AI       │
  └──────────────┘      └──────┬───────┘      └──────┬───────┘
                               │                     │
                               ▼                     │
                        ┌──────────────┐              │
                        │   README     │              │
                        │  Fetcher     │              │
                        └──────┬───────┘              │
                               │                       │
                               └───────┬───────────────┘
                                       │
                                       ▼
                               ┌──────────────┐
                               │  Database    │
                               │  (SQLite)    │
                               └──────┬───────┘
                                      │
                                      ▼
                               ┌──────────────┐
                               │   Trend      │
                               │  Analyzer    │
                               └──────┬───────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
             ┌──────────────┐                   ┌──────────────┐
             │   Email      │                   │    Web       │
             │  Reporter    │                   │  Generator   │
             └──────┬───────┘                   └──────┬───────┘
                    │                                   │
                    ▼                                   ▼
             ┌──────────────┐                   ┌──────────────┐
             │   Resend     │                   │  GitHub      │
             │   Sender     │                   │   Pages      │
             └──────┬───────┘                   └──────────────┘
                    │
                    ▼
                   ──────► 您的邮箱

快速开始

环境要求

• Python 3.11+
• GitHub Personal Access Token
• Claude API Key（支持智谱代理）
• Resend API Key

安装

# 克隆仓库
git clone https://github.com/geekjourneyx/github-topics-trending.git
cd github-topics-trending

# 安装依赖
pip install -r requirements.txt

配置

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API Keys
nano .env

运行

# 设置环境变量
export GH_TOKEN="your_github_token"
export ZHIPU_API_KEY="your_api_key"
export RESEND_API_KEY="your_resend_key"
export EMAIL_TO="[email protected]"

# 运行（完整流程）
python -m src.main

# 仅获取数据，不发送邮件
python -m src.main --fetch-only

注意: 环境变量已配置为使用 GH_TOKEN 和 TOPIC，避免以 GITHUB_ 开头的 Secret 名称。

# 设置环境变量
export GH_TOKEN="your_github_token"
export TOPIC="claude-code"

---

## 配置说明

### 环境变量

| 变量 | 必需 | 说明 | 默认值 |
|-----|------|------|--------|
| `GH_TOKEN` | Yes | GitHub Personal Access Token | - |
| `TOPIC` | No | 要追踪的 GitHub Topic | `claude-code` |
| `ZHIPU_API_KEY` | Yes | Claude API Key（智谱代理） | - |
| `ANTHROPIC_BASE_URL` | No | Claude API 地址 | `https://open.bigmodel.cn/api/anthropic` |
| `RESEND_API_KEY` | Yes | Resend API Key | - |
| `EMAIL_TO` | Yes | 收件人邮箱 | - |
| `RESEND_FROM_EMAIL` | No | 发件人邮箱 | `[email protected]` |
| `DB_PATH` | No | 数据库路径 | `data/github-trending.db` |
| `DB_RETENTION_DAYS` | No | 数据保留天数 | `90` |
| `SURGE_THRESHOLD` | No | 暴涨阈值（比例） | `0.3` |

### GitHub Token 配置

#### 申请 Personal Access Token (PAT)

1. 登录 GitHub
2. 点击头像 → **Settings**
3. 左侧菜单最下方 → **Developer settings**
4. **Personal access tokens** → **Tokens (classic)**
5. **Generate new token** → **Generate new token (classic)**
6. 配置 Token：
   - **Note**: 输入 `GitHub Topics Bot`
   - **Expiration**: 选择有效期（建议 `90 days` 或 `No expiration`）
   - **勾选权限**:
     - ☑️ `public_repo` (访问公共仓库)
   - 点击 **Generate token**
7. 复制 token（只显示一次！请妥善保存）

#### 在 GitHub Actions 中配置

1. 进入 GitHub 仓库页面
2. **Settings** → **Secrets and variables** → **Actions**
3. **New repository secret**
4. 配置:
   - **Name**: `GITHUB_TOKEN`
   - **Value**: 粘贴你的 token
5. 点击 **Add secret**

### Resend 配置

1. 注册 [Resend](https://resend.com)
2. 创建 API Key
3. 配置发件人域名（或使用默认的 `[email protected]`）

---

## 使用方法

### 命令行运行

```bash
# 完整流程（获取数据 + AI 分析 + 发送邮件 + 生成网站）
python -m src.main

# 仅获取数据
python -m src.main --fetch-only

数据库查询

# 查看最新数据日期
sqlite3 data/github-trending.db "SELECT date FROM repos_daily ORDER BY date DESC LIMIT 1;"

# 查看今日排行榜 Top 10
sqlite3 data/github-trending.db "SELECT rank, repo_name, stars FROM repos_daily WHERE date = '2026-01-27' ORDER BY rank LIMIT 10;"

# 查看仓库详情
sqlite3 data/github-trending.db "SELECT repo_name, summary, category FROM repos_details WHERE repo_name = 'anthropics/claude-code';"

GitHub Pages 配置

启用 GitHub Pages

第一步：配置 Pages

1. 进入仓库 Settings → Pages

2. Build and deployment 配置：

   • Source: Deploy from a branch
   • Branch: gh-pages 分支
   • Folder: / (root)
   • 点击 Save

第二步：确保仓库为 Public

1. 仓库 Settings → General
2. 滚动到底部 Danger Zone
3. Change repository visibility → 选择 Public
4. 确认更改

第三步：访问网站

https://geekjourneyx.github.io/github-topics-trending/

⚠️ 注意：首次部署后需要等待 5-10 分钟才能访问。

GitHub Actions 配置

Secrets 配置

1. Settings → Secrets and variables → Actions → New repository secret

2. 添加以下 Secrets：

Actions 权限配置

1. Settings → Actions → General
2. Workflow permissions → 选择 Read and write permissions
3. 点击 Save

手动触发

1. 点击 Actions 标签
2. 选择 GitHub Topics Trending workflow
3. 点击 Run workflow → Run workflow

定时执行

默认每天 UTC 02:00（北京时间 10:00）自动运行。

故障排查

数据模型

repos_daily - 每日快照

repos_details - 仓库详情

repos_history - 历史趋势

开发指南

项目结构

github-topics-trending/
├── .github/workflows/
│   └── github-trending.yml     # GitHub Actions 配置
├── src/
│   ├── config.py               # 配置管理
│   ├── database.py             # SQLite 操作
│   ├── github_fetcher.py       # GitHub API 采集
│   ├── readme_fetcher.py       # README 获取
│   ├── claude_summarizer.py    # AI 分析
│   ├── trend_analyzer.py       # 趋势计算
│   ├── email_reporter.py       # 邮件生成
│   ├── web_generator.py        # 网站生成
│   ├── resend_sender.py        # 邮件发送
│   └── main.py                 # 主入口
├── plugins/
│   └── github-topics/          # Claude Code Skill
├── docs/                       # GitHub Pages 输出
├── data/
│   └── github-trending.db      # 数据库（运行时生成）
├── requirements.txt
├── .env.example
├── CHANGELOG.md
└── README.md

核心模块说明

扩展开发

新增话题

# 修改 .env 或环境变量
export GITHUB_TOPIC="python"

新增分析维度

# 修改 trend_analyzer.py
def calculate_trends(self, today_repos, date, ai_summary_map):
    # 添加新的分析逻辑
    pass

自定义邮件样式

# 修改 email_reporter.py
def _get_header(self, date: str) -> str:
    # 修改样式和布局
    pass

常见问题

邮件没有收到？

1. 检查 Resend API Key 是否正确
2. 确认收件人邮箱地址
3. 查看垃圾邮件箱
4. 检查 GitHub Actions 日志

GitHub API 速率限制？

• 认证用户：5000 requests/hour
• 未认证用户：60 requests/hour
• 使用 GITHUB_TOKEN 环境变量可提高限制

数据库文件在哪里？

默认位置：data/github-trending.db

如何查看历史数据？

sqlite3 data/github-trending.db
.tables
SELECT * FROM repos_daily ORDER BY date DESC LIMIT 10;

如何更改运行时间？

编辑 .github/workflows/github-trending.yml：

schedule:
  - cron: '0 2 * * *'  # UTC 时间，每天 02:00

如何更换追踪的话题？

修改环境变量 TOPIC：

export TOPIC="your-topic"

打赏 Buy Me A Coffee

如果该项目帮助了您，请作者喝杯咖啡吧

WeChat

作者

• 作者: geekjourneyx
• X (Twitter): https://x.com/seekjourney
• 公众号: 极客杰尼

关注公众号，获取更多 AI 编程、AI 工具与 AI 出海建站的实战分享：

License

MIT

致谢

• GitHub - 数据来源
• Anthropic - Claude AI
• Resend - 邮件服务