paperseek/paperseek · 上手攻略

仓库：paperseek/paperseek
链接：https://github.com/paperseek/paperseek
分类：engineering / academic-writing / literature-search
作者：spark
更新：2026-10-29

0. 自检清单（三证）

[x] GitHub URL（已 fetch README + docs.paperseek.app 的 changelog / sources 文档）
[x] README 子模块 anchor：backend/（Python 项目）、integrations/skills/paperseek（Agent Skill）、.env.example、docker/、THIRD_PARTY_NOTICES.md、CONTRIBUTING.md、SECURITY.md 均在 README 中有明确说明
[x] 论文/机构 anchor —— 本仓库不是论文仓库，无顶会 venue 可引；替代锚点为 Apache-2.0 许可、官方文档站 docs.paperseek.app、在线版 paperseek.app、ModelScope Studio 镜像、版本 1.0.0b5
[x] 版本提示：本文写作时最新为 1.0.0-beta5（pip 包 paperseek==1.0.0b5，Docker tag 1.0.0-beta5）。changelog 明确说预发布版不会更新 latest，必须显式 pin

1. 是什么

PaperSeek 是一个开源的 AI 驱动文献检索与初步文献计量工具。核心命题一句话说清：把研究问题变成阅读清单——你不需要会写检索式，只需要描述"你想研究什么关系、方法、人群或空白"，它把问题翻译成各数据源的检索式，用检索反馈迭代优化，然后召回候选论文、做相关性排序，并让你看到排序过程。

它是一个完整产品而不只是脚本：包含 Web UI（Vue 3 + TypeScript + Vite）、CLI、HTTP API（/api/v1）、MCP 服务器（paperseek-mcp），以及一个可装进 Agent 的 Skill。1.0 线是一次彻底的架构重构，围绕"持久化任务 + 共享核心"重建：搜索、文献计量（Bibliometrics）、综述（Reviews）三个模块各有独立历史。

Python / FastAPI / httpx 后端，Apache-2.0 许可，约 209 stars（仓库卡显示周增 +14，属于低调但持续的类型）。成熟度标注为 experimental，学术相关度 80，学术主任务被判定为 systematic-review（literature-search 辅助）。

2. 解决什么问题

学术工作者找文献的经典痛点是"关键词检索 vs 真实问题"之间的鸿沟。PaperSeek 针对四个具体问题：

你有问题，但没有检索式。第一步"Understand"——解释问题、规划数据源特定检索式；空搜索时最多再自动生成两个查询并逐一对照你的问题做校验。
单库检索视野窄。它接入 OpenAlex、arXiv、Crossref、Semantic Scholar、PubMed、Google Scholar（经 Serper）、PaperHub（顶会）、Web of Science Starter，以及三个中文库：万方、NSSD（国家哲学社会科学文献中心）、Yiigle（中华医学会期刊）。中文库的检索计划、概念组和查询全部用中文构建。
结果只是一张平表。它做引文扩展（OpenAlex 沿 references 与 citing works 双向扩展）、交互式引文地图，以及覆盖完整去重语料的初步文献计量：分布、关键词共现、文献耦合。
写综述时找不到论文 / 引用对不上。Reviews 模块先定范围，再按主题自动选最多 256 篇，生成大纲与分段草稿，并显式列出大纲或草稿漏掉了哪些论文及原因；引用链接回 abstract 证据。

一个关键设计：整个检索过程可检视。查询迭代历史、各源命中数、候选召回、排序进度、"Why it ranks"解释都摆在界面上，保存的 run 可事后回看。## 3. 快速安装

方式 A：pip 安装（社区版，需要 Python 3.12+）

python -m pip install "paperseek==1.0.0b5"
paperseek serve

然后打开 http://127.0.0.1:8765，在界面里配置模型连接和数据源，再输入你的研究问题。社区版不需要注册账号。

⚠️ 版本必须 pin。README 与 changelog 都强调：预发布版不会更新 latest 标签，.env.example 和 Compose 文件默认也是 1.0.0-beta5。

方式 B：Docker Compose

git clone https://github.com/paperseek/paperseek.git
cd paperseek
cp .env.example .env
PAPERSEEK_VERSION=1.0.0-beta5 docker compose up -d

编辑 .env 后再启动。PowerShell 用户把 cp 换成 Copy-Item，并用 $env:PAPERSEEK_VERSION="1.0.0-beta5"; docker compose up -d。

Compose 服务默认只发布到 127.0.0.1:8765，并使用持久化的 paperseek-data 卷。若要从其他设备访问，需在 .env 里设 PAPERSEEK_HOST=0.0.0.0 并自行做访问保护（PAPERSEEK_PORT 改端口）。

方式 C：从源码开发

git clone https://github.com/paperseek/paperseek.git
cd paperseek
python -m pip install ./backend

Python 项目在 backend/ 下。前端开发与不含预构建资产时构建 checkout 的方法见 CONTRIBUTING.md。

MCP 服务器

python -m pip install "paperseek-mcp==1.0.0b5"
paperseek-mcp --transport stdio

