Pubmed eutils

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 个核心函数签名

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 配置加载逻辑（按优先级）

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", "[email protected]"),
            "tool":  os.getenv("NCBI_TOOL",  "claude-code-pubmed-eutils"),
        }

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

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

api_key: "your_36char_ncbi_api_key"
email:   "[email protected]"      # 必传，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,缺失则用 [email protected] 兜底
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