paper-search-cli 0.1.2 → 0.2.0

package/.env.example

@@ -1,11 +1,13 @@
 # ==============================================================================
 # Paper Search CLI - Environment Variables
 # ==============================================================================
-# Supports 20 academic sources/platforms with a unified CLI interface
+# Supports 25 academic sources/platforms with a unified CLI interface,
+# plus EasyScholar journal metrics lookup
 # Platforms: Crossref, OpenAlex, PubMed, PubMed Central, Europe PMC, arXiv,
 # bioRxiv, medRxiv, Semantic Scholar, CORE, OpenAIRE, Web of Science,
-# Google Scholar, IACR ePrint, Sci-Hub, ScienceDirect, Springer, Wiley,
-# Scopus, Unpaywall
+# Google Scholar, DBLP, ACM metadata, USENIX metadata, OpenReview,
+# IACR ePrint, Sci-Hub, IEEE Xplore, ScienceDirect, Springer/SpringerLink,
+# Wiley, Scopus, Unpaywall
 #
 # For global installs, prefer:
 #   paper-search config set KEY VALUE
@@ -26,6 +28,15 @@
 WOS_API_KEY=your_web_of_science_api_key_here
 WOS_API_VERSION=v1
 
+# ------------------------------------------------------------------------------
+# IEEE Xplore Metadata API - REQUIRED for IEEE search
+# ------------------------------------------------------------------------------
+# Official metadata search API for IEEE Xplore
+# Get API key: https://developer.ieee.org/
+# Documentation: https://developer.ieee.org/docs/read/Searching_the_IEEE_Xplore_Metadata_API
+# Pricing/access: Requires IEEE API access; entitlements may vary
+IEEE_API_KEY=your_ieee_api_key_here
+
 # ------------------------------------------------------------------------------
 # PubMed/NCBI E-utilities - OPTIONAL (but recommended)
 # ------------------------------------------------------------------------------
@@ -49,6 +60,17 @@ NCBI_TOOL=paper-search-cli
 # Pricing: Free for academic use
 SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_api_key_here
 
+# ------------------------------------------------------------------------------
+# EasyScholar Journal Metrics API - REQUIRED for journal metrics
+# ------------------------------------------------------------------------------
+# Query journal-level metrics such as impact factor, JCR quartile, CAS zones,
+# JCI, ESI, warning flags, and selected rank datasets.
+# Configure through `paper-search setup EASYSCHOLAR_KEY` when possible so the
+# SecretKey is entered through a hidden prompt instead of appearing in shell history.
+EASYSCHOLAR_KEY=your_easyscholar_secret_key_here
+# Legacy-compatible fallback name
+PAPER_SEARCH_EASYSCHOLAR_KEY=your_easyscholar_secret_key_here
+
 # ------------------------------------------------------------------------------
 # Unpaywall - REQUIRED for DOI-based open-access resolution
 # ------------------------------------------------------------------------------
@@ -138,11 +160,17 @@ WILEY_TDM_TOKEN=your_wiley_tdm_token_here
 # bioRxiv           | ✅ Free    | Biology preprints, PDF        | Biology research
 # medRxiv           | ✅ Free    | Medical preprints, PDF        | Medical research
 # Semantic Scholar  | 🟡 Optional| AI-powered search, citations  | CS, AI research
+# EasyScholar       | 🔴 Required| IF, JCR/CAS zones, JCI, ESI   | Journal metrics
 # CORE              | 🟡 Optional| Repository PDFs               | Open repositories
 # OpenAIRE          | 🟡 Optional| Repository discovery          | Open repositories
+# DBLP              | ✅ Free    | CS bibliography metadata      | CS literature
+# ACM metadata      | ✅ Free    | Crossref DOI-prefix metadata  | ACM papers
+# USENIX metadata   | ✅ Free    | DBLP-backed proceedings data  | Systems/security
+# OpenReview        | ✅ Free    | Notes/search metadata         | ML conferences
 # Unpaywall         | 📧 Email   | DOI OA resolution             | Fallback downloads
 # IACR ePrint       | ✅ Free    | Cryptography papers, PDF      | Cryptography
 # Sci-Hub          | ✅ Free    | Universal DOI access          | Any paper by DOI
