pubmed-stream

pubmed-stream：面向研究人员及其 AI 助手的 PubMed 文献检索

从 PubMed 检索到文献知识图谱。 pubmed-stream 可从 PubMed Central 下载全文文章，梳理关键论文周边的证据，并将研究收集的所有内容关联到 Obsidian 知识图谱中，让论文通过引用、相似性和 MeSH 主题彼此关联。它基于 NCBI 官方 E-utilities 构建，可通过命令行或 Python 使用，除 requests 外无需其他依赖。AI 助手也可以使用它：它是 Claude Code 和 Codex 的插件，也是它们及 Gemini CLI 的 MCP 服务。你可以用通俗的英语提出研究问题，并获得只引用助手已下载并阅读过的论文的答案。

文档：melhzy.github.io/pubmed-stream，教程、指南和参考文档都汇集在一个可搜索的网站中，每个笔记本均展示其运行结果。

使用它完成的一项研究：Aβ*56 撤稿影响页面，展示一篇被撤稿的阿尔茨海默病论文如何在文献中传播，以及语言模型学到了其中多少内容。这是一个交互式页面，其中每个数字都来自研究文件；参见研究。

刚开始编程？ 从教程 0开始，只需一个下午，就能把一个研究问题转化为相关文献图谱。点击在 Colab 中打开，即可在浏览器中运行，无需安装任何内容；你只需在一个设置单元格中输入问题。

flowchart LR
    S["PubMed searches"] -->|"download"| D["Full-text articles<br/>metadata, references, text"]
    K["Key papers"] -->|"neighborhood"| N["Similar, citing and cited papers<br/>flagged reviews, retractions, NIH funding"]
    D --> G["Knowledge graph<br/>kg_topic, an Obsidian vault"]
    N --> G
    G --> O["Explore, write, refresh"]

目录

• 快速开始
• 教程
• 研究
• 安装与配置
• 1. 下载全文文章
• 2. 编写检索式，找到合适的论文
• 3. 梳理一篇论文周边的证据
• 4. 构建研究的知识图谱
• 5. 与 AI 助手（MCP 和插件）、本地模型及 Obsidian 搭配使用
• Python API
• 故障排除
• 工作原理
• 贡献
• 常见问题
• 引用、致谢与许可证

快速开始

pip install pubmed-stream

# Size a search and preview its newest titles, without downloading: it counts PMC and all of PubMed
pubmed-stream search '"gut microbiota"[Title] AND frailty[Title/Abstract]'

# Download the full text of up to 50 articles, add the abstracts of those whose full text is not
# free, then read them compactly
pubmed-stream download '"gut microbiota"[Title] AND frailty[Title/Abstract]' --max-results 50
pubmed-stream abstracts '"gut microbiota"[Title] AND frailty[Title/Abstract]' --max-results 200
pubmed-stream list publications --abstracts

# Export them as citations for Zotero, EndNote or Mendeley
pubmed-stream export publications -o frailty.bib

# Map the evidence around one paper: similar, citing and cited papers, with retractions flagged
pubmed-stream neighborhood 31319564

# Build a study's knowledge graph in ./kg_gut_microbiome_frailty, then open it in Obsidian
pubmed-stream kg "gut microbiome frailty" -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' --seed 31319564
pubmed-stream open kg_gut_microbiome_frailty

# Summarize the 10 newest abstracts and save the summaries in the knowledge graph. --model picks who
# summarizes: a model on your own computer, in Ollama (https://ollama.com), so nothing leaves it, or the
# model of an AI assistant installed below: claude, codex or gemini. Section 5 helps you choose
ollama pull qwen3.5:4b
pubmed-stream review "Is the gut microbiota linked to frailty?" --limit 10 --model qwen3.5:4b --vault kg_gut_microbiome_frailty
pubmed-stream review "Is the gut microbiota linked to frailty?" --limit 10 --model claude --vault kg_gut_microbiome_frailty

# Or ask in plain English and let Claude Code, Codex or Gemini CLI run all of this: see below

使用 AI 助手：Claude Code、Codex 或 Gemini CLI

AI 助手可以为你完成上述所有操作。安装一个吧：Claude Code 需要付费的 Claude 方案，Codex 需要付费的 ChatGPT 方案，而 Gemini CLI 只需要 Google 账号。这些命令需要 Node.js 22 或更高版本；教程 7介绍了其他安装程序，并带你了解一次使用过程。

npm install -g @anthropic-ai/claude-code   # Claude Code
npm install -g @openai/codex               # Codex
npm install -g @google/gemini-cli          # Gemini CLI

然后通过以下两种方式之一，为你的助手提供 pubmed-stream 的工具：

# Claude Code or Codex: install the plugin once, for every folder. It needs uv (https://docs.astral.sh/uv/)
claude plugin install pubmed-stream --marketplace melhzy/pubmed-stream
codex plugin marketplace add melhzy/pubmed-stream
codex plugin add pubmed-stream@pubmed-stream

# Any of the three: set up one research folder with the MCP server and instructions
mkdir gut_frailty
cd gut_frailty
pubmed-stream init

在你的研究文件夹中，使用 claude、codex 或 gemini 启动助手。首次启动时，系统会提示你登录。使用 init 时，Claude Code 还会询问你是否批准 pubmed-stream 服务，Gemini CLI 则会询问你是否信任该文件夹：两者都选择“是”，否则助手将无法使用 pubmed-stream 的工具。/mcp 会列出这些工具。然后用自然语言提问：

肠道微生物群与衰弱有关联吗？先估算检索结果数量，下载临床研究，并使用 PMID 总结证据。

第 5 节比较了插件和 init。

使用 Python

以下是快速入门中的前几个步骤，使用 Python：

from pubmed_stream import create_kg, get_neighborhood, search_and_download

stats = search_and_download('"gut microbiota"[Title] AND frailty[Title/Abstract]', max_results=50)
hood = get_neighborhood("31319564")
result = create_kg("gut microbiome frailty", queries=['"gut microbiota"[Title] AND frailty[Title/Abstract]'],
                   seeds=["31319564"])
print(stats.successful, hood.totals, result.kg_dir)

教程

tutorials/ 中的笔记本面向研究人员，而非程序员。每个笔记本都围绕一个真实的研究问题展开。笔记本中只有一个供你填写问题的 你的设置 单元格，可在 Google Colab 中运行，无需安装任何内容；运行结果也会保存在笔记本中，因此你可以先在 GitHub 或文档网站上阅读；教程 7 则在终端中使用 AI 助手完成。

#	教程	使用场景
0	从这里开始：一个下午探索新的研究主题	从一个问题到其文献图谱：估算领域规模，找到人人引用的论文，构建知识图谱，了解其中的主题、证据和空白，并导出阅读清单
1	入门	下载搜索结果、读取文件、选择格式、继续下载、获取一篇已知文章、补救未找到结果的搜索，以及精简地读取下载内容
2	设计搜索策略	衡量同一搜索的五个版本在规模、精准度和可获取性方面的差异，并将关键词与 MeSH 主题词结合
3	文献综述语料库	运行关键词列表、去重、按主题筛选，并导出为 CSV 和 BibTeX
4	一篇论文周围的证据	绘制一篇论文的关联图谱，并筛查是否有撤稿论文
5	一项研究的知识图谱	构建图谱，并用 12 张图表和表格加以说明
6	文本挖掘与 RAG 准备	将文章拆分为章节，并分块以生成嵌入
7	使用 AI 助手进行文献检索	面向医学生和生物学家：安装 Claude Code 或 Codex，通过插件或 pubmed-stream init 将其连接到 pubmed-stream 的 MCP 工具，选择模型，用通俗英语提问、核查证据、将内容保存在 Obsidian 中，或通过 Ollama 使用本地模型
8	衡量一篇撤稿论文的影响	追踪 2006 年 Nature 上关于 Aβ*56 的撤稿论文，以及引用它的论文和引用这些论文的论文：它们何时以及如何引用该论文、撤稿后仍有哪些人引用它，以及描绘其影响的知识图谱

