Google Scholar API 技能

概述

本技能提供通过 SerpAPI 访问 Google Scholar 的功能，实现学术论文的智能检索和下载。包含完整的 Python 脚本、配置示例和使用指南。

快速开始

1. 安装依赖

pip install google-search-results requests

2. 设置 API 密钥

export SERP_API_KEY="your_serpapi_key_here"

3. 基本搜索示例

from scripts.google_scholar_search import GoogleScholarSearch

# 初始化客户端
client = GoogleScholarSearch()

# 搜索论文
results = client.search("machine learning", num_results=5)
papers = client.parse_results(results)

for paper in papers:
    print(f"标题: {paper['title']}")
    print(f"作者: {paper['authors']}")
    print(f"年份: {paper['year']}")
    if 'pdf_link' in paper:
        print(f"PDF 可用: {paper['pdf_link']}")

核心功能

1. 论文搜索（基于 SerpAPI）

• 基本搜索: 关键词、短语搜索
• 高级搜索: 作者搜索 (author:"姓名")、来源搜索 (source:"期刊")
• 时间过滤: 按年份范围筛选 (as_ylo, as_yhi)
• 排序选项: 相关性、日期（仅摘要）、日期（全部内容）
• 引用搜索: 搜索引用特定文章的文献 (cites 参数)
• 版本搜索: 搜索文章的所有版本 (cluster 参数)

2. 结果解析

• 完整元数据: 标题、作者、年份、期刊、摘要
• 引用信息: 引用次数、引用ID、集群ID
• 作者详情: 作者姓名、Google Scholar链接、作者ID
• 资源链接: PDF、HTML、相关页面、引用链接
• 搜索统计: 总结果数、处理时间、搜索状态

3. PDF 下载

• 智能检测: 自动识别可用的PDF链接
• 批量下载: 支持批量下载多个论文
• 文件命名: 按"年份_标题"格式自动命名
• 下载跟踪: 记录下载状态和路径
• 错误处理: 网络超时、链接失效等异常处理

4. 高级功能

• 作者专搜: 专门搜索某位作者的所有论文
• 引用分析: 分析某篇文章的引用网络
• 版本追踪: 查找文章的所有版本
• 多语言: 支持多种语言搜索 (hl 参数)
• 综述筛选: 仅显示综述文章 (as_rr 参数)

工作流程

步骤 1: 准备环境

1. 获取 SerpAPI 密钥（免费注册）
2. 安装 Python 依赖
3. 设置环境变量或直接传递密钥

步骤 2: 执行搜索

# 基础搜索
client.search("deep learning", num_results=10)

# 高级搜索（带过滤）
client.search(
    query="transformer",
    year_from=2020,
    year_to=2024,
    sort_by="date"
)

步骤 3: 处理结果

# 解析结果
papers = client.parse_results(search_data)

# 检查 PDF 可用性
for paper in papers:
    if 'pdf_link' in paper:
        print(f"可下载: {paper['title']}")

步骤 4: 下载文件

# 单个文件下载
client.download_pdf(pdf_url, "paper.pdf")

# 批量搜索和下载
result = client.search_and_download(
    query="reinforcement learning",
    download_dir="./papers",
    max_papers=5
)

使用示例

示例 1: 简单文献调研

# 搜索某个主题的最新论文
client = GoogleScholarSearch()
results = client.search("quantum machine learning", num_results=15, sort_by="date")
papers = client.parse_results(results)

print(f"找到 {len(papers)} 篇相关论文")
for i, paper in enumerate(papers[:5]):
    print(f"{i+1}. {paper['title']} ({paper['year']}) - {paper['cited_by']} 次引用")

示例 2: 下载特定年份的论文

# 下载 2020-2023 年的论文
result = client.search_and_download(
    query="computer vision",
    download_dir="./cv_papers",
    max_papers=10,
    year_from=2020,
    year_to=2023
)

print(f"成功下载 {result['successful_downloads']} 篇论文")

示例 3: 命令行使用

# 直接运行脚本
python scripts/google_scholar_search.py "artificial intelligence" --num 10 --output ./ai_papers

SerpAPI 配置

API 密钥和计划

• 免费计划: 每月 250 次搜索，50次/小时吞吐量
• Starter: $25/月，1000次搜索，200次/小时
• Developer: $75/月，5000次搜索，1000次/小时
• Production: $150/月，15000次搜索，3000次/小时
• Big Data: $275/月，30000次搜索，6000次/小时

重要限制

• 每页结果: 1-20 条（num 参数）
• 分页: 通过 start 参数（0, 10, 20...）
• 缓存: 默认启用，1小时有效期
• 异步模式: 支持异步请求 (async 参数)
• 输出格式: JSON（默认）或原始HTML

