Paper Search CLI

简体中文 | English

Paper Search CLI 是一个面向 AI agent 的 Skill + CLI 包，基于独立的 Node.js 命令行工具构建，用于学术文献工作。它为 AI agent、终端用户和脚本提供一个可复现的命令层，并通过 agent 友好的 JSON 输出覆盖文献元数据检索、施引/参考文献扩展、期刊指标检索、PDF 获取/下载和论文正文片段检索。

快速开始 | 架构说明 | 配置 | Agent Skill | 支持平台 | 命令 | 排障

核心功能

| 功能 | 主要命令 | 返回内容 | | --- | --- | --- | | 文献元数据检索 | paper-search search, paper-search run search_* | 题名、作者、年份、期刊、DOI、PMID/PMCID、arXiv ID、URL、摘要和来源元数据 | | 引文扩展 | paper-search run get_paper_citations, paper-search run get_paper_references | 已知 Semantic Scholar paper ID、DOI 或 arXiv ID 对应论文的施引文献和参考文献 | | 期刊指标检索 | paper-search journal-metrics, paper-search run query_journal_metrics | 影响因子、5 年 IF、JCR/SSCI 分区、中科院分区、JCI、ESI、预警和等级字段 | | PDF 获取和下载 | paper-search download, paper-search run download_with_fallback | 通过原生来源、开放获取、已配置权限来源和启用时的 Sci-Hub fallback 获取 PDF | | 正文片段检索 | paper-search run search_semantic_snippets | Semantic Scholar Open Access 正文片段，用于查方法、参数和写法线索 |

架构说明

paper-search 不是 MCP Server，而是普通 CLI。AI 工具可以通过随包发布的 Skill 调用它，终端用户和脚本也可以直接调用同一个 paper-search 命令。

| 层 | 负责什么 | | --- | --- | | CLI 本体 | 执行文献检索、引文扩展、期刊指标检索、PDF 获取/下载、正文片段检索和稳定 JSON 输出 | | Bundled Skill | 随包发布 skills/paper-search，提供 agent 路由规则和 focused references；不保存密钥、cookie 或账号信息 | | Friendly Management Layer | 围绕五个主要能力 metadata_search、citation_expansion、journal_metrics、pdf_discovery、body_snippet_search 提供 doctor、smoke、skills、config、tools。doctor 健康报告包含脱敏配置、Capability Profile、平台/来源状态、缺失项和降级项；smoke 检查命令入口连通性和 live 可用性；skills 负责同步随包发布的 Skill |

五个主要能力由 CLI 本体执行，由管理层报告和检查。Capability Profile 也会报告 entitled_access，让用户看到出版商 API key、数据库 key、TDM token 或机构权限是否已配置。某一个能力缺少配置或降级，不会导致其他独立能力不可用。

快速开始

要求 Node.js >= 18.0.0 和 npm。

npm install -g paper-search-cli
paper-search setup
paper-search doctor --pretty

尝试五个主要功能：

paper-search search "machine learning clinical prediction" --platform crossref --max-results 3 --pretty
paper-search run get_paper_citations --arg doi="10.1038/nature12373" --arg limit=5 --pretty
paper-search journal-metrics "Nature" "BMJ" --pretty
paper-search download 10.48550/arxiv.1201.0490 --platform arxiv --save-path ./downloads
paper-search run search_semantic_snippets --arg query="propensity score matching" --arg limit=3 --pretty

常用检查：

paper-search tools --pretty
paper-search doctor --format text
paper-search smoke --mock --pretty
paper-search skills status --pretty

支持平台

平台组表适合快速选来源；下面的能力矩阵用于更清楚地判断每个平台实际能做什么。

平台组