以下五篇简短指南为这些教程提供辅助：

指南	适用内容
如何运行教程	Colab、在 Windows 或 Mac 上安装 Python、运行笔记本、免费的 NCBI API 密钥
在 Obsidian 中阅读知识图谱	打开、探索、搜索图谱并在其中写作
术语表	用通俗语言解释 MeSH、PMC、stub、seed 及其他所有术语
pubmed-stream 能做什么，不能做什么	覆盖范围、盲点，以及它为何不属于系统综述
初学者故障排除指南	设置、笔记本、Colab 和 Obsidian 问题

tutorials README 列出了所有内容，包括程序员如何在本地运行笔记本。

研究

使用 pubmed-stream 开展的研究位于 studies/，每项研究各有一个文件夹，包含冻结的数据、脚本和研究报告；如果研究有网页，则会与文档站点一同发布。

研究	页面	问题
Aβ*56 撤稿影响	打开页面	延续教程 8。2006 年被撤稿的 Aβ*56 Nature 论文在文献中的传播范围有多广：引用该论文的 1,240 篇论文，以及引用这些论文的 44,957 篇论文，均以表格形式冻结保存；对论文所声称内容及其具体错误的溯源说明；两个开放语言模型训练语料库中该论断及其更正的计数；以及向语言模型提出的探查问题和首批回答

研究 README 介绍了研究文件夹的布局以及如何开始一项研究。

安装和配置

pip install pubmed-stream                  # the library and the pubmed-stream command
pip install "pubmed-stream[tutorials]"     # plus jupyter, matplotlib, networkx and pandas for the tutorials

第 5 节中的 AI 助手、本地模型和 Obsidian 功能需要 0.3.0 或更高版本；PubMed 摘要和引用导出需要 0.4.0；通过 Claude Code、Codex 或 Gemini CLI 进行审查（review --model claude）需要 0.4.1；教程 8 导入的 Claude Code 和 Codex 插件 pubmed_stream.impact，以及使用 init 保存 NCBI API 密钥，需要 0.4.2；MCP 服务的进度报告及其在 Windows 上隐藏控制台窗口的功能需要 0.4.3：运行 pubmed-stream --version 可查看当前版本，运行 pip install --upgrade pubmed-stream 可更新。从克隆的仓库安装时，pip install -e ".[dev]" 会以可编辑模式安装，并包含 pytest 和 ruff。pubmed-stream 需要 Python 3.9 或更高版本；它唯一的运行时依赖是 requests。

设置 NCBI API 密钥。 NCBI 不使用密钥时允许每秒发送 3 个请求，使用密钥时允许每秒发送 10 个，因此密钥能让所有操作快约 3 倍。密钥免费：在 NCBI 账户的设置中找到 API Key Management 并创建密钥。每个文件夹只需保存一次：

pubmed-stream init --ncbi-api-key "your-key"   # kept in ~/.pubmed-stream.json; init also asks for it while none is saved

init 会在保存密钥前通过 NCBI 验证密钥；如果 NCBI 后续拒绝已保存的密钥，pubmed-stream 会告知你并在不使用密钥的情况下继续，而不是让每个请求都失败。未设置密钥时，如果使用密钥本可以缩短 10 秒或更久的下载，结束时会显示使用密钥可节省的时间。

安装 pubmed-stream 插件时，Claude Code 会提示你输入密钥。对于脚本和服务端，也可以通过环境变量设置密钥，并可选提供联系邮箱；环境变量的优先级更高：

export NCBI_API_KEY="your-key"        # PowerShell: $env:NCBI_API_KEY = "your-key"
export NCBI_EMAIL="[email protected]"   # PowerShell: $env:NCBI_EMAIL = "[email protected]"

每条命令也都接受 --api-key 和 --email。pubmed-stream 会根据密钥自动设置请求速率；请求失败时会采用退避策略重试 3 次，并且绝不会将密钥写入日志。必要时可使用 --rate-limit SECONDS 进一步降低速率。

1. 下载全文文章

pubmed-stream download 直接搜索 PubMed Central，因此每条结果都是有 PMC 记录的文章，然后并行获取每篇文章的全文 XML，并将其保存为一个 JSON 文件。部分出版商不允许以 XML 格式下载其文章；这类文章会标记为 unavailable 并跳过，而不会保存不完整的文件。

pubmed-stream download "gut microbiome" --max-results 50

from pubmed_stream import search_and_download

stats = search_and_download("gut microbiome", max_results=50)
print(f"{stats.successful} saved, {stats.skipped} already there, {stats.unavailable} unavailable "
      f"of {stats.total_found} matches, in {stats.duration_seconds:.0f} s")

每次搜索都会有自己的文件夹，文件夹以查询命名；如果名称超过 100 个字符，就会缩短，并以查询的短哈希值结尾。再次运行搜索时，会跳过已存在的文件，因此中断的下载可以继续，而重复搜索只会获取新内容。

若想查看已下载的内容，而不必逐个打开文件，list 会按时间倒序为每篇文章打印一行；无论有多少次搜索找到它，都只显示一次：

pubmed-stream list publications                       # identifiers, year, title, journal, length
pubmed-stream list publications --id 31319564 --abstracts   # the abstracts of chosen articles
pubmed-stream list publications --cited               # the works the downloads cite most
pubmed-stream list publications --json --abstracts > corpus.jsonl

没有免费全文的文章。 PMC 仅保存部分文献的免费全文：search 会同时统计两者；快速入门中的衰弱搜索在 PubMed 中有 95 篇文章，而 PMC 中有 66 篇。abstracts 会将每条匹配结果的 PubMed 记录及其摘要、MeSH 术语和出版物类型保存到与全文相同的文件夹中。list、review 和知识图谱都会读取这两类内容；list 会为仅有摘要的文章标记 [abstract only]，而同时以两种方式保存的文章会显示全文。

pubmed-stream abstracts '"gut microbiota"[Title] AND frailty[Title/Abstract]' --max-results 200
pubmed-stream kg "gut microbiome frailty" -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' --abstracts

from pubmed_stream import fetch_abstracts

stats = fetch_abstracts('"gut microbiota"[Title] AND frailty[Title/Abstract]', max_results=200)
print(f"{stats.saved} abstracts saved of {stats.total_found} in PubMed; {stats.in_pmc} are also free in PMC")

引文。 export 会将文章、全文和摘要一并导出为 BibTeX 或 RIS 格式，Zotero（File > Import）、EndNote、Mendeley 和 LaTeX 均可读取。条目包含标题、作者、期刊、年份、DOI、PubMed 和 PMC ID、链接及摘要。每位作者姓名的第一个词会被视为姓氏，因此导入后请检查 “van der Berg” 之类的多词姓氏。

pubmed-stream export publications -o review.bib
pubmed-stream export publications --format ris --id 38686220 41113141 -o chosen.ris

