pubmed

name	pubmed
related_skills	["knowledge-acquisition"]
description	Deep PubMed/MEDLINE search via NCBI E-utilities — query construction, MeSH terms, batch retrieval, clinical query refinement.
version	1.0.0
license	MIT
author	Synthos
metadata	{"synthos":{"version":"2.0.1","author":"Synthos","signature":"query: str -> papers: list[dict]"}}

PubMed Search

快速参考

⚠️ Hermes cron 环境安全扫描拦截（v91 — 2026-06-08）：curl | python3 管道被 tirith:curl_pipe_shell 安全扫描拦截。在 cron/Hermes 环境中，必须使用 urllib.request stdlib（写入脚本文件后执行），不得使用 curl。

操作	安全命令（Hermes cron 环境）
搜索	写入脚本文件后执行（见 scripts/pubmed-urllib.py），不可使用 `curl
详情	写入脚本文件，用 urllib.request 读取 XML
摘要	写入脚本文件，用 urllib.request 读取 text
引用数	写入脚本文件，用 urllib.request 读取 JSON
PMC全文	写入脚本文件，用 urllib.request 读取 XML

正确做法：将查询写入 .py 脚本文件，用 terminal 执行。详见 scripts/pubmed-urllib.py。

⚠️ Python 3.12 urllib 裸空格拒绝（v106 — 2026-06-08）：urllib.request.urlopen() 拒绝 URL 路径中包含裸空格的请求，报 InvalidURL: URL can't contain control characters。所有 PubMed 查询必须使用 quote_plus(term, safe='') 编码。已在 scripts/pubmed-urllib.py 中修复，参见 references/python312-url-quirk.md。

⚠️ E-utilities 日期范围格式陷阱（v187 — 2026-06-22）：使用 .. 分隔符（如 2024/01/01..2026/06/08）进行日期过滤会静默返回0结果——PubMed API 不接受 .. 格式，必须使用 : 分隔符（如 2025/01/01:2026/06/22）。已在 scripts/pubmed-urllib.py 中自动转换，参见 references/pubmed-date-format-quirk.md。

搜索语法

字段	示例
MeSH	"vestibular diseases"[MeSH Terms]
标题	vestibular[Title]
摘要	vestibular[Abstract]
作者	"Smith J"[Author]
DOI	"10.1016/..."[DOI]
日期	"2020/01/01"[Date - Publication] : "2024/12/31"[Date - Publication]
文献类型	review[PT], randomized controlled trial[PT]
临床查询	"query"[filter] (therapy/diagnosis/prognosis/etiology)

逻辑运算符

• AND / OR / NOT
• 精确短语: "vestibular rehabilitation"
• 通配: vestibul* (匹配 vestibular, vestibule等)
• 邻近: saccade NEAR3 visual

速率限制

• 免费: 3 req/s (无API key)
• 有API key: 10 req/s (加 &tool=hermes-agent&email=[e-mail])
• 最大单次: 10,000结果, 200 PMIDs/efetch

参考文件

• references/mesh-terms.md — 眼动/前庭MeSH术语列表
• references/clinical-queries.md — 临床查询过滤器详解
• references/batch-retrieval.md — 批量检索和XML解析
• references/efetch-response-quirks.md — efetch 可能返回 text/plain 或 HTML（非JSON/XML）；esummary key 是 PMID 不在 pubmed 下；idlist 键名小写
• references/python312-url-quirk.md — Python 3.12 urllib.request 拒绝裸空格URL路径的修复（quote_plus编码，v106）
• references/pubmed-date-format-quirk.md — E-utilities 日期范围格式陷阱：.. 分隔符静默返回0结果，必须使用 : 分隔符

脚本

|- scripts/pubmed-urllib.py — 可复用PubMed查询脚本（urllib stdlib，无curl，安全Hermes cron环境，已修复Python 3.12 quote_plus编码）

• 用法：python3 pubmed-urllib.py "term" → count+PMIDs
• python3 pubmed-urllib.py "term" "2024/01/01:2026/06/08" → 日期过滤（使用 : 分隔符，勿用 ..）
• python3 pubmed-urllib.py --abstract "PMID1,PMID2" → 摘要提取

IO_CONTRACT

• input: search_query: str, max_results: int — 任务描述、参数配置
• output: papers: list[Paper] (pmid, title, authors, abstract, journal) — 执行结果

对应原则：P2（机械原子暴露输入输出规范）

• total_count: int — 符合查询条件的论文总数
• query_used: str — 实际执行的搜索查询

副作用:

• 调用NCBI E-utilities API（需网络访问）
• 遵守速率限制：免费3 req/s，有key 10 req/s
• 所有请求必须通过 urllib.request（cron安全，非curl管道）