paperseek 0.1.0

LLM based Literature Search Agent

PaperSeek

文档站：PaperSeek Docs | 语言：简体中文 | English

LLM based Literature Search Agent. PaperSeek 是一个面向研究者的文献发现工具，支持用自然语言发起检索、自动迭代查询、扩展候选论文、排序结果并导出可复核的文献列表。

在线体验：点击体验。在线版提供 Quick Start、ModelScope Service 和 Use your own API 三种模式：登录用户可使用站点提供的每日免费 Quick Start 额度；ModelScope 模式使用登录用户自己的 API-Inference 授权；自带 API 模式可由用户填写自己的模型和数据源 Key。详情见 在线体验版使用说明。

完整使用说明见 PaperSeek 用户手册；部署说明见 Docker、Vercel 与 ModelScope 部署指南。

概览

PaperSeek 将研究问题组织成一条可观察的检索工作流：

• 输入中文或英文研究问题。
• 由 LLM 生成适合数据源的检索查询。
• 根据命中数量自动放宽或收窄查询。
• 统一整理题名、作者、期刊、年份、DOI、摘要、引用数和链接等元数据。
• 对候选文献进行 LLM 相关性评分。
• 可选地通过 OpenAlex 引用关系扩展高匹配论文的前向引用和后向参考文献。
• 可选地用 Discipline Fields 把检索限制在一个或多个学科领域。
• 在网页中查看工作流、结果表和引用图，并导出 CSV。

PaperSeek 专注于第一轮候选文献发现和元数据整理。系统综述流程、全文获取、版权合规和最终研究判断仍需由研究者完成。

功能概览

功能	说明
自然语言检索	输入研究问题，自动生成数据源查询。
多轮迭代	根据目标结果数量自动调整查询，默认最多 5 轮。
相关性排序	LLM 对候选论文打分并给出简短理由。
Discipline Fields	在 Web UI 或 CLI 中选择 OpenAlex Field 学科分类；OpenAlex 使用原生 field filter，WoS 映射为 WC 类目，Crossref 作为检索上下文。
OpenAlex 引用扩展	从高匹配论文扩展参考文献和被引论文。
结果导出	在 Results 页面勾选论文并导出 CSV。
引用图	使用箭头显示引用方向，支持拖拽、缩放和平移。
CLI 与 Web UI	既可命令行运行，也可打开本地网页交互使用。
中英文界面	Web UI 可在 EN 和 中文 之间切换，选择会保存在当前浏览器。
本地历史记录	开源自托管版默认把搜索记录、日志事件和结果保存到本地 SQLite，便于回看和复用。
Docker / Vercel / ModelScope 部署	支持 Docker 完整部署、Vercel 一键体验部署和 ModelScope Docker 创空间部署。
配置诊断	doctor、smoke、sources 帮助排查 API Key、数据源和协议问题。
可选 Agent Skill	skills/paperseek/ 可单独复制到支持 Skill 的 agent 平台，不随 Python 包自动安装。

快速开始

git clone https://github.com/MingfengHong/paperseek.git
cd paperseek
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Windows PowerShell：

git clone https://github.com/MingfengHong/paperseek.git
cd paperseek
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

启动网页界面：

paperseek-web

打开：

http://127.0.0.1:8765/

也可以直接使用命令行：

paperseek "open innovation and digital platforms" --source openalex

部署

Docker 是完整 Web UI 的推荐部署方式：

docker compose up --build

打开：

http://127.0.0.1:8765/

Vercel 可用于快速体验和轻量 Web UI 部署：

ModelScope 创空间也可通过 Docker 方式部署。点击下方按钮查看 PaperSeek 的创空间部署步骤：

长时间搜索、引用扩展和大量请求建议使用 Docker 或 VPS。完整说明见 部署指南。

最小配置

PaperSeek 至少需要一个 LLM。默认数据源是 OpenAlex；OpenAlex 可匿名测试，但建议申请免费 API Key 以获得更稳定的访问体验。