publications/
└── gut_microbiome/
    ├── query.json          the original search, recorded for later tools
    ├── PMC12345678.json    a full text from PMC
    ├── PMC12345679.json
    └── PMID41361501.json   an abstract from PubMed, saved by 'abstracts'

每个文章文件的结构都相同。metadata.references 会列出具有 PubMed ID 或 DOI 的被引文献；这些文献会成为知识图谱中的引文链接。

{
  "pmcid": "PMC13279599",
  "source": "PMC",
  "download_date": "2026-10-18T13:20:45",
  "metadata": {
    "pmid": "42060019",
    "pmcid": "PMC13279599",
    "doi": "10.1007/s40520-026-03403-6",
    "title": "Association between gut microbiota and sarcopenia in older adults: ...",
    "journal": "Aging Clinical and Experimental Research",
    "year": "2026", "month": "4", "day": "30",
    "authors": ["Ramezani Kashal Fatemeh", "Sharifi Farshad", "..."],
    "abstract": "Introduction Investigating gut microbiota has emerged as a novel approach ...",
    "keywords": ["Sarcopenia", "Gut microbiota", "Aging", "Muscle metabolism"],
    "references": [
      {"pmid": "32033882", "doi": "10.1016/j.jamda.2019.12.012",
       "title": "Asian Working Group for Sarcopenia: 2019 Consensus Update ...", "year": "2020"}
    ],
    "linked_discoveries_url": "https://linkeddiscoveries.ncbi.nlm.nih.gov/42060019/"
  },
  "text": "Association between gut microbiota and sarcopenia ...\nAbstract\nIntroduction ..."
}

格式决定了元数据旁边保留哪些内容：

--format	添加内容	适用场景
text（默认）	text：标题、摘要和正文，每行一个段落	阅读、搜索、嵌入、大多数 NLP
xml	xml：原始 JATS XML	章节级解析、表格、图
both	text 和 xml	保留所有选择

选项	含义	默认值
QUERY	PubMed 搜索；支持 [Title] 等字段标签	必填
--max-results N	要下载的文章数，按时间倒序	100
--format	text、xml 或 both	text
--exclude-text	不包含 text 字段以节省空间	包含
--output-dir、-o	基础文件夹	./publications
--workers N、--sequential	并行下载；网络不稳定时可改为逐个下载	5 个工作线程
--topic、--vault	也将结果添加到知识图谱，参见第 4 节	关闭
--api-key、--email、--rate-limit、--user-agent、-v	NCBI 设置和详细日志	环境变量
--quiet	仅打印摘要，不显示进度	显示进度

如果文章已保存或已存在，download 会以 0 退出；如果搜索未找到结果，则以 1 退出；如果所有下载均失败，则以 2 退出。

2. 编写能找到合适论文的搜索式

PMC 会搜索每篇文章的全文，包括参考文献列表，因此像 gut microbiome frailty 这样的普通搜索会匹配数千篇仅在文中顺带提及这些词的文章。字段标签可以解决这个问题。在教程 2中，同一个问题的五种搜索式，匹配结果从 7,587 篇（几乎没有相关的近期结果）到 66 篇（大多数都切合主题）不等。

技巧	示例	效果
将核心概念放在标题中	"gut microbiota"[Title]	精确度提升最大
将其余内容限制在标题和摘要中	frailty[Title/Abstract]	排除正文中的顺带提及
将多个单词的术语加上引号，并用 OR 覆盖同义词	("gut microbiome" OR "gut microbiota")	保留完整短语，同时不损失召回率
限定为开放获取	AND "open access"[filter]	每条结果都可以下载
限定年份	AND 2020:2026[pdat]	覆盖较新的结果，或聚焦于这些结果

PMC 会优先返回最新的匹配结果，因此 --max-results 会选取最近发表的文章。下载前请先检查搜索结果：pubmed-stream search QUERY 会显示结果数量和最新标题，且不会下载任何内容；--show 0 则只显示数量。

$ pubmed-stream search '"gut microbiota"[Title] AND sarcopenia[Title/Abstract]' --show 2
80 articles in PMC for: "gut microbiota"[Title] AND sarcopenia[Title/Abstract]
Newest 2:
  2026  PMC13668947  PMID 42875678  Correspondence for the article: "Association between gut microbiota and sarcopenia ...
  2026  PMC13641649  PMID 41879259  Alterations in the Gut Microbiota of Cirrhotic Patients With Sarcopenia and PH After TIPS. ...

3. 绘制论文周边的证据图谱

搜索会根据词语查找论文。证据邻域则从一篇关键论文出发，沿着 PubMed 的链接展开：PubMed 评为相似的论文、引用该论文的论文，以及该论文引用的论文。每篇论文都会标记是否为综述、是否已撤稿或是否获得 NIH 资助。NLM 的 Linked Discoveries 网页工具也会展示类似的邻域，但没有 API；pubmed-stream 则根据有文档说明的 E-utilities 构建邻域。

pubmed-stream neighborhood 9500320

Seed: PMID 9500320 (1998) Ileal-lymphoid-nodular hyperplasia, non-specific colitis, and ...
Similar       100            (4 reviews, 0 retracted, 0 NIH-funded, 18 in PMC)
Cited by      100 of 489     (145 reviews, 0 retracted, 52 NIH-funded, 421 in PMC)
References      0            (0 reviews, 0 retracted, 0 NIH-funded, 0 in PMC)
Neighborhood  200 unique articles fetched
[RETRACTED] PMID 9500320 (1998) Ileal-lymphoid-nodular hyperplasia, non-specific colitis, and ...
Saved: publications/neighborhood_9500320/neighborhood.json
Explore the graph: https://linkeddiscoveries.ncbi.nlm.nih.gov/9500320/

100 of 489 表示有 489 篇 PubMed 文章引用了种子论文，已详细获取最新的 100 篇；--max-per-relation 用于更改此上限。方括号中的计数始终涵盖全部 489 篇，统计方式是搜索 PubMed，而非下载每条记录。[RETRACTED] 会列出已获取文章中的所有撤稿文章，因此在引用或以其为基础开展工作前，请先核查。

标记	含义
review	出版物类型为 Review、Systematic Review 或 Scoping Review；范围比 PubMed 的 Review 筛选器窄，后者也会统计指南和荟萃分析
retracted	出版物类型为 Retracted Publication，或存在关联的撤稿通知
NIH-funded	资助列表中包含 NIH 资助项目，或出版物类型为 N.I.H. research-support
in PMC	该文章有 PMC ID，因此可能可以下载全文

邻域会保存为 publications/neighborhood_<PMID>/neighborhood.json。使用 --download 还会将种子论文和每篇有全文的邻居的 PMC 全文保存到同一目录。在 Python 中：

from pubmed_stream import get_neighborhood, save_neighborhood, download_neighborhood

hood = get_neighborhood("31319564", max_per_relation=50)
print(hood.totals)                      # {"similar": 384, "cited_by": 239, "references": 139}
print(hood.flag_counts["cited_by"])     # reviews, retracted, NIH-funded and in-PMC counts across all of them

retracted = [a for a in hood.articles() if a.is_retracted]          # seed and neighbors
cites_retracted = [a for a in hood.references if a.is_retracted]    # does the paper cite retracted work?

save_neighborhood(hood)                 # publications/neighborhood_31319564/neighborhood.json
download_neighborhood(hood)             # PMC full text of the seed and its neighbors

每个邻居都是一个 RelatedArticle，包含 pmid、title、journal、year、authors、pub_types、is_review、is_retracted、nih_funded、pmcid、doi、mesh_terms，相似文章还包含相似度 score。最多处理 200 篇文章的邻域需要 2 次请求；每种因达到上限而被截断的关系需额外请求 5 次。

