nature-academic-search

Academic Paper Search

给 Codex、Claude Code 和 DeepSeek Harness 使用的文献检索与引用核验工具。

用中文描述研究问题，跨学术数据库找论文、去重、核对引用，导出文献管理器可用的文件。

快速开始 · 中文场景 · 工具与命令 · 批量工作流 · 数据源 · 常见问题

可选配套服务：WPIRONMAN AI 中转 提供可选模型入口，不是论文来源。学术源检索、元数据核验和引用下载不需要配置中转。

这是什么

本项目帮助科研用户完成可复现的文献检索、核验与引用导出。核心流程是 检索 → 去重 → 核验 → 导出；需要扩展阅读时，可以从种子论文追踪参考文献和后续引用。

安装标识仍为 nature-academic-search，展示名称为 Academic Paper Search。 名称中的 nature 不限制检索范围，也不表示与 Nature Portfolio 有官方关联。

默认论文源为 CrossRef、PubMed、arXiv、OpenAlex、Europe PMC； Semantic Scholar 按需启用，ClinicalTrials.gov 单独用于试验注册检索。

你会得到带来源的候选论文、字段级核验结果、可导入 Zotero / EndNote 的引用文件， 以及查询参数、时间、失败来源等审计信息。保存这些记录可以复查一次检索；上游数据持续更新， 同一检索式日后重跑不保证返回完全相同的结果。

30 秒开始

以下面向已装好客户端和 Python 工具的用户；首次安装依赖、下载运行环境可能需要更久。

1. 准备环境

• Python 3.10+，以及 uv（插件通过 uvx 启动服务）。
• Codex 或 Claude Code；选择自己实际使用的客户端即可。
• 一个用于 PubMed 请求的联系邮箱。把示例邮箱替换成自己的地址，并让启动客户端的环境能读取它：

export [email protected]

下列终端示例使用 Bash / Zsh 语法。桌面客户端未必继承终端里的 export，见常见问题。

2. 安装插件，二选一

Codex：

codex plugin marketplace add wp-a/nature-academic-search
codex plugin add nature-academic-search@wp-a-academic-tools

Claude Code：

claude plugin marketplace add wp-a/nature-academic-search
claude plugin install nature-academic-search@wp-a-academic-tools

插件同时提供 Skill 和 MCP 配置。安装后开启新会话，让客户端加载工具。 Codex 的市场命令见官方说明； 若本机没有 plugin 子命令，可使用下方的 Python 包安装方式。

3. 检查连接，发起第一次请求

uvx --from nature-academic-search==0.3.1 nature-academic-search preflight

检查报告中的 OK、FAIL、SKIP，再复制下一节的请求到客户端。 preflight 检查学术 API 的连通性，不代表客户端已加载 MCP；也不保证每次检索都成功。

uv tool install nature-academic-search
# 也可用 pipx install nature-academic-search

# 先预览，再注册自己使用的客户端
nature-academic-search install --client codex --email [email protected] --dry-run
nature-academic-search install --client codex --email [email protected]
nature-academic-search preflight

git clone https://github.com/wp-a/nature-academic-search.git
cd nature-academic-search
uv tool install --force .
nature-academic-search --help

bash install.sh --client both --email [email protected]
# 兼容旧用法：bash install.sh [email protected]

直接这样问

在 Codex 中可使用 $nature-academic-search 显式指定技能；也可在各客户端直接说明技能名称和任务：

使用 nature-academic-search，为“生成式 AI 在医学教育中的应用与风险”找文献。
先把中文问题拆成英文关键词；生物医学概念先核对 MeSH。
使用默认五个论文源，每源先取 5 条，去重后给出候选清单和各来源的成功、失败情况。
从候选中选 3 条，用原始标识符重新查询，并以候选的题名、作者、年份为 expected 做核验。
分别列出已核验、存在冲突和需要人工检查的记录，附 DOI / PMID 与来源链接。

