0.1.7

🔰 AI News Collector Library

一个用于收集AI相关新闻的Python库，支持多种搜索源和高级功能。

---

📊 支持的信息源（截止 v0.1.7）

AI News Collector 截止最新版本（v0.1.7），已支持从 15 个不同数据源 收集 AI 相关信息，覆盖 新闻资讯、学术论文、开源项目、AI 模型、视频内容、AI 搜索 等多种维度。

✅ 免费源（无需 API 密钥）

💰 付费源（需要 API 密钥）

注: MetaSota Search 通过 MCP 协议支持，需要特殊配置。

⏰ 所有搜索引擎的时间过滤参数 days_back 均以 UTC 时间为准，published 字段统一输出为 ISO8601（UTC 时区）。

---

🚀 最新更新 (v0.1.7 - Google 官方全新 google-genai SDK 迁移)

v0.1.7 版本更新 - 迁移 QueryEnhancer 至 Google 官方全新 google-genai SDK，消除废弃警告并增强容灾测试覆盖。

🔄 SDK 与依赖升级

• ✅ Google GenAI SDK 升级 - QueryEnhancer 迁移至 google-genai (from google import genai)，采用现代 Client 架构与 client.models.generate_content()
• ✅ 消除废弃警告 - 彻底消除旧版 google-generativeai 库的 FutureWarning
• ✅ 依赖与测试完善 - 核心依赖更新为 google-genai>=0.1.0，新增 Mock 生成、缓存与降级测试

📋 详见: 完整指南 | v0.1.7 发布总结

---

🚀 历史更新 (v0.1.3 - LLM 查询增强)

v0.1.3 版本更新 - 引入了 AI 驱动的查询增强功能。

🤖 LLM 查询增强（v0.1.3功能）

• ✅ AI 驱动查询优化 - 集成 Google Gemini LLM，智能优化用户查询
• ✅ 多引擎支持 - 为所有搜索引擎生成优化查询（单一 LLM 调用）
• ✅ 智能缓存 - 24 小时缓存，避免重复 LLM 调用
• ✅ 灵活配置 - 可选启用/禁用，支持自定义 LLM 提供商和模型
• ✅ 优雅降级 - LLM 调用失败时自动使用原始查询，确保服务可用性

📋 详见: 实现总结 | 完整指南

---

✨ 主要特性

核心功能

• 🔥 多源聚合 - 支持 15 个搜索源，覆盖新闻、论文、代码、模型、视频、AI 搜索
• 🤖 智能内容处理 - 自动提取文章内容和关键词
• 💾 智能缓存 - 避免重复搜索，提高效率
• ⏰ 定时任务 - 支持定时自动收集和报告生成
• 🔍 去重处理 - 基于相似度的智能去重
• 📊 数据分析 - 生成详细的收集结果报告
• 🤖 LLM 查询增强 - AI 驱动的查询优化，为不同引擎生成最优查询

测试与质量

• 🧪 离线测试 - 使用VCR cassettes实现完全离线的付费API测试
• 🔐 安全优先 - 所有测试数据中的凭证已清理
• 📈 覆盖率 - pytest-cov集成，详细的测试覆盖率报告
• 🤖 自动化 - GitHub Actions自动化测试和发布

---

📦 安装

从PyPI安装（推荐）

# 基础安装
pip install ai-news-collector-lib

# 安装开发/测试依赖
pip install ai-news-collector-lib[dev]

# 或从源代码安装
pip install -e .[dev]

系统要求

• Python 3.9+
• pip 或 conda

---

🔑 配置API密钥

创建 .env 文件并配置API密钥（可选，仅用于付费API）：

# v0.1.5+ 新增搜索引擎配置
YOUTUBE_API_KEY=your_youtube_key
GITHUB_TOKEN=your_github_token          # 可选 (提高速率限制)
HUGGINGFACE_API_KEY=your_hf_token       # 可选
PERPLEXITY_API_KEY=your_perplexity_key
BAIDU_SEARCH_API_KEY=your_baidu_key

# 现有搜索引擎配置
NEWS_API_KEY=your_newsapi_key
TAVILY_API_KEY=your_tavily_key
GOOGLE_SEARCH_API_KEY=your_google_key
GOOGLE_SEARCH_ENGINE_ID=your_engine_id
SERPER_API_KEY=your_serper_key
BRAVE_SEARCH_API_KEY=your_brave_key
METASOSEARCH_API_KEY=your_metasota_key