与 Linked Discoveries 相比：相似度来自 PubMed 的 Similar Articles 算法，而非 BiomedBERT 模型，因此邻居可能不同；没有疾病、基因或化学物质筛选器；引用链接仅存在于已提交参考文献列表的文章中，这些文章大多来自 PMC。和网页工具一样，这些标记描述的是关联，并不评判研究是否可靠。教程 4 会绘制邻域图，并演示撤稿筛查。

neighborhood 成功时退出代码为 0；PMID 无效或不在 PubMed 中时为 1；无法连接 NCBI 时为 2。它接受 PubMed ID，即 pubmed.ncbi.nlm.nih.gov/<PMID>/ 链接中的编号或下载文章的 metadata.pmid，而非 PMC ID。

4. 构建研究的知识图谱

下载结果和邻域会汇集成知识图谱。一项研究包含一个主题、收集相关文献的搜索，以及可选的关键论文，其邻域也会纳入图谱。pubmed-stream kg 会运行所有搜索，并将结果链接到名为 kg_<topic> 的 Obsidian 库中：该库由 Markdown 笔记组成，每篇论文、MeSH 概念和文献集合各有一篇笔记。在 Obsidian 中选择 Open folder as vault 打开，即可在图谱视图中查看论文之间的引用关系及其共同主题。

pubmed-stream kg "gut microbiome frailty" \
    -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' \
    -q '"gut microbiota"[Title] AND sarcopenia[Title/Abstract]' \
    --seed 31319564 --max-results 25 --max-per-relation 30

该研究生成的图谱包含 127 篇论文，其中 42 篇有全文，85 篇来自种子论文的邻域，并链接到 309 个 MeSH 概念：共 440 篇笔记。系统会记住该研究，因此只需提供主题，图谱就会持续扩充并保持更新：

pubmed-stream kg "gut microbiome frailty" -q "microbiome inflammaging"   # add a search
pubmed-stream kg "gut microbiome frailty" --add ./publications/old_query # add earlier downloads
pubmed-stream kg "gut microbiome frailty" --refresh                      # rerun everything, add new papers
pubmed-stream kg "gut microbiome frailty"                                # rebuild the notes only

download 和 neighborhood 也可以加入研究：使用 --topic "gut microbiome frailty"，其搜索或种子论文会像通过 kg 创建的一样被记录。单独使用 --vault 时，图谱会以查询或邻域命名；使用 --vault DIR 或 --kg-dir DIR 则可以指定任意文件夹。Obsidian 只会在同一个库内链接笔记，因此同一项研究的每次搜索都要使用相同的主题。

图谱包含的内容

说明	位置	链接到
论文	papers/PMID<id>.md	引用的论文、引用它的论文、相似论文、其 MeSH 概念和集合
概念	concepts/<MeSH heading>.md	使用该标题编目的论文
集合	collections/Search - <query>.md、collections/Neighborhood - PMID <id>.md	其中的论文和热门概念
主页	PubMed Stream.md	集合、关联最多的概念、撤回的论文

以下是示例研究图谱的一个片段。其中的每个链接都真实存在：来自不同搜索的两篇 2026 年研究引用了同一篇 2021 年研究，而 PubMed 也将这篇研究评为与种子综述相似。这类关联正是搜索结果列表所隐藏的内容。

flowchart LR
    C1["Search -<br/>gut microbiota AND sarcopenia"] --> P1["PMID 42060019<br/>gut microbiota and sarcopenia<br/>in older adults, 2026"]
    C2["Search -<br/>gut microbiota AND frailty"] --> P4["PMID 41601864<br/>gut microbiota and<br/>cognitive frailty, 2026"]
    C3["Neighborhood -<br/>PMID 31319564"] --> P2["PMID 31319564<br/>seed review, 2019"]
    C3 --> P3["PMID 33633246<br/>microbiota in patients<br/>with sarcopenia, 2021"]
    P1 -->|cites| P3
    P4 -->|cites| P3
    P2 -.->|similar| P3
    P1 --> M1(["Sarcopenia"])
    P1 --> M2(["Gastrointestinal Microbiome"])
    P3 --> M1
    P3 --> M2
    P2 --> M1
    classDef collection fill:#8E4EC6,stroke:#8E4EC6,color:#fff
    classDef stub fill:#8B8D98,stroke:#8B8D98,color:#fff
    classDef concept fill:#12A594,stroke:#12A594,color:#fff
    class C1,C2,C3 collection
    class P2,P3 stub
    class M1,M2 concept

链接来源：

• 引文来自已下载文章的参考文献列表（仅限有 PMID 的参考文献），以及邻域中的引用论文和被引论文。只有 DOI 的参考文献会列在 其他参考文献 下。
• 相似度来自邻域中的相似文章，并附有 PubMed 的评分。
• 概念是从 PubMed 获取的 MeSH 标题，每 200 篇论文获取一次，并缓存在图谱中。检查标签（如 Humans 或 Aged）仍保留在论文属性中，但不会生成笔记，因为它们会关联几乎所有论文。
• 存根是未下载的邻域论文。其笔记包含 PubMed 详情和链接，并带有 pubmed/stub 标签。

论文笔记先包含 Obsidian 属性，然后是生成的区块，最后留出空间供你添加自己的笔记：

---
type: "paper"
title: "Association between gut microbiota and sarcopenia in older adults: ..."
pmid: "42060019"
year: 2026
journal: "Aging Clinical and Experimental Research"
mesh:
  - "Sarcopenia"
  - "Gastrointestinal Microbiome"
status: "full-text"
tags:
  - "pubmed/paper"
---
%% pubmed-stream:start - generated; edits inside this block are overwritten %%
# Association between gut microbiota and sarcopenia in older adults: ...

**Published:** *Aging Clinical and Experimental Research* · 2026 · [PubMed](...) · [PMC](...) · [DOI](...)

## Abstract
## MeSH concepts
- [[Sarcopenia]] (major topic)
## Cites (39)
- [[PMID33633246|Alterations in intestinal microbiota diversity, composition, and function in patients with sarcop... (2021)]]
## Cited by (1)
%% pubmed-stream:end %%

## Notes

Your own notes go here and survive every rebuild.

安全重建。 重建只会替换生成的区块和工具管理的属性。区块以外的文本，以及你在 Obsidian 中添加的属性、标签和别名都会保留；未更改的笔记不会重写。请勿重命名或移动生成的笔记，否则重建时会重新创建这些笔记。属性可用于 Obsidian 搜索、Bases 和 Dataview 插件；首次构建时，图谱视图会为撤回的论文、综述、存根、概念和集合添加颜色。

Tutorial 5 会构建此研究，并通过图表讲解图谱：论文的来源、哪些概念经常同时出现、研究最依赖哪些论文，以及哪些论文连接了研究的不同部分。

kg 选项	含义	默认值
TOPIC	研究主题；图谱位于 ./kg_<topic>	必需
--query、-q	要下载到研究中的搜索；可重复使用	无
--seed、-s	将其邻域加入研究的 PMID；可重复使用	无
--add DIR	之前下载的文件夹或文件；可重复使用	无
--refresh	重新运行所有已记录的搜索和种子	仅运行新的
--max-results、--max-per-relation	每次搜索的文章数；每种关系的邻居数	100、100
--download-neighbors	下载邻居的全文，而不是生成存根笔记	存根
--fulltext	将每篇文章的全文放入其笔记	仅摘要
--offline	仅使用缓存的 MeSH 术语	获取缺失项
--kg-dir DIR	使用指定图谱文件夹，而非 ./kg_<topic>	./kg_<topic>