搜索参数详解

• q: 搜索查询（支持 author:, source: 语法）
• num: 每页结果数（1-20，默认10）
• start: 分页起始位置（0, 10, 20...）
• as_ylo/as_yhi: 年份范围过滤
• scisbd: 排序方式（0=相关性, 1=日期仅摘要, 2=日期全部）
• hl: 语言代码（en, zh-CN, ja 等）
• as_vis: 是否包含引用（0=包含, 1=排除）
• as_rr: 是否仅显示综述文章（0=全部, 1=仅综述）
• cites: 搜索引用特定文章的文献
• cluster: 搜索文章的所有版本

下载设置

• download_dir: 下载目录（默认 "./downloads"）
• 自动创建目录
• 文件按论文标题命名

错误处理

常见问题

1. API 密钥错误: 检查密钥是否正确设置
2. 额度不足: 免费计划每月 100 次搜索
3. 网络问题: 检查网络连接和代理设置
4. PDF 不可用: 并非所有论文都有公开 PDF

调试建议

import logging
logging.basicConfig(level=logging.DEBUG)

try:
    results = client.search("test query")
except Exception as e:
    print(f"错误详情: {e}")
    # 检查环境变量
    print(f"API Key: {os.getenv('SERP_API_KEY')}")

最佳实践

搜索优化

1. 使用具体、相关的关键词
2. 添加引号进行精确匹配
3. 合理设置结果数量避免超限
4. 使用年份过滤获取最新研究

资源管理

1. 缓存常用搜索结果
2. 分批处理大量请求
3. 定期清理下载目录
4. 备份重要论文

合规使用

1. 仅用于个人学术研究
2. 尊重版权和访问条款
3. 不要大规模批量下载
4. 遵守目标网站的 robots.txt

资源文件

scripts/ 目录

包含可执行的 Python 脚本：

1. google_scholar_search.py - 核心搜索和下载脚本

   • 主要功能类 GoogleScholarSearch
   • 支持搜索、解析、下载完整流程
   • 命令行接口

2. config_example.py - 配置和使用示例

   • 基础搜索示例
   • PDF 下载示例
   • 高级搜索示例

3. requirements.txt - 依赖包列表

   • google-search-results: SerpAPI Python 客户端
   • requests: HTTP 请求库

references/ 目录

包含详细参考文档：

1. api_guide.md - API 使用指南
   • SerpAPI 密钥获取
   • 搜索参数详解
   • 结果字段说明
   • 错误处理和最佳实践

文件结构

google-scholar-api/
├── SKILL.md (本文件)
├── scripts/
│   ├── google_scholar_search.py (核心脚本)
│   ├── config_example.py (配置示例)
│   └── requirements.txt (依赖列表)
└── references/
    └── api_guide.md (API 指南)

使用提示

在 OpenClaw 中使用

当用户请求搜索学术论文时：

1. 检查是否设置了 SERP_API_KEY 环境变量
2. 使用 scripts/google_scholar_search.py 执行搜索
3. 根据需要下载 PDF 文件
4. 提供格式化的搜索结果

常见用户请求模式

• "帮我搜索关于机器学习的论文"
• "下载最近3年关于深度学习的PDF"
• "查找引用次数超过1000的经典论文"
• "批量下载某个研究主题的相关文献"

响应格式建议

## 搜索结果：机器学习

找到 15 篇相关论文，其中 8 篇有 PDF 可用：

1. **Attention Is All You Need** (2017)
   - 作者：Vaswani et al.
   - 引用：125,000+
   - PDF: ✅ 可用
   - 下载：`python scripts/google_scholar_search.py "Attention Is All You Need"`

2. **Deep Residual Learning for Image Recognition** (2015)
   - 作者：He et al.
   - 引用：85,000+
   - PDF: ✅ 可用
   - 下载：`python scripts/google_scholar_search.py "Deep Residual Learning"`

...

注意事项

限制和约束

1. API 限制: SerpAPI 免费计划每月 100 次搜索
2. PDF 可用性: 并非所有论文都有公开 PDF
3. 下载速度: 受网络和服务器响应影响
4. 版权遵守: 仅用于个人学术研究

扩展建议

如需更多功能，可考虑：

1. 集成其他学术数据库（arXiv、PubMed 等）
2. 添加引用管理功能（BibTeX 导出）
3. 实现论文推荐系统
4. 添加文献综述自动生成

技能维护: 定期检查 SerpAPI 的 API 变化，更新脚本以保持兼容性。