[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81441":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},81441,"paper-search-cli","dr-dumpling\u002Fpaper-search-cli","dr-dumpling","Agent-friendly CLI for academic paper, journal metric search and paper download",null,"TypeScript",72,7,32,1,0,17,40,8,2.71,"MIT License",false,"main",[],"2026-06-12 02:04:15","# Paper Search CLI\n\n[English](README-en.md)\n\nPaper Search CLI 是一个独立的 Node.js 命令行工具，用于跨多个学术来源检索论文、核验元数据、EasyScholar 检索影响因子和期刊分区等信息、下载 PDF。它面向终端直接使用、自动化脚本和 agent 工作流，提供稳定命令入口和可预测的 JSON 输出。\n\n![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode.js->=18.0.0-green.svg)\n![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftypescript-^5.5.3-blue.svg)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)\n![Platforms](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatforms-25-brightgreen.svg)\n![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-0.2.0-blue.svg)\n[![LinuxDo](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLinuxDo-community-1f6feb)](https:\u002F\u002Flinux.do)\n\n感谢真诚、友善、团结、专业的 [LinuxDo](https:\u002F\u002Flinux.do) 社区。本项目的 CLI + Skill 路线和论文检索工作流改进，来自社区交流与开源分享的启发。\n\n[快速开始](#快速开始) · [配置](#配置) · [Agent Skill](#agent-skill) · [支持的平台](#支持的平台) · [命令](#命令) · [工具参考](#工具参考) · [排障](#排障)\n\n## 设计目标\n\n- **免费来源优先**：优先使用公开元数据和开放获取全文路径，再考虑受限或不稳定来源。\n- **单一命令入口**：检索、状态检查、下载和精确工具调用都收口到同一个可执行命令。\n- **适合 agent 解析**：默认输出稳定 JSON，避免让调用方解析终端文本。\n- **来源能力透明**：明确区分哪些平台只能提供元数据、哪些能下载 PDF、哪些需要 API key。\n- **无后台服务负担**：每次调用只执行一个命令，返回结果后退出。\n\n## 核心特性\n\n- **25 个学术来源\u002F平台**：Crossref、OpenAlex、PubMed、PubMed Central、Europe PMC、arXiv、bioRxiv、medRxiv、Semantic Scholar、CORE、OpenAIRE、DBLP、ACM Digital Library 元数据、USENIX 元数据、OpenReview、Web of Science、Google Scholar、IACR ePrint、Sci-Hub、IEEE Xplore、ScienceDirect、Springer Nature\u002FSpringerLink、Wiley、Scopus、Unpaywall。\n- **影响因子与期刊分区检索**：通过 EasyScholar，检索影响因子、5 年影响因子、JCR\u002FSSCI 分区、中科院分区、JCI、ESI、预警字段，以及可选的官方\u002F自定义原始等级字段等。\n- **PDF 下载支持**：支持 arXiv、bioRxiv、medRxiv、Semantic Scholar、IACR、Sci-Hub、Springer 开放获取、Wiley DOI 下载等路径。\n- **正文片段检索**：用于检索论文正文片段，数据来源于 Semantic Scholar 中，适合查找论文中的方法学细节等。\n- **适合 agent 调用**：`tools`、`status`、`search`、`journal-metrics`、`download`、`run` 覆盖简单检索和精确工具调用。\n\n## 快速开始\n\n### 安装\n\n要求 Node.js >= 18.0.0 和 npm。\n\n```bash\nnpm install -g paper-search-cli\npaper-search setup\npaper-search search \"machine learning\" --platform crossref --max-results 3 --pretty\n```\n\n安装后运行 `paper-search setup`，即可把可选 API key 和 email 写入用户级配置。\n其中 Unpaywall 和 Crossref 的邮箱项可以直接回车跳过，CLI 会自动写入一个随机前缀的 Gmail 格式邮箱；如果你想使用自己的邮箱，后续再用 `paper-search config set` 覆盖即可。\n\n如果你需要本地开发版，或要验证尚未发布的改动，可以从源码安装：\n\n```bash\ngit clone git@github.com:dr-dumpling\u002Fpaper-search-cli.git\ncd paper-search-cli\nnpm install\nnpm run build\nnpm install -g .\n```\n\n### 常用检查\n\n```bash\npaper-search status --pretty\npaper-search tools --pretty\npaper-search config doctor --pretty\n```\n\n## 支持的平台\n\n### 平台类型\n\n下面的能力表仍然是平台能力的准确信息来源。除 25 个论文检索\u002F获取来源外，CLI 还提供 EasyScholar 影响因子、期刊分区等检索；EasyScholar 不参与 `platform=all` 或 `--sources`，应使用 `journal-metrics` \u002F `query_journal_metrics` 调用。\n\n如果只是快速选择检索来源或查询工具，可以先按这些类型判断：\n\n| 类型 | 平台 | 适合场景 |\n| --- | --- | --- |\n| 综合检索 | Crossref、OpenAlex、Semantic Scholar、Google Scholar | 广覆盖发现、DOI 元数据、引用线索、文献初筛 |\n| 影响因子\u002F期刊分区 | EasyScholar | 影响因子、5 年影响因子、JCR\u002FSSCI 分区、中科院分区、JCI、ESI、预警和等级信息 |\n| 医学\u002F生命科学 | PubMed、PubMed Central、Europe PMC | 临床、生物医学、公卫、生物医学元数据和开放全文 |\n| 预印本\u002F会议稿 | arXiv、bioRxiv、medRxiv、OpenReview、IACR ePrint | 跨学科预印本、生命科学\u002F医学预印本、AI\u002FML 投稿和密码学 ePrint |\n| 计算机\u002F工程 | DBLP、ACM Digital Library 元数据、IEEE Xplore、USENIX | CS 文献目录、工程数据库、系统\u002F安全会议论文 |\n| 开放全文\u002F仓储 | CORE、OpenAIRE、Unpaywall | 跨学科仓储发现和开放获取 PDF 回退路径 |\n| 引文库\u002F出版商 | Web of Science、Scopus、ScienceDirect、Springer Nature\u002FSpringerLink、Wiley | 机构权限型元数据、引文数据库、出版商记录和下载 |\n| DOI 定向获取 | Sci-Hub | DOI 定向获取，并作为 PDF 下载漏斗的最后自动兜底；除非传入 `useSciHub=false` |\n\n部分平台会跨多个实际工作流。例如 Semantic Scholar 既适合广覆盖检索，也常用于 CS\u002FAI；arXiv 覆盖计算机、数学、物理和部分定量学科。这里按主要使用方式归类；做计算机方向检索时，通常会同时用“计算机\u002F工程”和“预印本\u002F会议稿”两组。\n\n### 能力矩阵\n\n#### 综合检索\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| Crossref | ✅ | ❌ | ❌ | ✅ | ❌ | 默认搜索平台，广泛元数据覆盖 |\n| OpenAlex | ✅ | 🟡 条件支持 | ❌ | ✅ | ❌ | 广泛免费元数据；记录含开放链接时可用于回退下载 |\n| Semantic Scholar | ✅ | ✅ | ✅ 正文片段 | ✅ | 🟡 可选* | AI 语义检索 + OA 正文片段 |\n| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | 广泛学术发现，基于页面解析 |\n\n#### 影响因子与期刊分区\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| EasyScholar | ✅ 影响因子\u002F分区检索 | ❌ | ❌ | ❌ | ✅ 必需 | 影响因子、5 年影响因子、JCR\u002FSSCI 分区、中科院分区、JCI、ESI、预警字段，以及可选的官方\u002F自定义原始等级字段 |\n\n#### 医学\u002F生命科学\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| PubMed | ✅ | ❌ | ❌ | ❌ | 🟡 可选 | NCBI E-utilities 生物医学文献 |\n| PubMed Central | ✅ | ✅ | ✅ | ❌ | ❌ | 生物医学开放全文和 PMC PDF |\n| Europe PMC | ✅ | ✅ | ✅ | ❌ | ❌ | 生物医学元数据和开放全文链接 |\n\n#### 计算机\u002F工程\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| DBLP | ✅ | ❌ | ❌ | ❌ | ❌ | 通过官方 DBLP search API 检索计算机文献目录 |\n| ACM Digital Library | ✅ | ❌ | ❌ | ✅ | ❌ | 通过 Crossref 的 ACM DOI 前缀元数据检索；不抓取 ACM 页面 |\n| USENIX | ✅ | ❌ | ❌ | ❌ | ❌ | 基于 DBLP 的 USENIX 会议元数据；不抓取 USENIX 搜索页 |\n| IEEE Xplore | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 通过官方 IEEE Xplore Metadata API 检索 IEEE 元数据 |\n\n#### 开放全文\u002F仓储\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| CORE | ✅ | 🟡 条件支持 | 🟡 条件支持 | ❌ | 🟡 可选 | 记录含 PDF 或全文链接时可下载 |\n| OpenAIRE | ✅ | 🟡 条件支持 | ❌ | ❌ | 🟡 可选 | 记录含开放链接时可用于回退下载 |\n| Unpaywall | 🟡 条件支持 | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | 仅支持 DOI 查询；需要 email；发现 OA PDF 时可下载 |\n\n#### 预印本\u002F会议稿\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | 物理、计算机、数学等预印本 |\n| bioRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 生物学预印本 |\n| medRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 医学预印本 |\n| OpenReview | ✅ | ❌ | ❌ | ❌ | ❌ | 通过公开 OpenReview notes search 检索会议投稿、评审和预印本 |\n| IACR ePrint | ✅ | ✅ | ✅ | ❌ | ❌ | 密码学论文 |\n\n#### 引文库\u002F出版商\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 引文数据库、日期排序、年份范围 |\n| ScienceDirect | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | Elsevier 元数据和摘要 |\n| Springer Nature \u002F SpringerLink | ✅ | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | `springerlink` 是现有 Springer Nature 集成的别名 |\n| Wiley | ❌ 关键词搜索 | ✅ | ✅ | ❌ | ✅ 必需 | TDM API，仅支持 DOI 下载 PDF |\n| Scopus | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 摘要和引文数据库 |\n\n#### DOI 定向获取\n\n| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |\n| --- | --- | --- | --- | --- | --- | --- |\n| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | 基于 DOI 查询和下载 |\n\n说明：\n\n- 能力列中，`✅` 表示直接支持，`❌` 表示不支持，`🟡 条件支持` 表示只在满足条件时可用，例如记录里含 PDF\u002F开放获取链接、只能按 DOI 查询，或只能下载开放获取记录。\n- API Key 列中，`❌` 表示不需要配置，`🟡 可选` 表示不配置也能用但限额或稳定性较弱，`✅ 必需` 表示只在启用该平台时必须配置，不代表新用户默认都要配置。Unpaywall 需要的是 email，不是传统 API key。\n- Wiley TDM API 不支持关键词搜索。应先用 `search_crossref` 找到 Wiley 文章 DOI，再用 `download_paper` 配合 `platform=wiley` 下载。\n- ACM 和 USENIX 检索刻意走元数据后端，不抓取平台搜索页，以遵守 robots.txt 并降低 IP 被封风险。\n- `platform=all` 会尝试所有已注册检索来源，但不包含 Wiley 这类只支持 DOI 下载、不能关键词搜索的平台。未配置 key、超时或请求失败的来源会写入 `failed_sources` \u002F `errors`，其他来源继续返回。\n- `--sources` 接受逗号分隔来源，例如 `--sources crossref,openalex,pmc`。\n- `🟡 可选*` 对 Semantic Scholar 的含义是：普通检索可选；`search_semantic_snippets` 正文片段检索必需配置 `SEMANTIC_SCHOLAR_API_KEY`。\n- EasyScholar 是影响因子、期刊分区等检索工具，不是论文检索来源；使用 `paper-search journal-metrics \"Nature\"` 或 `paper-search run query_journal_metrics`。\n\n## 配置\n\n多数免费元数据来源无需配置。API key 和 email 推荐写入用户级配置文件，这样 CLI 在任意目录运行都能读取：\n\n```bash\npaper-search setup\npaper-search config set SEMANTIC_SCHOLAR_API_KEY your_semantic_scholar_api_key_here\npaper-search setup EASYSCHOLAR_KEY  # 隐藏输入；更适合配置 EasyScholar SecretKey\npaper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com  # 可选：手动覆盖 setup 自动生成的邮箱\npaper-search config list --pretty\npaper-search config doctor --pretty\npaper-search diagnostics --pretty\n```\n\n默认配置路径：\n\n```text\n~\u002F.config\u002Fpaper-search-cli\u002Fconfig.json\n```\n\n配置文件权限会写成 `0600`。`config list` 和 `config doctor` 会自动脱敏。\n\n`paper-search setup` 是引导式配置命令。默认只询问推荐配置：Semantic Scholar、Unpaywall email、Crossref email、CORE 和 EasyScholar。需要遍历所有支持项时使用 `paper-search setup --all`；只想配置指定项时使用 `paper-search setup --keys SEMANTIC_SCHOLAR_API_KEY,CORE_API_KEY`。\n\n为降低首次配置成本，如果 `PAPER_SEARCH_UNPAYWALL_EMAIL` \u002F `UNPAYWALL_EMAIL` \u002F `CROSSREF_MAILTO` 尚未配置，setup 时直接回车会自动写入一个随机前缀的 Gmail 格式邮箱，例如 `paper.search.xxxxxx@gmail.com`，用于让 Unpaywall 和 Crossref 的基础请求能直接运行。\n\n`paper-search diagnostics --pretty` 会列出所有依赖 API key 或 email 的能力、相关配置项、当前是否已配置、常见失败原因和建议排查动作。检索命令在 key-backed 平台返回 0 结果，或遇到 401、403、400、429 时，也会在 JSON 输出里附带 `diagnostic` 字段。\n\n### API key 推荐策略\n\n`paper-search setup` 默认只询问最适合普通新用户先配置的项目。平台表里的 `✅ 必需` 是“使用该平台必需”，不是“所有安装都建议配置”。\n\n| 等级 | 配置项 | 是否建议新用户配置 | 说明 |\n| --- | --- | --- | --- |\n| 默认推荐 | `SEMANTIC_SCHOLAR_API_KEY` | 建议配置 | 开启 Semantic Scholar 正文片段检索，适合方法学细节检索，也能提高请求稳定性。 |\n| 默认推荐 | `PAPER_SEARCH_UNPAYWALL_EMAIL` 或 `UNPAYWALL_EMAIL` | 建议配置 | 用 DOI 查找开放获取 PDF；只需要邮箱，不需要申请 API key。`setup` 直接回车会自动生成随机 Gmail 格式邮箱，也可以手动换成自己的邮箱。 |\n| 默认推荐 | `CROSSREF_MAILTO` | 建议配置 | 让 Crossref 请求进入 polite pool，适合长期或高频检索。`setup` 直接回车会复用自动生成的邮箱，也可以手动换成自己的邮箱。 |\n| 默认推荐 | `CORE_API_KEY` 或 `PAPER_SEARCH_CORE_API_KEY` | 建议配置 | CORE 匿名访问容易限流；配置 key 后更适合开放仓储检索。 |\n| 默认推荐 | `EASYSCHOLAR_KEY` 或 `PAPER_SEARCH_EASYSCHOLAR_KEY` | 需要检索影响因子、期刊分区等时建议配置 | 开启 EasyScholar 检索影响因子、JCR 分区、中科院分区、JCI、ESI 和预警字段等能力。建议用 `paper-search setup EASYSCHOLAR_KEY` 通过隐藏输入配置 SecretKey。 |\n| 生物医学高频 | `PUBMED_API_KEY`、`NCBI_EMAIL`、`NCBI_TOOL` | 经常用 PubMed 时建议配置 | 提高 NCBI E-utilities 限额，并让请求带上明确客户端信息。 |\n| 机构权限型 | `WOS_API_KEY` | 有 Web of Science API 权限再配置 | 用于 Web of Science 检索和引文数据；需要 Clarivate API 权限。 |\n| 机构权限型 | `IEEE_API_KEY` | 有 IEEE Xplore API 权限再配置 | 用于 IEEE Xplore 元数据检索；IEEE 可能要求注册 API 访问和产品权限。 |\n| 机构权限型 | `ELSEVIER_API_KEY` | 有 Scopus 或 ScienceDirect API 权限再配置 | 同一个 Elsevier key 不等于自动拥有两个产品权限，Scopus 和 ScienceDirect 需要分别开通。 |\n| 机构权限型 | `SPRINGER_API_KEY`、`SPRINGER_OPENACCESS_API_KEY` | 需要 Springer 平台时再配置 | 用于 Springer 元数据和开放获取记录；401 通常表示 key 无效或产品权限未开通。 |\n| 机构权限型 | `WILEY_TDM_TOKEN` | 有 Wiley TDM\u002F机构全文权限再配置 | 仅支持 DOI 下载；能否下载取决于 token 和机构订阅权限。 |\n| 通常不用 | `PAPER_SEARCH_OPENAIRE_API_KEY` 或 `OPENAIRE_API_KEY` | 不建议默认配置 | OpenAIRE 公开检索通常无需 key；只有账号或配额要求时再配置。 |\n\n也可以从现有 `.env` 导入：\n\n```bash\npaper-search config import-env .env --pretty\n```\n\n配置优先级：\n\n1. shell 环境变量。\n2. 当前工作目录 `.env`。\n3. 用户级配置文件。\n4. 免费来源的内置默认值。\n\n仓库本地开发时，继续复制 `.env.example` 也可以：\n\n```bash\ncp .env.example .env\n```\n\n### 环境变量\n\n```bash\n# Web of Science，搜索 Web of Science 时必需\nWOS_API_KEY=your_web_of_science_api_key_here\nWOS_API_VERSION=v1\n\n# IEEE Xplore，IEEE 元数据检索必需\nIEEE_API_KEY=your_ieee_api_key_here\n\n# PubMed，可选；从 3 requests\u002Fsec 提升到 10 requests\u002Fsec\nPUBMED_API_KEY=your_ncbi_api_key_here\nNCBI_EMAIL=you@example.com\nNCBI_TOOL=paper-search-cli\n\n# Semantic Scholar，正文片段检索必需，也可提升请求限额\nSEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_api_key_here\n\n# EasyScholar，检索影响因子、JCR 分区和中科院分区等信息时必需\nEASYSCHOLAR_KEY=your_easyscholar_secret_key_here\n\n# Elsevier，Scopus 和 ScienceDirect 必需；两个产品仍需要分别开通权限\nELSEVIER_API_KEY=your_elsevier_api_key_here\n\n# Springer Nature，Springer 检索和开放获取下载必需\nSPRINGER_API_KEY=your_springer_api_key_here\nSPRINGER_OPENACCESS_API_KEY=your_openaccess_api_key_here\n\n# Wiley TDM，Wiley DOI 下载必需\nWILEY_TDM_TOKEN=your_wiley_tdm_token_here\n\n# Crossref polite pool，可选但推荐；setup 直接回车会自动生成\u002F复用随机 Gmail 格式邮箱\nCROSSREF_MAILTO=you@example.com\n\n# Unpaywall，DOI 开放获取解析必需；setup 直接回车会自动生成随机 Gmail 格式邮箱\nPAPER_SEARCH_UNPAYWALL_EMAIL=you@example.com\nUNPAYWALL_EMAIL=you@example.com\n\n# CORE，可选但推荐；匿名访问经常被强限流\nPAPER_SEARCH_CORE_API_KEY=your_core_api_key_here\nCORE_API_KEY=your_core_api_key_here\n\n# OpenAIRE，可选；公开搜索无需 key\nPAPER_SEARCH_OPENAIRE_API_KEY=your_openaire_api_key_here\nOPENAIRE_API_KEY=your_openaire_api_key_here\n```\n\n### API Key 获取入口\n\n- Web of Science: [Clarivate Developer Portal](https:\u002F\u002Fdeveloper.clarivate.com\u002Fapis)\n- IEEE Xplore: [IEEE Xplore Metadata API](https:\u002F\u002Fdeveloper.ieee.org\u002Fdocs\u002Fread\u002FSearching_the_IEEE_Xplore_Metadata_API)\n- PubMed: [NCBI API Keys](https:\u002F\u002Fncbiinsights.ncbi.nlm.nih.gov\u002F2017\u002F11\u002F02\u002Fnew-api-keys-for-the-e-utilities\u002F)\n- Semantic Scholar: [Semantic Scholar API](https:\u002F\u002Fwww.semanticscholar.org\u002Fproduct\u002Fapi)\n- EasyScholar: [EasyScholar Open API](https:\u002F\u002Fwww.easyscholar.cc\u002Fconsole\u002Fuser\u002Fopen)\n- Elsevier: [Elsevier Developer Portal](https:\u002F\u002Fdev.elsevier.com\u002Fapikey\u002Fmanage)\n- Springer Nature: [Springer Nature Developers](https:\u002F\u002Fdev.springernature.com\u002F)\n- Wiley TDM: [Wiley Text and Data Mining](https:\u002F\u002Fonlinelibrary.wiley.com\u002Flibrary-info\u002Fresources\u002Ftext-and-datamining)\n- Unpaywall: [Unpaywall Data Format and API](https:\u002F\u002Funpaywall.org\u002Fproducts\u002Fapi)\n- CORE: [CORE API](https:\u002F\u002Fcore.ac.uk\u002Fservices\u002Fapi)\n- OpenAIRE: [OpenAIRE APIs](https:\u002F\u002Fdevelop.openaire.eu\u002F)\n\n`.env` 已被 git 忽略。不要提交 API key 或 token。\n\n## Agent Skill\n\n本仓库提供一个可选的 agent skill，位置是 `skills\u002Fpaper-search\u002FSKILL.md`。如果你的 agent 支持 skills，可以把它安装到对应的 skill 目录。\n\n例如：\n\n```bash\nmkdir -p ~\u002F.agents\u002Fskills\u002Fpaper-search\ncp skills\u002Fpaper-search\u002FSKILL.md ~\u002F.agents\u002Fskills\u002Fpaper-search\u002FSKILL.md\n```\n\n这个 skill 只负责告诉 agent 如何调用 `paper-search` CLI。API key 仍然通过 `paper-search setup`、`paper-search config`、`.env` 或 shell 环境变量配置。不要把密钥写进 skill 文件。\n\n## 输出约定\n\n默认所有命令都向 stdout 输出 JSON。\n\n```json\n{\n  \"ok\": true,\n  \"tool\": \"search_papers\",\n  \"message\": \"Found 1 papers.\",\n  \"data\": []\n}\n```\n\n使用 `--pretty` 输出格式化 JSON：\n\n```bash\npaper-search search \"machine learning\" --platform crossref --max-results 1 --pretty\n```\n\n需要原始文本响应时使用 `--format text`：\n\n```bash\npaper-search search \"machine learning\" --platform crossref --max-results 1 --format text\n```\n\n需要在 JSON 中保留原始响应文本时使用 `--include-text`：\n\n```bash\npaper-search run search_crossref --arg query=\"machine learning\" --arg maxResults=3 --include-text --pretty\n```\n\n## 命令\n\n### `paper-search search`\n\n统一检索入口。\n\n```bash\npaper-search search \u003Cquery> [options]\n```\n\n示例：\n\n```bash\npaper-search search \"machine learning\" --platform crossref --max-results 10 --pretty\npaper-search search \"machine learning\" --sources crossref,openalex --max-results 2 --pretty\npaper-search search \"cancer immunotherapy\" --platform all --max-results 2 --pretty\npaper-search search \"transformer neural networks\" --platform arxiv --category cs.AI --year 2023 --pretty\npaper-search search \"COVID-19 vaccine efficacy\" --platform pubmed --max-results 20 --year 2023 --pretty\npaper-search search \"CRISPR gene editing\" --platform webofscience --journal Nature --max-results 15 --pretty\n```\n\n常用选项：\n\n| 参数 | 说明 |\n| --- | --- |\n| `--platform` | 数据来源。默认 `crossref` |\n| `--sources` | 逗号分隔的多源检索列表，例如 `crossref,openalex,pmc` |\n| `--max-results` | 最大返回数量 |\n| `--year` | 年份过滤，例如 `2024`、`2020-2024`、`2020-` |\n| `--author` | 作者过滤 |\n| `--journal` | 期刊过滤 |\n| `--category` | 分类过滤，主要用于 arXiv\u002FbioRxiv\u002FmedRxiv |\n| `--days` | bioRxiv\u002FmedRxiv 回溯天数 |\n| `--sort-by` | `relevance`、`date` 或 `citations` |\n| `--sort-order` | `asc` 或 `desc` |\n\n### `paper-search run`\n\n按内部工具名执行。这个入口最适合 agent 精确调用。\n\n```bash\npaper-search run \u003Ctool-name> --arg key=value --arg key=value\npaper-search run \u003Ctool-name> --json-args '{\"key\":\"value\"}'\npaper-search run \u003Ctool-name> --json-args @args.json\n```\n\n示例：\n\n```bash\npaper-search run search_crossref --arg query=\"machine learning\" --arg maxResults=5 --pretty\npaper-search run search_papers --json-args '{\"query\":\"machine learning\",\"sources\":\"crossref,openalex\",\"maxResults\":2}' --pretty\npaper-search run search_pubmed --json-args '{\"query\":\"osteoarthritis\",\"maxResults\":5,\"sortBy\":\"date\"}' --pretty\npaper-search run get_paper_by_doi --arg doi=\"10.1038\u002Fnature12373\" --pretty\npaper-search run query_journal_metrics --json-args '{\"journals\":[\"Nature\",\"BMJ\"],\"includeRaw\":true}' --pretty\n```\n\n### `paper-search journal-metrics`\n\n通过 EasyScholar 检索影响因子、期刊分区等信息。需要配置 `EASYSCHOLAR_KEY` 或 `PAPER_SEARCH_EASYSCHOLAR_KEY`。\n\n```bash\npaper-search journal-metrics \"Nature\" \"BMJ\" --pretty\npaper-search journal-metrics --file journals.txt --include-raw --pretty\n```\n\n标准化返回字段包括 `impact_factor`、`impact_factor_5y`、`jcr_quartile`、`ssci_quartile`、`jci`、`cas_base`、`cas_upgraded`、`cas_small`、`cas_top`、`cas_zone`、`esi`、`warning`、`pku`、`cssci`、`cscd`、`ahci`、`ccf`、`ei` 和 `china_st_core`，具体以 EasyScholar 对该期刊实际返回字段为准。加 `--include-raw` 会额外保留 `official_all`、`official_select` 和 `custom_rank`。\n\n### `paper-search tools`\n\n列出全部可用工具名、说明和输入 schema。\n\n```bash\npaper-search tools --pretty\n```\n\n### `paper-search status`\n\n查看平台能力和 API key 状态。不会打印密钥内容。\n\n```bash\npaper-search status --pretty\npaper-search status --validate --pretty\n```\n\n`--validate` 可能会向平台发起实时请求，只在确实需要验证凭证时使用。\n\n### `paper-search diagnostics`\n\n查看依赖 API key \u002F email 的能力和排障建议。不会打印密钥内容。\n\n```bash\npaper-search diagnostics --pretty\n```\n\n当命令在已配置 key 的平台返回 0 结果，或遇到 401、403、400、429 时，JSON 输出会包含 `diagnostic` 字段，说明可能原因和下一步操作。\n\n### `paper-search config`\n\n管理用户级配置文件。\n\n```bash\npaper-search config init --pretty\npaper-search config set SEMANTIC_SCHOLAR_API_KEY your_key --pretty\npaper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty  # 可选：手动覆盖 setup 自动生成的邮箱\npaper-search config import-env .env --pretty\npaper-search config list --pretty\npaper-search config doctor --pretty\npaper-search config path --pretty\npaper-search config keys --pretty\n```\n\n### `paper-search download`\n\n从支持下载的平台下载论文 PDF。\n\n```bash\npaper-search download \u003Cpaper-id-or-doi> --platform \u003Cplatform> [--save-path .\u002Fdownloads]\n```\n\n示例：\n\n```bash\npaper-search download 2301.00001 --platform arxiv --save-path .\u002Fdownloads\npaper-search download 10.1000\u002Fexample --platform scihub --save-path .\u002Fdownloads\npaper-search download 10.1111\u002Fjtsb.12390 --platform wiley --save-path .\u002Fdownloads\npaper-search run download_with_fallback --arg source=arxiv --arg paperId=1201.0490 --arg doi=10.48550\u002Farxiv.1201.0490 --arg savePath=.\u002Fdownloads --pretty\n```\n\n## 工具参考\n\n以下工具名可用于 `paper-search run`。\n\n### `search_papers`\n\n通过统一调度器检索。\n\n```bash\npaper-search run search_papers --json-args '{\"query\":\"machine learning\",\"platform\":\"crossref\",\"maxResults\":10,\"year\":\"2023\",\"sortBy\":\"date\"}' --pretty\n```\n\n支持的平台：\n\n```text\ncrossref, arxiv, webofscience, wos, pubmed, biorxiv, medrxiv, semantic,\niacr, googlescholar, scholar, scihub, ieee, sciencedirect, springer,\nspringerlink, scopus, openalex, unpaywall, pmc, europepmc, core,\nopenaire, dblp, acm, usenix, openreview, all\n```\n\n多源检索使用 `sources`：\n\n```bash\npaper-search run search_papers --json-args '{\"query\":\"machine learning\",\"sources\":\"crossref,openalex,pmc\",\"maxResults\":2}' --pretty\n```\n\n### `search_crossref`\n\n搜索 Crossref，默认免费元数据来源。\n\n```bash\npaper-search run search_crossref --arg query=\"machine learning\" --arg maxResults=10 --arg year=2023 --arg sortBy=relevance --arg sortOrder=desc --pretty\n```\n\n### `search_arxiv`\n\n搜索 arXiv 预印本。\n\n```bash\npaper-search run search_arxiv --arg query=\"transformer neural networks\" --arg maxResults=10 --arg category=cs.AI --arg year=2023 --arg sortBy=date --arg sortOrder=desc --pretty\n```\n\n### `search_pubmed`\n\n搜索 PubMed\u002FMEDLINE 生物医学文献。\n\n```bash\npaper-search run search_pubmed --json-args '{\"query\":\"COVID-19 vaccine efficacy\",\"maxResults\":20,\"year\":\"2023\",\"journal\":\"New England Journal of Medicine\",\"publicationType\":[\"Journal Article\",\"Clinical Trial\"],\"sortBy\":\"date\"}' --pretty\n```\n\n### 开放元数据与全文来源\n\n这些命令用于开放元数据检索、开放全文发现和 PDF 回退查找：\n\n```bash\npaper-search run search_openalex --arg query=\"machine learning\" --arg maxResults=3 --pretty\npaper-search run search_unpaywall --arg query=\"10.48550\u002Farxiv.1201.0490\" --pretty\npaper-search run search_pmc --arg query=\"cancer immunotherapy\" --arg maxResults=3 --pretty\npaper-search run search_europepmc --arg query=\"cancer genomics\" --arg maxResults=3 --pretty\npaper-search run search_core --arg query=\"machine learning\" --arg maxResults=3 --pretty\npaper-search run search_openaire --arg query=\"machine learning\" --arg maxResults=3 --pretty\n```\n\nUnpaywall 只支持 DOI，且需要配置 email。CORE 匿名访问可能很快返回空结果或被限流，长期使用建议配置 API key。\n\n### 注册表驱动的平台检索\n\n这些偏元数据检索的工具由平台注册表生成；后续接入新平台时，只需要增加新的 searcher 和平台注册信息：\n\n```bash\npaper-search run search_dblp --arg query=\"graph neural networks\" --arg maxResults=5 --pretty\npaper-search run search_acm --arg query=\"software testing\" --arg maxResults=5 --pretty\npaper-search run search_usenix --arg query=\"file systems\" --arg maxResults=5 --pretty\npaper-search run search_openreview --arg query=\"large language models\" --arg maxResults=5 --pretty\npaper-search run search_springerlink --arg query=\"machine learning\" --arg maxResults=5 --pretty\n```\n\n`search_ieee` 使用同一套通用参数，但需要配置 `IEEE_API_KEY`：\n\n```bash\npaper-search run search_ieee --arg query=\"wireless networks\" --arg maxResults=5 --arg articleTitle=\"wireless\" --pretty\n```\n\n### `search_webofscience`\n\n搜索 Web of Science。需要 `WOS_API_KEY`。\n\n```bash\npaper-search run search_webofscience --arg query=\"CRISPR gene editing\" --arg maxResults=15 --arg year=2022 --arg journal=Nature --pretty\n```\n\n### `search_google_scholar`\n\n搜索 Google Scholar。\n\n```bash\npaper-search run search_google_scholar --arg query=\"deep learning\" --arg maxResults=10 --arg yearLow=2020 --arg yearHigh=2024 --pretty\n```\n\n### `search_biorxiv` 和 `search_medrxiv`\n\n按最近天数窗口和可选分类搜索预印本。\n\n```bash\npaper-search run search_biorxiv --arg query=\"genomics\" --arg maxResults=10 --arg days=30 --pretty\npaper-search run search_medrxiv --arg query=\"epidemiology\" --arg maxResults=10 --arg days=60 --pretty\n```\n\n### `search_semantic_scholar`\n\n搜索 Semantic Scholar，可附加领域过滤。\n\n```bash\npaper-search run search_semantic_scholar --json-args '{\"query\":\"graph neural networks\",\"maxResults\":10,\"fieldsOfStudy\":[\"Computer Science\"]}' --pretty\n```\n\n### `search_semantic_snippets`\n\n搜索 Semantic Scholar 的 Open Access snippet 索引，用于定位论文正文中的方法学细节片段。需要 `SEMANTIC_SCHOLAR_API_KEY`。\n\n```bash\npaper-search run search_semantic_snippets --arg query=\"CMAverse mediation bootstrap confidence interval\" --arg limit=5 --arg fieldsOfStudy=Medicine --pretty\n```\n\n### `query_journal_metrics`\n\n检索 EasyScholar 影响因子、期刊分区等信息。它不是论文检索来源，而是影响因子与期刊分区检索工具，适合投稿规划、目标期刊筛选和投稿前检查。需要配置 `EASYSCHOLAR_KEY` 或 `PAPER_SEARCH_EASYSCHOLAR_KEY`。\n\n```bash\npaper-search run query_journal_metrics --json-args '{\"journals\":[\"Nature\",\"BMJ\"]}' --pretty\npaper-search run query_journal_metrics --json-args '{\"journal\":\"Journal of Medical Internet Research\",\"includeRaw\":true}' --pretty\n```\n\n标准化的 `core` 对象只返回 EasyScholar 对该期刊实际存在的字段，例如影响因子、JCR\u002FSSCI 分区、中科院分区、JCI、ESI、预警字段和中文\u002F学科等级信息。需要完整官方和自定义等级数据时，使用 `includeRaw=true` 保留 `officialRank.all`、`officialRank.select` 和 `customRank`。\n\n### `search_iacr`\n\n搜索 IACR ePrint Archive。\n\n```bash\npaper-search run search_iacr --arg query=\"zero knowledge proof\" --arg maxResults=10 --arg fetchDetails=true --pretty\n```\n\n### `search_sciencedirect`\n\n搜索 ScienceDirect。需要 `ELSEVIER_API_KEY`。\n\n```bash\npaper-search run search_sciencedirect --arg query=\"materials science\" --arg maxResults=10 --arg openAccess=true --pretty\n```\n\n### `search_scopus`\n\n搜索 Scopus。需要 `ELSEVIER_API_KEY`。\n\n```bash\npaper-search run search_scopus --arg query=\"citation analysis\" --arg maxResults=10 --arg documentType=ar --pretty\n```\n\n### `search_springer`\n\n搜索 Springer Nature。需要 `SPRINGER_API_KEY`。\n\n```bash\npaper-search run search_springer --arg query=\"machine learning\" --arg maxResults=10 --arg type=Journal --arg openAccess=true --pretty\n```\n\n### `search_scihub`\n\n通过 DOI 或文章 URL 查询 Sci-Hub，并可选择下载 PDF。\n\n```bash\npaper-search run search_scihub --arg doiOrUrl=\"10.1038\u002Fnature12373\" --arg downloadPdf=false --pretty\npaper-search run search_scihub --arg doiOrUrl=\"10.1038\u002Fnature12373\" --arg downloadPdf=true --arg savePath=.\u002Fdownloads --pretty\n```\n\n### `check_scihub_mirrors`\n\n查看 Sci-Hub 镜像状态。\n\n```bash\npaper-search run check_scihub_mirrors --pretty\npaper-search run check_scihub_mirrors --arg forceCheck=true --pretty\n```\n\n### `get_paper_by_doi`\n\n按 DOI 查询元数据。\n\n```bash\npaper-search run get_paper_by_doi --arg doi=\"10.1038\u002Fnature12373\" --arg platform=all --pretty\npaper-search run get_paper_by_doi --arg doi=\"10.1038\u002Fnature12373\" --arg platform=arxiv --pretty\n```\n\n### `download_paper`\n\n从指定平台下载 PDF。如果该平台没有原生下载器，或原生下载失败，会进入与 `download_with_fallback` 相同的下载漏斗。\n\n```bash\npaper-search run download_paper --arg paperId=\"2301.00001\" --arg platform=arxiv --arg savePath=.\u002Fdownloads --pretty\n```\n\n原生下载平台：\n\n```text\narxiv, biorxiv, medrxiv, semantic, iacr, scihub, springer, wiley,\npmc, europepmc, core\n```\n\n其他已注册来源，例如 `crossref`、`openalex`、`dblp`、`acm`、`usenix`、`openreview`，也可以传给 `download_paper`；它们会直接进入元数据\u002F仓储\u002FUnpaywall\u002FSci-Hub 回退漏斗。\n\n### `download_with_fallback`\n\n按完整下载漏斗尝试下载。顺序是原生下载、元数据 PDF URL、仓储发现、Unpaywall DOI 解析，最后默认使用 Sci-Hub 兜底：\n\n```bash\npaper-search run download_with_fallback --arg source=arxiv --arg paperId=1201.0490 --arg doi=10.48550\u002Farxiv.1201.0490 --arg savePath=.\u002Fdownloads --pretty\npaper-search run download_with_fallback --arg source=crossref --arg paperId=\"10.1038\u002Fnature12373\" --arg doi=\"10.1038\u002Fnature12373\" --arg savePath=.\u002Fdownloads --pretty\n```\n\n`useSciHub` 默认为 `true`；只有需要关闭该最后兜底路径时才设置为 `false`。`download_paper` 在指定平台下载失败或平台不支持直接下载时，也会进入同一条漏斗。\n\n### `search_wiley`\n\nWiley TDM API 不支持关键词搜索。应先用 Crossref 检索，再按 DOI 下载：\n\n```bash\npaper-search run search_crossref --arg query=\"site:wiley.com machine learning\" --arg maxResults=10 --pretty\npaper-search run download_paper --arg paperId=\"10.1111\u002Fexample\" --arg platform=wiley --pretty\n```\n\n### `get_platform_status`\n\n等价于 `paper-search status`。\n\n```bash\npaper-search run get_platform_status --pretty\npaper-search run get_platform_status --arg validate=true --pretty\n```\n\n## 排障\n\n### 找不到命令\n\n直接从项目运行：\n\n```bash\nnode dist\u002Fcli.js status --pretty\n```\n\n或注册为本机命令：\n\n```bash\nnpm link\npaper-search status --pretty\n```\n\n### 缺少 API Key\n\n运行：\n\n```bash\npaper-search status --pretty\n```\n\n如果某个平台显示 `missing`，通过 `paper-search setup`、用户级配置或 `.env` 添加对应 key 后重试。\n\n全局安装时推荐写入用户级配置：\n\n```bash\npaper-search setup\npaper-search config set SEMANTIC_SCHOLAR_API_KEY your_key\npaper-search config doctor --pretty\n```\n\n### 平台限流\n\n减少 `--max-results`，避免反复实时验证，优先使用官方 API。PubMed、Semantic Scholar 和 CORE 可通过可选 key 提升限额。CORE 匿名访问可能返回 HTTP 429；如果要稳定使用，建议配置 `PAPER_SEARCH_CORE_API_KEY`。\n\n### 脚本解析 JSON\n\n默认解析 stdout 即可。人类可读诊断会写入 stderr。\n\n## 使用边界\n\n部分来源可能受平台条款、机构订阅或当地法律限制。请只在你具备相应访问权限、并符合所在机构和平台规则的前提下使用相关功能。\n\n## 项目来源\n\n本项目认可并感谢 [LinuxDo](https:\u002F\u002Flinux.do) 社区。\n\n本项目的 CLI + Skill 路线和论文检索工作流改进，来自社区交流与开源分享的启发。当前定位是单命令终端工具，不需要 MCP 运行时。\n\n项目也参考了 [openags\u002Fpaper-search-mcp](https:\u002F\u002Fgithub.com\u002Fopenags\u002Fpaper-search-mcp) 的相关思路，并将工作流适配为独立 CLI。\n\n## License\n\nMIT\n","Paper Search CLI 是一个基于 Node.js 的命令行工具，用于跨多个学术来源检索论文、核验元数据、获取影响因子和期刊分区等信息以及下载 PDF。其核心功能包括支持 25 个学术平台（如 Crossref、PubMed 和 arXiv）的论文检索，通过 EasyScholar 检索影响因子和期刊分区，以及支持多种路径的 PDF 下载。该工具设计为单一命令入口，输出稳定 JSON 格式，适合自动化脚本和 agent 工作流使用。它特别适用于需要批量处理学术文献的场景，例如科研人员进行文献调研、自动化脚本编写者构建数据处理流程或开发者集成到其他应用中。",2,"2026-06-11 04:05:03","CREATED_QUERY"]