当一切正常时，kg 返回 0；无内容可构建或选项无效时返回 1；搜索或邻域获取失败时返回 2。即使如此，它仍会使用其他所有内容构建图谱。

请注意以下限制：

• 有些论文没有 MeSH 术语。 编目需要数月，而 MEDLINE 以外期刊中的论文永远不会被编目，因此这类论文没有概念链接。之后重新构建，即可收录新近编目的论文；其余论文仍不会链接到概念，但会保留引文链接。
• 从 pubmed-stream 0.1.1 或更早版本下载的内容没有参考文献列表，除非保存时使用了 --format xml 或 both。请重新下载，以添加引文链接。
• 许多参考文献没有 PMID。 会议论文、预印本和书籍会出现在 其他参考文献 中，不会进入图谱。
• 笔记永远不会被删除。 移除来源后，其笔记仍保留在图谱中。

5. 与 AI 助手、本地模型和 Obsidian 搭配使用

pubmed-stream 可连接研究人员如今常用的工具：在终端中运行的 AI 助手、将所有内容保存在电脑本地的模型，以及承载知识图谱的 Obsidian。

flowchart LR
    A["Claude Code, Codex,<br/>Gemini CLI"] -->|"MCP tools, from the plugin<br/>or pubmed-stream init"| P["pubmed-stream"]
    P --> K["kg_topic<br/>Obsidian vault"]
    P -->|"pubmed-stream review"| O["Ollama<br/>local model"]
    O -->|"review notes"| K
    A -->|"obsidian CLI"| K

在 Claude Code、Codex 和 Gemini CLI 中使用 pubmed-stream（MCP）

工作原理。 MCP 服务是 Python 库的一部分：运行命令 pubmed-stream mcp 即可启动。无需安装其他内容。AI 助手会在后台启动该命令，之后便能像你输入命令一样，自行调用 pubmed-stream 的工具。设置只会告知助手如何启动服务。共有三种设置方式，区别仅在于库的来源，以及工具适用于哪些文件夹：

flowchart LR
    L["The pubmed-stream library<br/>(PyPI)"]
    L -->|"uv fetches it"| P["The plugin<br/>Claude Code, Codex<br/>every folder"]
    L -->|"pip install"| I["pubmed-stream init<br/>all three assistants<br/>one folder"]
    L -->|"pip install"| M["claude / codex mcp add<br/>every folder"]
    P --> S["pubmed-stream mcp<br/>the MCP server"]
    I --> S
    M --> S
    S -->|"9 tools"| A["The assistant"]

1. 插件：适用于 Claude Code 或 Codex 的所有文件夹。 插件位于 plugins/pubmed-stream，不包含任何代码。它由几个设置文件组成，用于告知助手通过 uvx --from pubmed-stream==<version> pubmed-stream mcp 启动服务。uv 会从 PyPI 下载该版本的库并运行，因此无需 pip install；插件的版本始终对应其运行的库版本。此外，插件还会提供 literature-search 技能中的指令。安装 uv，然后：

claude plugin install pubmed-stream --marketplace melhzy/pubmed-stream   # Claude Code; asks for your NCBI API key

codex plugin marketplace add melhzy/pubmed-stream                         # Codex
codex plugin add pubmed-stream@pubmed-stream

首次启动会花费较长时间，因为 uv 需要下载 pubmed-stream；如果助手报告服务未能启动，请重新启动助手。如果 Claude Code 没有询问你的 NCBI API 密钥，请在其中输入 /plugin configure pubmed-stream@pubmed-stream。

2. pubmed-stream init：适用于任意一个研究文件夹中的三种助手。 执行 pip install pubmed-stream 后，在该文件夹中运行此命令。它会写入设置文件，使用已安装该库的 Python 启动服务：Claude Code 使用 .mcp.json，Codex 使用 .codex/config.toml，Gemini CLI 使用 .gemini/settings.json。它还会将指令写入 AGENTS.md，并由 CLAUDE.md 和 GEMINI.md 导入；此外，它会询问一次你的 NCBI API 密钥。init --claude-model opus 和 init --review-model <ollama model> 可设置该文件夹使用的模型。

cd my_research_folder
pubmed-stream init

3. 手动设置：不使用插件，为每个文件夹单独配置。 执行 pip install pubmed-stream 后，注册一次该命令；--scope user 可让 Claude Code 在每个文件夹中加载该命令，而不只是在你运行命令的文件夹中加载。助手可以使用这些工具，但不会获得指令文件，因此建议使用前两种方式之一。

claude mcp add --scope user pubmed-stream -- pubmed-stream mcp
codex mcp add pubmed-stream -- pubmed-stream mcp

然后开始使用。 在研究文件夹中启动助手：运行 claude、codex 或 gemini；下载的文件会保存在该文件夹中。输入 /mcp，确认列表中有 pubmed-stream 及其工具，然后用日常语言提出研究问题：

粪菌移植是否有助于帕金森病患者？查找临床证据，并附上 PMID 进行总结。 助手会自行从九个工具中选择。每个工具都会返回精简文本，因此它可以用大约 3,000 个 token 扫描 64 篇论文，而不必阅读 4.3 MB 的全文。指令要求它在下载前估算搜索规模，只引用本次会话中已下载并读过的论文，说明每篇论文提供的证据类型，报告搜索及其结果数量，并指出哪些内容无法读取。下载数百篇文章或构建知识图谱需要几分钟；服务运行期间会报告进度，Claude Code 会显示这些进度。

如需主动调用 pubmed-stream，而不是让助手自行选择：

位置	输入内容
Claude Code：终端、VS Code、JetBrains，以及 Claude 桌面应用的 Code 标签页	/pubmed-stream 将菜单缩小到 /pubmed-stream:literature-search；选择它并输入你的问题
Codex 应用	输入 / 或 @，然后选择 pubmed-stream
Codex CLI	输入 $pubmed-stream:literature-search，或输入 /skills 并选择它
Gemini CLI	在已通过 init 设置的文件夹中提问；它没有技能菜单
Claude 桌面应用中的 Cowork	首先将插件添加到你的 claude.ai 账户：Customize > Plugins > Add > Add marketplace，输入 melhzy/pubmed-stream，然后添加 pubmed-stream。Cowork 会在你的电脑上启动服务，因此必须安装 uv。然后输入 / 并选择 literature-search（列在 pubmed-stream 下），也可以直接提问。该插件也会通过你的账户连接到 Claude Code；如果终端版本已安装，Claude Code 会继续使用该版本
Claude 桌面应用中的 Claude 聊天	无法通过插件使用，因为只有 Claude Code 和 Cowork 会启动插件。请按照教程 7，选项 C所述，将服务添加到应用配置中，然后聊天界面便可调用其工具
网页版和手机上的 Claude 聊天	不可用：它们无法在你的电脑上启动程序。将插件添加到你的账户后，输入 / 会列出该技能，但它没有可调用的工具

