GitHub AI Sentinel 🤖

自动监控 GitHub Trending，使用 LLM 智能推荐最新的 AI 项目，并通过邮件发送给你。

✨ 功能特性

• 🔍 自动爬取：每日爬取 GitHub Trending 中的 Python AI 相关项目
• 🧠 智能分析：使用私有化部署的 vLLM 对项目进行智能评分和总结
• 📧 邮件推送：自动发送精选的 Top-K 项目推荐到你的邮箱
• 🔄 去重机制：智能过滤已推荐过的项目，避免重复
• ⏰ 定时运行：支持每天定时自动执行（默认 8:00 AM）

🏗️ 架构

graph LR
    A[GitHub Trending] -->|爬取| B[Crawler]
    B --> C[History Manager]
    C -->|过滤新项目| D[Analyzer]
    D -->|vLLM 分析| E[Top-K Ranking]
    E --> F[Email Notifier]
    F -->|QQ Mail| G[用户邮箱]
    E -->|更新| C

Loading

📦 安装

前置要求

• Python 3.8+
• 私有化部署的 vLLM 服务
• QQ 邮箱（或其他 SMTP 邮箱）

安装依赖

pip install requests beautifulsoup4 openai schedule python-dotenv

⚙️ 配置

1. 复制环境变量模板

cp .env.example .env

2. 编辑 .env 文件

# GitHub Trending 配置（可选）
TRENDING_URL=https://github.com/trending/python?since=monthly

# vLLM 配置
VLLM_API_BASE=http://your-vllm-host:8000
VLLM_API_KEY=your-vllm-key
VLLM_MODEL_NAME=your-model-name

# 邮件配置
EMAIL_SENDER=[email protected]
EMAIL_PASSWORD=your-qq-app-password
EMAIL_RECEIVER=[email protected]

# SMTP 配置（可选，默认为 QQ 邮箱）
SMTP_SERVER=smtp.qq.com
SMTP_PORT=465

📝 配置说明

vLLM 配置

• VLLM_API_BASE: 你的 vLLM 服务地址（无需手动添加 /v1，程序会自动处理）
• VLLM_API_KEY: API 密钥，如果不需要认证可设为 EMPTY
• VLLM_MODEL_NAME: 使用的模型名称

QQ 邮箱配置

1. 登录 QQ 邮箱
2. 进入 设置 > 账户
3. 开启 SMTP 服务
4. 生成 授权码（用作 EMAIL_PASSWORD）

其他邮箱配置

如需使用其他邮箱服务，修改 SMTP 配置：

# Gmail
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587

# 163 邮箱
SMTP_SERVER=smtp.163.com
SMTP_PORT=25

🚀 使用方法

单次运行

手动执行一次分析：

cd /path/to/ottomator-agents
python -m github_ai_sentinel.main

定时运行

启动调度器，每天 8:00 AM 自动运行：

python -m github_ai_sentinel.scheduler_service

建议：使用系统级服务管理工具（如 systemd、supervisor 或 Windows 任务计划程序）来保持调度器持续运行。

📁 项目结构

github_ai_sentinel/
├── __init__.py              # 包初始化
├── config.py                # 配置管理
├── crawler.py               # GitHub 爬虫
├── history_manager.py       # 历史记录管理
├── analyzer.py              # LLM 分析器
├── notifier.py              # 邮件通知
├── main.py                  # 主逻辑
├── scheduler_service.py     # 定时调度器
├── .env.example             # 环境变量模板
├── .env                     # 环境变量配置（需自行创建）
├── history.json             # 历史记录（自动生成）
└── README.md                # 本文件

🔧 自定义

修改推荐数量

编辑 config.py：

TOP_K_RECOMMENDATIONS = 10  # 默认为 5

修改爬取周期

在 .env 中修改：

# 可选值: daily, weekly, monthly
TRENDING_URL=https://github.com/trending/python?since=daily

修改执行时间

编辑 scheduler_service.py：

schedule.every().day.at("06:00").do(job)  # 改为早上 6 点

🐛 常见问题

1. vLLM 404 错误

问题：日志显示 HTTP/1.1 404 Not Found

解决：

• 确认 VLLM_API_BASE 配置正确
• 程序会自动添加 /v1 后缀，无需手动添加

2. 邮件发送失败

问题：Failed to send email: Authentication failed

解决：

• 确认使用的是 QQ 邮箱的授权码，而非登录密码
• 检查 SMTP 服务器和端口配置

3. 历史记录不生效

问题：已推荐的项目重复出现

解决：

• 检查 history.json 文件是否在 github_ai_sentinel 目录下
• 确认文件权限允许读写

4. JSON 解析错误

问题：Could not parse JSON from LLM response

解决：

• 这是正常现象，部分 LLM 模型可能返回格式不规范
• 程序会跳过这些项目，继续处理其他项目
• 建议使用遵循指令能力较强的模型

📝 日志

程序运行时会生成 sentinel.log 文件，记录详细的执行信息。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

• GitHub Trending
• vLLM
• OpenAI Python SDK