⚠️ 重要：请勿将 .env 文件提交到版本控制。参见 API密钥安全指南。

---

🎯 快速开始

基础使用（免费源）

import asyncio
from ai_news_collector_lib import AINewsCollector, SearchConfig

async def main():
    # 创建配置
    config = SearchConfig(
        enable_hackernews=True,
        enable_arxiv=True,
        enable_duckduckgo=True,
        enable_github_search=True,     # v0.1.5 新增，免费
        enable_huggingface=True,       # v0.1.5 新增，免费
        max_articles_per_source=10,
        days_back=7
    )
    
    # 创建收集器
    collector = AINewsCollector(config)
    
    # 收集新闻
    result = await collector.collect_news("machine learning")
    
    # 输出结果
    print(f"收集 {result.total_articles} 篇文章（去重后 {result.unique_articles} 篇）")
    for article in result.articles[:5]:
        print(f"- [{article.source}] {article.title}")
    
    return result

# 运行
asyncio.run(main())

🤖 LLM 查询增强

import asyncio
from ai_news_collector_lib import AdvancedAINewsCollector, AdvancedSearchConfig

async def main():
    # 创建带 LLM 查询增强的配置
    config = AdvancedSearchConfig(
        enable_hackernews=True,
        enable_arxiv=True,
        enable_tavily=True,
        enable_github_search=True,            # v0.1.5 新增
        enable_query_enhancement=True,        # ✨ 启用 LLM 查询增强
        llm_provider="google-gemini",
        llm_model="gemini-2.5-pro",
        llm_api_key="your-google-api-key",    # 从环境变量设置更安全
        query_enhancement_cache_ttl=86400,    # 24 小时缓存
        max_articles_per_source=10
    )
    
    # 创建收集器
    collector = AdvancedAINewsCollector(config)
    
    # LLM 会自动为各个搜索引擎优化查询
    result = await collector.collect_news_advanced("machine learning")
    
    # 查看增强后的查询
    if result.get('enhanced_queries'):
        for engine, query in result['enhanced_queries'].items():
            print(f"  - {engine}: {query}")
    
    return result

asyncio.run(main())

🔧 灵活配置（独立引擎参数）

import asyncio
from ai_news_collector_lib import FlexibleAINewsCollector, FlexibleSearchConfig, TimeRange

async def main():
    # 灵活配置 - 为每个搜索引擎独立设置参数
    config = FlexibleSearchConfig()
    
    # 为 HackerNews 设置独立的时间范围和文章数
    config.set_engine_config("hackernews", enabled=True, max_articles=20, time_range=TimeRange.ONE_DAY)
    
    # 为 GitHub 设置较长的时间范围
    config.set_engine_config("github_search", enabled=True, max_articles=15, time_range=TimeRange.ONE_MONTH)
    
    # 为 YouTube 设置 API 密钥和参数
    config.set_engine_config("youtube", enabled=True, max_articles=10, api_key="your-key")
    
    # 创建灵活收集器
    collector = FlexibleAINewsCollector(config)
    result = await collector.collect_news("artificial intelligence")
    
    print(f"收集 {result.total_articles} 篇文章")
    return result

asyncio.run(main())

高级使用（包含内容提取和关键词提取）

import asyncio
from ai_news_collector_lib import AdvancedAINewsCollector, AdvancedSearchConfig

async def main():
    # 创建高级配置
    config = AdvancedSearchConfig(
        enable_hackernews=True,
        enable_arxiv=True,
        enable_duckduckgo=True,
        enable_github_search=True,
        enable_content_extraction=True,      # 自动提取内容
        enable_keyword_extraction=True,      # 自动提取关键词
        cache_results=True,                  # 启用缓存
        max_articles_per_source=10
    )
    
    # 创建高级收集器
    collector = AdvancedAINewsCollector(config)
    
    # 收集增强新闻
    result = await collector.collect_news_advanced("artificial intelligence")
    
    # 分析结果
    total_words = sum(article.get('word_count', 0) for article in result['articles'])
    print(f"总字数: {total_words}")
    
    return result

# 运行
asyncio.run(main())

付费API使用（带缓存）

import asyncio
from ai_news_collector_lib import AdvancedAINewsCollector, AdvancedSearchConfig