工具	助手如何使用
search_pmc	统计 PMC 搜索结果，并列出最新匹配项，不下载内容
download	下载搜索结果的全文，每篇文章保存为一个 JSON 文件
fetch_abstracts	保存 PubMed 摘要，包括没有免费全文的文章
list_articles	精简列出已下载的文章，可按需附上摘要
most_cited	找出下载内容中引用次数最多的作品
read_article	阅读一篇文章，或仅阅读包含某个词语的段落
neighborhood	绘制某个 PMID 的相似论文、引用它的论文和它引用的论文，并标记撤稿论文
export_citations	为 Zotero、EndNote 或 Mendeley 导出 BibTeX 或 RIS
build_knowledge_graph	将一项研究的搜索结果和关键论文关联到 Obsidian 知识库中

这些方式不会冲突：在已安装插件的位置，init 不会将其服务写入文件夹，因此工具不会重复列出；在之前已设置过的文件夹中再次运行该命令，则会移除多余的服务。

本地模型和 Obsidian

本地模型。 对于你不想发送给公司的问题，pubmed-stream review 会让一个运行在你自己电脑上的模型通过 Ollama 总结你选定的摘要；只有 PubMed 搜索会离开你的电脑。模型一次只读取一篇摘要，温度设为 0，且永远不会看到你的问题，因此它无法把问题说成研究发现。pubmed-stream 会自行附上每篇文章的 PubMed ID，并标记摘要不支持的数字和引用。

1. 安装 Ollama，从 ollama.com/download 下载，或在 Windows 上运行 winget install Ollama.Ollama。它会在后台运行；运行 ollama list 可检查是否正常工作。 2. 选择一款电脑能够运行的模型。 Ollama 的模型库中的任何模型都可以使用，包括 Qwen、Gemma 或 Llama 等开放权重模型；pubmed-stream 会关闭带有「思考」步骤的模型的这一功能，避免占用摘要的长度。较大的模型错误更少，但需要更多内存：模型的下载大小应不超过电脑内存的大约三分之二；如果模型能装进显卡内存，运行速度会快得多。

你的电脑	模型大小	示例（下载大小）
任意笔记本电脑，8 GB 内存	10 亿到 40 亿参数	llama3.2:3b（2.0 GB）、qwen3.5:4b（4.0 GB）
16 GB 内存，或配备 8 GB 显存的显卡	80 亿到 120 亿参数	qwen3.5:9b（7.6 GB）、gemma4:12b（7.7 GB）
32 GB 内存，或配备 16 到 24 GB 显存的显卡	260 亿到 350 亿参数	gemma4:26b（16 GB）、qwen3.5:27b（20 GB）

如果不指定 --model，review 会使用 Llama 3.2 1B（807 MB）。它几乎能在任何电脑上运行，但错误更多：在 7 篇帕金森病论文中，它把一篇涵盖 11 项研究的综述称为随机对照试验，而 Qwen3.5 2B 没有犯这个错误。

3. 下载模型并提问：

ollama pull qwen3.5:9b
pubmed-stream review "Does FMT help people with Parkinson's disease?" --id 38686220 41826284 41113141 --model qwen3.5:9b --vault kg_fmt_parkinson

--vault 还会将摘要保存为知识图谱 reviews 文件夹中的笔记，笔记以问题、日期和模型命名，因此多个模型生成的综述可以并排查看。pubmed-stream init --review-model qwen3.5:9b 会将该模型设为文件夹的默认模型，因此可以省略 --model。--answer 会根据所有摘要生成一个回答；请对照摘要检查，因为较小的模型可能会把研究结果归到错误的论文名下。如果 Ollama 在另一台电脑上运行，例如实验室服务器，请使用 --ollama-host http://<server>:11434 指定其地址。

或者使用 AI 助手的模型。 如果 Claude Code、Codex 或 Gemini CLI 已安装并在你的电脑上登录，--model claude、--model codex 或 --model gemini 就会改用它们进行摘要（参见快速入门）。这些模型远大于笔记本电脑所能运行的模型，因此错误更少：在上面提到的 7 篇帕金森病论文中，Claude Code 生成的摘要都准确无误，包括 Llama 3.2 1B 误称为试验的那篇 11 项研究综述。代价是，摘要会发送给 Anthropic、OpenAI 或 Google，而且每次运行都会消耗一部分套餐额度。pubmed-stream 会在一个空文件夹中运行助手，并关闭其工具，因此助手只会回答问题；其他方面与 Ollama 相同：一次处理一篇摘要，不会收到问题，并使用相同的检查、--answer 和 --vault 功能。可以在冒号后添加助手自己的模型，例如 --model claude:opus。

pubmed-stream review "Does FMT help people with Parkinson's disease?" --id 38686220 41826284 41113141 --model codex --vault kg_fmt_parkinson

--model	摘要由谁生成	摘要会发送到哪里
Ollama 模型，例如 qwen3.5:9b	你电脑上的模型	不会发送到任何地方
claude、claude:opus	Claude Code	Anthropic
codex、codex:<model>	Codex	OpenAI
gemini、gemini:<model>	Gemini CLI	Google

Obsidian。 每个知识图谱都包含适用于 Obsidian 的属性类型和 Papers.base，这是一个包含所有论文的 Bases 表格，并提供全文、综述、撤稿论文和 #to-read 列表视图。运行 pubmed-stream open kg_<topic> 即可打开；启用 Obsidian 的命令行后，助手还可以查询它：obsidian vault=kg_<topic> base:query path=Papers.base view="Reading list"。

Tutorial 7 通过实际使用过程进行讲解：助手如何从 4,863 条搜索结果生成带引用的报告、Claude Code 和 Codex 如何使用 MCP 工具，以及 10 亿参数的本地模型有哪些优缺点。如此小的模型擅长生成摘要，但无法自行执行搜索。

Python API

命令的所有功能都可以通过 pubmed_stream 使用：

函数	用途	返回值
search_and_download(query, max_results, fmt="text", ...)	搜索 PMC 并下载全文	DownloadStats
get_neighborhood(pmid, max_per_relation=100, ...)	获取相似论文、引用该论文的论文和该论文引用的论文，并附带标记	Neighborhood
save_neighborhood(hood, output_dir=None)	写入 neighborhood.json	路径
download_neighborhood(hood, ...)	下载种子论文和邻近论文的全文	DownloadStats
create_kg(topic, queries, seeds, sources, refresh=False, ...)	开展研究并构建知识图谱	KGResult
load_study(kg_dir)、record_study(kg_dir, topic, queries, seeds)	读取图谱已记录的研究，或将研究添加到图谱记录中	dict
build_vault(sources, vault_dir, ...)	仅根据下载文件夹构建图谱笔记	VaultStats
topic_vault_dir(topic)	主题对应的 kg_<topic> 文件夹	路径
search_pmc(query, max_results=10, ...)	统计搜索结果并列出最新匹配项，不下载	SearchResult
count_pubmed(query)	匹配搜索条件的 PubMed 文章数量	int
fetch_abstracts(query, max_results=100, ...)	保存 PubMed 摘要，包括没有免费全文的文章	AbstractStats
list_articles(path)	下载的文章和摘要的简要记录，按时间从新到旧排列，每篇仅列一次	list of dicts
export_citations(path, fmt="bibtex", ids=None)、to_bibtex(records)、to_ris(records)	导出供 Zotero、EndNote 或 Mendeley 使用的引文	(text, count, missing)、str
most_cited(path, n=10)	下载的文章引用次数最多的文献	list of dicts
review(question, path, ids, model, answer=False, ...)	通过 Ollama 调用本地模型，或调用 claude、codex 或 gemini 生成摘要，并进行检查	Review
init_folder(folder)	为 Claude Code、Codex 和 Gemini CLI 提供说明和 MCP 设置	list of actions
open_vault(kg_dir)	在 Obsidian 中打开知识图谱	(opened, message)
esearch_pmc(term, max_results, api_key, session, rate_limiter)	执行一次 PMC 搜索：获取 ID 和总数	(ids, total)
esummary_pmc(pmcids, api_key, session, rate_limiter)	获取 PMC 文章的标题、期刊、年份和标识符	list of dicts
efetch_pmc(pmcid, out_dir, fmt, api_key, session, rate_limiter)	下载一篇文章	(ok, status)
extract_metadata_from_pmc_xml(xml)、extract_text_from_pmc_xml(xml)	解析已有的 JATS XML	dict、str
create_session(user_agent)、RateLimiter(seconds)	供底层函数使用的构建模块