以 DeepSeek 为例：

export LLM_PROVIDER=deepseek
export LLM_API_TYPE=openai_chat
export LLM_MODEL=deepseek-v4-flash
export LLM_BASE_URL=https://api.deepseek.com
export LLM_API_KEY=your-llm-api-key
paperseek-web

以中国科技云为例：

export LLM_PROVIDER=cstcloud
export LLM_API_TYPE=openai_chat
export LLM_MODEL=DeepSeek-V4-Flash
export LLM_BASE_URL=https://uni-api.cstcloud.cn/v1
export LLM_API_KEY=your-cstcloud-api-key
paperseek-web

以 ModelScope API-Inference 为例：

export LLM_PROVIDER=modelscope
export LLM_API_TYPE=openai_chat
export LLM_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507
export LLM_BASE_URL=https://api-inference.modelscope.cn/v1
export LLM_API_KEY=your-modelscope-token
paperseek-web

Windows PowerShell：

$env:LLM_PROVIDER = "deepseek"
$env:LLM_API_TYPE = "openai_chat"
$env:LLM_MODEL = "deepseek-v4-flash"
$env:LLM_BASE_URL = "https://api.deepseek.com"
$env:LLM_API_KEY = "your-llm-api-key"
paperseek-web

本地 Ollama 不需要 LLM API Key：

export LLM_PROVIDER=ollama
export LLM_API_TYPE=openai_chat
export LLM_MODEL=qwen3:8b
export LLM_BASE_URL=http://127.0.0.1:11434/v1
paperseek-web

项目提供 .env.example。你可以复制为 .env 作为本地配置参考，但不要提交真实 API Key。CLI 和 Web 后端会自动读取当前目录或项目根目录下的 .env；已经存在的系统环境变量优先于 .env。

Web UI

PaperSeek 的网页界面分为四个工作区：

页面	用途
Search	输入研究问题，选择 Discipline Fields，配置数据源、LLM、迭代次数和目标结果数；实时查看工作流与系统日志。
Results	查看最终排序结果，搜索、过滤、排序、勾选，并导出论文 CSV。
Citation Map	查看 OpenAlex 引用扩展形成的关系图，按箭头方向探索论文之间的引用关系。
History	查看本地保存的搜索运行、最终检索式、结果列表和运行事件。

如果后端已经通过系统环境变量或 .env 配置了 API Key，Web UI 会显示环境中已配置的状态，不会把密钥内容发送到浏览器。Web UI 中填写的 API Key、Base URL 和参数只用于当前浏览器会话，不写入本地配置文件。历史记录会保存运行参数摘要、检索式、日志事件和结果，但不会保存任何 API Key。

Results 导出的 CSV 文件名使用研究问题主题和本地日期，便于区分多次运行。

CLI 用法

基本检索：

paperseek "responsible AI governance in public sector" --source openalex

显式子命令：

paperseek search "digital platforms and open innovation" --source openalex

JSON 输出：

paperseek search "open innovation" --source openalex --output json

常用参数：

paperseek search "your research question" \
  --source openalex \
  --field management \
  --discipline "Computer Science" \
  --min 5 \
  --max 50 \
  --iterations 5 \
  --llm-provider deepseek \
  --llm-api-type openai_chat \
  --llm-model deepseek-v4-flash \
  --llm-base-url https://api.deepseek.com \
  --llm-key your-llm-api-key

诊断配置：

paperseek doctor
paperseek doctor --source openalex --json

测试数据源最小真实请求：

paperseek smoke --source openalex --query "machine learning"
paperseek smoke --source crossref --query "open innovation" --json

查看数据源能力：

paperseek sources
paperseek sources --json

查看本地历史记录：

paperseek history list
paperseek history show <RUN_ID> --json
paperseek history path

保存 CLI 用户级配置：