| 平台组 | 平台 | 主要用途 | | --- | --- | --- | | 综合学术元数据 | Crossref, OpenAlex, Semantic Scholar, Google Scholar | 广覆盖发现、DOI 元数据、引用线索、文献初筛 | | 期刊指标 | EasyScholar | 影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警 | | 生物医学和生命科学 | PubMed, PubMed Central, Europe PMC | 生物医学元数据、PMID/PMCID 核验、开放全文 | | 预印本和会议稿 | arXiv, bioRxiv, medRxiv, OpenReview, IACR ePrint | 预印本、AI/ML 投稿、密码学 ePrint | | 计算机和工程 | DBLP, ACM metadata, IEEE Xplore, USENIX | CS 目录、工程元数据、会议论文 | | 开放获取和仓储 | CORE, OpenAIRE, Unpaywall | 仓储发现和开放获取 PDF fallback | | 引文库和出版商 | Web of Science, Scopus, ScienceDirect, Springer Nature/SpringerLink, Wiley | 机构权限元数据、出版商记录、entitled access | | DOI 定向 fallback | Sci-Hub | 启用时作为 DOI 定向 PDF fallback |

能力矩阵

综合学术元数据

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | Crossref | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ✅ 支持 | ❌ 不需要 | 默认广覆盖元数据来源 | | OpenAlex | ✅ 支持 | 🟡 条件支持 | ❌ 不支持 | ✅ 支持 | ❌ 不需要 | 免费元数据；记录含 OA 链接时可帮助 PDF fallback | | Semantic Scholar | ✅ 支持 | 🟡 条件支持 | ✅ 正文片段 | ✅ 支持 | 🟡 可选；正文片段需要 SEMANTIC_SCHOLAR_API_KEY | 适合 AI/CS、引文扩展和正文片段线索 | | Google Scholar | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ✅ 支持 | ❌ 不需要 | 基于页面解析的广覆盖发现 |

期刊指标

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | EasyScholar | 🟡 仅期刊指标 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ✅ 必需 EASYSCHOLAR_KEY | 影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警和等级字段 |

生物医学和生命科学

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | PubMed | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | 🟡 可选 PUBMED_API_KEY, NCBI_EMAIL, NCBI_TOOL | NCBI E-utilities 生物医学元数据 | | PubMed Central | ✅ 支持 | ✅ 支持 | ✅ 支持 | ❌ 不支持 | ❌ 不需要 | 生物医学开放全文和 PMC PDF | | Europe PMC | ✅ 支持 | 🟡 条件支持 | 🟡 条件支持 | ❌ 不支持 | ❌ 不需要 | 生物医学元数据和开放全文链接 |

预印本和会议稿

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | arXiv | ✅ 支持 | ✅ 支持 | ✅ 支持 | ❌ 不支持 | ❌ 不需要 | 物理、计算机、数学等预印本 | | bioRxiv | ✅ 支持 | ✅ 支持 | ✅ 支持 | ❌ 不支持 | ❌ 不需要 | 生物学预印本 | | medRxiv | ✅ 支持 | ✅ 支持 | ✅ 支持 | ❌ 不支持 | ❌ 不需要 | 医学预印本 | | OpenReview | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不需要 | 公开 OpenReview notes、评审和投稿记录 | | IACR ePrint | ✅ 支持 | ✅ 支持 | ✅ 支持 | ❌ 不支持 | ❌ 不需要 | 密码学 ePrint 论文 |

计算机和工程

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | DBLP | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不需要 | 官方 DBLP 计算机文献目录 | | ACM metadata | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ✅ 支持 | ❌ 不需要 | 通过 Crossref 的 ACM DOI 前缀元数据检索；不抓取 ACM 页面 | | USENIX | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不需要 | 基于 DBLP 的 USENIX 元数据；不抓取 USENIX 搜索页 | | IEEE Xplore | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ✅ 支持 | ✅ 必需 IEEE_API_KEY | 官方 IEEE Xplore Metadata API |

开放获取和仓储

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | CORE | ✅ 支持 | 🟡 条件支持 | 🟡 条件支持 | ❌ 不支持 | 🟡 可选 CORE_API_KEY | 仓储记录可能暴露 PDF 或全文链接 | | OpenAIRE | ✅ 支持 | 🟡 条件支持 | ❌ 不支持 | ❌ 不支持 | 🟡 可选 OPENAIRE_API_KEY | 公开检索通常不需要 key | | Unpaywall | 🟡 仅 DOI 查询 | 🟡 条件支持 | ❌ 不支持 | ❌ 不支持 | ✅ 必需 UNPAYWALL_EMAIL 或 PAPER_SEARCH_UNPAYWALL_EMAIL | DOI 开放获取 PDF 定位；需要邮箱，不是 API key |