调用 NCBI 的函数接受 api_key、email、user_agent、rate_limit 和可复用的 session，并会回退到环境变量。底层函数需要显式传入 session 和速率限制器：

from pathlib import Path
from pubmed_stream import RateLimiter, create_session, efetch_pmc, esearch_pmc

session, limiter = create_session("my-project/1.0"), RateLimiter(0.34)
ids, total = esearch_pmc('"gut microbiota"[Title] AND frailty[Title/Abstract]', 20, None, session, limiter)
for pmc_id in ids:
    ok, status = efetch_pmc(pmc_id, Path("downloads"), "both", None, session, limiter)   # success, unavailable, exists or error

论文在文献中的传播情况由独立模块负责衡量：from pubmed_stream import impact。impact.citers_of(pmids) 会向 PubMed 查询同时引用多篇论文的文章；impact.count_by_year(pmids, first, last) 和 impact.count_flags(pmids) 会按年份统计这些文章，或统计其中的综述、已撤稿文章和 NIH 资助文章，而无需下载其记录；impact.corrections(pmid) 会列出论文的撤稿通知、勘误和评论。impact.citation_contexts(folder, pmid, doi) 会查找每篇已下载全文中引用该论文的句子；impact.semantic_scholar_contexts(pmid) 会补充 Semantic Scholar 为全文不免费提供的论文收录的句子；impact.classify(sentences) 会对这些句子分类：讨论撤稿或对论文的质疑、指出论文的发现，或一般性地引用论文。impact.annotate(kg_dir, properties) 会将结果写入知识图谱的笔记中。教程 8 会通过两层引用论文追踪一篇已撤稿论文的传播过程。

故障排查

症状	原因和解决方法
Windows 上的带引号短语被忽略	Windows PowerShell 5.1 会丢弃内部的双引号，而命令提示符不支持单引号。在 PowerShell 中，写作 '\"gut microbiota\"[Title] AND frailty[Title/Abstract]'；在命令提示符中，写作 "\"gut microbiota\"[Title] AND frailty[Title/Abstract]"。PowerShell 7.3 及更高版本、macOS 和 Linux 可按原样使用这些示例
保存了 0 篇，但匹配项很多	文件已存在，因此被跳过；跳过也算成功。stats.skipped 会显示跳过的文件
很多文章显示为 不可用	这些文章的出版商不允许下载 XML。在搜索中添加 AND "open access"[filter]
HTTP 429，请求过多	请求会自动重试。添加 NCBI API 密钥（pubmed-stream init --ncbi-api-key），或使用 --rate-limit 0.5 降低请求速率
NCBI 拒绝了 API 密钥	保存的密钥有拼写错误或已被撤销；pubmed-stream 会在没有该密钥的情况下继续运行。在 NCBI 账户设置中创建密钥，然后使用 pubmed-stream init --ncbi-api-key 再次保存
超时或网络不稳定	使用 --sequential，或减少 --workers 数量
助手将 pubmed-stream 的每个工具都列出了两次	该文件夹在安装插件之前已通过 init 设置。在该文件夹中再次运行 pubmed-stream init：安装插件后，它会移除文件夹自带的服务
插件的服务未启动	首次启动时会通过 uv 下载 pubmed-stream，这可能比助手的等待时间更长：请重新启动助手。如果仍然失败，可能是未安装 uv
助手使用了其他 PubMed 工具	Claude Code 也可能安装了 Anthropic 的 PubMed 连接器；两者都能回答文献问题。想要将文章保存到文件夹时，请说“use pubmed-stream”，或者在 claude.ai 设置中关闭该连接器
桌面应用启动 pubmed-stream 时打开了控制台窗口（Windows）	桌面应用没有控制台，因此 Windows 会为服务打开一个控制台，而应用会让该窗口留在屏幕上。pubmed-stream 0.4.3 及更高版本会在服务启动后立即隐藏窗口，因此它只会闪现一下；它只会触碰仅包含自身进程的控制台，绝不会触碰终端
结果与问题无关	搜索会匹配文章中的任意文本；请参阅第 2 节
'PMC…' 是 PMC ID	neighborhood 和 --seed 需要 PubMed ID；已下载文件的 metadata.pmid 中包含该 ID
邻域中的参考文献或引用很少	NCBI 仅为已提交参考文献列表的文章提供引用链接，这些文章大多来自 PMC
图中没有概念链接的论文	PubMed 尚未使用 MeSH 对其进行索引；请稍后重新构建

Python、Jupyter、Colab 或 Obsidian 的安装问题，请参阅初学者故障排查指南。

如需详细信息，可在任意命令后添加 -v；也可以仅为此软件包启用调试日志，因为 HTTP 库的调试输出会记录包含 API 密钥的请求 URL：

import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("pubmed_stream").setLevel(logging.DEBUG)

工作原理

pubmed-stream 由五个小模块组成。每个模块只使用位于它下方的模块，从命令行一直到 HTTP 客户端：

模块	作用
cli.py	pubmed-stream 命令：init、search、download、abstracts、list、export、neighborhood、kg、review、open 和 mcp
corpus.py	将下载的文章和摘要读回为精简记录，并查找被引用次数最多的作品
export.py	BibTeX 和 RIS 引文
abstracts.py	PubMed 搜索和摘要，适用于没有免费全文的文章
mcp_server.py	为 AI 助手提供 pubmed-stream 工具的 MCP 服务
review.py	通过 Ollama 本地模型或 AI 助手生成摘要，并检查数字和引文
obsidian.py、assistants.py	在 Obsidian 中打开图谱；为 AI 助手设置文件夹
settings.py	保存在 ~/.pubmed-stream.json 中的 NCBI API 密钥，以及每个文件夹的设置
impact.py	论文如何在文献中传播：按年份列出的引用论文、引文句子、注释
kg.py	研究：运行搜索和种子查询、记录并刷新研究
vault.py	知识图谱笔记：合并所有来源、生成笔记、安全地重建
neighborhood.py	相似论文、引用该论文的论文和被该论文引用的论文，以及标记和 MeSH 术语
downloader.py	E-utilities 客户端、PMC 搜索和下载、JATS 解析

架构指南通过图表、表格和示意图介绍整个代码库：每个 NCBI 请求、请求流程、知识图谱如何合并并安全重建、数据模型，以及代码的扩展位置。

pubmed-stream/
├── pubmed_stream/      the package
├── tests/              163 offline tests; NCBI is faked with canned responses
├── tutorials/          eight notebooks, the AI assistant tutorial and instructions, guides, kg_study.py, keyword lists, tools
├── plugins/            the Claude Code and Codex plugin: MCP server settings and the literature-search skill
├── .claude-plugin/     the Claude Code marketplace that lists the plugin
├── .agents/plugins/    the Codex marketplace that lists the plugin
├── docs/               the architecture guide and its figures
├── pyproject.toml      package metadata and dependencies
├── server.json         the MCP server's entry in the official MCP Registry
├── studies/            research done with pubmed-stream, with its frozen data; see studies/README.md
├── CHANGELOG.md        changes in each version
├── CITATION.cff        how to cite pubmed-stream
└── LICENSE             MIT