paperseek config path
paperseek config set LLM_API_KEY your-llm-api-key
paperseek config list
paperseek config unset LLM_API_KEY

环境变量优先于用户级配置。paperseek config list 会遮蔽密钥。

Discipline Fields 支持使用 OpenAlex Field ID、字段标签或 https://openalex.org/fields/<id> URL。多个字段可以重复传入 --discipline / --discipline-field，也可以在环境变量中用分号分隔，例如：

export DISCIPLINE_FIELDS="17;14"
paperseek search "open innovation and digital platforms" --source openalex

--field / SEARCH_FIELD 是自由文本领域提示，主要影响 LLM 生成的检索式；--discipline / DISCIPLINE_FIELDS 是结构化学科限制。OpenAlex 会应用 primary_topic.field.id 过滤，WoS Starter 会映射到 WC= 类目，Crossref 没有共享学科 taxonomy 时会把所选学科作为查询上下文。

数据源

数据源	默认状态	API Key	适合场景	说明
OpenAlex	默认	推荐	精确检索、摘要、引用数、引用扩展、引用图	开放学术元数据库，适合通用文献发现与引用关系探索。
Crossref	支持	通常不需要	DOI、出版元数据、期刊和出版社信息校验	DOI 与出版元数据注册库，适合题录校验和 DOI 补全。
Web of Science Starter	适配中	必需	已有 Clarivate API 权限的机构用户	商业数据库 API，返回字段和可用性取决于订阅计划与机构授权。

LLM 服务商

PaperSeek 支持两类主流接口协议：OpenAI 风格接口和 Anthropic Messages API。Provider 表示模型服务商，API Type 表示请求协议。

Provider	默认 API Type	默认模型
OpenAI	openai_responses	gpt-5.4-mini
Anthropic	anthropic_messages	claude-sonnet-4-6
Google Gemini	openai_chat	gemini-3.5-flash
DeepSeek	openai_chat	deepseek-v4-flash
中国科技云 CSTCloud	openai_chat	DeepSeek-V4-Flash
阿里云百炼 DashScope	openai_chat	qwen3.6-plus
Kimi Moonshot	openai_chat	kimi-k2.6
智谱 AI GLM	openai_chat	glm-5.1
硅基流动 SiliconFlow	openai_chat	deepseek-ai/DeepSeek-V4-Flash
OpenRouter	openai_chat	openai/gpt-5.4-mini
火山方舟	openai_chat	doubao-seed-2-0-mini-260428
腾讯混元	openai_chat	hunyuan-turbos-latest
百度千帆	openai_chat	ernie-5.0
ModelScope 魔搭	openai_chat	Qwen/Qwen3-235B-A22B-Instruct-2507
Ollama	openai_chat	qwen3:8b
Custom	openai_chat	空，用户自行填写

默认模型用于初始化表单和命令参数示例。实际可用模型以各服务商控制台、账号权限和兼容层为准。

中国科技云 CSTCloud 提供 OpenAI API Compatible 大模型接口，Base URL 为 https://uni-api.cstcloud.cn/v1。PaperSeek 内置的 provider 为 cstcloud，默认模型为 DeepSeek-V4-Flash。获取 Key 可打开 中国科技云 API Keys，登录中国科技云统一认证后按页面要求提交申请信息；中国科学院院内用户可使用中国科技云通行证登录，通行证通常为院邮箱账号及密码。接口说明见 中国科技云大模型 API 接口使用手册。

工作流

一次搜索通常包含四步：

1. Query Generation：LLM 根据研究问题、可选 Field Hint 和 Discipline Fields 生成初始查询。
2. Source Search：请求 OpenAlex、Crossref 或 WoS Starter，并记录 HTTP 状态和命中数量。
3. Query Refinement：若命中数过少或过多，LLM 调整查询并继续下一轮。
4. Ranking & Results：将候选池交给 LLM 统一评分，输出前若干条结果。