引文库和出版商

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | Web of Science | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ✅ 支持 | ✅ 必需 WOS_API_KEY | 引文数据库元数据、日期排序、年份范围 | | ScienceDirect | ✅ 支持 | 🟡 条件支持 | ❌ 不支持 | ✅ 支持 | ✅ 必需 ELSEVIER_API_KEY | Elsevier 元数据；ScienceDirect 和 Scopus 产品权限需要分别开通 | | Springer Nature / SpringerLink | ✅ 支持 | 🟡 条件支持 | ❌ 不支持 | ❌ 不支持 | ✅ 必需 SPRINGER_API_KEY；🟡 可选 SPRINGER_OPENACCESS_API_KEY | springerlink 是现有 Springer 集成的别名 | | Wiley | ❌ 不支持关键词搜索 | ✅ DOI 下载 | ✅ 支持 | ❌ 不支持 | ✅ 必需 WILEY_TDM_TOKEN | TDM API；先通过其他元数据来源找到 DOI 再下载 | | Scopus | ✅ 支持 | 🟡 条件元数据 | ❌ 不支持 | ✅ 支持 | ✅ 必需 ELSEVIER_API_KEY | 摘要和引文数据库；ScienceDirect 和 Scopus 产品权限需要分别开通 |

DOI 定向 fallback

| 平台 | 元数据检索 | PDF 路径 | 正文/全文 | 被引统计 | 配置 | 说明 | | --- | --- | --- | --- | --- | --- | --- | | Sci-Hub | ❌ 不支持 | ✅ 支持 | ❌ 不支持 | ❌ 不支持 | ❌ 不需要 | DOI/URL 定向查询；启用时作为 PDF 最后 fallback |

说明：

• 元数据检索指发现和初筛论文，不等于 PDF 下载或正文证据。
• pdf_discovery 会区分开放获取来源、已配置权限来源，以及单独标识的 Sci-Hub 最后 fallback。
• EasyScholar 是期刊指标来源，不是论文检索来源。
• Sci-Hub 不属于 metadata_search，只作为 DOI/URL 定向 PDF fallback。
• 🟡 条件支持 表示只有记录暴露 DOI、开放获取链接、PDF URL，或用户配置了相应权限时才可用。
• API key 只在使用对应 key-backed 来源或工作流时才需要。

配置

多数免费元数据来源无需配置。为了稳定支持 agent 工作流，建议先运行 setup，把凭证写入用户级配置：

paper-search setup
paper-search config list --pretty
paper-search doctor --pretty

默认配置路径：

~/.config/paper-search-cli/config.json

配置文件权限会写成 0600。config list、doctor 和相关命令都会脱敏密钥。

API Key 分级

| 等级 | 配置项 | 用途 | 什么时候配置 | | --- | --- | --- | --- | | 多数用户推荐 | SEMANTIC_SCHOLAR_API_KEY | 正文片段检索，以及更稳定的 Semantic Scholar 请求 | 需要查方法细节或高频使用 Semantic Scholar 时配置 | | 多数用户推荐 | UNPAYWALL_EMAIL 或 PAPER_SEARCH_UNPAYWALL_EMAIL | DOI 开放获取 PDF 解析 | setup 时配置；需要的是邮箱，不是 API key | | 多数用户推荐 | CROSSREF_MAILTO | Crossref polite pool | 长任务或高频元数据检索时配置 | | 多数用户推荐 | CORE_API_KEY | CORE 仓储检索 | 依赖 CORE 或遇到匿名限流时配置 | | 期刊指标 | EASYSCHOLAR_KEY | EasyScholar 影响因子、JCR/SSCI、中科院分区、JCI、ESI、预警 | 需要期刊指标时配置；建议用 paper-search setup EASYSCHOLAR_KEY 隐藏输入 | | 生物医学高频 | PUBMED_API_KEY, NCBI_EMAIL, NCBI_TOOL | NCBI E-utilities 稳定性和更高限额 | 高频使用 PubMed 时配置 | | 机构或出版商权限 | WOS_API_KEY, IEEE_API_KEY, ELSEVIER_API_KEY, SPRINGER_API_KEY, SPRINGER_OPENACCESS_API_KEY, WILEY_TDM_TOKEN | Web of Science、IEEE、Scopus、ScienceDirect、Springer、Wiley 元数据或权限访问 | 只有具备对应 API 或机构权限时配置 | | 通常可选 | OPENAIRE_API_KEY | OpenAIRE 账号或配额场景 | 公开检索通常不需要 |

