semantic-scholar

Semantic Scholar 论文检索与验证

概述

基于 Semantic Scholar Academic Graph API 的论文检索工具，支持：

• 并发搜索：同时查询多个关键词
• 批量验证：通过 DOI / ArXiv ID / S2 ID 批量查询论文详情
• 引用分析：获取引用数、被引论文
• 开放获取：识别 OA 论文和 PDF 链接

覆盖 214M+ 学术论文，免费无需注册。

执行步骤

1. 确认搜索意图：用户提供关键词、DOI 或论文 ID
2. 选择搜索模式：单关键词搜索、多关键词并发搜索、批量 ID 查询
3. 执行搜索脚本 search_papers.py，获取结果 JSON
4. 如需摘要补全，执行 batch_abstract.py 批量获取缺失摘要
5. 如需格式化输出，执行 export_md.py 生成 Markdown 报告
6. 返回结果给用户，附带论文数量和关键统计

约束

• 禁止在无用户确认的情况下自动清除缓存（--clear-cache）
• 禁止将 API Key 硬编码到脚本或 commit 中
• 不可绕过速率限制器直接发请求
• 批量查询每批不可超过 500 篇（API 限制）
• 缓存 TTL 固定 3600s，不可在运行时修改

使用场景

• 按关键词检索论文标题、作者、年份
• 验证论文是否存在及其元数据是否正确
• 批量查询一组 DOI 对应的论文信息
• 与 OpenAlex 交叉验证检索结果
• 查找某领域高引论文

快速开始

依赖安装

pip install aiohttp

API Key 配置（可选）

无 Key 可用（1 req/s），配置 Key 后提升至 10 req/s。三种配置方式：

# 方式 1：交互式配置（推荐，保存到配置文件）
python $SCRIPTS/search_papers.py --setup

# 方式 2：环境变量
export S2_API_KEY="your-key-here"

# 方式 3：手动写入配置文件
# ~/.config/semantic-scholar/config.json
# {"api_key": "your-key-here"}

Key 解析优先级：--api-key 参数 → S2_API_KEY 环境变量 → 配置文件

支持两种 Key：

• 官方 Key：申请地址 https://www.semanticscholar.org/product/api#api-key-form
• ai4scholar.net 代理 Key：以 sk-user- 开头，自动路由到 ai4scholar.net

CLI 用法

SCRIPTS=~/.claude/skills/semantic-scholar/scripts

# 单关键词搜索
python $SCRIPTS/search_papers.py "blockchain consensus"

# 并发多关键词搜索
python $SCRIPTS/search_papers.py "HotStuff BFT" "DAG consensus" "PBFT protocol"

# 按 DOI 批量查询
python $SCRIPTS/search_papers.py --ids "DOI:10.1145/3293611.3331591" "ARXIV:1803.05069"

# 年份 + 引用数过滤
python $SCRIPTS/search_papers.py "consensus algorithm" --year "2020-" --min-cite 50

# 输出到 JSON
python $SCRIPTS/search_papers.py "BFT consensus" -n 20 -o results.json

# 跳过缓存（强制重新请求）
python $SCRIPTS/search_papers.py "HotStuff" --no-cache

# 清除所有缓存
python $SCRIPTS/search_papers.py --clear-cache

Python API 用法

import asyncio
from scripts.s2_client import S2Client

async def main():
    client = S2Client()  # 或 S2Client(api_key="your-key")

    # 单次搜索
    result = await client.search("blockchain consensus", limit=5)
    for p in result["data"]:
        print(f"{p['title']} ({p['year']}) - 引用: {p['citationCount']}")

    # 并发搜索多个关键词
    queries = ["HotStuff BFT", "DAG consensus", "PBFT protocol"]
    results = await client.search_concurrent(queries, limit=5)
    for q, r in results.items():
        print(f"\n== {q} ({r['total']} 条) ==")
        for p in r["data"]:
            print(f"  {p['title']}")

    # 批量 ID 查询
    papers = await client.batch_papers([
        "DOI:10.1145/3293611.3331591",
        "ARXIV:1803.05069",
    ])
    for p in papers:
        if p:
            print(f"{p['title']} ({p['year']})")

    await client.close()

asyncio.run(main())