Streamable HTTP 也可用（给兼容客户端）。MCP 工具可以：发起 run、跟踪状态、读结果与引文图、取消任务、导出 JSON/CSV/BibTeX/RIS。

⚠️ 一个环境变量陷阱

直接跑 CLI 时读的是进程环境变量，不会自动加载 .env；Docker Compose 才会显式加载该文件。 这意味着你 cp .env.example .env 后直接 paperseek serve，模型密钥可能读不到。

本地历史默认存在 ~/.paperseek/paperseek.db。备份时要把它周围的数据目录、artifacts 和加密密钥一起搬，否则恢复不出来。

4. 核心用法

4.1 四步工作流

步骤	发生什么	你能检查什么
1. Understand	解释问题、规划数据源特定检索式	研究范围与检索策略
2. Refine	用源反馈测试并调整查询	查询历史、源命中计数
3. Retrieve & rank	收集候选、可选引文扩展、算相关性	召回进度、排序结果
4. Explore	呈现论文、连接与导出	结果、引文地图、保存的历史

一次 run 只从一个选定数据源开始——"互补的检索路径"不等于所有库同时被搜。源命中数、下载的候选数、最终结果是三个不同的集合，别混。

4.2 CLI

六个命令：serve、worker、search、doctor、migrate、version。

paperseek search "How does open-source funding affect maintenance?" \
  --source openalex \
  --search-budget medium \
  --output json

凭据要先配到进程环境里（CLI 不读 .env）。doctor 可以用来诊断连接与配置问题。

4.3 模型与排序

主模型负责查询规划和相关性评估，协议要选供应商真正支持的那个：

协议	配置值
OpenAI Responses	`openai_responses`
OpenAI 兼容 Chat Completions	`openai_chat`
Anthropic Messages	`anthropic_messages`

初步排序（preliminary ranking）有三条路径：

Local fusion（默认）：融合本地词法与语义信号，不需要额外配置排序服务。但它不免除主模型要求。
Embedding + Rerank：用外部向量与重排服务。
System One：用配置的决策服务做初筛，例如 TypeSafe Jev。

Jev 路径：加一个 System One 连接（provider 选 TypeSafe，模型 jev-latest），再把 preliminary ranking 选为 System One decision。Jev 会对本地融合后的候选做评估，评估数量最多是最终候选预算的两倍，之后主模型再给最终子集打分。

4.4 数据源与凭据

源	用途	是否需要 key
OpenAlex	广谱学术发现 + 引文扩展	推荐（Community 可选）
arXiv	预印本	不需要
Crossref	DOI 与出版元数据	不需要
Semantic Scholar	论文与学术图谱	可选
PubMed	生物与生命科学	可选 NCBI key
Google Scholar（Serper）	Scholar 结果	必须
PaperHub	顶会 CS 论文集（含 OpenReview 已接收）	不需要
Web of Science Starter	WoS 集合检索	必须 Clarivate key
万方数据	中文学位/期刊/会议论文	必须 Wanfang AppKey
NSSD	中文社科人文期刊	不需要
中华医学会期刊（Yiigle）	中文医学期刊标题与摘要	不需要

Online BYOK 模式策略不同：每个需要 key 的源（包括 OpenAlex、PubMed、Semantic Scholar）都得在 Settings 里存自己的 key；arXiv、Crossref、PaperHub 不需要。另外"模型 key 不等于数据源 key"——PaperSeek Service 托管源访问，但 WoS 和万方永远要你自己的 key。

三个中文库的查询形式各不相同：

万方：发 Wanfang PQ 表达式，例如 (数字治理 OR 数字化治理) AND 乡村振兴，核心概念需要时才加 标题: / 关键词: / 摘要: 字段限定；
NSSD：中文词用 AND / OR / NOT，每个词同时搜标题、主题词和摘要；
中华医学会期刊：2–4 个空格分隔的中文词，数据库要求全部匹配、没有 OR，所以每个概念只保留一个词。

常用缩写保持原样（SGLT2、COVID-19 这类不会被翻译）。

4.7 综述功能（实验性）

流程：先设主题与长度 → 选有可用 abstract 的论文（或让写作模型按主题自动选）→ 生成并编辑大纲 → 写并修改各段。工位支持版本管理、链接引用，以及 Markdown / Word / BibTeX 导出。

限制说得很直白：综述只基于可用 abstract 和元数据，不代表模型读过全文 PDF。用草稿前必须回原文核对证据与引用。

4.8 期刊分区与会议接收

CAS 分区、Top、JCR 分区与影响因子、CCF 等级来自 ShowJCR（运行时下载，不再分发）；
会议接收（venue、年份、Oral/Spotlight/Poster）来自 PaperHub 和 OpenReview，只计入主会、NeurIPS Datasets & Benchmarks、TMLR；
中文期刊标注北大核心、CSSCI 来源期刊/来源集/扩展，带版本信息。

4.9 Agent Skill

integrations/skills/paperseek 目录下有 PaperSeek Skill，可加进兼容的 Agent 做本地文献检索。它会引导安装检查、Community 隔离安装（缺失时）、配置、检索与结果保存。CLI 使用不需要 MCP。