async def main():
    # 创建配置 - 混合使用免费和付费源
    config = AdvancedSearchConfig(
        enable_hackernews=True,
        enable_arxiv=True,
        enable_tavily=True,              # 付费搜索API
        enable_google_search=True,       # 谷歌自定义搜索
        enable_serper=True,              # Serper搜索API
        enable_youtube=True,             # YouTube 视频搜索
        enable_perplexity=True,          # Perplexity AI 搜索
        enable_baidu_search=True,        # Baidu Search（百度千帆）
        cache_results=True,              # 启用缓存减少API调用
        max_articles_per_source=15,
        similarity_threshold=0.85
    )
    
    collector = AdvancedAINewsCollector(config)
    result = await collector.collect_news_advanced("deep learning")
    
    return result

asyncio.run(main())

---

⚙️ 详细配置

搜索配置选项

from ai_news_collector_lib import AdvancedSearchConfig

config = AdvancedSearchConfig(
    # 传统源
    enable_hackernews=True,
    enable_arxiv=True,
    enable_rss_feeds=False,
    
    # 付费搜索源
    enable_tavily=False,
    enable_google_search=False,
    enable_serper=False,
    enable_brave_search=False,
    enable_metasota_search=False,
    enable_baidu_search=False,
    enable_newsapi=False,
    
    # v0.1.5+ 新增搜索源
    enable_youtube=False,           # YouTube 视频搜索（需要 API 密钥）
    enable_github_search=False,     # GitHub 项目搜索（可选 API 密钥）
    enable_huggingface=False,       # HuggingFace 模型搜索（可选 API 密钥）
    enable_perplexity=False,        # Perplexity AI 搜索（需要 API 密钥）
    enable_baidu_search=False,      # Baidu Search（需要 API 密钥）
    
    # 网页搜索
    enable_duckduckgo=True,
    
    # 高级功能
    enable_content_extraction=False,     # 自动提取文章内容
    enable_keyword_extraction=False,     # 自动提取关键词
    cache_results=False,                 # 缓存结果
    
    # 搜索参数
    max_articles_per_source=10,
    days_back=7,
    # ⏰ 本参数对所有引擎有效；内部时间过滤使用 UTC；所有 published 输出均为 ISO8601(UTC)
    similarity_threshold=0.85,
)

---

🛠️ 高级功能

定时收集

from ai_news_collector_lib import DailyScheduler, AdvancedAINewsCollector, AdvancedSearchConfig

async def collect_news():
    config = AdvancedSearchConfig(
        enable_hackernews=True,
        enable_arxiv=True,
        cache_results=True
    )
    collector = AdvancedAINewsCollector(config)
    return await collector.collect_news_advanced("AI")

# 创建定时任务 - 每天上午9点
scheduler = DailyScheduler(
    collector_func=collect_news,
    schedule_time="09:00",
    timezone="Asia/Shanghai"
)

# 启动调度器
scheduler.start()

缓存管理

from ai_news_collector_lib import CacheManager

# 创建缓存管理器
cache = CacheManager(cache_dir="./cache", default_ttl_hours=24)

# 获取缓存
cache_key = cache.get_cache_key("AI news", ["hackernews", "arxiv"])
cached_result = cache.get_cached_result(cache_key)

if cached_result:
    print("使用缓存结果")
    result = cached_result
else:
    # 执行搜索
    result = await collector.collect_news("AI news")
    # 缓存结果
    cache.cache_result(cache_key, result)

报告生成

from ai_news_collector_lib import ReportGenerator

# 创建报告生成器
reporter = ReportGenerator(output_dir="./reports")

# 生成Markdown报告
report = reporter.generate_daily_report(result, format="markdown")
reporter.save_report(result, filename="daily_report.md")

# 生成CSV报告
reporter.generate_daily_report(result, format="csv")

---

🧪 测试

运行所有测试

# 运行基础测试
pytest

# 运行所有测试（包括付费API测试）
pytest -v

# 生成覆盖率报告
pytest --cov=ai_news_collector_lib --cov-report=html

离线付费API测试（使用VCR Cassettes）

项目包含预录制的VCR cassettes，允许在完全离线状态下测试所有付费API集成 - 无需真实API密钥。

# 运行付费API测试（使用cassettes，完全离线）
pytest tests/test_integration_advanced.py -v

# 查看cassette记录详情
cat tests/cassettes/advanced_ml_hn_ddg.yaml

VCR Cassette原理

VCR库记录真实的HTTP请求/响应，然后在测试中重放（无需真实API调用）：

import pytest
from vcr import VCR

