PubMed E-utilities 检索实战基于 NCBI API 构建可复现的生物医学文献查询流程scientific-agent-skills paper-lookup 详解【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文基于 scientific-agent-skills 仓库中 paper-lookup 技能的 PubMed 参考文档系统讲解如何通过 NCBI E-utilities 接口检索 PubMed 上 3700 万 条生物医学与生命科学文献的题录、摘要与元数据。你将掌握 eSearch / eSummary / eFetch / eLink 四大端点的完整调用方式与参数语义、PubMed 检索语法字段标签、布尔运算、日期区间、出版类型、速率限制与错误处理规范并了解该技能如何在实践中与 PMC 全文库、Europe PMC 及仓库自带脚本paginate.py、jats_to_text.py协同把一次文献检索变成可审计、可复现的工程流程。一、PubMed 在 paper-lookup 技能中的定位paper-lookup 技能覆盖 11 个学术文献 APIPubMed、PMC、Europe PMC、bioRxiv、medRxiv、arXiv、OpenAlex、Crossref、Semantic Scholar、CORE、Unpaywall每个数据库都在references/目录下有一份独立参考文件。根据 SKILL.md 中的数据库选择指南PubMed 被定位为生物医学主题检索的默认首选库用户意图首选库备选库生物医学主题的论文检索PubMedEurope PMC、Semantic Scholar、OpenAlex生物医学文章全文Europe PMCPMC、CORE综合文献检索PubMed Europe PMC OpenAlex Semantic Scholar—查找并阅读论文PubMed查找 UnpaywallOA 链接 Europe PMC/CORE全文—理解 PubMed 的能力边界是正确使用它的前提PubMed 只提供题录、摘要与元数据不提供全文——全文检索与获取应交给 PMC 或 Europe PMC详见 PMC 参考文档 与 Europe PMC 参考文档。二、Base URL 与认证API Key 机制所有 E-utilities 调用都基于同一入口https://eutils.ncbi.nlm.nih.gov/entrez/eutils/认证要点如下API key 可选但强烈推荐无 key 时速率为 3 次/秒携带 key 可提升到 10 次/秒通过api_keyYOUR_KEY传参所有请求都应附带toolyour_app_nameemailyouremail.com这是 NCBI 要求的使用者标识便于官方识别调用方身份。在 SKILL.md 中这一认证约定被映射为环境变量NCBI_API_KEY技能会先检查环境变量若工作目录存在.env文件只读取表格中列出的四个变量NCBI_API_KEY、CORE_API_KEY、S2_API_KEY、OPENALEX_API_KEY绝不把整个.env载入上下文以避免无关密钥泄露。安全红线E-utilities 通过查询字符串认证因此你实际请求的 URL 本身就携带凭证。仓库脚本在输出溯源信息时会主动脱敏——见 scripts/_common.py 中定义的REDACTED_PARAMS frozenset({api_key, apikey, key, email, mailto, tool})任何手工记录的 URL 也应执行同样的脱敏处理只保留参数名、替换参数值。三、eSearch检索并获取 PMIDeSearch 负责把检索词转换成 PMID 列表是整个流程的入口。GET /esearch.fcgi?dbpubmedterm{query}retmodejson参数表参数必填默认值说明db是--固定为pubmedterm是--检索式支持 PubMed 语法字段标签[AU]、[TI]、[TA]、[MH]MeSH布尔 AND/OR/NOTretmax否20返回的 PMID 最大条数上限 10,000retstart否0分页偏移量retmode否xmljson或xmlrettype否uilistuilist返回 ID 列表或count只返回总数sort否relevancerelevance、pub_date、Author、JournalNamedatetype否--pdat出版日期、mdat修改日期、edatEntrez 入库日期mindate/maxdate否--日期范围格式YYYY/MM/DDreldate否--最近 N 天内的记录usehistory否--设为y可把结果存到 History Server适合大规模结果集示例请求https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?dbpubmedtermCRISPRgenetherapyretmodejsonretmax5sortpub_date响应结构{ esearchresult: { count: 224107, retmax: 5, retstart: 0, idlist: [39984857, 39984678, 39984543, 39984210, 39983901] } }与仓库脚本的衔接count与分页对账注意响应中的count字段——它是这条检索式命中的总记录数。当需要穷举式检索如某作者的全部论文时SKILL.md 要求在调用前先读取count再确定性分页并把实际取回的条数与总数对账。这一逻辑在仓库中由 scripts/paginate.py 统一实现walk()记录reconciliation.expectedAPI 报告的总数与reconciliation.retrieved实际取回数若分页走完仍不足总数则以退出码4明确报警——记录丢失与调用方主动设置上限在 scripts/_common.py 的Reconciliation类中被区分为三种状态complete、stopped_at_limit、shortfall绝不允许把不完整的检索结果伪装成完整结论。四、eSummary获取文档摘要元数据拿到 PMID 后eSummary 可批量返回每篇文献的结构化摘要信息适合快速浏览命中结果的题录概览。GET /esummary.fcgi?dbpubmedid{pmids}retmodejson参数表参数必填说明db是固定为pubmedid是逗号分隔的 PMID 列表单次最多 10,000 个retmode否json或xml示例请求https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?dbpubmedid39984857,39984678retmodejson响应字段说明uidPMID、pubdate出版日期、source期刊缩写、authors作者列表、title标题、volume/issue/pages卷期页、fulljournalname期刊全名、elocationidDOI、articleidsPMC、DOI 等各体系标识符、pubtype出版类型、pmcrefcountPMC 被引次数。实战要点为什么eSearch eSummary是标准组合SKILL.md 的输出格式示例中标准溯源记录写作PubMed (esearchesummary)——这正是在 paper-lookup 中最常见的 PubMed 检索流水线先用 eSearch 按主题拿到 PMID 候选集再用 eSummary 一次批量取回题录元数据避免对每条 PMID 单独发请求浪费速率配额。两者结合把两次调用变成一次主题 → 结构化文献列表的完整检索。五、eFetch获取完整记录摘要与 MEDLINEeFetch 是四个端点中返回内容最完整的一个可获取含摘要的完整题录或 MEDLINE 格式记录。GET /efetch.fcgi?dbpubmedid{pmids}rettype{type}retmode{mode}rettype × retmode 组合rettyperetmode返回内容省略xmlPubMed 完整 XML题录 摘要medlinetextMEDLINE 格式abstracttext纯文本摘要uilisttextPMID 列表示例以 XML 获取摘要https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?dbpubmedid39984857retmodexml返回的 XML 包含PubmedArticle节点内部由两部分构成MedlineCitation标题、摘要、MeSH 主题词、作者与PubmedData各体系文章 ID、出版历史。重要边界eFetch 只属于 PubMed 题录不是全文通道在 paper-lookup 技能的语境下必须强调PubMed 的 eFetch 拿到的完整记录是完整题录 摘要而不是全文。真正获取全文要走dbpmcPMC eFetch 返回 JATS XML而 PMC eFetch 存在一个本技能反复强调的200 陷阱当出版商不允许 XML 再分发时它会返回格式良好但没有body的 XML失败信息藏在 XML 注释里——详见 PMC 参考文档。这正是仓库提供 scripts/jats_to_text.py 的原因该脚本检测到无body时以退出码2明确报错并输出full_text_available: false同时把被解析器丢弃的出版商限制注释重新呈现给调用方jats_to_text.py 起杜绝把题录当全文汇报的错误。对应的测试用例见 tests/paper-lookup/test_scripts.py其中jats_no_body.xmlfixture 专门复现这一静默失败场景。六、eLink发现相关文献eLink 用于查找与给定文献相关被共同引用/共同关键词等维度的文献是构建引文关联与推荐的基础能力。GET /elink.fcgi?dbfrompubmeddbpubmedid{pmid}cmdneighbor_scoreretmodejson返回相关 PMID 及关联度分数。当用户问有没有类似这篇的文献或需要从一个起点扩展综述范围时eLink 是最直接的答案来源。七、PubMed 检索语法速查掌握检索式语法能显著提升命中精度避免宽泛关键词淹没相关文献。字段标签aspirin[TI]标题、Smith J[AU]作者、Nature[TA]期刊、neoplasms[MH]MeSH 主题词布尔运算CRISPR AND (therapy OR treatment)日期范围2020/01/01:2024/12/31[PDAT]出版类型review[PT]综述、clinical trial[PT]临床试验物种限定humans[MH]、mice[MH]。与 eSearch 参数的配合语法中的字段标签与 eSearch 的datetype/mindate/maxdate/reldate参数互为补充日期既可以通过检索式写成2020/01/01:2024/12/31[PDAT]也可以拆成datetypepdatmindate2020/01/01maxdate2024/12/31参数形式。实践中按可读性与复用性选择其一即可。八、速率限制与合规调用NCBI 对 E-utilities 有明确的速率与使用规范无 API key3 次请求/秒带 API key10 次请求/秒每次请求都必须携带tool和email参数大批量作业应避开高峰时段美东时间周一至周五 5:00–21:00。在 SKILL.md 的Making API Calls章节中这一约束被落实为工程纪律串行化调用限速 APINCBIPubMed、PMC无 key 3 req/s、有 key 10 req/sarXiv 更是严格到 1 请求/3 秒只对不同的开放 API 并行化OpenAlex、Crossref、Semantic Scholar、Europe PMC、Unpaywall 可并发但绝不针对同一个限速主机做并行限制总工作量先看 count 或首页超过约 1,000 条记录或 50 次调用前必须与用户确认方案——paginate.py的默认值DEFAULT_MAX_RECORDS 1000、DEFAULT_MAX_CALLS 50见 scripts/paginate.py正是这两个约束的落地遇到 HTTP 429/503 短暂等待后重试一次仍失败则如实报告并提示用户申请 key。九、错误格式与失败识别E-utilities 的错误响应采用如下 JSON 格式{error: API rate limit exceeded, count: 11}状态码语义HTTP 400表示请求格式错误HTTP 429表示触发速率限制。本技能的第一原则200 不等于成功SKILL.md 反复强调These APIs fail with HTTP 200.这些 API 会用 HTTP 200 返回失败。对 PubMed 而言虽然基础错误400/429是标准状态码但当 eFetch 切换到dbpmc时无全文的文章会以 HTTP 200 无body的 XML 返回——失败完全伪装成成功。因此本技能的调试清单是确认是否真的失败检查 JATS 是否有body、arXiv 是否返回Error条目、Europe PMC 的 body 是否带errCode、bioRxiv 是否返回status: no articles found检查标识符格式参考 SKILL.md 的标识符对照表——PMID 是纯整数arXiv ID 是YYMM.NNNNNPMCID 是PMC 数字DOI 是10.xxxx/xxxxx用错体系是查不到最常见的根因转换标识符或换库重试DOI 失败可转 PMID/PMCID用 PMC ID ConverterPubMed 查不到 CS 论文就换 Semantic Scholar 或 OpenAlex如实报告失败告诉用户哪个库失败了、错误是什么、尝试了什么替代方案——报告出来的缺口是有价值的沉默的缺口是误导。十、标识符体系与跨库互转不同数据库使用不同的标识符体系SKILL.md 给出了完整的对照表其中与 PubMed 直接相关的是标识符格式示例使用方DOI10.xxxx/xxxxx10.1038/nature12373所有数据库PMID纯整数34567890PubMed、PMC、Europe PMC、Semantic ScholarPMCIDPMC 数字PMC7029759PMC、Europe PMCORCID0000-XXXX-XXXX-XXXX0000-0001-6187-6610OpenAlex、CrossrefISSNXXXX-XXXX0028-0836Crossref、OpenAlex跨库检索时Semantic Scholar 通过前缀接收多种 IDDOI:...、PMID:34567890、ARXIV:...OpenAlex 接收doi:与pmid:前缀。PMID → PMCID → DOI 的转换由 PMC ID Converter 完成当某库对当前标识符返回空结果时转换后再试通常比重写检索式更快。完整的转换 API 用法见 PMC 参考文档 的 ID Converter 一节支持ids、idtype、format参数返回pmcid/pmid/doi三字段映射且只对已收录于 PMC 的文章返回 PMCID。十一、全文与摘要的边界PubMed、PMC、Europe PMC 的分工这是 paper-lookup 技能中最容易出错、也是本参考文档最想传达的一点。三者分工如下库内容何时选用PubMed3700 万 条题录、摘要、MeSH 元数据无全文主题检索、定位文献、确认题录PMC1000 万 篇生物医学全文JATS XML、BioC API、ID 转换、OA 可用性服务获取全文但仅 OA 子集约 300 万篇可通过 eFetch 直接取到 XMLEurope PMC单索引覆盖 PubMed PMC 预印本支持全文关键词检索fullTextXML对非 OA 文章返回干净的404全文内检索、预印本关键词检索、需要诚实的失败时实践中推荐的最优路径是用 PubMed 找到 PMID → 用 PMC OA Web Service 预检全文是否可用 → 用 eFetchdbpmc或 Europe PMCfullTextXML取全文 → 用 Unpaywall 找开放获取副本。若全文不可用就明确返回摘要并说明在哪里可能找到 OA 副本绝不把front元数据当成全文呈现给用户。十二、输出与溯源规范让每次检索都可复现paper-lookup 技能对检索结果有一套强制性的输出格式见 SKILL.md 的 Output Format 章节PubMed 查询的结果应按此结构返回## Retrieval Summary - Query: 用户的实际问题 - Scope: targeted lookup | exhaustive retrieval - Databases queried: PubMed (esearchesummary), Unpaywall (DOI lookup) - Access date: 日期 ## Results ### PubMed 文献列表标题、作者、年份、期刊、DOI/PMID ## Provenance - Endpoints parameters: 足以复现调用的完整参数 - Identifier conversions: 如有 ID 转换 - Count reconciliation: 预期 vs 实际取回、分页数穷举检索必填 - Warnings: 空结果、分页不完整、仅有元数据无全文、缺少 key、端点过时要点包括默认输出用户关心的可读字段摘要而非原始 JSON 堆砌对大数据量全文PMC/Europe PMC/CORE保存到本地文件并报告路径绝不把元数据冒充全文每条结果的溯源信息要足够让人类或其他 Agent 原样重放这次调用。paginate.py在输出中通过redact_url()scripts/_common.py保证溯源 URL 里不残留任何密钥或个人邮箱。十三、仓库资源导航若要深入本主题建议按以下路径阅读当前仓库PubMed 参考文档本文的核心依据包含全部端点参数与响应细节SKILL.md11 库的统一工作流、选择指南、错误恢复与输出规范PMC 参考文档全文获取、ID Converter、BioC API 与无 body 的 200陷阱详解Europe PMC 参考文档跨语料全文检索、预印本关键词检索、fullTextXML诚实 404scripts/paginate.py分页、限速与计数对账的统一实现PubMed 场景下建议配合retmax/count理解其设计scripts/jats_to_text.pyJATS 全文解析与元数据冒充全文防线scripts/_common.py输入边界MAX_INPUT_BYTES、文本清洗collapse_ws、URL 脱敏redact_url与计数对账Reconciliation的公共底座tests/paper-lookup/test_scripts.py离线测试fixtures 全部来自 2026-07-27 真实响应覆盖无body、非 JATS、OpenAlex 倒排摘要等静默失败场景。结语把查文献变成可复现的工程PubMed E-utilities 的四个端点构成了生物医学文献检索的最小完备集——eSearch 定位找什么、eSummary 概览是什么、eFetch 取录读摘要、eLink 扩展还看什么。在 scientific-agent-skills 的 paper-lookup 技能中这套 API 被进一步封装为带有速率纪律、计数对账、URL 脱敏、结构化溯源与失败必须可见原则的检索流程。无论你是要为一个 Agent 技能编写检索逻辑还是要构建自己的文献查询管线遵循选对库 → 读参考文档 → 有界调用 → 核对响应形状 → 输出可审计结果这一工作流都能让每一次检索既快又可信。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考