常用申请入口：

| 服务 | 链接 | | --- | --- | | EasyScholar | EasyScholar Open API | | Semantic Scholar | Semantic Scholar API | | Unpaywall | Unpaywall API | | CORE | CORE API | | PubMed | NCBI API Keys | | Web of Science | Clarivate Developer Portal | | IEEE Xplore | IEEE Xplore Metadata API | | Elsevier | Elsevier Developer Portal | | Springer Nature | Springer Nature Developers | | Wiley TDM | Wiley Text and Data Mining | | OpenAIRE | OpenAIRE APIs |

Agent Skill

npm 包会随包发布 agent Skill，位置是 skills/paper-search/SKILL.md。终端用户可以只用 CLI；AI agent 工作流应安装或同步 Skill，让 agent 正确路由五个主要功能。

paper-search setup --install-skills agents
paper-search skills status --pretty
paper-search skills diff --targets agents --format text
paper-search skills update --targets agents --pretty

支持的 target 包括 agents、codex、claude、cursor、gemini、antigravity 和 all。Skill 更新会覆盖 package-managed Skill 文件，同时保留 installed Skill 目录里的 extra files。

Skill 只告诉 agent 如何调用 paper-search CLI。API key 仍然应通过 paper-search setup、paper-search config、.env 或 shell 环境变量配置。

命令

| 命令 | 用途 | | --- | --- | | paper-search search | 集成式元数据检索 | | paper-search journal-metrics | EasyScholar 期刊指标检索 | | paper-search download | 对已核验 paper ID 或 DOI 下载 PDF | | paper-search run | 用 --arg 或 --json-args 精确调用工具 | | paper-search tools | 运行时工具名和 schema | | paper-search doctor | 脱敏配置、Capability Profile 和平台状态 | | paper-search smoke | mock 或 live 自检 | | paper-search skills | Bundled Skill 状态、diff 和同步 | | paper-search config | 用户级配置管理 |

完整命令和工具 schema：运行 paper-search tools --pretty，或查看 skills/paper-search/references/cli-contract.md。

输出

命令默认返回 JSON。需要格式化 JSON 时使用 --pretty；需要可读报告时再使用 --format text。

paper-search search "machine learning" --platform crossref --max-results 1 --pretty
paper-search doctor --format text

排障

| 问题 | 首先检查 | | --- | --- | | 找不到命令 | 用 npm install -g paper-search-cli 重新全局安装 | | 能力缺失 | 运行 paper-search doctor --pretty，再用 paper-search setup 配置缺失 key | | 平台限流 | 降低 --max-results，配置对应 key，或切换来源 | | Skill 似乎过期 | 运行 paper-search skills status --pretty，再运行 paper-search skills update --targets agents --pretty | | 需要完整 CLI 细节 | 运行 paper-search tools --pretty |

使用边界

部分来源可能受平台条款、机构订阅或本地法律约束。只有在具备相应访问权和授权时才使用受限集成。

项目来源

本项目感谢 LinuxDo 社区。CLI + Skill 路线和 paper-search 工作流改进来自社区交流与开源分享。

本项目也参考了 openags/paper-search-mcp 的思路，并将工作流调整为独立 CLI。

License

MIT