# 使用cassette进行测试
@pytest.mark.vcr
def test_with_cassette(vcr):
    # 首次运行记录HTTP交互，后续测试直接重放
    result = collector.search(query="AI")
    assert len(result) > 0

详见: VCR Cassette详解 | 测试指南 | FAQ

---

🔄 CI/CD 与自动化

GitHub Actions 工作流

项目使用GitHub Actions实现完整的自动化测试和发布：

发布新版本

# 1. 确保所有测试通过
pytest

# 2. 创建版本标签
git tag -a v0.1.6 -m "Release v0.1.6"

# 3. 推送标签（自动触发发布工作流）
git push origin v0.1.6

详见: 发布指南 | 快速发布

---

📚 文档

核心文档

• 架构设计 - 项目结构和设计理念
• 使用指南 - 详细使用文档
• 实现总结 - v0.1.3 LLM 查询增强实现详情
• VCR说明 - 离线测试机制解析
• 测试指南 - 完整测试说明

快速参考

• 发布指南 - 版本发布流程
• 快速发布 - 快速发布清单
• PyPI指南 - PyPI发布说明
• FAQ - 常见问题解答

API参考

• 搜索配置 - 配置选项说明
• 模型对象 - 数据模型定义
• 搜索工具 - 各源工具实现

---

🗓️ ArXiv 日期处理

ArXiv日期解析包含完整的回退机制：

• 默认使用BeautifulSoup的XML解析获取published字段
• 若解析异常则回退到feedparser
• 在feedparser中支持published_parsed和updated_parsed字段
• 回退顺序: published_parsed → updated_parsed → datetime.now()
• 时区处理: Atom格式中Z表示UTC，使用datetime.fromisoformat解析

最小验证脚本：

python scripts/min_check_feedparser_fallback.py

该脚本验证RSS和Atom格式在缺少日期字段时的回退逻辑。

---

🤝 贡献

欢迎贡献代码和改进建议！

贡献流程

1. Fork本项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启Pull Request

开发指南

• 遵循PEP 8代码风格
• 添加测试用例
• 更新相关文档

详见: 完整贡献指南

---

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

---

🆘 支持

获取帮助

• 📖 完整文档
• 🐛 提交Issue
• 💬 讨论区
• 📧 邮件支持

常见问题

Q: 部分旧文章会拖低时间过滤准确率吗？ A: 不会。所有时间过滤严格按 UTC 执行，并跳过无法识别的发布时间，准确率不会被历史无效数据影响。

Q: GitHub 和 HuggingFace 需要 API 密钥吗？ A: 不需要。两者都可以在无密钥的情况下使用。设置 GITHUB_TOKEN 可以将速率限制从 60 次/小时提升到 5000 次/小时；设置 HUGGINGFACE_API_KEY 可以提高速率限制。

Q: 如何不使用API密钥运行测试？ A: 使用VCR cassettes！测试会自动使用预录制的HTTP响应。详见VCR说明。

Q: 是否可以在生产环境中使用此库？ A: 可以，但请确保：

• 安全地管理API密钥（使用.env文件）
• 合理设置缓存TTL避免过时数据
• 监控API调用限制

Q: 如何贡献新的搜索源？ A: 详见架构设计中的"添加新搜索源"部分。

详见: 完整FAQ

---

📈 更新日志

v0.1.7 (2026-08-22) - 🔄 Google 官方全新 google-genai SDK 迁移

• 🔄 迁移至 google-genai SDK - QueryEnhancer 全面迁移至 Google 官方全新 SDK（from google import genai），采用现代 Client 架构
• 🛡️ 彻底消除废弃警告 - 消除旧版 google-generativeai 抛出的 FutureWarning 弃用警告
• 📦 依赖与环境同步 - 移除 google-generativeai，引入 google-genai>=0.1.0
• 🧪 测试用例扩充 - 增加针对 QueryEnhancer 的 Mock 生成、缓存与异常降级容灾测试用例

v0.1.6 (2026-03-17) - 🧭 新增百度搜索支持

• ✨ 新增 BaiduSearchTool - 接入百度千帆 web_search API
• ✅ 新增 BAIDU_SEARCH_API_KEY 环境变量支持与自动启用
• ✅ SearchConfig / AdvancedSearchConfig / FlexibleSearchConfig / APIKeyManager 同步支持
• ✅ 增强百度结果解析与日期过滤（search_filter.range.page_time + 客户端 UTC 过滤）
• ✅ 新增与更新测试，覆盖百度工具与引擎注册

