2. 文献检索（及元数据抓取）¶
当我们确定了研究起点（或者任何研究中途中需要进行文献调研的前置头脑风暴阶段），我们可以开始进行文献检索了。
这里我们不会帮你设计文献调研的query，但是我们建议你在使用我们的搜索工具前，一定要精确使用符合语法格式、高命中的query语句，以确保检索到相关文献。
我们工具囊括的文献数据库主要集中于生物医学以及计算交叉领域，包括但不限于：
- PubMed/Medline
- arXiv
- bioRxiv，medRxiv，chemRxiv 等预印本平台
⚠️：预印本检索 = Crossref 相关性检索 + 本地布尔复核（不是全库拉取，也不用各平台官方 API）。 每次请求都会让 Crossref 只在其平台前缀内检索（
filter=prefix:10.64898 / 10.26434,type:posted-content）——平台圈定发生在服务端，而不是本地对全量结果再做前缀过滤。bioRxiv 与 medRxiv 共用 openRxiv 前缀10.64898，故二者再用 DOI 编号位数（6 位 = bioRxiv、8 位 = medRxiv）在本地区分。相关性这一步的行为：
query.bibliographic是模糊、OR 式的打分排序（两个词的查询返回量比任一单词都多，例如 chemRxiv 上 "base editing" ≈ "base" 与 "editing" 的并集），即它是严格命中的超集。抓取端用 cursor 把整个结果集翻到底（不是截断的 top-N），再在本地只保留元数据里 query 每个词都真实出现的记录（对标题/摘要等做布尔 AND）。因为 严格命中 ⊆ relevance 超集，排序不会丢掉任何元数据层面的精确命中——它只改变返回顺序。相关性检索的限制：
① 入库延迟——刚上传几分钟的预印本可能尚未被 Crossref 收录。
② 仅元数据匹配——Crossref 只对沉积的元数据（标题/摘要等）打分，只出现在正文里的词对它不可见。仅 bioRxiv/medRxiv 的 Europe PMC 索引全文；ChemRxiv 无任何全文，故正文词漏检属预期。
③ 版本重复——每次改版都被注册成独立 DOI work，
.../v1与.../v2会同时命中，可能需手动去重。与"全量枚举拉取"的区别： 相关性检索是对沉积元数据的启发式。想"构造性零遗漏"则改为全库枚举——
filter=prefix…不带query，用 cursor 把整个平台的记录翻完（约 5.5 万 chemRxiv / 43.6 万 openRxiv），再在本地做布尔 AND；不经任何相关性引擎，召回 = "该前缀下元数据真正全词命中的全部记录"（配合--start/--end-date窗口可缩小拉取量）。代价是每次搜索都要下载整个语料，且仍继承上面的源层边界（入库延迟 / 仅元数据 / 版本重复）。本工具目前的search()走相关性，暂未提供全量模式开关。全库拉取对于轻量级的文献调研并不适用，除非你有明确的理由需要获取某一特定数据库的全部文献，而且每年每月更新的文献本身就具有一定的冗余性，所以从效率+数量上考虑，单纯相关性检索应该能够满足绝大多数科研工作者的文献调研需求(
因为真正重要的内容一定会反复出现，往往不需要担心全量遗漏)。当然，对于全量拉取，可以参考其他开源工具如 paperscraper 等的实现。
建议用户提前学习并熟练掌握上述数据库的检索语法，本工具内置搜索模块的运行逻辑与数据库网页端搜索框基本一致。
✨ 这里我们为你提供了几个特定文献数据库构建搜索query的skill，paper query skill
以 PubMed 为例，以下为一组典型且结构较复杂的检索式示例：
"""
(
"Intrinsically Disordered Proteins"[Mesh] OR
"Intrinsically Disordered Protein"[Title/Abstract] OR
"Intrinsically Disordered Proteins"[Title/Abstract] OR
"Intrinsically Disordered Region"[Title/Abstract] OR
"Intrinsically Disordered Regions"[Title/Abstract] OR
"Natively Unfolded Protein"[Title/Abstract] OR
"Natively Unfolded Proteins"[Title/Abstract] OR
"Unstructured Protein"[Title/Abstract] OR
"Unstructured Proteins"[Title/Abstract] OR
"IDR"[Title/Abstract] OR
"IDP"[Title/Abstract]
)
AND
(
"Protein Interaction Maps"[Mesh] OR
"Protein Interaction Maps"[Title/Abstract] OR
"Protein Interaction Networks"[Title/Abstract] OR
"Protein-Protein Interaction Map"[Title/Abstract] OR
"Protein-Protein Interaction Network"[Title/Abstract] OR
"Protein Interaction Mapping"[Mesh] OR
"Protein Interaction Mapping"[Title/Abstract] OR
"Binding Sites"[Title/Abstract] OR
"Protein Binding"[Title/Abstract] OR
"Protein Interaction Domains and Motifs"[Title/Abstract] OR
"Protein Interaction Maps"[Title/Abstract] OR
"Protein Interaction Domains and Motifs"[Mesh] OR
"Protein Interaction"[Title/Abstract] OR
"Protein-Protein Interaction"[Title/Abstract] OR
"PPI"[Title/Abstract] OR
"Interaction"[Title/Abstract] OR
"Binding"[Title/Abstract] OR
"Interface"[Title/Abstract] OR
"Complex"[Title/Abstract]
)
AND
(
"Artificial Intelligence"[Mesh] OR
"Deep Learning"[Mesh] OR
"Machine Learning"[Mesh] OR
"Neural Networks, Computer"[Mesh] OR
"Artificial Intelligence"[Title/Abstract] OR
"Deep Learning"[Title/Abstract] OR
"Machine Learning"[Title/Abstract] OR
"Neural Network"[Title/Abstract]
)
AND (
"2023/01/01"[Date - Publication] : "2026/12/31"[Date - Publication]
)
"""
完成检索query构建后，即可开始检索文献，我们将以PubMed相关 API 为例进行演示。
pubmed-search 模块可帮助你快速检索 PubMed 文献，并返回符合条件的 PMIDs 列表。
❯ paperflow pubmed-search --help
Usage: paperflow pubmed-search [OPTIONS] QUERY
Search PubMed using Your customized query and return PMIDs.
Notes:
- 1, This command only searches and returns PMIDs, it does not fetch paper metadata.
- 2, This command will print the found PMIDs and also save them to 'pubmed_searched_ids.txt' in the specified output
directory.
If --output-dir is not specified, it will default to the storage directory.
- 3, Note that storage_dir is used to initialize the fetcher for consistency, while output_dir is where the PMIDs are saved.
They are different parameters!
Example usage:
- 1. Search for papers related to "machine learning" and return up to 500 PMIDs/per batch:
paperflow pubmed-search "machine learning" --retmax 500 --output-dir ./MyPapers --email "YOUR_EMAIL@example.com" --api-key
"YOUR_NCBI_API_KEY"
╭─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * query TEXT PubMed search query. [required] │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --retmax -n INTEGER Max number of PMIDs to return every batch, must less than 10000. [default: 500] │
│ * --email TEXT Entrez Email. [required] │
│ --api-key TEXT NCBI API Key (recommended). │
│ --storage-dir -s TEXT Directory in Repository-level to store paper data for Initialization. │
│ [default: ./Papers] │
│ --output-dir -o TEXT Directory in result-level to store output IDs. │
│ --max-retries INTEGER Maximum number of retries for Entrez API calls. [default: 3] │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
在本阶段，我们建议通过文献检索获取论文元数据（以摘要为主），而不急着下载全文。
因为文献收集本质是一个迭代优化的过程：通常仅通过摘要即可筛选出目标文献，随后在下一步针对性下载所需论文；特殊情况下也可下载全部检索结果。
需要重点强调：你可以在任意阶段重新开展头脑风暴。每个阶段的输出结果，均可作为后续文献调研的输入依据。基于本阶段的产出，你可进一步完善研究起点，精准定义研究问题。
pubmed-meta 模块接受用户自定义的检索 query 或者之前pubmed-search模块返回的 pmid 列表文件，获取 PubMed 文献元数据（以json格式存储），并保存到指定存储目录。
❯ paperflow pubmed-meta --help
Usage: paperflow pubmed-meta [OPTIONS]
Fetch paper metadata from PubMed using Your customized query, pmid list file and save to storage.
Notes:
- 1, You must provide one of --query, or --file to specify which papers to fetch. Note that they are mutually exclusive.
- 2, -f can be used to fetch one or more PMIDs listed in a text file (one PMID per line).
Example usage:
- 1. Fetch papers for a query and save to storage:
paperflow pubmed-fetch --query "machine learning" --output-dir ./MyPapers --email "YOUR_EMAIL@example.com" --api-key "YOUR_NCBI_API_KEY"
- 2. Fetch papers from a list of PMIDs in a file:
paperflow pubmed-fetch --file ./pmid_list.txt --output-dir ./MyPapers --email "YOUR_EMAIL@example.com" --api-key "YOUR_NCBI_API_KEY"
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --query -q TEXT PubMed search query. │
│ --file -f TEXT Text file containing PMIDs (one per line), -q and -f are mutually exclusive. │
│ --batch-size -b INTEGER Batch size for fetching. [default: 50] │
│ * --email TEXT Entrez Email. [required] │
│ --api-key TEXT NCBI API Key (recommended). │
│ --storage-dir -s TEXT Directory in Repository-level to store paper data for Initialization. [default: ./Papers] │
│ --max-retries INTEGER Maximum number of retries for Entrez API calls. [default: 3] │
│ --output-dir -o TEXT Directory in result-level to store output papers, default is current directory. If not specified, will be set to root │
│ directory of the repository-level which is storage_dir. 🌟 We will create a '/pubmed' subfolder under the output │
│ directory to save all pubmed related data │
│ [default: .] │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