Academic Paper Search

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

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

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

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

这是什么

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

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

组成	做什么	什么时候需要
Skill	指导 AI 拆解问题、选数据库、核对字段、报告来源与缺口	希望直接用自然语言安排检索任务
MCP 服务	提供 4 个工具，实际查询学术 API、解析标识符、生成引用、查 MeSH	让 Codex、Claude Code 等客户端调用工具
CLI	在终端运行连通性检查、引用下载、YAML 工作流；源码版另有 search / verify	批量任务、脚本调用和本地调试

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

flowchart LR
    Q[研究问题] --> P[英文关键词 / MeSH 检索式]
    P --> S[多源检索与去重]
    S --> V[标识符与字段核验]
    V --> E[引用文件与核验记录]
    S --> G[可选：上下游引文图谱]

你会得到带来源的候选论文、字段级核验结果、可导入 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；也不保证每次检索都成功。

Python 包 / 手动注册 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

--client 可选 codex、claude、both；仅当两者都已安装时使用 both。 安装器复制 Skill，并通过客户端 CLI 注册 MCP；会更新所选客户端中已有的同名注册。 已经通过插件安装的用户通常无需再重复注册。只用终端时，跳过 install --client 即可。

源码版：使用本次 0.3.1 修复与 search / verify 命令

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

也可从仓库一次完成源码安装和客户端注册，按需将 both 改为 codex 或 claude：

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

版本说明： 0.3.1 包含 CLI search / verify、自动 workflow 核验和筛选导出修复， 包版本和本仓库插件配置统一为 0.3.1。旧 PyPI 0.3.0 不包含这两个 CLI 命令， 也没有本次 workflow 修复。升级 CLI 可运行 uv tool upgrade nature-academic-search； 插件用户还需更新插件并开启新会话，仅升级 CLI 不会改变已安装插件的固定运行时。

DeepSeek Harness

使用独立的 dsh-academic-paper-search Bundle。 它桥接同一套 Python MCP 服务，工具显示为 mcp__academic_search__*。 安装要求、发布状态和配置步骤以该仓库为准。

更多配置见安装文档。

[!IMPORTANT] 安装后下一步：配置可选模型入口

如果要启用 workflow 的计划或筛选辅助，请先阅读模型层说明： 当前 runner 自动调用模型的是 screen 步骤，plan.json 由本地配置生成。 进入 WPIRONMAN 控制台 →。不配置中转也能使用学术检索工具。

直接这样问

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

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

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

六个可复制的中文场景

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

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 工具

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

工具	用途	关键参数
search_papers	多源检索、去重、过滤与相关性排序	query、sources、rows、filters、ranking、entity_type、enrich
get_paper_by_id	解析标识符；可选字段核验和引文图谱	id、id_type、expected、include_relations、relation、depth、relation_sources
get_citation	生成单条格式化引用	id、id_type、style，如 apa、nature、vancouver
lookup_mesh	查询 MeSH 规范主题词	term

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

以下是传给相应 MCP 工具的 JSON 参数，不是终端命令。

按日期检索并排序 — search_papers：

{
  "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"
}

rows 是每个来源的返回上限，检索范围为 1–50；去重、过滤后的总数可能更少。 省略 sources 使用默认五源，显式指定时只查询所选来源。 filters 还支持 language、author、document_type、identifiers；缺失必要字段的记录可能被过滤掉。 相关性排序是本地规则评分，会写入 ranking_score、ranking_reasons 和 score_version。

核对真实引用 — get_paper_by_id：

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

只提供 id 时是元数据查询；提供 expected 才增加 verification。 只核对传入的字段，不能把“题名匹配”表述为“整条引用已全部核验”。

获取一跳关系 — get_paper_by_id：

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

图谱的 rows 是每个来源、每个方向的邻居上限（1–100）；depth 支持 1 或 2。 还受节点和边预算限制，判断是否完整请检查 truncated、truncation_reason、depth_completed。

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

文件	内容与用途
plan.json	从 YAML 生成的计划；未批准时只生成此文件
results.json	检索结果、来源状态、错误与 search_run
verification.json	每条候选按标识符回查后的字段核验状态
screening.csv	初筛建议；未配置模型时为 pending_manual
references.ris	按核验白名单选择论文；有 screen 时还需筛选为 include
report.md / run.json	汇总说明、实际导出数 exported_count、运行时间、产物列表、步骤状态与错误
graph.json	可选；在 steps 中加入 expand_citations 后生成

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