+# IEEE Xplore       | 🔴 Required| IEEE metadata                 | Engineering
 # ScienceDirect     | 🔴 Required| Elsevier journals             | Full-text search
 # Springer          | 🔴 Required| Dual API (Meta+OpenAccess)    | Books & journals
 # Wiley             | 🔴 Required| TDM API, full text mining     | Data mining

package/README-sc.md

@@ -2,15 +2,13 @@
 
 [English](README.md)
 
-Paper Search CLI 是一个独立的 Node.js 命令行工具，用于跨多个学术来源检索论文、核验元数据和下载 PDF。它面向终端直接使用、自动化脚本和 agent 工作流，提供稳定命令入口和可预测的 JSON 输出。
-
-它继承了之前 Paper Search 实现中的平台覆盖、统一数据模型和详细功能说明，但运行方式已经收口为普通 CLI：每次调用执行一次命令，执行完即退出，不需要配置、启动或维护长期后台服务。
+Paper Search CLI 是一个独立的 Node.js 命令行工具，用于跨多个学术来源检索论文、核验元数据、EasyScholar 检索影响因子和期刊分区等信息、下载 PDF。它面向终端直接使用、自动化脚本和 agent 工作流，提供稳定命令入口和可预测的 JSON 输出。
 
 ![Node.js](https://img.shields.io/badge/node.js->=18.0.0-green.svg)
 ![TypeScript](https://img.shields.io/badge/typescript-^5.5.3-blue.svg)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Platforms](https://img.shields.io/badge/platforms-20-brightgreen.svg)
-![Version](https://img.shields.io/badge/version-0.1.2-blue.svg)
+![Platforms](https://img.shields.io/badge/platforms-25-brightgreen.svg)
+![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)
 [![LinuxDo](https://img.shields.io/badge/LinuxDo-community-1f6feb)](https://linux.do)
 
 感谢真诚、友善、团结、专业的 [LinuxDo](https://linux.do) 社区。本项目的 CLI + Skill 路线和论文检索工作流改进，来自社区交流与开源分享的启发。
@@ -27,16 +25,11 @@ Paper Search CLI 是一个独立的 Node.js 命令行工具，用于跨多个学
 
 ## 核心特性
 
-- **20 个学术来源/平台**：Crossref、OpenAlex、PubMed、PubMed Central、Europe PMC、arXiv、bioRxiv、medRxiv、Semantic Scholar、CORE、OpenAIRE、Web of Science、Google Scholar、IACR ePrint、Sci-Hub、ScienceDirect、Springer Nature、Wiley、Scopus、Unpaywall。
-- **单一命令入口**：安装后通过 `paper-search` 调用，适合终端、脚本和 agent。
-- **JSON 优先输出**：stdout 默认输出 JSON，stderr 保留给人类可读日志和错误。
-- **统一论文数据模型**：标准化标题、作者、DOI、来源、日期、摘要、PDF 链接、引用数和平台扩展字段。
-- **多源检索与去重**：用 `--sources crossref,openalex,pmc` 选择来源，或用 `platform=all` 尝试所有已注册检索来源，再按 DOI、标题+作者合并重复结果。
-- **Semantic Scholar 正文片段检索**：`search_semantic_snippets` 用于检索 Semantic Scholar Open Access snippet 索引中的正文片段，适合查找论文中的方法学细节。该功能需要 `SEMANTIC_SCHOLAR_API_KEY`。
-- **开放获取优先下载链**：`download_with_fallback` 会先尝试原生下载、结果里的 PDF URL、PMC/Europe PMC/CORE/OpenAIRE、Unpaywall DOI 解析，只有显式开启时才把 Sci-Hub 作为最后兜底。
-- **限速与重试**：内置平台级限速和可重试 API 错误处理。
+- **25 个学术来源/平台**：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/SpringerLink、Wiley、Scopus、Unpaywall。
+- **EasyScholar 影响因子与期刊分区检索**：检索影响因子、5 年影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警字段，以及可选的官方/自定义原始等级字段等。
 - **PDF 下载支持**：支持 arXiv、bioRxiv、medRxiv、Semantic Scholar、IACR、Sci-Hub、Springer 开放获取、Wiley DOI 下载等路径。
-- **适合 agent 调用**：`tools`、`status`、`search`、`download`、`run` 覆盖简单检索和精确工具调用。
+- **正文片段检索**：用于检索论文正文片段，数据来源于 Semantic Scholar 中，适合查找论文中的方法学细节等。
+- **适合 agent 调用**：`tools`、`status`、`search`、`journal-metrics`、`download`、`run` 覆盖简单检索和精确工具调用。
 
 ## 快速开始
 
@@ -51,6 +44,7 @@ paper-search search "machine learning" --platform crossref --max-results 3 --pre
 ```
 
 安装后运行 `paper-search setup`，即可把可选 API key 和 email 写入用户级配置。
+其中 Unpaywall 和 Crossref 的邮箱项可以直接回车跳过，CLI 会自动写入一个随机前缀的 Gmail 格式邮箱；如果你想使用自己的邮箱，后续再用 `paper-search config set` 覆盖即可。
 
 如果你需要本地开发版，或要验证尚未发布的改动，可以从源码安装：
 
@@ -72,37 +66,103 @@ paper-search config doctor --pretty
 
 ## 支持的平台
 
+### 平台类型
+
+下面的能力表仍然是平台能力的准确信息来源。除 25 个论文检索/获取来源外，CLI 还提供 EasyScholar 影响因子、期刊分区等检索；EasyScholar 不参与 `platform=all` 或 `--sources`，应使用 `journal-metrics` / `query_journal_metrics` 调用。
+
+如果只是快速选择检索来源或查询工具，可以先按这些类型判断：
+
+| 类型 | 平台 | 适合场景 |
+| --- | --- | --- |
+| 综合检索 | Crossref、OpenAlex、Semantic Scholar、Google Scholar | 广覆盖发现、DOI 元数据、引用线索、文献初筛 |
+| 影响因子/期刊分区 | EasyScholar | 影响因子、5 年影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警和等级信息 |
+| 医学/生命科学 | PubMed、PubMed Central、Europe PMC | 临床、生物医学、公卫、生物医学元数据和开放全文 |
+| 预印本/会议稿 | arXiv、bioRxiv、medRxiv、OpenReview、IACR ePrint | 跨学科预印本、生命科学/医学预印本、AI/ML 投稿和密码学 ePrint |
+| 计算机/工程 | DBLP、ACM Digital Library 元数据、IEEE Xplore、USENIX | CS 文献目录、工程数据库、系统/安全会议论文 |
+| 开放全文/仓储 | CORE、OpenAIRE、Unpaywall | 跨学科仓储发现和开放获取 PDF 回退路径 |
+| 引文库/出版商 | Web of Science、Scopus、ScienceDirect、Springer Nature/SpringerLink、Wiley | 机构权限型元数据、引文数据库、出版商记录和下载 |
+| DOI 定向获取 | Sci-Hub | DOI 定向获取，并作为 PDF 下载漏斗的最后自动兜底；除非传入 `useSciHub=false` |
+
+部分平台会跨多个实际工作流。例如 Semantic Scholar 既适合广覆盖检索，也常用于 CS/AI；arXiv 覆盖计算机、数学、物理和部分定量学科。这里按主要使用方式归类；做计算机方向检索时，通常会同时用“计算机/工程”和“预印本/会议稿”两组。
+
+### 能力矩阵
+
+#### 综合检索
+
 | 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
 | --- | --- | --- | --- | --- | --- | --- |
 | Crossref | ✅ | ❌ | ❌ | ✅ | ❌ | 默认搜索平台，广泛元数据覆盖 |
 | OpenAlex | ✅ | 🟡 条件支持 | ❌ | ✅ | ❌ | 广泛免费元数据；记录含开放链接时可用于回退下载 |
-| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | 物理、计算机、数学等预印本 |
-| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 引文数据库、日期排序、年份范围 |
+| Semantic Scholar | ✅ | ✅ | ✅ 正文片段 | ✅ | 🟡 可选* | AI 语义检索 + OA 正文片段 |
+| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | 广泛学术发现，基于页面解析 |
+
+#### 影响因子与期刊分区
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| EasyScholar | ✅ 影响因子/分区检索 | ❌ | ❌ | ❌ | ✅ 必需 | 影响因子、5 年影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警字段，以及可选的官方/自定义原始等级字段 |
+
+#### 医学/生命科学
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
 | PubMed | ✅ | ❌ | ❌ | ❌ | 🟡 可选 | NCBI E-utilities 生物医学文献 |
 | PubMed Central | ✅ | ✅ | ✅ | ❌ | ❌ | 生物医学开放全文和 PMC PDF |
 | Europe PMC | ✅ | ✅ | ✅ | ❌ | ❌ | 生物医学元数据和开放全文链接 |
-| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | 广泛学术发现，基于页面解析 |
-| bioRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 生物学预印本 |
-| medRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 医学预印本 |
-| Semantic Scholar | ✅ | ✅ | ✅ 正文片段 | ✅ | 🟡 可选* | AI 语义检索 + OA 正文片段 |
+
+#### 计算机/工程
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| DBLP | ✅ | ❌ | ❌ | ❌ | ❌ | 通过官方 DBLP search API 检索计算机文献目录 |
+| ACM Digital Library | ✅ | ❌ | ❌ | ✅ | ❌ | 通过 Crossref 的 ACM DOI 前缀元数据检索；不抓取 ACM 页面 |
+| USENIX | ✅ | ❌ | ❌ | ❌ | ❌ | 基于 DBLP 的 USENIX 会议元数据；不抓取 USENIX 搜索页 |
+| IEEE Xplore | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 通过官方 IEEE Xplore Metadata API 检索 IEEE 元数据 |
+
+#### 开放全文/仓储
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
 | CORE | ✅ | 🟡 条件支持 | 🟡 条件支持 | ❌ | 🟡 可选 | 记录含 PDF 或全文链接时可下载 |
 | OpenAIRE | ✅ | 🟡 条件支持 | ❌ | ❌ | 🟡 可选 | 记录含开放链接时可用于回退下载 |
 | Unpaywall | 🟡 条件支持 | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | 仅支持 DOI 查询；需要 email；发现 OA PDF 时可下载 |
+
+#### 预印本/会议稿
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | 物理、计算机、数学等预印本 |
+| bioRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 生物学预印本 |
+| medRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 医学预印本 |
+| OpenReview | ✅ | ❌ | ❌ | ❌ | ❌ | 通过公开 OpenReview notes search 检索会议投稿、评审和预印本 |
 | IACR ePrint | ✅ | ✅ | ✅ | ❌ | ❌ | 密码学论文 |
-| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | 基于 DOI 查询和下载 |
+
+#### 引文库/出版商
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 引文数据库、日期排序、年份范围 |
 | ScienceDirect | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | Elsevier 元数据和摘要 |
-| Springer Nature | ✅ | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | 开放获取记录可下载；元数据 API 需要 key |
+| Springer Nature / SpringerLink | ✅ | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | `springerlink` 是现有 Springer Nature 集成的别名 |
 | Wiley | ❌ 关键词搜索 | ✅ | ✅ | ❌ | ✅ 必需 | TDM API，仅支持 DOI 下载 PDF |
 | Scopus | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 摘要和引文数据库 |
 
+#### DOI 定向获取
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | 基于 DOI 查询和下载 |
+
 说明：
 
 - 能力列中，`✅` 表示直接支持，`❌` 表示不支持，`🟡 条件支持` 表示只在满足条件时可用，例如记录里含 PDF/开放获取链接、只能按 DOI 查询，或只能下载开放获取记录。
 - API Key 列中，`❌` 表示不需要配置，`🟡 可选` 表示不配置也能用但限额或稳定性较弱，`✅ 必需` 表示只在启用该平台时必须配置，不代表新用户默认都要配置。Unpaywall 需要的是 email，不是传统 API key。
 - Wiley TDM API 不支持关键词搜索。应先用 `search_crossref` 找到 Wiley 文章 DOI，再用 `download_paper` 配合 `platform=wiley` 下载。
+- ACM 和 USENIX 检索刻意走元数据后端，不抓取平台搜索页，以遵守 robots.txt 并降低 IP 被封风险。
 - `platform=all` 会尝试所有已注册检索来源，但不包含 Wiley 这类只支持 DOI 下载、不能关键词搜索的平台。未配置 key、超时或请求失败的来源会写入 `failed_sources` / `errors`，其他来源继续返回。
 - `--sources` 接受逗号分隔来源，例如 `--sources crossref,openalex,pmc`。
 - `🟡 可选*` 对 Semantic Scholar 的含义是：普通检索可选；`search_semantic_snippets` 正文片段检索必需配置 `SEMANTIC_SCHOLAR_API_KEY`。
+- EasyScholar 是影响因子、期刊分区等检索工具，不是论文检索来源；使用 `paper-search journal-metrics "Nature"` 或 `paper-search run query_journal_metrics`。
 
 ## 配置
 
@@ -111,7 +171,8 @@ paper-search config doctor --pretty
 ```bash
 paper-search setup
 paper-search config set SEMANTIC_SCHOLAR_API_KEY your_semantic_scholar_api_key_here
-paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com
+paper-search setup EASYSCHOLAR_KEY  # 隐藏输入；更适合配置 EasyScholar SecretKey
+paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com  # 可选：手动覆盖 setup 自动生成的邮箱
 paper-search config list --pretty
 paper-search config doctor --pretty
 paper-search diagnostics --pretty
@@ -125,7 +186,7 @@ paper-search diagnostics --pretty
 
 配置文件权限会写成 `0600`。`config list` 和 `config doctor` 会自动脱敏。
 
-`paper-search setup` 是引导式配置命令。默认只询问推荐配置：Semantic Scholar、Unpaywall email、Crossref email 和 CORE。需要遍历所有支持项时使用 `paper-search setup --all`；只想配置指定项时使用 `paper-search setup --keys SEMANTIC_SCHOLAR_API_KEY,CORE_API_KEY`。
+`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`。
 
 为降低首次配置成本，如果 `PAPER_SEARCH_UNPAYWALL_EMAIL` / `UNPAYWALL_EMAIL` / `CROSSREF_MAILTO` 尚未配置，setup 时直接回车会自动写入一个随机前缀的 Gmail 格式邮箱，例如 `paper.search.xxxxxx@gmail.com`，用于让 Unpaywall 和 Crossref 的基础请求能直接运行。
 
@@ -138,11 +199,13 @@ paper-search diagnostics --pretty
 | 等级 | 配置项 | 是否建议新用户配置 | 说明 |
 | --- | --- | --- | --- |
 | 默认推荐 | `SEMANTIC_SCHOLAR_API_KEY` | 建议配置 | 开启 Semantic Scholar 正文片段检索，适合方法学细节检索，也能提高请求稳定性。 |
-| 默认推荐 | `PAPER_SEARCH_UNPAYWALL_EMAIL` 或 `UNPAYWALL_EMAIL` | 建议配置 | 用 DOI 查找开放获取 PDF；只需要邮箱，不需要申请 API key。 |
-| 默认推荐 | `CROSSREF_MAILTO` | 建议配置 | 让 Crossref 请求进入 polite pool，适合长期或高频检索。 |
+| 默认推荐 | `PAPER_SEARCH_UNPAYWALL_EMAIL` 或 `UNPAYWALL_EMAIL` | 建议配置 | 用 DOI 查找开放获取 PDF；只需要邮箱，不需要申请 API key。`setup` 直接回车会自动生成随机 Gmail 格式邮箱，也可以手动换成自己的邮箱。 |
+| 默认推荐 | `CROSSREF_MAILTO` | 建议配置 | 让 Crossref 请求进入 polite pool，适合长期或高频检索。`setup` 直接回车会复用自动生成的邮箱，也可以手动换成自己的邮箱。 |
 | 默认推荐 | `CORE_API_KEY` 或 `PAPER_SEARCH_CORE_API_KEY` | 建议配置 | CORE 匿名访问容易限流；配置 key 后更适合开放仓储检索。 |
+| 默认推荐 | `EASYSCHOLAR_KEY` 或 `PAPER_SEARCH_EASYSCHOLAR_KEY` | 需要检索影响因子、期刊分区等时建议配置 | 开启 EasyScholar 检索影响因子、JCR 分区、中科院分区、JCI、ESI 和预警字段等能力。建议用 `paper-search setup EASYSCHOLAR_KEY` 通过隐藏输入配置 SecretKey。 |
 | 生物医学高频 | `PUBMED_API_KEY`、`NCBI_EMAIL`、`NCBI_TOOL` | 经常用 PubMed 时建议配置 | 提高 NCBI E-utilities 限额，并让请求带上明确客户端信息。 |
 | 机构权限型 | `WOS_API_KEY` | 有 Web of Science API 权限再配置 | 用于 Web of Science 检索和引文数据；需要 Clarivate API 权限。 |
+| 机构权限型 | `IEEE_API_KEY` | 有 IEEE Xplore API 权限再配置 | 用于 IEEE Xplore 元数据检索；IEEE 可能要求注册 API 访问和产品权限。 |
 | 机构权限型 | `ELSEVIER_API_KEY` | 有 Scopus 或 ScienceDirect API 权限再配置 | 同一个 Elsevier key 不等于自动拥有两个产品权限，Scopus 和 ScienceDirect 需要分别开通。 |
 | 机构权限型 | `SPRINGER_API_KEY`、`SPRINGER_OPENACCESS_API_KEY` | 需要 Springer 平台时再配置 | 用于 Springer 元数据和开放获取记录；401 通常表示 key 无效或产品权限未开通。 |
 | 机构权限型 | `WILEY_TDM_TOKEN` | 有 Wiley TDM/机构全文权限再配置 | 仅支持 DOI 下载；能否下载取决于 token 和机构订阅权限。 |
@@ -174,6 +237,9 @@ cp .env.example .env
 WOS_API_KEY=your_web_of_science_api_key_here
 WOS_API_VERSION=v1
 
+# IEEE Xplore，IEEE 元数据检索必需
+IEEE_API_KEY=your_ieee_api_key_here
+
 # PubMed，可选；从 3 requests/sec 提升到 10 requests/sec
 PUBMED_API_KEY=your_ncbi_api_key_here
 NCBI_EMAIL=you@example.com
@@ -182,6 +248,9 @@ NCBI_TOOL=paper-search-cli
 # Semantic Scholar，正文片段检索必需，也可提升请求限额
 SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_api_key_here
 
+# EasyScholar，检索影响因子、JCR 分区和中科院分区等信息时必需
+EASYSCHOLAR_KEY=your_easyscholar_secret_key_here
+
 # Elsevier，Scopus 和 ScienceDirect 必需；两个产品仍需要分别开通权限
 ELSEVIER_API_KEY=your_elsevier_api_key_here
 
@@ -192,10 +261,10 @@ SPRINGER_OPENACCESS_API_KEY=your_openaccess_api_key_here
 # Wiley TDM，Wiley DOI 下载必需
 WILEY_TDM_TOKEN=your_wiley_tdm_token_here
 
-# Crossref polite pool，可选但推荐
+# Crossref polite pool，可选但推荐；setup 直接回车会自动生成/复用随机 Gmail 格式邮箱
 CROSSREF_MAILTO=you@example.com
 
-# Unpaywall，DOI 开放获取解析必需
+# Unpaywall，DOI 开放获取解析必需；setup 直接回车会自动生成随机 Gmail 格式邮箱
 PAPER_SEARCH_UNPAYWALL_EMAIL=you@example.com
 UNPAYWALL_EMAIL=you@example.com
 
@@ -211,8 +280,10 @@ OPENAIRE_API_KEY=your_openaire_api_key_here
 ### API Key 获取入口
 
 - Web of Science: [Clarivate Developer Portal](https://developer.clarivate.com/apis)
+- IEEE Xplore: [IEEE Xplore Metadata API](https://developer.ieee.org/docs/read/Searching_the_IEEE_Xplore_Metadata_API)
 - PubMed: [NCBI API Keys](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)
 - Semantic Scholar: [Semantic Scholar API](https://www.semanticscholar.org/product/api)
+- EasyScholar: [EasyScholar Open API](https://www.easyscholar.cc/console/user/open)
 - Elsevier: [Elsevier Developer Portal](https://dev.elsevier.com/apikey/manage)
 - Springer Nature: [Springer Nature Developers](https://dev.springernature.com/)
 - Wiley TDM: [Wiley Text and Data Mining](https://onlinelibrary.wiley.com/library-info/resources/text-and-datamining)
@@ -319,8 +390,20 @@ paper-search run search_crossref --arg query="machine learning" --arg maxResults
 paper-search run search_papers --json-args '{"query":"machine learning","sources":"crossref,openalex","maxResults":2}' --pretty
 paper-search run search_pubmed --json-args '{"query":"osteoarthritis","maxResults":5,"sortBy":"date"}' --pretty
 paper-search run get_paper_by_doi --arg doi="10.1038/nature12373" --pretty
+paper-search run query_journal_metrics --json-args '{"journals":["Nature","BMJ"],"includeRaw":true}' --pretty
 ```
 
+### `paper-search journal-metrics`
+
+通过 EasyScholar 检索影响因子、期刊分区等信息。需要配置 `EASYSCHOLAR_KEY` 或 `PAPER_SEARCH_EASYSCHOLAR_KEY`。
+
+```bash
+paper-search journal-metrics "Nature" "BMJ" --pretty
+paper-search journal-metrics --file journals.txt --include-raw --pretty
+```
+
+标准化返回字段包括 `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`。
+
 ### `paper-search tools`
 
 列出全部可用工具名、说明和输入 schema。
@@ -357,7 +440,7 @@ paper-search diagnostics --pretty
 ```bash
 paper-search config init --pretty
 paper-search config set SEMANTIC_SCHOLAR_API_KEY your_key --pretty
-paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty
+paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty  # 可选：手动覆盖 setup 自动生成的邮箱
 paper-search config import-env .env --pretty
 paper-search config list --pretty
 paper-search config doctor --pretty
@@ -398,8 +481,9 @@ paper-search run search_papers --json-args '{"query":"machine learning","platfor
 
 ```text
 crossref, arxiv, webofscience, wos, pubmed, biorxiv, medrxiv, semantic,
-iacr, googlescholar, scholar, scihub, sciencedirect, springer, scopus,
-openalex, unpaywall, pmc, europepmc, core, openaire, all
+iacr, googlescholar, scholar, scihub, ieee, sciencedirect, springer,
+springerlink, scopus, openalex, unpaywall, pmc, europepmc, core,
+openaire, dblp, acm, usenix, openreview, all
 ```
 
 多源检索使用 `sources`：
@@ -447,6 +531,24 @@ paper-search run search_openaire --arg query="machine learning" --arg maxResults
 
 Unpaywall 只支持 DOI，且需要配置 email。CORE 匿名访问可能很快返回空结果或被限流，长期使用建议配置 API key。
 
+### 注册表驱动的平台检索
+
+这些偏元数据检索的工具由平台注册表生成；后续接入新平台时，只需要增加新的 searcher 和平台注册信息：
+
+```bash
+paper-search run search_dblp --arg query="graph neural networks" --arg maxResults=5 --pretty
+paper-search run search_acm --arg query="software testing" --arg maxResults=5 --pretty
+paper-search run search_usenix --arg query="file systems" --arg maxResults=5 --pretty
+paper-search run search_openreview --arg query="large language models" --arg maxResults=5 --pretty
+paper-search run search_springerlink --arg query="machine learning" --arg maxResults=5 --pretty
+```
+
+`search_ieee` 使用同一套通用参数，但需要配置 `IEEE_API_KEY`：
+
+```bash
+paper-search run search_ieee --arg query="wireless networks" --arg maxResults=5 --arg articleTitle="wireless" --pretty
+```
+
 ### `search_webofscience`
 
 搜索 Web of Science。需要 `WOS_API_KEY`。
@@ -488,6 +590,17 @@ paper-search run search_semantic_scholar --json-args '{"query":"graph neural net
 paper-search run search_semantic_snippets --arg query="CMAverse mediation bootstrap confidence interval" --arg limit=5 --arg fieldsOfStudy=Medicine --pretty
 ```
 
+### `query_journal_metrics`
+
+检索 EasyScholar 影响因子、期刊分区等信息。它不是论文检索来源，而是影响因子与期刊分区检索工具，适合投稿规划、目标期刊筛选和投稿前检查。需要配置 `EASYSCHOLAR_KEY` 或 `PAPER_SEARCH_EASYSCHOLAR_KEY`。
+
+```bash
+paper-search run query_journal_metrics --json-args '{"journals":["Nature","BMJ"]}' --pretty
+paper-search run query_journal_metrics --json-args '{"journal":"Journal of Medical Internet Research","includeRaw":true}' --pretty
+```
+
+标准化的 `core` 对象只返回 EasyScholar 对该期刊实际存在的字段，例如影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI、预警字段和中文/学科等级信息。需要完整官方和自定义等级数据时，使用 `includeRaw=true` 保留 `officialRank.all`、`officialRank.select` 和 `customRank`。
+
 ### `search_iacr`
 
 搜索 IACR ePrint Archive。
@@ -549,29 +662,31 @@ paper-search run get_paper_by_doi --arg doi="10.1038/nature12373" --arg platform
 
 ### `download_paper`
 
-从支持的平台下载 PDF。
+从指定平台下载 PDF。如果该平台没有原生下载器，或原生下载失败，会进入与 `download_with_fallback` 相同的下载漏斗。
 
 ```bash
 paper-search run download_paper --arg paperId="2301.00001" --arg platform=arxiv --arg savePath=./downloads --pretty
 ```
 
-支持下载的平台：
+原生下载平台：
 
 ```text
 arxiv, biorxiv, medrxiv, semantic, iacr, scihub, springer, wiley,
 pmc, europepmc, core
 ```
 
+其他已注册来源，例如 `crossref`、`openalex`、`dblp`、`acm`、`usenix`、`openreview`，也可以传给 `download_paper`；它们会直接进入元数据/仓储/Unpaywall/Sci-Hub 回退漏斗。
+
 ### `download_with_fallback`
 
-按开放获取优先顺序尝试下载：
+按完整下载漏斗尝试下载。顺序是原生下载、元数据 PDF URL、仓储发现、Unpaywall DOI 解析，最后默认使用 Sci-Hub 兜底：
 
 ```bash
 paper-search run download_with_fallback --arg source=arxiv --arg paperId=1201.0490 --arg doi=10.48550/arxiv.1201.0490 --arg savePath=./downloads --pretty
-paper-search run download_with_fallback --arg source=crossref --arg paperId="10.1038/nature12373" --arg doi="10.1038/nature12373" --arg savePath=./downloads --arg useSciHub=false --pretty
+paper-search run download_with_fallback --arg source=crossref --arg paperId="10.1038/nature12373" --arg doi="10.1038/nature12373" --arg savePath=./downloads --pretty
 ```
 
-`useSciHub` 默认为 `false`；只有明确选择该最后兜底路径时才设置为 `true`。
+`useSciHub` 默认为 `true`；只有需要关闭该最后兜底路径时才设置为 `false`。`download_paper` 在指定平台下载失败或平台不支持直接下载时，也会进入同一条漏斗。
 
 ### `search_wiley`