europepmc-search

Europe PMC RESTful Web Service 的薄封装。一次请求 = 多源召回:PubMed(MED)、PubMed Central(PMC)、AGRICOLA(AGR)、CABI(CBA)、预印本(PPR,涵盖 bioRxiv/medRxiv/ChemRxiv/arXiv 生命科学子集/Research Square/SSRN/Preprints.org)、专利(PAT)、NCBI Bookshelf(NBK)、ETHOS 论文集等。

跨平台 Python(Windows / macOS / Linux 均可),无需 Anaconda 锁定环境。

1. 何时使用本 skill

| 场景 | 用本 skill | 应改用 | |------|-----------|------| | RAG 知识库构建,需"撒网"式广召回 | ✅ | — | | 同时要 PubMed + 预印本 | ✅ | — | | 拿 DOI 反查全文 OA 链接 | ✅ | — | | 找特定基金(NIH/NSFC/Wellcome)资助的研究 | ✅(grant_id) | — | | 只要 PubMed 官方源 + Clinical Queries | ❌ | pubmed-eutils | | 抽取已知 PMCID 的全文 XML / 段落 | ❌ | bioc-fulltext-fetch | | 临床试验注册号检索 | ❌ | clinical-trials-v2 | | 实体(基因/疾病/化合物)关联 | ❌ | pubtator-entity-search | | 给文献排 GRADE 等级 | ❌ | medical-evidence-grading | | 报告 Appendix C 终态参考文献 | ❌ | evidence-appendix-sync |

与 pubmed-eutils 的差异化(必读):

• pubmed-eutils:PubMed 单源 · Clinical Queries · MeSH 精准 · PubDate 严格范围 → 高精准
• europepmc-search:多源聚合 + 自动去重 + 全文链接 + citations metadata → 高召回
• 推荐编排:RAG 知识库构建 → 本 skill 广召回 → 输出 PMID 列表 → pubmed-eutils 精准复核 → bioc-fulltext-fetch 取 OA 全文 → pubtator-entity-search 实体抽取 → medical-evidence-grading 分级 → evidence-appendix-sync 写入报告

2. 配置加载

Europe PMC RESTful 是完全开放 API,无需 API key,但服务条款要求传 email 联系方式。

配置加载顺序(高到低):

1. 项目级:.config/europepmc.local.yaml
2. 用户级:~/.config/europepmc.yaml
3. 环境变量:EUROPEPMC_EMAIL
4. 都没有 → 退化为 anonymous@example.org 并打印 ⚠️ 警告

yaml
# ~/.config/europepmc.yaml
email: yong.qi.gpt@gmail.com
default_page_size: 100
default_result_type: core      # lite | core | idlist
default_format: json
timeout_seconds: 30
max_retries: 3

3. API 端点速查

基础 URL:https://www.ebi.ac.uk/europepmc/webservices/rest/

| 端点 | 用途 | |------|------| | search | 通用检索(本 skill 主力) | | article/{source}/{id} | 单篇详情 | | {source}/{id}/fullTextXML | 全文 XML(仅 OA PMC 子集) | | {source}/{id}/references | 参考文献 | | {source}/{id}/citations | 被引列表 | | {source}/{id}/supplementaryFiles | 补充材料 | | grant/search | 资助检索 |

4. 核心检索能力(5 个原子函数,带 type hint)

4.1 search_articles

python
from typing import Literal
def search_articles(
    query: str,
    source_filter: list[str] | None = None,
    max_results: int = 200,
    sort: Literal["date", "cited"] | None = None,
) -> list[dict]:
    """通用多源检索,自动 cursorMark 分页拉满到 max_results。"""

• source_filter:["MED","PMC","PPR"] 限定来源;None = 全部。详细来源代码见 references/source-filters.md
• 返回每条含 pmid / pmcid / doi / title / authors / journal / pub_year / abstract / source / is_preprint / preprint_server / has_full_text / oa_status / cited_by_count 等(完整 schema 见 §11)

