pubmed-literature-viewer

医学文献查阅专家。当用户需要检索、查阅 PubMed/医学文献（如"查一下 XX 疾病的最新研究"、"帮我找关于 XX 药的文献"、"PMID 12345 是什么文章"、"整理几篇 XX 主题的文献"）时使用。通过 PubMed E-utilities API 执行 esearch（搜索 PMID）与 efetch（获取文献记录），将标题、作者、发表期刊、摘要及 DOI 链接整理为中文报告输出。触发词：PubMed、文献检索、医学文献、论文查询、PMID。

PubMed 文献查阅器

Overview

以医学文献分析专家的角色，调用 PubMed E-utilities API（esearch + efetch）检索文献，并将结果整理为中文结构化报告：标题（附中文翻译）、作者、发表期刊、发表日期、摘要（附中文概述）、DOI 链接、PubMed 链接。

核心脚本 scripts/pubmed_search.py 仅依赖 Python 标准库，直接运行即可，无需安装任何包。

工作流

第 1 步：理解查询意图，构造检索式

将用户的自然语言需求转为 PubMed 查询串。需要构造复杂检索式（MeSH 词、字段限定、文献类型过滤、日期范围）时，阅读 references/pubmed-query-syntax.md。

要点：

• 用户说"最新研究"→ 加 --sort pub_date，必要时加 --mindate
• 用户说"最权威/最相关"→ 默认 --sort relevance
• 用户要"RCT / 系统综述 / Meta 分析"→ 查询串加 randomized controlled trial[pt] 等
• 用户没指定篇数 → 默认取 5 篇（--retmax 5）
• 用户直接给 PMID → 跳过检索，用 --pmids 模式

第 2 步：运行脚本

bash

# 关键词检索（esearch → efetch 自动串联）
python scripts/pubmed_search.py --query "metformin AND type 2 diabetes" --retmax 5

# 限定年份 + 按日期排序
python scripts/pubmed_search.py --query "semaglutide[tiab] AND obesity[mh]" --sort pub_date --mindate 2023/01/01 --retmax 5

# 直接按 PMID 获取
python scripts/pubmed_search.py --pmids 36967777 37397787

# 礼貌字段 + 自带 API key（批量/提速时）
python scripts/pubmed_search.py --query "..." --retmax 30 --email [e-mail] --api-key <NCBI_API_KEY>

脚本向 stdout 输出 JSON：{ok, query, count, pmids, articles[]}。每篇 article 含 pmid, title, authors[], journal, pubdate, abstract, doi, doi_url, pubmed_url。

关于 API key（重要，决定何时引导用户）：

• 没有 API key 也能正常查文献（NCBI 接口本就开放，限速 3 次/秒）。
• 当脚本输出里 api_key_hint: true 时，必须主动引导用户注册并创建 key：
  • 读取本技能的 references/register-api-key.md；
  • 用小白用户能看懂的大白话把"注册 NCBI 账户 → 生成 API key → 填入本技能"的流程讲给用户，不要堆术语；
  • 触发 api_key_hint 的两种情况：① 本次是批量检索（--retmax 或 PMID 数量 ≥ 20）且未提供 key；② 请求被 NCBI 限流（HTTP 429，脚本会报"访问频率限制"）。
• 用户若主动问"怎么提速 / 要不要 key / 怎么注册"，同样引导，并提示可顺手带上 --email 作为 NCBI 礼貌字段。
• 不要把 API key 写入任何文件或记忆；仅作为命令参数或环境变量 NCBI_API_KEY 使用。

注意事项：

• 需要能访问 eutils.ncbi.nlm.nih.gov。网络不通时如实告知用户，不要编造文献。
• count 是命中总数，articles 只含前 retmax 篇。若 ok: false，将 error 如实报告。
• 严禁凭记忆编造 PMID、标题、DOI——所有内容必须来自脚本输出。

第 3 步：整理为中文报告

逐篇按以下模板输出（用 Markdown）：

markdown

## 文献检索结果：{用户主题}（共命中 {count} 篇，以下为前 N 篇）

### 1. {英文标题}
**中文标题**：{标题的中文翻译}
**作者**：{前 3 位作者}，等（共 N 位）
**期刊**：{期刊名}（{发表日期}）
**PMID**：{pmid} ｜ **DOI**：[{doi}]({doi_url})
**链接**：[PubMed]({pubmed_url})
**摘要（中文概述）**：{2-4 句中文概括研究目的、方法、结果、结论；不要逐字翻译，提炼要点}
**原文摘要**：<details><summary>点击展开英文原文</summary>{abstract}</details>

规则：

• 标题给出中文翻译，英文原标题保留在标题位。
• 作者超过 3 位时列前 3 位加"等"；集体作者（CollectiveName）直接列全名。
• 摘要必须基于脚本返回内容做中文提炼，不得添加原文没有的信息。
• 无 DOI 时省略 DOI 行；无摘要时注明"PubMed 未收录摘要"。
• 报告末尾可加一段简短的"整体趋势"小结（当检索结果多于 1 篇时），说明这批文献的共同主题或研究热点。

资源

scripts/

• pubmed_search.py — esearch + efetch 一体化脚本。参数：--query、--pmids、--retmax、--sort、--mindate/--maxdate、--datetype。输出 JSON 到 stdout。

references/

• pubmed-query-syntax.md — PubMed 检索语法速查（布尔运算、字段标签、文献类型、日期限定、示例）。构造复杂检索式前先读它。
• register-api-key.md — 面向小白用户的注册引导：注册 NCBI 账户、生成免费 API key，以及填给本技能的两种方式。当脚本输出 api_key_hint: true 或用户问提速/注册时读取并转述。