贡献

欢迎贡献。请 Fork 代码库，创建功能分支，然后提交拉取请求。为新行为添加测试，并确保 pytest 和 ruff check . 均通过；GitHub Actions 会在每个拉取请求上运行这两项检查。测试可在几秒内离线运行：

pip install -e ".[dev]"
pytest

文档网站由 README、tutorials/、docs/ 和变更日志构建，并由 GitHub Actions 在每次推送到 main 时发布。使用以下命令在 http://127.0.0.1:8000 预览：

pip install -r docs/requirements.txt
mkdocs serve

路线图上的想法：搜索查询构建器和进度条。

发布到 PyPI

维护者手动发布新版本。将 X.Y.Z 替换为新版本号。

1. 更新版本号：在 pubmed_stream/__init__.py（__version__ = "X.Y.Z"）和 CITATION.cff（version 和 date-released）中更新，pyproject.toml 会读取前者。在插件 plugins/pubmed-stream 中，在两个 plugin.json 文件中更新版本号（version）；更新该版本的服务所运行的版本号（.codex-plugin/mcp.json 和 .claude-plugin/plugin.json 中的 pubmed-stream==X.Y.Z）；并在技能说明中更新两处版本号。在 server.json 中更新两处（version 和包的 version）。将变更日志中的 Unreleased 标题改为 X.Y.Z - YYYY-MM-DD。测试会指出遗留的副本。

2. 运行测试：pytest。

3. 构建并检查发行包；dist/ 已加入 git 忽略：

   pip install --upgrade build twine
   rm -rf dist build *.egg-info
   python -m build
   python -m twine check dist/*
   

4. 上传到 PyPI：使用从 https://pypi.org/manage/account/token/ 获取、限定为 pubmed-stream 项目的 API 令牌。用户名必须是 __token__；PyPI 密码不起作用。出现 403 Forbidden 表示令牌错误、已过期或未限定为此项目。PyPI 不接受重复上传同一版本，因此请使用新的补丁版本修复有问题的发行版。出现 InvalidDistribution: Metadata is missing required fields: Name, Version 表示 twine 版本过旧，无法读取软件包的元数据（版本 2.4）；请使用 twine 6.1 或更高版本。在 Anaconda 等共享环境中，升级 twine 也会升级该环境中其他工具所依赖的软件包，因此请在单独的虚拟环境中运行它。

   python -m twine upload -u __token__ dist/*
   

   twine 提示时粘贴令牌；在此处输入的令牌不会留在 shell 历史记录中。请先上传，再推送发行版：GitHub 上的插件会运行其 pubmed-stream==X.Y.Z 所指定的发行版，因此在 PyPI 上有该发行版之前，插件的服务无法启动。

5. 提交、打标签并推送发行版：

   git commit -am "chore: Release X.Y.Z"
   git tag X.Y.Z
   git push origin main X.Y.Z
   

   如果标签已指向错误的提交，请移动它并仅强制推送该标签，绝不要强制推送 main：git tag -f X.Y.Z <commit>，然后运行 git push --force origin refs/tags/X.Y.Z。

6. 创建 GitHub 发行版。 在网页界面中，打开 https://github.com/melhzy/pubmed-stream/releases/new?tag=X.Y.Z，将标题设为 X.Y.Z，将 CHANGELOG.md 中该版本的部分粘贴为说明，附加 dist/ 中的两个文件，然后发布。使用 GitHub CLI 时，先运行一次 gh auth login，然后运行：gh release create X.Y.Z --title "X.Y.Z" --notes "<the changelog section>" dist/*。

7. 更新官方 MCP Registry中的条目，其他 MCP 目录会从中复制信息。它只保存 server.json，因此请在 PyPI 上已有该发行版后再执行此操作：Registry 会检查该版本是否存在于 PyPI，以及 PyPI 上显示的 README 是否包含 mcp-name: io.github.melhzy/pubmed-stream 这一行；README 通过隐藏注释包含该行。安装 mcp-publisher 后，在仓库根目录运行：

   mcp-publisher login github   # once; it signs in as the GitHub account that owns melhzy/pubmed-stream
   mcp-publisher publish
   

8. 验证：运行 pip install --upgrade pubmed-stream，然后运行 pubmed-stream --version。

常见问题

PubMed 和 PMC 有什么区别？ PubMed 收录了超过 3,500 万篇文章的引文和摘要。PubMed Central（PMC）是 NCBI 的全文档案库，其中收录了部分文章。pubmed-stream 从 PMC 下载全文，并使用 PubMed 获取相似文章、MeSH 术语，以及无法免费获取全文的文章摘要。

它是否符合 NCBI 的条款？ 是。它使用官方的 E-utilities，遵守 NCBI 的速率限制，通过 User-Agent 标识自身，并在你设置联系邮箱后发送该邮箱地址。

为什么每篇文章保存为一个 JSON 文件？ 一个文件可以将文章的元数据、参考文献和文本保存在一起，并保留所有格式，还能让语料库易于筛选、合并和续传。

可以恢复中断的下载吗？ 可以。再次运行相同的命令即可；已存在的文件会被跳过。

我可以用它进行系统综述吗？ 可以用于前期步骤：摸清领域、测试并记录检索，以及查找关键论文。系统综述还需要查询其他数据库、由两名审阅者进行筛选，并评估偏倚风险；请参阅 pubmed-stream 能做什么和不能做什么。

为什么有些重要论文没有收录？ 全文仅来自 PMC，而且检索结果会优先显示最新匹配项。abstracts 会保存其余文章的 PubMed 摘要；较早发表和仅订阅用户可读的论文也会通过关键论文的相似文章关系，以占位条目的形式或作为引用它们的论文的链接进入知识图谱。

我需要 Obsidian 吗？ 只有在需要直观地探索知识图谱时才需要。笔记是纯 Markdown 文件，教程 5 则会用 Python 分析其中一个知识图谱。

我可以将它用于商业用途吗？ 可以，但需遵守 NCBI 的使用政策，并遵循 MIT 许可证。

引用、致谢与许可证

pubmed-stream 由马萨诸塞大学的 Haran Lab、Bucci Lab 和 Microbiology & Microbiome Dynamics AI HUB 开发，用于支持生物医学研究。感谢 NCBI 提供 E-utilities 和 PubMed Central 的开放访问权限。如果你在研究中使用了它，请引用本项目。GitHub 仓库主页上的 Cite this repository 按钮会根据 CITATION.cff 提供 APA 和 BibTeX 格式的引用：

@software{pubmed_stream_2026,
  title = {pubmed-stream: From PubMed Searches to Knowledge Graphs of the Biomedical Literature},
  author = {Haran Lab and Bucci Lab and Microbiology \& Microbiome Dynamics AI HUB},
  organization = {University of Massachusetts},
  year = {2026},
  url = {https://github.com/melhzy/pubmed-stream},
  note = {Built on NCBI E-utilities}
}

pubmed-stream 是遵循 MIT License 发布的自由软件。每个版本的更改都列在变更日志中。

如有疑问或需报告错误：提交问题。软件包：pypi.org/project/pubmed-stream。