Paper Search CLI：重构学术检索的 CLI + Skill 范式

背景

在 AI Agent 和自动化工作流日益普及的今天，学术文献检索作为科研辅助的核心环节，其工具链的维护成本正成为痛点。此前，许多开发者依赖 paper-search-mcp 等基于 Model Context Protocol (MCP) 的解决方案进行论文检索。虽然功能完整，但在实际应用中，当用户在多个 AI 模型或 Agent 平台间切换时，MCP 配置往往需要针对每个环境单独设置，导致维护复杂且缺乏灵活性。

与此同时，社区内出现了一种新的趋势：未来的主流交互模式可能逐渐从复杂的 MCP 配置转向更轻量、更通用的 CLI + Skill 架构。在这种架构下，CLI（命令行界面）负责执行具体的逻辑任务，而 Skill（技能描述）则负责向 Agent 解释何时调用、如何调用以及返回何种格式的数据。

基于这一洞察，Paper Search CLI 应运而生。该项目并非从零开始，而是对现有开源项目（如 paper-search-mcp 及原始作者的项目）进行重构与整合。它旨在通过 CLI + Skill 的组合，提供一个面向 Agent、终端用户和脚本的多来源学术文献检索工具，解决配置碎片化问题，并提升在自动化场景下的可用性。

核心内容

Paper Search CLI 是一个开源的学术文献工具，其核心设计理念是将“元数据检索”、“期刊指标”、“PDF 获取”和“正文片段检索”四大能力解耦，并通过统一的命令入口和结构化的 JSON 输出，实现 Agent 友好型（Agent-friendly）的交互体验。

1. 多来源学术检索与漏斗式回退机制

该工具最大的亮点在于其极其广泛的数据源覆盖和智能的下载策略。

• 数据源覆盖：支持超过 20 个主流学术平台，包括 Crossref、OpenAlex、PubMed、arXiv、Semantic Scholar、Web of Science、IEEE Xplore、ScienceDirect 等。此外，还集成了 EasyScholar 以提供中文语境下的期刊指标（如中科院分区、JCR 分区等）。
• 漏斗式 PDF 下载链：在 PDF 获取环节，工具实现了一个名为 download_with_fallback 的智能回退机制。下载优先级依次为：
  1. 原生来源直接下载；
  2. PDF URL 直接获取；
  3. 开放获取仓储（PMC / Europe PMC / CORE / OpenAIRE）；
  4. Unpaywall DOI 解析；
  5. Sci-Hub 兜底：作为最后手段，自动尝试通过 Sci-Hub 获取。 注意：用户可通过传入 useSciHub=false 显式关闭 Sci-Hub 兜底功能，以满足合规性要求。

2. 四大核心工作流

工具将学术任务拆解为四个独立但协同的工作流，每个工作流都有明确的入口和适用场景：

1. 文献元数据检索 (paper-search search)：
   • 功能：查找论文、扩展关键词、综述初筛、验证 DOI/PMID/PMCID/arXiv ID。
   • 输出：题名、作者、年份、期刊、DOI、URL、摘要及来源元数据。
2. 期刊指标检索 (paper-search journal-metrics)：
   • 功能：查询期刊的影响因子、JCR/SSCI 分区、中科院分区、JCI、ESI 预警等。
   • 特点：专注于期刊级指标，而非单篇论文搜索，需配置 EASYSCHOLAR_KEY。
3. PDF 获取和下载 (paper-search download / run download_with_fallback)：
   • 功能：在确认论文身份后，通过原生来源、开放获取来源、权限来源或 Sci-Hub 兜底获取 PDF 文件。
   • 输出：本地保存的 PDF 文件路径及元数据。
4. 正文片段检索 (search_semantic_snippets)：
   • 功能：深入论文正文，查找方法描述、参数、模型名、统计写法等具体线索。
   • 来源：主要依赖 Semantic Scholar 的开放获取（OA）片段。
   • 要求：需配置 SEMANTIC_SCHOLAR_API_KEY 以提升稳定性。

3. CLI + Skill 架构设计

• Skill 层：负责向 AI Agent 提供“能力画像”（Capability Profile）。它告诉 Agent 在什么场景下应该使用 paper-search，选择哪个平台，以及如何解析返回结果。
• CLI 层：负责实际执行逻辑，包括多源检索、去重、指标查询、文件下载和健康检查。
• 管理命令：提供 doctor（健康检查）、smoke（冒烟测试）、skills（Skill 同步）、config（配置查看）和 tools（工具 Schema 查看）等命令，确保工具链的稳定性和可维护性。

4. 平台支持与 API Key 需求

不同平台对 API Key 的要求各异，工具设计兼顾了免 Key 基础使用和 Key 增强体验：

• 免 Key 可用：Crossref、OpenAlex、arXiv、PubMed、DBLP、ACM、USENIX、OpenReview 等提供基础元数据检索。
• 需 Key 增强：
  • SEMANTIC_SCHOLAR_API_KEY：用于正文片段检索及提升 Semantic Scholar 稳定性。
  • CORE_API_KEY：减少 CORE 开放仓储的匿名限流。
  • UNPAYWALL_EMAIL：Unpaywall 仅支持 DOI 查询，需注册邮箱。
  • EASYSCHOLAR_KEY：必需，用于期刊指标查询。
  • IEEE_API_KEY：必需，用于 IEEE Xplore 元数据。
  • 其他出版商（Web of Science, ScienceDirect, Scopus 等）通常需机构权限或特定 API Key。

关键要点

• 架构革新：从 MCP 转向 CLI + Skill，解决了多 AI 环境下的配置碎片化问题，更符合 Agent 调用的标准化需求。
• 极致覆盖：整合了 Crossref、OpenAlex、PubMed、arXiv、Semantic Scholar 等 20+ 平台，几乎覆盖所有主流学术资源。
• 智能下载：内置“漏斗式”回退机制，优先尝试合法开放获取路径，最后以 Sci-Hub 兜底，最大化 PDF 获取成功率。
• Agent 友好：默认输出结构化 JSON，提供 doctor、tools 等管理命令，便于脚本解析和 Agent 自动决策。
• 模块化设计：将元数据、指标、下载、正文片段解耦为四个独立工作流，用户可根据需求灵活调用，无需加载全部功能。
• 开源合规：项目完全开源，无未开源部分，并遵循 LINUX DO 社区的开源推广规范，接受社区监督。

意义与影响

Paper Search CLI 的出现标志着学术检索工具向“自动化优先”和“标准化接口”迈出了重要一步。

首先，它降低了 AI Agent 接入学术资源的门槛。通过 Skill 描述和标准化的 JSON 输出，Agent 可以更准确地理解何时调用检索、何时下载、何时分析，从而构建更复杂的科研辅助工作流（如自动文献综述、竞品分析、实验参数复现等）。

其次，它解决了多源数据整合的痛点。研究人员无需在多个数据库间切换，一个命令即可通过统一的漏斗机制获取最全面的元数据和全文资源，极大地提升了科研效率。

最后，该项目为开源社区提供了一个优秀的 CLI + Skill 实践案例。它证明了在 AI Agent 时代，轻量级、模块化、标准化的命令行工具依然具有强大的生命力，并为后续其他领域（如代码搜索、专利检索）的工具开发提供了可参考的架构范式。