O0000-code/paper-search-pro · 上手攻略
- 仓库：O0000-code/paper-search-pro
- 链接：https://github.com/O0000-code/paper-search-pro
- 分类：academic-writing · research-tool
- 作者：Tom
- 更新：2026-08-13
是什么
paper-search-pro 是一个面向 AI Agent 的学术文献检索 Skill，专为 Claude Code、Codex 等加载 SKILL.md 的 Agent 设计。它以对话触发、多源并行检索、可视化报告为特色——对 Agent 说"找几篇关于 X 的论文"，Agent 就会自动跨 OpenAlex、Semantic Scholar、CrossRef、PubMed、arXiv 五大英文来源发起检索，必要时加上中文原生来源（NSSD 国家哲社文献中心、yiigle 中华医学期刊），并通过并行 SubAgent 做相关性分类，最终吐出一份自包含的 Shadcn 风格 HTML 报告，同时导出 BibTeX、RIS、CSV、PRISMA-S 16 项审计日志。
核心设计哲学：Python 脚本做确定性 API 调用（无 LLM、无外部密钥），LLM 分类全部委托给 Agent 自身的 SubAgent，因此不需要任何第三方 LLM API 密钥。配置文件在 ~/.paper-search-pro/config.yaml。
解决什么问题
学术文献检索一直是 Agent 工作流的痛点：单源搜索覆盖率不够；跨源整合靠人工；下载工具和检索工具互相割裂；Zotero/Mendeley 需要的 BibTeX/RIS 要手动转换。paper-search-pro 把这件事自动化到 Agent 内部——你说"帮我做系统评价的文献检索"，Agent 跑完全套流程，直接给你一份带期刊分区的 HTML 报告和可导入 Zotero 的 BibTeX 文件。
快速安装
前置：Python 3.10+，5 个免费 API 密钥（约 15 分钟完成配置）。
# 克隆到 Skills 目录（选择与你 Agent 对应的路径）
git clone https://github.com/O0000-code/paper-search-pro.git \
~/.claude/skills/paper-search-pro # Claude Code
# 或 ~/.codex/skills/paper-search-pro # Codex CLI
# 或 ~/.agents/skills/paper-search-pro # 跨 Agent 通用
# 安装 Python 依赖
export PSP_HOME="$HOME/.claude/skills/paper-search-pro"
pip install -r "$PSP_HOME/scripts/requirements.txt"
5 个免费 API 密钥（详见 references/setup.md）：
| 层级 | 来源 | 用途 | 密钥申请 |
|---|---|---|---|
| L1（必选） | OpenAlex | 主检索源 | openalex.org/settings/api（免费） |
| L2 | PubMed | 医学/MeSH 丰富 | account.ncbi.nlm.nih.gov（免费） |
| L2 | arXiv | CS 预印本新鲜度（T-0~T-4） | 无需密钥（SDK 内置限速 1 req/3s） |
| L3 | Semantic Scholar | 引用影响力 + 摘要兜底 | semanticscholar.org（免费） |
| L3 | CrossRef | 资助方/许可证/临床试验号 | 无需密钥（只需 email） |
⚠️ NSSD 和 yiigle 两个中文来源无需额外密钥，当查询含中文时自动路由启用。
验证配置就绪：
PYTHONPATH=$PSP_HOME python3 -c \
"from scripts.config import load_config; c = load_config(); \
print('ready' if c.openalex_api_key and c.ncbi_email else 'missing')"
核心用法
Agent 对话触发（主要方式）
在 Agent 对话中直接说：
Find papers on working memory training in older adults
找几篇关于大语言模型幻觉的论文
帮我做一下系统评价的文献检索
Agent 会自动加载 SKILL.md 并执行 14 步流程，无需手动干预。
四种深度档位
| 档位 | 耗时 | 文献量 | 触发词 |
|---|---|---|---|
| Quick | ~5–8 分钟 | 20–60 篇 | "scan" / "找几篇" / "before tomorrow" |
| Standard（默认） | ~10–17 分钟 | 60–180 篇 | 默认 / "background reading" / "课程论文" |
| Deep | ~30–45 分钟 | 180–400 篇 | "thorough" / "review article" / "综述写作" |
| Audit | ~2–3 小时 | 400–1000+ 篇 | "systematic review" / "PRISMA" / "Cochrane" |
⚠️ Audit 档位运行时间长，Skill 会在启动前给出限制警告，需显式确认。
Agent 机器模式（结构化数据）
如果你自己就是 Agent，希望拿到结构化 JSON 而不是 HTML 报告：
PYTHONPATH=$PSP_HOME python3 -m scripts.agent_search "<query>" > result.json
这会跳过 LLM 分类步骤，直接输出含相关性分数、期刊指标、配额状态的 JSON 包。适合作为上游喂给其他 Agent 流程。详见 references/agent_mode.md。
输出文件结构
所有结果落入 $PWD/paper-search-results/<search_id>/：
| 文件 | 用途 |
|---|---|
report.html |
Shadcn 风格三标签页报告，可直接浏览器打开 |
report.md |
Markdown 版本，适合 pandoc 或笔记工具 |
papers.csv |
电子表格导出 |
papers.bib |
BibTeX，导入 Zotero / Mendeley / LaTeX |
papers.ris |
RIS，导入 EndNote / Papers |
papers.json |
完整结构化数据（UnifiedPaperEntity[]） |
kg_classified.json |
含 RCS 相关性分数的知识图谱 |
execution_log.json |
PRISMA-S 16 项审计日志 |
summary.md |
300 词执行摘要（Agent 风格） |
典型适用场景
- 开题报告前文献调研：Standard 档 10–17 分钟拿到 60–180 篇覆盖 + 期刊分区标记，快速判断研究空白
- 系统评价 / Meta 分析准备：Audit 档输出 PRISMA-S 16 项审计日志，兼容 PRISMA 规范
- 研究生课程论文：Quick 档 5 分钟快速摸底，背景章节 BibTeX 直接导入 Zotero
- 中文核心期刊文献检索：查询含中文自动路由 NSSD/yiigle，覆盖 CSSCI、中华医学期刊等中文原生来源
- 新研究领域入门：把生成的
report.html直接丢给新来的研究助理，三个标签页 + hover 上下文，无需解释就能上手
坑与注意
-
不要
cd进 Skill 目录：SKILL.md 明确禁止，.会指向 Skill 资产目录，导致输出文件落在安装目录内（重装丢失）。始终在用户 PWD 运行，用PYTHONPATH=$PSP_HOME方式调用脚本。 -
SubAgent 必须并行调度：STEP 6 的相关性分类每次最多 5 个 SubAgent 并行写入同一文件；串行调度会让 Standard 档从 ~10 分钟膨胀到 ~17 分钟。
-
OpenAlex 配额耗尽自动降级：当主源（L1）配额不足时，自动切到 Semantic Scholar 做主源，不是中断。这是一种降级优雅，不是错误。
-
arXiv 无需密钥但严格限速：SDK 内置 1 req/3s，不申请密钥反而是正确做法，不要尝试申请。
-
中文查询路由 NSSD/yiigle：这两个中文来源不需要额外密钥，当查询检测到中文时会自动启用。但中文来源覆盖率受限于平台本身数据量，非所有中文论文都能命中。
-
期刊分区数据实时拉取：中科院 CAS/JCR/SJR 分区数据来自运行时公开镜像，非打包静态数据；镜像不可用时会退化为"分区未知"。JCR 数值标注了 impact factor 标签，CAS/SJR 未标注，注意区分。
-
PRISMA-S 日志仅 Audit 档完整：Quick/Standard 档的
execution_log.json字段不完整，不适合用作正式系统评价的审计记录。
与同类对比
| 工具 | 定位 | 优点 | 缺点 |
|---|---|---|---|
| paper-search-pro（本工具） | Agent 内置 Skill | 无需第三方 LLM 密钥、多源并行、中文原生支持、报告完整 | 需 5 个 API 密钥配置、仅 Agent 内使用体验最佳 |
| Connected Papers | 可视化引文图 | 交互友好、开箱即用 | 非 API、无法批量、不支持中文 |
| ResearchRabbit | 引用网络挖掘 | 可视化强 | 无命令行/Agent 接口 |
| Semantic Scholar | 单源检索 | 免费、无需配置 | 多源整合差、无报告导出 |
| Litmaps | 引文时序地图 | 视觉化优秀 | 无 Agent 接口、贵 |
paper-search-pro 的核心差异是深度嵌入 Agent 工作流：不是独立工具，而是让 AI Agent 本身具备文献检索能力的 Skill，且无需额外 LLM 密钥（SubAgent 的 LLM 就是 Agent 自己）。
一句话推荐结论
如果你在用 Claude Code 或类似 Agent 写论文、做文献综述，paper-search-pro 是目前最顺滑的「零额外密钥、全流程自动化」学术检索方案——开口就能得到一份带期刊分区和 BibTeX 导出、可直接交给 Zotero 的完整报告。
原始仓库：https://github.com/O0000-code/paper-search-pro · Apache-2.0 License