判断是否跑通：客户端实际调用了工具，返回来源状态，并给出字段核验结果。 只收到模型生成的题名列表，还不能算完成核验。

六个可复制的中文场景

前三个可复制的中文场景附有历史实测截图。本次真实结果记录日期为 2026-07-31， 版本、输入和失败来源见各案例；它们展示结果格式，不代表今天的实时命中数。

开题检索

引用核验

PubMed / MeSH

1. 开题检索

使用 nature-academic-search 检索“生成式 AI 在医学教育中的应用与风险”。
先给出英文检索式，再用默认论文源搜索；按强标识符去重。
整理 10 条候选线索，注明年份、文献类型、来源、DOI / PMID 和待核验项；
报告实际检索日期及失败来源，区分预印本与正式发表记录。

得到：可继续筛选的候选清单、检索范围和来源缺口。查看案例

2. AI 幻觉引用核验

下面故意给一条 DOI 存在、其他字段错误的引用，用于演示冲突检测：

使用 nature-academic-search 核验：
Smith et al. (2024). Large language models for clinical diagnosis. Nature.
DOI: 10.1038/nature14539
将题名、首位作者、年份和期刊作为 expected，逐项比较真实元数据；
保留冲突及来源链接，不要因为 DOI 可解析就判定引用正确。

该 DOI 对应 Deep learning（2015）；示例应出现 mismatch。查看完整核验记录

3. PubMed / MeSH 检索

使用 nature-academic-search 为“生成式 AI 与医学教育”设计 PubMed 起始检索式。
先用 lookup_mesh 核对 Artificial Intelligence、Generative Artificial Intelligence、
Education, Medical 的规范主题词和 MeSH ID，再组合 MeSH 与题名/摘要自由词。
输出核词结果、最终检索式和仍需补充的同义词；PubMed 专用语法只用于 PubMed。

得到：核验过的主题词和可继续调整的检索式。查看案例

4. 上下游引文追踪

使用 nature-academic-search 解析 DOI 10.1038/nature14539。
调用 get_paper_by_id，设置 include_relations=true、relation=both、depth=1、rows=10。
分别解释它引用了哪些论文、哪些论文引用了它，保留每条边的 observed_by；
报告失败来源、缺少的关系方向和截断原因，将 citation_graph 保存为 graph.json。

得到：结构化 nodes / edges。references 指“它引用了谁”，cited_by 指“谁引用了它”； 边始终采用 citing → cited 方向。工具返回 JSON，图形展示需要客户端或其他可视化工具另行生成。

5. 综述整理

使用 nature-academic-search，为“数字疗法对抑郁症的随机对照试验”拟定检索计划。
记录检索式、数据库、日期、纳入排除标准，等我确认后再检索。
对候选逐条调用 get_paper_by_id 并传 expected 核验，只将 verified 记录导出为 RIS；
把冲突、未找到和人工待处理记录单独列出。初筛建议不代表最终纳入决定。
若使用 CLI workflow，需要筛选时启用 screen；无需模型初筛时省略 screen，直接导出核验通过记录。

得到：计划、候选集、核验清单和引用文件。CLI 的具体行为见批量工作流。

6. 临床试验关联

使用 nature-academic-search，以英文关键词检索肺癌新辅助免疫治疗相关试验。
调用 search_papers(entity_type="trial")，按 NCT ID 整理试验状态、干预和申办方，
再根据返回状态标出正在招募的记录。若包含 linked publications，单独核验其 PMID / DOI；
试验注册和已发表论文分开列出，不把注册状态当作疗效结果。

得到：ClinicalTrials.gov 注册记录，以及需要另行解析的关联论文线索。

工具与命令

四个 MCP 工具

客户端可能添加工具名前缀。以下为服务端名称：

支持 DOI、PMID、PMCID、arXiv、OpenAlex、Semantic Scholar 和 NCT 等标识符； 原始 Semantic Scholar ID 应显式指定 id_type="semantic_scholar"。 NCT 用于试验查询，不生成论文引用。图谱通过 get_paper_by_id 返回，不需要额外安装工具。