如何读懂结果

检索结果

字段	如何理解
sources_queried / sources_succeeded	实际尝试的来源 / 成功响应的来源；成功也可能返回 0 条
sources_skipped / errors	跳过的操作及原因 / 请求失败详情；未选择的来源不一定出现在 skipped 中
raw_result_count / result_count	本次取回的原始记录数 / 去重、过滤后的交付数；不是完整文献库规模
record_id	记录的稳定标识，优先由 DOI、PMID 等强标识符构造
sources / source_records / conflicts	合并记录的来源、逐源记录和字段冲突
search_run	查询、UTC 时间、范围、来源状态、过滤与排序信息
result_fingerprint	基于记录 ID 的结果集合指纹；不能替代原始 JSON 存档

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

引用核验

verification.status	表示什么	下一步
verified	本次提供的 expected 字段与解析元数据匹配	保留核验字段与来源；引用科学结论前还需读原文
mismatch	至少一个字段不一致	查看 fields 中的预期值和实际值，检查错引或版本差异
not_found	标识符查询明确报告未找到记录	检查标识符、原始出处和其他来源
manual_needed	缺少字段、字段不可核对，或流程尚需人工处理	补充信息并人工复查

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

数据源如何分工

来源	代码中的名称	启用方式	主要用途与关系覆盖
CrossRef	crossref	默认论文源	DOI、出版元数据、引用格式；提供 references
PubMed	pubmed	默认论文源	生物医学、PMID、MeSH；ELink 提供可用的双向引用关系
arXiv	arxiv	默认论文源	预印本及版本线索；当前不提供引用边
OpenAlex	openalex	默认论文源	跨学科发现、开放获取信息；references / cited_by
Europe PMC	europe_pmc	默认论文源	PMID / PMCID、生物医学记录；当前适配器提供 references
Semantic Scholar	semantic_scholar	显式搜索、enrich 或图谱	补充元数据、来源化引用计数和双向关系
ClinicalTrials.gov	clinicaltrials_gov	entity_type="trial"	NCT、招募状态、干预、申办方及关联论文线索

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

环境变量

变量	用途
PUBMED_EMAIL	PubMed 联系邮箱；客户端安装器要求提供
NCBI_API_KEY	可选 NCBI 凭据
CROSSREF_MAILTO	可选 CrossRef 联系邮箱
OPENALEX_API_KEY	OpenAlex 凭据；可用权限和配额以上游要求为准
SEMANTIC_SCHOLAR_API_KEY	Semantic Scholar 凭据；未配置时其 credentialed preflight 检查会跳过
NATURE_ACADEMIC_SEARCH_CONFIG	可选 TOML 配置文件路径

本项目从进程环境和可选 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 真实性、字段核验或研究质量判断。

常见问题

现象	检查与处理
uvx / nature-academic-search 找不到	确认 uv 或 Python 工具已安装，且客户端启动环境的 PATH 包含相应命令；重开终端或客户端
安装后看不到工具	开启新会话，检查插件是否启用、MCP 是否启动；手动注册方式可用 codex mcp get nature-academic-search --json 或 claude mcp get nature-academic-search 检查配置
已 export 邮箱，桌面端仍读不到	终端环境不一定传给桌面进程；可使用 install --client codex/claude --email ... 注册带邮箱的本地 MCP，注意避免与插件重复启用
search / verify 提示无效命令	PyPI 0.3.0 尚未包含这两个子命令；安装当前源码，或通过客户端调用同名用途的 MCP 工具
部分来源超时、429 或鉴权失败	查看 preflight 和返回的 errors；检查网络、来源凭据与配额，降低 rows，稍后只重试失败来源
中文查询结果少或不相关	先把问题转成英文关键词，生物医学任务先核对 MeSH；本地相关性排序不负责翻译
workflow 已完成，但 RIS 是空的	查看 verification.json、screening.csv 和 exported_count。只有允许的核验状态且筛选纳入的论文才导出；无模型时可省略 screen。旧版 0.3.0 需升级以接通自动回查

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

能力边界

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

文档与开发

入口	内容
安装与配置	客户端注册、源码安装和环境配置
Skill 指令	AI 执行任务时的路由、步骤与证据规则
检索工作流	查询构造、过滤、去重、图谱和核验流程
来源分层 / 引用文件	数据源边界和文件格式
维护手册	测试、打包、插件校验与发布步骤

运行时源码位于 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