4.2 get_article_details

python
def get_article_details(identifier: str) -> dict:
    """单篇完整元数据。identifier 自动识别:
    - 纯数字 → PMID(查 MED)
    - PMC 前缀 → PMCID(查 PMC)
    - 10. 开头 → DOI(用 query=DOI:"..." 反查)
    - PPR 前缀 → 预印本 ID(查 PPR)
    """

4.3 get_full_text_links

python
def get_full_text_links(pmid_or_pmcid: str) -> dict[str, str | list[str] | None]:
    """返回所有可用全文链接,按类型分类:
    {
      "oa_xml": "...",            # OA 子集才有
      "oa_pdf": "...",
      "publisher_html": "...",
      "subscription": [...],       # SUBSCRIPTION 类型
      "text_mining": [...],        # TM 类型
      "preprint_server": "..."     # 仅预印本
    }"""

4.4 search_with_grants

python
def search_with_grants(
    query: str,
    grant_id: str | None = None,
    funder: str | None = None,
) -> list[dict]:
    """资助检索。Europe PMC 有专门的 GRANT_ID / FUNDER 字段。
    例:search_with_grants(query="cancer", grant_id="R01-CA123456")
        search_with_grants(query="cardiology", funder="Wellcome Trust")
    """

4.5 find_similar_articles

python
def find_similar_articles(pmid_or_pmcid: str, limit: int = 20) -> list[dict]:
    """调用 Europe PMC 内置 'Similar Articles' 算法(MeSH + 文本相似度)。
    比 PubMed elink neighbor 召回略广,适合 RAG 邻域扩展。"""

5. Auto-trigger prompt 模拟

| 用户 prompt 示例 | 应否触发本 skill | |------------------|----------------| | "找血液 IFI 相关的 PubMed + PMC + 预印本聚合检索" | ✅ 触发 | | "给我所有支持论文的全文链接,包括 OA 状态" | ✅ 触发(get_full_text_links) | | "查特定 NIH grant R01CA255621 资助的肿瘤研究" | ✅ 触发(search_with_grants) | | "我做 RAG 知识库,需要广撒网召回 1000 条" | ✅ 触发 | | "DOI 10.1038/... 反查全文链接" | ✅ 触发(get_article_details + get_full_text_links) | | "我只要 PubMed 官方源的高精准查询 + Clinical Queries 过滤" | ❌ 改用 pubmed-eutils | | "查 PMC 文章 PMC10987654 的全文段落" | 部分:本 skill get_full_text_links 给链接 → 全文取用交 bioc-fulltext-fetch | | "给 200 篇文献排 GRADE 等级" | ❌ 改用 medical-evidence-grading(可链式接本 skill 输出) | | "找 NCT12345678 临床试验招募信息" | ❌ 改用 clinical-trials-v2 |

6. 查询语法核心字段

最常用字段速查(完整 cheatsheet 见 references/query-syntax.md):

| 字段 | 示例 | |------|------| | TITLE / TITLE_ABS | TITLE_ABS:"acute myeloid leukemia" | | AUTH | AUTH:"Smith J" | | JOURNAL | JOURNAL:"Nature" | | PUB_YEAR | PUB_YEAR:[2020 TO 2024] | | PUB_TYPE | PUB_TYPE:"Review" | | SRC | SRC:MED / SRC:PPR | | HAS_FT / OPEN_ACCESS | HAS_FT:Y AND OPEN_ACCESS:Y | | MESH | MESH:"Hematologic Neoplasms" | | GRANT_ID / FUNDER | GRANT_ID:"R01CA12345" | | DOI | DOI:"10.1038/s41586-020-2196-x" |

⚠️ 字段名 必须大写,title:foo 会被当成普通短语。

7. 多源去重(本 skill 强制内置)

同一篇文章常在 MED + PMC + PPR 同时出现。去重规则按优先级:

1. PMID 相同 → 合并,保留 MED 版本(PubMed 元数据最权威)
2. PMCID 相同 → 合并,保留 PMC 版本(因含全文)
3. DOI 相同 → 合并,优先 MED > PMC > PPR
4. 预印本特殊处理:同一 DOI 既有预印本(PPR)又有正式发表(MED) → 两条都保留,但预印本条目标记 superseded_by_pmid: <发表版 PMID>,下游 medical-evidence-grading 据此自动丢弃。

8. 预印本处理(医学证据特别注意)

每条 PPR 结果显式标注:

python
{
  "source": "PPR",
  "is_preprint": True,
  "preprint_server": "bioRxiv",   # 或 medRxiv / ChemRxiv / Research Square / SSRN
  "preprint_doi": "10.1101/2024.03.15.123456",
  "posted_date": "2024-03-15",
  "version": 2
}

下游 medical-evidence-grading 看到 is_preprint=True 自动降权(GRADE 中作为 "very low" 起点)。本 skill 自身不做证据分级,只如实标注。

9. 失败模式表(标准化)

| ID | 故障 | 现象 | 处理 / 抛出 | |----|------|------|------------| | F1 | API 速率限制(429) | HTTP 429 + Retry-After | 指数退避 2^n + jitter,最多 max_retries=3;仍失败抛 EuropePMCRateLimitError | | F2 | 多源去重失败 | 同 DOI/PMID 出现多条未合并 | 走 _dedupe_three_tier() 强制去重;若三级 ID 都缺,按 (title 前 80 字 + first_author + pub_year) MD5 哈希再合并;无法合并则保留并标 dedup_warning=True | | F3 | 预印本未标记 | 结果里 source=="PPR" 但 is_preprint=False | 检测到 source==PPR 强制设 is_preprint=True,补 preprint_server 字段(从 publisher 字段映射);写 WARN log | | F4 | cursorMark 分页失败 | nextCursorMark 与上次相同但 hitCount 未取完 / 连续两次空响应 | 第一种正常终止;第二种抛 EuropePMCPaginationError,附最后一次 cursor 值便于断点续抓。详见 references/cursormark-pagination.md | | F5 | email 未配置警告 | 配置链 4 级全空 | 退化用 anonymous@example.org,首次请求前打印 ⚠️ WARN,提示用户配置 ~/.config/europepmc.yaml | | F6 | 查询语法错误 | HTTP 400 + errMsg | 抛 EuropePMCQueryError(errMsg),不静默吞;常见原因:字段名小写、引号未配对、AND/OR 未大写 | | F7 | 命中为 0 | HTTP 200 + hitCount=0 | 返回空列表 + WARN"无命中,建议放宽 query / 移除 source_filter / 检查字段大小写" | | F8 | 服务端 5xx / 超时 | HTTP 5xx 或 requests.Timeout | 指数退避重试 max_retries 次;仍失败抛 EuropePMCServerError | | F9 | 结果超 max_results | hitCount > max_results | 截断并在返回 dict 顶层设 truncated=True,附 last_cursor_mark 便于续抓 |

致命错误一律抛异常,不静默吞(遵循 coding-style.md 错误处理原则)。

10. 分页与流量(摘要)

• 单页上限 pageSize=1000
• 强制使用 cursorMark(从 * 起),不要用 page= 偏移分页(>1000 条时官方不保证一致性)
• 全局并发 ≤ 5,QPS ≤ 8
• 详细分页规则、退避策略、并发陷阱 → references/cursormark-pagination.md

11. 输出契约(下游 skill 依赖)

每篇文章返回的标准 schema(本 skill 是契约源 — bioc-fulltext-fetch / pubtator-entity-search / medical-evidence-grading / evidence-appendix-sync 都按此消费):

python
{
  "primary_id": "PMID:38123456" | "PMCID:PMC10987654" | "DOI:10.xxx/...",
  "all_ids": {"pmid": str|None, "pmcid": str|None, "doi": str|None, "ppr_id": str|None},
  "title": str,
  "authors": [{"full_name": str, "affiliation": str|None, "orcid": str|None}],
  "journal": {"name": str, "iso_abbr": str|None, "issn": str|None},
  "pub_year": int,
  "pub_date": "YYYY-MM-DD",
  "abstract": str|None,
  "mesh_terms": list[str],
  "keywords": list[str],
  "source": "MED" | "PMC" | "PPR" | "AGR" | "CBA" | "PAT" | "NBK",
  "sources_merged": list[str],         # 去重前出现的所有源
  "is_preprint": bool,
  "preprint_server": str|None,
  "preprint_doi": str|None,
  "version": int|None,
  "superseded_by_pmid": str|None,
  "has_full_text": bool,
  "oa_status": "OA" | "SUBSCRIPTION" | "UNKNOWN",
  "full_text_links": {"oa_xml": str|None, "oa_pdf": str|None, "publisher_html": str|None},
  "cited_by_count": int,
  "grants": [{"grant_id": str, "agency": str, "country": str|None}],
  "fetched_at": "ISO-8601 UTC",
  "europepmc_url": "https://europepmc.org/article/MED/38123456"
}

字段缺失用 None,不省略 key(下游解构稳定性)。

12. 与同体系其他 skill 的协作链路

[用户问题]
    │
    ├─→ europepmc-search       ← 本 skill (广召回 200~1000 条 + 多源去重)
    │       │
    │       ├─→ pubmed-eutils         ← 拿 PMID 子集精准复核 + Clinical Queries
    │       │       │
    │       │       └─→ bioc-fulltext-fetch  ← OA PMC 全文 XML
    │       │               │
    │       │               └─→ pubtator-entity-search  ← 实体识别
    │       │                       │
    │       │                       └─→ medical-evidence-grading  ← GRADE 分级
    │       │                              (依据 is_preprint 自动降权)
    │       │                              │
    │       │                              └─→ evidence-appendix-sync  ← 终下游(写 Appendix C)
    │       │
    │       └─→ medical-evidence-grading 也可直接消费本 skill 输出(跳过精准复核)
    │
    └─→ clinical-trials-v2 / aact-bulk-trials  ← 试验注册号另走专线

13. 调用示例

python
from europepmc_search import EuropePMCClient

cli = EuropePMCClient()  # 自动加载 ~/.config/europepmc.yaml

# 1) 广召回:急性髓系白血病近 5 年 PubMed + 预印本
hits = cli.search_articles(
    query='(TITLE:"acute myeloid leukemia" OR ABSTRACT:"AML") AND PUB_YEAR:[2020 TO 2025]',
    source_filter=["MED", "PPR"],
    max_results=500,
    sort="date",
)
print(f"去重后 {len(hits)} 条,预印本 {sum(h['is_preprint'] for h in hits)} 条")

# 2) DOI 反查全文链接
links = cli.get_full_text_links("10.1056/NEJMoa2024850")

# 3) NIH R01 资助的 CAR-T 研究
ft = cli.search_with_grants(query="CAR-T", grant_id="R01CA255621")

# 4) 邻域扩展(RAG)
similar = cli.find_similar_articles("38123456", limit=30)

14. 进阶参考(references/)

| 文件 | 内容 | |------|------| | references/query-syntax.md | 完整字段表 + 布尔/通配/邻近搜索 + 5 个常用查询配方 + 排序参数 | | references/source-filters.md | 全部 SRC 来源代码 + 量级 + 预印本子源(bioRxiv/medRxiv/...) + 选择策略 | | references/cursormark-pagination.md | cursorMark 流程伪代码 + 终止条件 + 退避策略 + 5 个常见坑 |

参考链接

• Europe PMC RESTful Web Service:https://europepmc.org/RestfulWebService
• 查询语法 Help:https://europepmc.org/Help#SSR
• 字段速查:https://europepmc.org/Help#fieldsearch
• 服务条款:https://europepmc.org/About#TermsOfUse