ScanSci PDF

让 Agent 替你下载学术论文 —— 20+ 数据源并行竞速，100+ 高校机构通道，一句自然语言拿下整份文献清单。

能力 · 快速开始 · 怎么用 · 机构通道 · 社区 · 致谢

能力

给出 DOI、arXiv 号或一份文献清单，ScanSci PDF 会自动挑最快能下的那条路：OA 直链、预印本、出版商 API、你的学校通道都试一遍，付费墙自动路由，结果落地成规整命名的 PDF 文件。

• 单篇，一句话的事 — DOI / arXiv 进，作者_年份_标题.pdf 出；BibTeX / RIS / EndNote 引文顺手导出，可直推 Zotero。
• 清单，整批拿下 — APA / BibTeX / DOI 列表直接喂，自动补全缺失 DOI；上千篇先分「OA / 灰色源 / 需机构」三桶再分批下载，不瞎跑不浪费。
• 付费墙，走你的学校 — 100+ 高校 WebVPN、CARSI 联邦认证、EZProxy、Elsevier API 快速通道（1–2 秒/篇）；登录在你自己的浏览器完成，密码不经过工具。
• 对抗与自愈全自动 — Cloudflare / CAPTCHA / SSO 分层处理；出版商封 IP 自动停损；机构会话过期自动重登，登录一次全程复用。
• Agent 原生 — 标准 MCP 服务器、17 个工具即装即用；Codex App、ZCode、Claude Code 都有现成的插件或配置。

近期更新

• 统一任务管线 — 任意输入（xlsx/csv 表格、文献清单、检索结果、文章页 URL）自动归一成带渠道预测的下载队列；batch --lanes 四车道调度：Elsevier API / OA 快车道并行，灰色源竞速与机构级联接续，失败逐级溢流。
• SI 附件下载 — get <DOI> --si 把补充材料一并拉下来；被 Cloudflare 挡住的 Elsevier 自动切隐身浏览器通道。
• AI 阅读层 — get <DOI> --md 顺手把 PDF 转成 agent 友好的 Markdown（PDF 仍是默认交付物）。
• OpenAIRE 仓储源接入 — 绿色 OA / 机构库副本进入免费竞速池，Unpaywall 漏掉的它来补（现已 20+ 数据源）。
• MCP 工具面瘦身 — 45 → 17 个工具，每次会话的 schema token 开销降约 60%，能力零损失。
• 更抗封、更稳 — 竞速引擎新增 (源 × 出版商) 负缓存，被 Cloudflare 拦一次不再反复烧超时；cloakbrowser 强制 0.5.9+（Chromium 151 内核）；每周出版商金丝雀巡检。

快速开始

安装和更新是同一句话——对 Codex、ZCode、Claude Code 都这么说：

帮我安装或更新这个插件：https://github.com/Rimagination/scansci-pdf

Agent 会克隆（或原地更新）仓库、装好依赖并注册插件，然后你就能直接让它下论文了——例子见下一节怎么用。

pip install scansci-pdf

{
  "mcpServers": {
    "scansci-pdf": {
      "command": "scansci-pdf",
      "args": ["run"]
    }
  }
}

powershell -NoProfile -ExecutionPolicy Bypass -Command '$p=Join-Path $HOME "plugins\scansci-pdf"; if(Test-Path $p){ git -C $p pull --ff-only } else { git clone --branch main --single-branch https://github.com/Rimagination/scansci-pdf.git $p }; & (Join-Path $p "scripts\install-scansci-pdf.ps1")'

scansci-pdf run --mode streamable_http --host 127.0.0.1 --port 8000

scansci-pdf web --port 8080   # 浏览器打开 http://localhost:8080

docker compose up -d

怎么用

装好后，对着 Agent 说一句话就行。这些例子覆盖最常见的日常场景：

帮我下载 10.1038/nature12373 这篇论文

这个清单里有 3000 篇文献，先分类哪些能直接下、哪些要走机构权限，然后分批下载

搜一下 "urban heat island" 2023 年以来被引最高的 10 篇论文，并下载

用北大的 WebVPN 登录，把这篇 Elsevier 的论文下下来

把刚才那批论文的 BibTeX 导出，再推送到 Zotero

这篇下载失败了，帮我诊断一下网络问题

不动 Agent、直接命令行也行：

scansci-pdf get 10.1038/nature12373            # 单篇下载
scansci-pdf batch 文献清单.xlsx --lanes        # 批量下载（xlsx/csv/队列通用，四车道调度）
scansci-pdf search "carbon cycle" --out q.txt  # 检索结果落成队列文件，直接接 batch
scansci-pdf check                             # 依赖与环境体检

机构通道

付费墙论文优先走这四条机构通道。登录都在你自己的浏览器里完成，密码不经过本工具。

Elsevier API（推荐，无需浏览器）

ScienceDirect / Cell Press 等 Elsevier 论文走 API 直接下载，速度从 15–30 秒降到 1–2 秒。Key 申请免费、个人邮箱即可：

1. 访问 Elsevier Developer Portal 创建应用，勾选 ScienceDirect Article Retrieval
2. 配置 Key：scansci_pdf_elsevier_setup（MCP 会打开浏览器引导）或 scansci_pdf_config(key="elsevier_api_key", value="...")

WebVPN（高校代理）

1. scansci_pdf_schools(action="search", query="北京")  → 搜你的学校
2. scansci_pdf_schools(action="set", school="你的学校")
3. scansci_pdf_login(kind="webvpn")                    → 浏览器完成 CAS 认证
4. scansci_pdf_channel_status(kind="webvpn_test")      → 确认连接正常

支持 100+ 所中国高校，命令行等价：scansci-pdf schools 北京 / scansci-pdf setup 北京航空航天大学。

CARSI（出版商联邦认证）

1. scansci_pdf_config(key="carsi_enabled", value="true")
2. scansci_pdf_config(key="carsi_idp_name", value="你的学校名称")
3. scansci_pdf_login(kind="carsi", publisher="sciencedirect")

支持 sciencedirect、springer、wiley、ieee、tandfonline、nature 等。SAGE 中国站首次使用 scansci_pdf_login(kind="carsi", publisher="sage-cn") 登录；之后下载会复用已保存会话， 从文章页解析实际 articleId 并请求站点自身的 PDF 下载接口，无需反复开启浏览器。

EZProxy（图书馆代理）

1. scansci_pdf_config(key="ezproxy_enabled", value="true")
2. scansci_pdf_config(key="ezproxy_login_url", value="https://libproxy.你的学校.edu.cn/login?url={url}")
3. scansci_pdf_login(kind="ezproxy")

ezproxy_login_url 支持两种模板：

• 前缀式（大多数学校）：https://ezproxy.lib.xxx.edu.cn/login?url={url}，{url} 会被替换成目标文章地址；
• 域名重写式（如港科大 lib.ezproxy.hkust.edu.hk）：https://{host_dashed}.lib.ezproxy.hkust.edu.hk， {host_dashed} 会被替换成出版商域名的连字符形式（onlinelibrary.wiley.com → onlinelibrary-wiley-com）。这类部署不认 login?url= 前缀，必须用域名重写。

登录检测以 ezproxy/libproxy 域名下的会话 cookie 为准，不会把「被重定向到出版商原站」 误判为登录成功；会话校验也只探测代理自身的 /login 端点，对两类部署都有效。

配置与策略

⚠ 已自动停止：连续检测到 IP 被出版商封禁（N 篇返回 ip_blocked），剩余任务已取消。

scansci-pdf config-cmd batch_workers 2          # 调低并发（默认 10）
scansci-pdf config-cmd request_delay_min 5      # 拉大随机延迟下限（默认 2）
scansci-pdf config-cmd request_delay_max 12     # 拉大随机延迟上限（默认 5）

scansci-pdf config-cmd proxy_pool "socks5://1.1.1.1:1080,http://2.2.2.2:8080"

故障排查

Tier 1 (4s)  ─ 出版商直链（OA/机构访问）
Tier 2 (5s)  ─ OpenAlex / Unpaywall / DOAJ
Tier 3 (8s)  ─ EuropePMC / CORE / PMC / arXiv
Tier 4 (25s) ─ LibGen / Sci-Hub（带 FlareSolverr 绕过）
Tier 5 (20s) ─ WebVPN / CARSI 机构代理

交流群 / Community

扫码加入微信交流群，一起聊 AI for Science —— 偏 AI 应用与科研工具，也欢迎讨论 ScanSci PDF 的用法、bug 和需求。

微信交流群 / WeChat Group 群码 7 天有效，过期会更新

加群主微信 / Contact 群码失效？扫码备注 scansci 拉你进群

群聊方向 AI 在科研场景的落地与工具链 论文检索、下载、阅读、整理的工作流 ScanSci PDF 使用问题与改进建议 二维码过期会更新；着急进群可直接加群主微信。

更偏好异步交流？欢迎直接在 Issues 或 Discussions 区开贴。

赞助者

贡献者

• annsyun — SAGE 中国站（sage.cnpereading.com）机构授权下载通道：CARSI 会话复用、articleId 解析与站点原生下载接口（#58）

致谢

本项目在开发过程中参考和借鉴了以下开源项目：

• FlareSolverr — 早期反 bot 绕过架构设计
• ref-downloader — Publisher 专用下载策略（Elsevier crasolve 检测、Wiley PDFDirect、AIP loading page 等）
• paper-fetch-skill — 论文获取 Agent Skill 设计
• paper-fetcher — 论文下载流程参考
• cloakbrowser — Chromium stealth 浏览器引擎

感谢以上项目作者的开源贡献。

许可证

Apache License 2.0

例外：src/scansci_pdf/_core/ 中的 Cython 编译扩展（.pyd/.so）为预编译二进制，仅通过 PyPI 分发。其 Cython 源码（.pyx）为专有代码，不包含在本仓库中。

Star History

手绘星标曲线，每日由仓库自建的 Action 自动更新——数据与图表都在本仓库内，不依赖任何第三方服务。