5. 典型适用场景

系统综述的选题与初步检索：定问题、生成检索式、跨源收集、去重、文献计量、导出 BibTeX/RIS 送进 Zotero/EndNote；
开题阶段的文献地图：用引文扩展 + 引文图看清方向脉络与枢纽论文；
中文社科/医学综述：万方 + NSSD + 中文医学期刊覆盖英文库覆盖不到的中文文献；
团队私有部署：社区版无账号体系、数据全本地，只需自备模型 API key；
给 Agent 装文献检索工具：MCP 或 Skill 两种接法，可发起 run、查状态、取结果、导出。

6. 坑与注意

版本必须显式 pin。1.0.0-beta5 是预发布版，latest 不会跟着更新。1.0 之前的 beta 之间是原地升级、无需迁移；但从 0.2 升级需要 Python 3.12+，且旧的内部 import、前端 endpoint、废弃的命令与配置不保留。
CLI 不读 .env。直接 paperseek serve 可能读不到模型配置；Docker Compose 会显式加载。这是最高频的"装完跑不起来"原因。
社区版是"单用户、受信环境"设计，没有登录。ModelScope Studio 那份是共享的——任何能打开公开 Studio 的人都能看到你的设置、存的 key 和历史，一定要 fork 成私有副本。
空结果不代表文献不存在。最多两个额外查询之后仍无果，会给出说明性提示并结束，而不是静默丢掉你问题里的必要条件。rate limit 和 API 格式错误会被识别为"源的问题"，不是"零匹配"。
速率限制是共享的：同一 PaperSeek 进程里所有任务共享同一源的 pacing 和冷却，arXiv 无论几个搜索并行都是每 3 秒一个请求。但另一个独立进程或另一个用同一账号的应用仍然共享上游配额，重试保证不了可用性。
网络代理不等于提额。代理能绕开按 IP 限速的源，但不会提升 key 的配额。代理地址加密存储，界面只显示 host 和 port。
限制字段可能误伤交叉学科工作。文档建议：除非研究设计确实需要，否则先别加字段限制。
缺失元数据不是质量判断。记录可能没有 abstract、年份、引用数或开放 PDF 链接——别把它读成"差论文"。
1.0.0-beta5 没有跨源 abstract 补全或引用数增强开关，写综述时要挑 abstract 信息量大的论文。
综述是实验性功能。自动选题只看前 256 篇有可用 abstract 的论文，按主题覆盖度挑选并给理由；每段计划最多用 10 篇；写时跳过某篇必须写原因，证据检查会标记存疑项。
ShowJCR 分区表在运行时从 GitHub 下载。GitHub 不可达时需自己配代理或导入本地文件；否则分区标签会缺失。
升级后旧结果没有新标签。分区标签是在搜索完成时加的，早于该版本的结果没有；需重跑一次搜索。想看 Venue rankings 视图要重新生成文献计量分析。
⚠️ 本地历史数据库与加密密钥绑在一起，单独备份 .db 而丢掉密钥目录会导致历史无法解密。
⚠️ 本文依据 README 与 docs 站 changelog / sources / cli 文档编写，未实机安装运行；具体 CLI 参数以 paperseek search --help 与本机版本文档为准。

7. 与同类对比

对比 Semantic Scholar / arXiv：PaperSeek 的价值在"问题驱动"与"多源统一 + 可检视的检索过程"，SS 是"图谱与作者视角"，arXiv 是"预印本纵深"。只找几篇经典的话，SS 更轻。
对比 Elicit：两者都做"问题 → 论文 + 综述"。Elicit 是闭源 SaaS，PaperSeek 是可自托管、可审计、可接 MCP 的开源方案；代价是成熟度（experimental）明显低于 Elicit，且需自备模型 key。
对比 Connected Papers：后者是纯引文可视化，PaperSeek 的引文地图只是其中一个视图，重心在检索与综述。
对比 Zotero + 手工：Zotero 是管理器不是检索器；PaperSeek 做完检索再导出 BibTeX/RIS 进 Zotero，二者是流水线上下游而非竞争关系——这也是它把引用管理器导出做得很认真的原因。

覆盖与协议上，PaperSeek 接 10+ 源（含 3 个中文库）、做 LLM 打分排序、有初步文献计量（分布/共现/耦合）、标注 CAS/JCR/CCF 分区与会议接收、导出 BibTeX/RIS/CSV/JSON 并提供 MCP；Semantic Scholar 以单库图谱为主、Elicit 有综述但无自托管、Connected Papers 只做图谱、Zotero 需手工检索。

8. 一句话推荐结论

如果你需要"从一个问题出发、可检视过程、可自托管、能接进 Agent"的文献检索流水线，PaperSeek 是当前开源阵营里完成度相当高的一个；但它现在仍是 beta，请把它当成"研究流程加速器"而不是"系统综述的合规工具"——它自己不承诺穷尽性检索，综述也只基于 abstract，真要投系统综述，检索式还得手工复核、原文还得自己读。