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 步：运行脚本
# 关键词检索（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 you@example.com --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）：
## 文献检索结果：{用户主题}（共命中 {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或用户问提速/注册时读取并转述。
