pubmed-literature-viewer

SKILL.md

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

# 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 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）：

```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` 或用户问提速/注册时读取并转述。