v0.1.5 (2026-02-20) - 🔍 新增4大搜索引擎 + 架构统一

• ✨ 新增 YouTube 搜索 - YouTube Data API v3，视频搜索与频道信息
• ✨ 新增 GitHub 搜索 - REST API 搜索 AI 开源项目（可选 Token）
• ✨ 新增 HuggingFace 搜索 - Hub API 搜索 AI 模型、数据集
• ✨ 新增 Perplexity 搜索 - Sonar API，AI 驱动搜索，带引用和摘要映射
• ✅ 架构统一 - 所有搜索引擎在 SearchConfig、AdvancedSearchConfig、FlexibleSearchConfig 中均可使用
• ✅ 移除 Bing Search - 微软已停止支持
• ✅ 新增 FlexibleSearchConfig - 支持为每个引擎独立配置参数
• ✅ 新增 FlexibleAINewsCollector - 灵活收集器，支持引擎级别参数控制

v0.1.4 (2025-10-29) - ⏰ 时间过滤增强

• ✅ 100%时间过滤准确率 - 彻底解决时间过滤问题
• ✅ 双重过滤机制 - API级别过滤 + 客户端备用过滤
• ✅ 全搜索引擎支持 - 修复了所有搜索引擎的时间过滤问题

v0.1.3 (2025-10-22) - 🤖 LLM 查询增强

• ✨ AI 驱动查询优化 - 集成 Google Gemini LLM，为所有搜索引擎生成优化查询
• ✅ 新增 EnhancedQuery 数据模型
• ✅ 新增 QueryEnhancer 工具类
• ✅ 智能缓存 - 24 小时 TTL 避免重复 LLM 调用
• ✅ 优雅降级 - LLM 不可用时自动使用原始查询

v0.1.2 (2025-10-21) - 🔒 安全版本

• ✅ 全面安全审计 - 清理VCR cassettes中的所有凭证
• ✅ 将测试API密钥替换为"FILTERED"占位符
• ✅ GitHub Actions自动化测试和PyPI发布

v0.1.0 (2025-10-07)

• 初始预发布版本
• 支持基础搜索功能
• 支持多种搜索源
• 支持高级功能（内容提取、关键词分析、缓存等）

---

📊 项目结构

ai_news_collector_lib/
├── __init__.py                    # 主模块入口
├── cli.py                        # 命令行接口
├── config/                       # 配置模块
│   ├── __init__.py
│   ├── settings.py              # SearchConfig / AdvancedSearchConfig
│   ├── flexible_config.py       # FlexibleSearchConfig
│   └── api_keys.py              # API密钥管理
├── core/                        # 核心功能
│   ├── __init__.py
│   ├── collector.py             # 基础收集器 (AINewsCollector)
│   ├── advanced_collector.py    # 高级收集器 (AdvancedAINewsCollector)
│   └── flexible_collector.py    # 灵活收集器 (FlexibleAINewsCollector)
├── models/                      # 数据模型
│   ├── __init__.py
│   ├── article.py              # 文章模型
│   ├── enhanced_query.py       # LLM 增强查询模型
│   └── result.py               # 结果模型
├── tools/                       # 搜索工具 (15 个搜索引擎)
│   ├── __init__.py
│   └── search_tools.py         # 各种搜索工具实现
├── utils/                       # 工具函数
│   ├── __init__.py
│   ├── cache.py                # 缓存管理
│   ├── content_extractor.py    # 内容提取
│   ├── keyword_extractor.py    # 关键词提取
│   ├── query_enhancer.py       # LLM 查询增强
│   ├── reporter.py             # 报告生成
│   └── scheduler.py            # 定时任务
└── examples/                    # 使用示例
    ├── basic_usage.py
    └── advanced_usage.py

tests/
├── conftest.py                 # pytest配置
├── test_basic.py               # 基础功能测试
├── test_integration_basic.py    # 基础集成测试
├── test_integration_advanced.py # 付费API集成测试
├── test_new_search_tools.py     # 新搜索引擎测试
├── cassettes/                  # VCR cassette文件
│   ├── basic_ai_hn_ddg.yaml
│   ├── advanced_ml_hn_ddg.yaml
│   └── ...
└── test_arxiv_fallback_offline.py # ArXiv特殊测试

---

祝你使用愉快！ 🎉

如有问题或建议，欢迎提交Issue或加入讨论区。