如果启用 OpenAlex 引用扩展，PaperSeek 会从高匹配论文中选择 seed paper，加入 seed 的参考文献和被引论文，再对完整候选池统一评分。默认最大输出 50 条。

候选池较大时，LLM 排序会自动分批并发执行。默认批大小为 8、并发为 4；超过 32 篇候选论文时会自适应放大批大小。单个排序批次失败时只回退该批次，不会使整次检索失败。

引用图

Citation Map 使用箭头表示引用方向：

A -> B  表示 A 引用了 B

图中节点来自最终结果和 OpenAlex 引用扩展记录。你可以拖动节点、缩放和平移画布，并查看节点详情。引用图适合发现关键词检索遗漏的经典文献、相邻主题和近期延伸研究。

环境变量

变量	说明
DATA_SOURCE	openalex、crossref 或 wos，默认 openalex。
LLM_PROVIDER	LLM 服务商，例如 openai、deepseek、cstcloud、anthropic、ollama。
LLM_API_TYPE	openai_responses、openai_chat 或 anthropic_messages。
LLM_MODEL	模型名称。
LLM_BASE_URL	API Base URL。
LLM_API_KEY	LLM API Key；Ollama 可不填。
OPENALEX_API_KEY	OpenAlex API Key，推荐填写。
OPENALEX_EMAIL	OpenAlex 联系邮箱。
CROSSREF_EMAIL	Crossref polite pool 邮箱。
WOS_API_KEY	Clarivate Web of Science Starter API Key。
WOS_DB	WoS 数据库代码，默认 WOS。
SEARCH_FIELD	自由文本学科或领域提示。
DISCIPLINE_FIELDS	OpenAlex Field ID、标签或 URL；多个值建议用分号分隔，并会映射到 OpenAlex / WoS 学科限定。
TARGET_MIN / TARGET_MAX	目标结果数量范围。
MAX_ITERATIONS	最大查询调整轮数。
EXPAND_CITATIONS	是否启用 OpenAlex 引用扩展，默认 true。
FETCH_ABSTRACTS	是否尝试从外部 DOI 元数据补摘要，默认 false。
CITATION_SEED_COUNT	引用扩展 seed 论文数量。
CITATION_PER_SEED	每个 seed 抓取的引用邻居数量。
CITATION_MAX_RECORDS	引用扩展候选上限。
RANKING_BATCH_SIZE	LLM 排序批大小，默认 8；候选数较多时会自适应放大以减少批次数。
RANKING_CONCURRENCY	LLM 排序并发数，默认 4；单个批次失败不会使整个检索失败。
LLM_TIMEOUT_SECONDS	单次 LLM 请求超时秒数，默认 180，最小 30。
PAPERSEEK_HISTORY_ENABLED	是否启用本地历史记录，默认 true。
PAPERSEEK_TIMEZONE	本地历史记录时间戳时区，默认 Asia/Shanghai；Web UI 会优先使用浏览器检测到的时区。
PAPERSEEK_DATA_DIR	本地数据目录，默认 ~/.paperseek。
PAPERSEEK_HISTORY_DB	本地历史 SQLite 数据库路径，默认 ~/.paperseek/paperseek.db。

API 获取方式

OpenAlex

OpenAlex 可匿名访问，但推荐配置免费 API Key：

1. 打开 OpenAlex 并注册账号。
2. 进入 OpenAlex API settings。
3. 复制 API Key。
4. 在 Web UI 填写 OpenAlex API Key，或设置 OPENALEX_API_KEY。

Crossref

Crossref REST API 通常不需要 API Key。建议设置邮箱进入 polite pool：

export CROSSREF_EMAIL=[e-mail]

如果需要更高限额、优先支持或生产级 SLA，可以了解 Crossref Metadata Plus。PaperSeek 使用 Crossref 公共/Polite REST API 路径。

Web of Science Starter API

