Skip to content

OpenSenseNova/SenseNova-Skills / skills/sn-search-academic

sn-search-academic

Verified

用于学术调研、论文精读、相关工作梳理、百科知识查询和引用链追溯。

scripts/semantic_scholar_search.py

View on GitHub
#!/usr/bin/env python3
"""Semantic Scholar 论文搜索。优先使用 semanticscholar SDK,失败时回退 Graph API HTTP。"""

import sys
import time
from datetime import date, datetime
from pathlib import Path


from search_utils import build_parser, get_client, make_item, make_result, print_json

try:
    from semanticscholar import SemanticScholar
except ImportError:  # SDK 是优先路径;缺失时仍可使用 HTTP fallback。
    SemanticScholar = None

API_URL = "https://api.semanticscholar.org/graph/v1/paper/search"
MAX_429_ATTEMPTS = 4
BASE_429_DELAY_SECONDS = 1.0


def _dependency_hint(package: str) -> str:
    skill_dir = Path(__file__).resolve().parents[1]
    requirements = skill_dir / "requirements.txt"
    return (
        f"缺少依赖 {package}。请安装到当前 Python 环境:"
        f"python3 -m pip install -r {requirements}"
    )

FIELDS = ",".join([
    "title", "abstract", "tldr", "year", "venue", "publicationVenue", "publicationDate",
    "authors", "citationCount", "influentialCitationCount",
    "referenceCount", "isOpenAccess", "openAccessPdf",
    "externalIds", "fieldsOfStudy", "publicationTypes", "journal",
])
SDK_FIELDS = FIELDS.split(",")


def _retry_after_delay(response, attempt: int) -> float:
    retry_after = response.headers.get("Retry-After")
    if retry_after:
        try:
            return max(0.0, float(retry_after))
        except ValueError:
            pass
    return BASE_429_DELAY_SECONDS * (2 ** attempt)


def _get_with_429_retry(client, url: str, *, params: dict) -> object:
    for attempt in range(MAX_429_ATTEMPTS):
        resp = client.get(url, params=params)
        if getattr(resp, "status_code", None) != 429:
            resp.raise_for_status()
            return resp
        if attempt == MAX_429_ATTEMPTS - 1:
            resp.raise_for_status()
            return resp
        time.sleep(_retry_after_delay(resp, attempt))
    raise RuntimeError("unreachable")


def _value(obj, key: str, default=None):
    if obj is None:
        return default
    if isinstance(obj, dict):
        return obj.get(key, default)
    return getattr(obj, key, default)


def _names(items) -> list[str]:
    names = []
    for item in items or []:
        name = _value(item, "name")
        if name:
            names.append(name)
        elif isinstance(item, str):
            names.append(item)
    return names


def _text(obj) -> str | None:
    if obj is None:
        return None
    if isinstance(obj, str):
        return obj
    return _value(obj, "text")


def _date_string(value):
    if isinstance(value, datetime):
        return value.date().isoformat()
    if isinstance(value, date):
        return value.isoformat()
    return value


def _open_access_pdf_url(paper) -> str | None:
    pdf = _value(paper, "openAccessPdf")
    return _value(pdf, "url")


def _publication_venue(paper) -> dict | None:
    pub_venue = _value(paper, "publicationVenue") or {}
    publication_venue = {
        k: _value(pub_venue, k)
        for k in ("id", "name", "type", "url")
        if _value(pub_venue, k)
    }
    return publication_venue or None


def _external_ids(paper) -> dict:
    external_ids = _value(paper, "externalIds") or {}
    return external_ids if isinstance(external_ids, dict) else {}


def _item_from_paper(paper, fallback_paper_id: str = "") -> dict:
    authors = _names(_value(paper, "authors"))
    external_ids = _external_ids(paper)

    paper_id = _value(paper, "paperId") or fallback_paper_id
    url = _value(paper, "url") or (f"https://www.semanticscholar.org/paper/{paper_id}" if paper_id else "")

    abstract = _value(paper, "abstract") or ""
    tldr = _text(_value(paper, "tldr"))
    snippet = abstract or tldr or ""

    journal = _value(paper, "journal") or {}
    venue = _value(paper, "venue") or _value(journal, "name")

    return make_item(
        title=_value(paper, "title") or "",
        url=url,
        snippet=snippet,
        tldr=tldr,
        authors=authors,
        year=_value(paper, "year"),
        venue=venue if venue else None,
        publication_venue=_publication_venue(paper),
        publication_date=_date_string(_value(paper, "publicationDate")),
        citation_count=_value(paper, "citationCount"),
        influential_citation_count=_value(paper, "influentialCitationCount"),
        reference_count=_value(paper, "referenceCount"),
        is_open_access=_value(paper, "isOpenAccess"),
        open_access_pdf=_open_access_pdf_url(paper),
        fields_of_study=_names(_value(paper, "fieldsOfStudy")) or None,
        publication_types=_value(paper, "publicationTypes") or None,
        doi=_value(paper, "doi") or external_ids.get("DOI"),
        arxiv_id=external_ids.get("ArXiv"),
        paper_id=paper_id,
    )


def _build_sdk_client(api_key: str | None):
    if SemanticScholar is None:
        raise ImportError(_dependency_hint("semanticscholar"))
    if api_key:
        return SemanticScholar(api_key=api_key)
    return SemanticScholar()


def _search_with_sdk(query: str, limit: int, api_key: str | None = None) -> list[dict]:
    sch = _build_sdk_client(api_key)
    results = sch.search_paper(query, limit=min(limit, 100))

    items = []
    for paper in results:
        paper_id = _value(paper, "paperId")
        details = sch.get_paper(paper_id, fields=SDK_FIELDS) if paper_id else paper
        items.append(_item_from_paper(details, fallback_paper_id=paper_id))
        if len(items) >= limit:
            break
    return items


def _search_with_http(query: str, limit: int, api_key: str | None = None) -> list[dict]:
    headers: dict[str, str] = {}
    if api_key:
        headers["x-api-key"] = api_key

    params = {
        "query": query,
        "limit": min(limit, 100),
        "fields": FIELDS,
    }

    with get_client(timeout=30, headers=headers) as client:
        resp = _get_with_429_retry(client, API_URL, params=params)
        data = resp.json()

    items = []
    for paper in data.get("data", [])[:limit]:
        items.append(_item_from_paper(paper))

    return items


def search(query: str, limit: int, api_key: str | None = None) -> list[dict]:
    """执行 Semantic Scholar 搜索:SDK 优先,失败时使用原 HTTP Graph API。"""
    try:
        return _search_with_sdk(query, limit, api_key)
    except Exception:
        return _search_with_http(query, limit, api_key)


def main():
    parser = build_parser("搜索 Semantic Scholar 学术论文")
    parser.add_argument("--api-key", help="Semantic Scholar API Key(可选,提高限额)")
    args = parser.parse_args()

    try:
        items = search(args.query, args.limit, getattr(args, "api_key", None))
        print_json(make_result(True, args.query, "semantic_scholar", items))
    except Exception as e:
        print_json(make_result(False, args.query, "semantic_scholar", [], str(e)))
        sys.exit(1)


if __name__ == "__main__":
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall