pubmed-eutils · NCBI E-utilities 原子封装

一句话定义

把 NCBI E-utilities (esearch / efetch / esummary / elink) 封装成医学证据检索流水线里唯一的 PubMed 召回入口。只负责"把 PMID 列表 + 结构化元数据拿回来"，不做相关性重排、不抽全文、不评证据等级。

何时调用

• 用户提到 PubMed、文献检索、pmid、医学文献、NCBI、MeSH、Clinical Queries
• 任务需要 召回 PMID 列表（系统综述起点、市场调研证据池、疾病机制文献池）
• 需要 PMID → PMCID 映射（给 bioc-fulltext-fetch 取全文）
• 需要 批量摘要 + MeSH 标签（给 medical-evidence-grading 排序、给 pubtator-entity-search 实体标注）
• 需要 Clinical Queries 内置过滤器（therapy / diagnosis / etiology / prognosis / clinical_prediction_guides / systematic_reviews + narrow / broad）

何时不调用

• 取全文 XML/JATS → 用 bioc-fulltext-fetch（PMC OAI / BioC API）
• 取 Europe PMC 特有字段（如 preprint、欧洲灰色文献）→ 用 europepmc-search（互补召回）
• 取 临床试验注册信息 → 用 clinical-trials-v2 + aact-bulk-trials
• 做 基因/疾病/药物实体标注 → 用 pubtator-entity-search
• 做 GRADE/Cochrane RoB 证据评级 → 用 medical-evidence-grading
• 做 语义重排 / 相关度排序 → 本 skill 输出后由 medical-evidence-grading 或 reranker 处理

与其他 skill 的协作关系

                    ┌─ pubmed-eutils（本 skill · 召回主力 · PMID + 元数据）
                    │
召回层 (recall)  ───┼─ europepmc-search（互补 · preprint / 欧洲文献）
                    │
                    └─ clinical-trials-v2 / aact-bulk-trials（试验注册）

                                │
                                ▼ PMID list
全文层 (fulltext) ─── bioc-fulltext-fetch（PMC 全文 JATS / BioC）
                                │
                                ▼ entity-rich text
标注层 (annotate) ─── pubtator-entity-search（gene/disease/drug NER）
                                │
                                ▼
排序层 (rank)     ─── medical-evidence-grading（GRADE / RoB / 证据等级）
                                │
                                ▼
终下游           ─── evidence-appendix-sync（市场调研附录 C 同步）

显式 skill 引用路径（同 ~/.claude/skills/ 下）:

• ~/.claude/skills/europepmc-search/SKILL.md — 互补召回(preprint / 欧洲灰文献)
• ~/.claude/skills/bioc-fulltext-fetch/SKILL.md — 下游全文获取(PMID/PMCID → JATS/BioC)
• ~/.claude/skills/pubtator-entity-search/SKILL.md — 互补实体级关系挖掘(疾病-药物-基因)
• ~/.claude/skills/medical-evidence-grading/SKILL.md — 上层证据排序(GRADE / OCEBM / RoB)
• ~/.claude/skills/evidence-appendix-sync/SKILL.md — 终下游附录 C 同步
• ~/.claude/skills/clinical-trials-v2/SKILL.md — 试验注册(非文献)互补

协作规则：本 skill 永远先跑,输出 PMID + 摘要 + MeSH,让下游 skill 决策"取哪些做全文 / 哪些进证据矩阵"。

5 个核心函数签名

python
from typing import Literal
from dataclasses import dataclass

@dataclass
class PubMedRecord:
    pmid: str
    title: str
    abstract: str | None
    authors_first: str | None
    authors_count: int
    journal: str | None
    year: int | None
    mesh_terms: list[str]
    publication_types: list[str]
    doi: str | None = None
    pmcid: str | None = None
    cited_count: int | None = None  # 通过 elink pubmed_pubmed_citedin 获取，可选

# 1) 检索 → PMID 列表
def esearch_pubmed(
    query: str,
    max_results: int = 200,
    filters: dict | None = None,   # {"pubdate_from": "2020/01/01", "pubdate_to": "2025/12/31",
                                    #  "pub_types": ["Randomized Controlled Trial"],
                                    #  "species": "humans", "language": "english"}
    sort: Literal["relevance", "pub_date", "first_author", "journal"] = "relevance",
) -> list[str]: ...

# 2) 批量取摘要 + MeSH（XML 解析）
def efetch_abstracts(pmid_list: list[str]) -> list[PubMedRecord]: ...

# 3) 简表（标题 + 第一作者 + 年份 + 期刊，比 efetch 快 5-10x）
def esummary_pubmed(pmid_list: list[str]) -> list[dict]: ...

# 4) PMID → PMCID 映射（给 bioc-fulltext-fetch 用）
def elink_pubmed_to_pmc(pmid_list: list[str]) -> dict[str, str]:
    """返回 {pmid: pmcid} · 没有全文的 PMID 不出现在结果里"""
    ...

# 5) Clinical Queries 内置过滤器
def pubmed_clinical_queries(
    query: str,
    category: Literal[
        "therapy", "diagnosis", "etiology", "prognosis",
        "clinical_prediction_guides", "systematic_reviews"
    ],
    scope: Literal["narrow", "broad"] = "narrow",
    max_results: int = 200,
) -> list[str]: ...

API 配置加载逻辑（按优先级）

python
def load_ncbi_config() -> dict:
    # 1. 项目本地（最高优先级）
    project_yaml = Path.cwd() / ".config" / "ncbi.local.yaml"
    if project_yaml.exists():
        return yaml.safe_load(project_yaml.read_text())

    # 2. 用户全局
    user_yaml = Path.home() / ".config" / "ncbi.yaml"
    if user_yaml.exists():
        return yaml.safe_load(user_yaml.read_text())

    # 3. 环境变量
    if os.getenv("NCBI_API_KEY"):
        return {
            "api_key": os.environ["NCBI_API_KEY"],
            "email": os.getenv("NCBI_EMAIL", "anonymous@example.com"),
            "tool":  os.getenv("NCBI_TOOL",  "claude-code-pubmed-eutils"),
        }

    # 4. 降级：无 key 模式（NCBI 允许 3 RPS）
    return {"api_key": None, "email": "anonymous@example.com",
            "tool": "claude-code-pubmed-eutils", "rps": 3}

配置文件示例 ~/.config/ncbi.yaml:

yaml
api_key: "your_36char_ncbi_api_key"
email:   "you@example.com"      # 必传，NCBI 礼貌要求
tool:    "your-project-name"    # 必传，便于 NCBI 联系
rps:     10                     # 有 key 上限 10

> 关键：每次请求都要带 email + tool + api_key(如有)，否则 NCBI 可能 ban IP。

检索式构造模板 + 跨疾病移植清单

7 个 ready-to-use 医学场景检索式(系统综述 / RCT / Clinical Queries / 流行病学 / RWE / 中国人群 / 指南)和疾病迁移指引详见参考文件,以保持主文件精简:

→ references/query-templates.md(同目录 ~/.claude/skills/pubmed-eutils/references/query-templates.md)

速率限制 + endpoint 速查

完整 endpoint 表 / dbfrom-db 组合 / 速率限制详见:

→ references/endpoint-table.md

主文件保留要点:

| 模式 | RPS | 单批 PMID 上限 | 超时 | | --------- | --- | -------------- | ---- | | 有 API key | 10 | 200 | 30s | | 无 key | 3 | 200 | 30s |

实现要求:令牌桶限流 + 429/503 指数退避(1s→2s→4s,3 次) + 单批超 200 自动切片 + 长 query (>2000 字符) 切 POST。

失败模式速查表

| # | 失败模式 | 根因 | 修复 | |---|---------------------------|-------------------------------------------|-------------------------------------------------------------------| | 1 | 无 key 限速被 ban | HTTP 429 持续 / 缺 email+tool | 检查是否传 email + tool + api_key;申请 API key(免费) | | 2 | 429 / 5xx 暂时性错误 | 限速触发 / NCBI 服务器抖动 | 指数退避重试 3 次(1s→2s→4s);仍失败抛 EUtilsTransientError | | 3 | XML 解析错误 | <ERROR>...</ERROR> 节点 | 单条 PMID 失效 → 跳过该条 + log warning,不 raise 中断整批 | | 4 | PMID 不存在 / 已撤稿(404) | efetch 返回空 <PubmedArticle> | 在 PubMedRecord.title 标 [RETRACTED] 或 [NOT FOUND] | | 5 | MeSH term 不规范返 0 结果 | preferred term 拼写 / 已被合并 | 用 einfo 查 MeSH 树;退化为 [tiab] 自由词 + 同义词扩展 | | 6 | email 未传被 NCBI 警告 | 请求缺 email 参数 | 强制配置加载层校验 email,缺失则用 anonymous@example.com 兜底 | | 7 | 网络超时 | httpx.ReadTimeout | 退避重试 3 次仍失败 → 抛 EUtilsTimeout(上游可降级到 europepmc) | | 8 | 长 query GET 414 | URL too long | 自动切到 POST(E-utilities 支持) | | 9 | 日期格式错 | NCBI 返回 <ERROR>Empty term</ERROR> | 强制 YYYY/MM/DD;过滤器 builder 入口校验 | | 10| WebEnv 失效 | history server 过期(8h) | 重新 esearch 而非缓存 history |

证据等级提示（本 skill 不排序）

本 skill 只给原始召回结果，不做证据等级判断。证据等级排序由 medical-evidence-grading 完成，依据：

• Publication type（meta-analysis > RCT > cohort > case-control > case report）
• 期刊影响因子（可选 · 需配 IF 数据源）
• 引用数（本 skill 通过 elink pubmed_pubmed_citedin 选配输出 cited_count）
• 样本量（需 bioc-fulltext-fetch 取全文后正则抽取）

输出 PubMedRecord 时保留 publication_types 原始列表，让下游 skill 自行映射 GRADE / OCEBM / 牛津等级。

跨平台兼容（Claude Code / Codex / Gemini CLI）

| 平台 | 触发方式 | 备注 | | ------------ | --------------------------------- | --------------------------------------------------- | | Claude Code | 自动 (description 包含触发词) | SKILL.md frontmatter 已优化 | | Codex CLI | codex skill use pubmed-eutils | 全部函数签名是纯 Python type hint，可直接 import | | Gemini CLI | /skill pubmed-eutils <query> | description 用关键词 + 自然语言双语，通用触发 |

实现层兼容要求：

• 函数实现层不依赖任何平台特定 SDK（不用 anthropic / openai / google.genai）
• 仅依赖：httpx / lxml（XML 解析）/ pydantic 或 dataclasses / pyyaml / aiolimiter
• 同步 + 异步双版本（esearch_pubmed + aesearch_pubmed），让 agent 编排器自由选用

必含章节自检

1. frontmatter(中英双语 + 推式触发词)✅
2. 一句话定义 ✅
3. 何时调用 / 不调用 ✅
4. 与其他 skill 协作关系(显式相对路径)✅
5. 5 个核心函数签名(标准 Python type hint)✅
6. API 配置加载逻辑 ✅
7. 检索式模板(放 references/query-templates.md)✅
8. 速率限制摘要(完整表放 references/endpoint-table.md)✅
9. 失败模式速查表(10 条 · 标准化 # | 模式 | 根因 | 修复 格式)✅
10. 证据等级提示 ✅
11. 跨平台兼容 ✅

参考资料

项目内 references(progressive disclosure):

• ~/.claude/skills/pubmed-eutils/references/query-templates.md — 7 个医学场景检索式 + 跨疾病移植清单
• ~/.claude/skills/pubmed-eutils/references/endpoint-table.md — endpoint 速查 / dbfrom-db 组合 / 速率限制详情

外部官方文档:

• E-utilities 完整文档: https://www.ncbi.nlm.nih.gov/books/NBK25500/
• E-utilities In Depth: https://www.ncbi.nlm.nih.gov/books/NBK25497/
• Clinical Queries 过滤器: https://pubmed.ncbi.nlm.nih.gov/help/#clinical-queries-filters
• API key 申请: https://www.ncbi.nlm.nih.gov/account/settings/
• MeSH 浏览器: https://www.ncbi.nlm.nih.gov/mesh/
• 速率限制官方说明: https://www.ncbi.nlm.nih.gov/books/NBK25497/#chapter2.Usage_Guidelines_and_Requiremen