{
  "query": "generative AI medical education",
  "sources": ["crossref", "pubmed", "europe_pmc"],
  "rows": 5,
  "filters": {"date_from": "2022-01-01", "date_to": "2026-09-09"},
  "ranking": "relevance"
}

{
  "id": "10.1038/nature14539",
  "expected": {"title": "Deep learning", "year": 2015, "journal": "Nature"}
}

{
  "id": "10.1038/nature14539",
  "include_relations": true,
  "relation": "both",
  "depth": 1,
  "rows": 10,
  "relation_sources": ["openalex", "crossref", "pubmed", "europe_pmc"]
}

CLI 示例

发布版可用：

nature-academic-search --help
nature-academic-search preflight
nature-academic-search citation --pmid 28344011 --format ris --output references/
nature-academic-search citation --input refs.txt --format bib --output references/

refs.txt 每行使用带类型前缀的标识符，例如：

DOI:10.1038/nature14539
PMID:28344011
ARXIV:1706.03762

没有类型前缀的行会被当作 PubMed 自由文本查询，而非标识符直接解析。 citation --output 指定的是目录，批量命令会生成各条记录的引用文件。 支持 nbib、ris、bib、enw；下载或格式转换不会自动对你原先的引用做 expected 核验。 给其他 MCP 客户端接入时，启动命令为 nature-academic-search-mcp，也可用 nature-academic-search serve（stdio）。

0.3.1 源码版及后续发布包：

nature-academic-search search "generative AI medical education" \
  --sources crossref,pubmed --rows 5 > search-results.json

nature-academic-search verify 10.1038/nature14539 \
  --expected-title "Deep learning" --expected-year 2015 --expected-journal "Nature" \
  > verification.json

nature-academic-search search "lung cancer neoadjuvant immunotherapy" \
  --entity-type trial --rows 5 > trials.json

CLI search 默认 --ranking relevance。日期等 filters 和引文图谱参数目前通过 MCP / workflow 配置， 没有对应的 search --filters 或 verify --include-relations 选项。 脚本调用后仍需检查 JSON 中的 errors 和 verification.status，退出码为 0 不代表所有来源成功或引用匹配。

批量工作流

YAML workflow 保存检索配置、生成计划，并按候选的强标识符重新查询元数据、逐字段核验。 从 0.3.1 起，CLI 自动执行回查核验；缺少标识符、字段不足或来源失败时仍保留人工待处理状态。 默认只导出 verified 论文；启用 screen 时还必须获得明确的 include 决定。 核验范围记录在 fields、lookup_id / lookup_id_type。来源未提供的附加 ID 列入 unchecked_identifiers，保留在原始结果中；RIS 只写入已匹配的 DOI / PMID。 搜索列表末尾的 et al. 视为作者截断提示，不当作作者比较或导出。

将以下内容保存为 review.yml。question 会直接作为搜索查询，因此先使用英文关键词； runner 不会自动把中文问题翻译成数据库检索式。

workflow: medical-education-scoping
question: "generative AI medical education"
steps: [plan, search, verify, export]
search:
  entity_type: publication
  sources: [crossref, pubmed, europe_pmc]
  rows: 5
  filters:
    date_from: "2022-01-01"
    date_to: "2026-09-09"
  ranking: relevance
verification:
  include_statuses: [verified]
privacy:
  allow_full_text: false

这是不需要模型的检索、核验、导出流程。需要摘要级初筛时，在 steps 中加入 screen： [plan, search, verify, screen, export]，并配置下方的可选模型层。

# 先生成 plan.json，查看检索范围
nature-academic-search workflow run --file review.yml --output artifacts/review-01

# 确认配置后重新执行，加 --approve 才开始查询学术源
nature-academic-search workflow run --file review.yml --output artifacts/review-01 --approve