WoS Starter 需要在 Clarivate Developer Portal 申请，通常适合已有机构订阅权限的用户：

1. 打开 Clarivate Developer Portal 注册页，点击 Register。
2. 建议使用机构邮箱注册，并尽量与 Web of Science 数据库账号一致。
3. 登录后进入 Applications，点击 Register Application。
4. 填写应用信息：
   • Application ID 使用数字、小写字母、- 或 _。
   • Application Name 可写为机构或项目名称。
   • Application Description 可说明用于 Web of Science API 检索。
   • Client Type 保持默认 Public: Single Page Application。
   • 不勾选 OAuth2.0 Flows。
5. 打开 Web of Science Starter API 页面。
6. 找到刚注册的 Application，点击 Subscribe。
7. 按身份和机构权限选择计划。机构成员通常选择 Institutional Member 相关计划。
8. 看到 Subscription approval is pending 后等待审批。机构申请通常需要数个工作日。
9. 获得 API Key 后，在 Web UI 填写 WoS API Key，或设置 WOS_API_KEY。

WoS Starter 的权限、每日请求量和返回字段取决于订阅计划与机构授权。若遇到 HTTP 401，先检查是否使用 https:// 和正确 key；若遇到 Clarivate 返回的非标准 HTTP 512，应优先检查 Clarivate 服务状态、订阅审批和检索式兼容性。

Python API 与 core

社区版安装包已经内置可复用核心模块 paperseek_core，不需要额外安装单独的 paperseek-core 仓库依赖。常规用户和下游代码建议从 paperseek 导入稳定入口：

from paperseek import PaperSeekAgent

LiteratureSearchAgent 和 WosSearchAgent 仍保留为兼容旧代码的别名，新代码请使用 PaperSeekAgent。

Agent Skill

仓库包含一个可选的 PaperSeek Skill：

skills/paperseek/

它用于指导支持 Skill 的 AI agent 正确调用 PaperSeek，包括数据源选择、配置诊断、JSON 结果解析和引用图边界。Skill 使用 progressive disclosure：SKILL.md 保持简短，详细命令契约放在 references/。

这个 Skill 不会随 Python 包自动安装。如果需要在 agent 平台中使用，可以手动复制或链接 skills/paperseek/ 到对应平台的 Skill 目录。

Skill 中的 launcher 与自包含 runtime：

skills/paperseek/scripts/paperseek.py
skills/paperseek/scripts/paperseek_skill_runtime.py

单独发布 Skill 时，复制 skills/paperseek/ 即可。paperseek.py 会优先调用完整 PaperSeek 包；如果未安装包，会回退到 paperseek_skill_runtime.py，使用 Python 标准库直接完成 OpenAlex、Crossref 和带 key 的 WoS Starter 核心文献检索。Web UI、引用图和完整历史管理仍需要安装完整包。

项目状态

PaperSeek 当前处于 alpha 阶段。CLI、Web UI、OpenAlex、Crossref、引用扩展、CSV 导出和 Skill 基本可用，但仍建议对正式研究结论进行人工复核。

欢迎贡献：

• 新数据源适配器。
• 更稳健的查询生成与排序提示词。
• 更好的引用图交互。
• Web API、CLI、provider parsing 和导出行为测试。
• 文档、示例和错误诊断改进。

贡献前可阅读 CONTRIBUTING.md。安全问题请参考 SECURITY.md。

致谢

PaperSeek 的设计和实现参考了以下开源项目：

• dr-dumpling/paper-search-cli：参考 CLI 使用方式与文献检索工作流设计。
• 666ghj/MiroFish：参考 Web 前端界面的左右分栏和工作流展示风格。
• clarivate/wosstarter_python_client：参考 Web of Science Starter API 的客户端调用方式。
• Lloyd-Jahn/openclaw-paper-search：参考文献搜索工具的组织方式。

开源协议

PaperSeek 使用 Apache License 2.0 开源。