每次独立运行使用新输出目录，避免覆盖上次文件。有 screen 时，exclude、pending_manual、 缺失或无效的筛选决定均不进入 RIS；模型未配置或失败时，记录保留在审计文件中等待人工处理。 screening.csv 是本次筛选输出，手动修改它不会在重跑时自动导入。省略 screen 则只应用核验白名单。 试验注册保留在 JSON 中，不作为论文导出到 RIS。模型筛选仍需人工复核。 completed / completed_with_skips 是流程状态，仍需查看 results.json 的来源错误和实际产物。

如何读懂结果

检索结果

保存完整响应，尤其是 search_run 和 errors。多源失败时仍可能返回部分记录； “拿到了结果”与“五个源全部成功”是两种情况。

引用核验

网络失败可能直接返回 error，不能解释成论文不存在。 核验比较的是书目信息，不判断研究质量，也不证明论文支持某句话。

数据源如何分工

未连接 Google Scholar、Web of Science、Scopus、Embase、CNKI、万方。 数据库收录范围及关系覆盖不同；缺少接口或没有返回引用边，不表示该论文从未被引用。 不同来源的 citation_counts 不相加为“全网引用数”。

环境变量

本项目从进程环境和可选 TOML 读取配置，不会自动加载 .env 文件。 源 API 的密钥与下方的模型密钥用途不同；密钥不要写入仓库或检索结果。

WPIRONMAN AI 中转：可选模型层

WPIRONMAN AI 中转 为模型请求提供 OpenAI-compatible HTTP 入口。 当前 workflow runner 用它执行摘要级 screen 辅助；plan.json 由 YAML 本地生成， 研究问题和计划也可先在客户端与 AI 讨论，再写入配置。

export ACADEMIC_SEARCH_LLM_BASE_URL=https://api.wpironman.top/v1
export ACADEMIC_SEARCH_LLM_API_KEY=your-relay-key
export ACADEMIC_SEARCH_LLM_MODEL=your-model
export ACADEMIC_SEARCH_LLM_PROTOCOL=responses_http

将占位值替换成自己的配置。responses_http 使用普通 HTTP，不要求 WebSocket； 也支持 chat_completions。这些变量配置的是本项目 runner，不会替你修改客户端的模型设置。

默认发送标题、摘要、标识符等允许的元数据；只有设置 privacy.allow_full_text: true 才允许附带全文。 未配置模型或模型请求失败时，筛选步骤会跳过并保留人工待处理项，学术源检索仍可继续。

中转不提供 Crossref、PubMed 或其他论文数据库覆盖，不负责 DOI 真实性、字段核验或研究质量判断。

常见问题

lookup_mesh 的 ESummary 解析修复已包含在 PyPI 0.3.0 与插件固定版本中； 仍遇到旧行为时，检查客户端实际加载的 Skill / MCP 版本及是否存在重复安装。

能力边界

• 检索与元数据为主：不保证获取付费全文；摘要级整理不能替代原文阅读。
• 候选发现有数量上限：当前接口不是全库穷尽导出，不能直接把一次检索称为完成系统综述。
• 来源冲突保留待查：强标识符优先去重，弱题名匹配仍需人工确认；预印本、正式发表版本和试验注册要区分。
• 引用关系用于导航：图谱边、引用次数和相关性分数都不表示证据质量、因果关系或结论支持。
• 输出需要复核：正式提交前核对出版社元数据、原文和目标期刊的引用要求。

文档与开发

运行时源码位于 src/nature_academic_search/；plugins/nature-academic-search/ 保存客户端插件包， mcp-server/ 与 scripts/ 保留兼容入口。贡献前可运行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'
python -m ruff check src tests
python -m pytest
python -m pytest mcp-server/tests

提交 Issue 时请附安装方式、版本、最小查询、 失败来源和脱敏错误信息。修改代码时保留四个 MCP 工具名、实体边界和来源审计字段，并补充相关回归测试。

第三方收录：TensorBlock MCP Server Directory。 如果这个项目帮助你更可靠地整理文献，欢迎 Star 或提交改进建议。

License

MIT