Rimagination scansci-pdf — 学术论文下载 MCP 服务
⚠️ 修改反爬/嗅探/镜像相关代码前必读
先读 docs/PLAYBOOK.md：镜像健康唯一存储（domain_db wall_state 表）、
结构性失败签名表、节奏参数、已知死镜像清单、以及六条铁律（含"造轮子前先 grep 家底"——
镜像健康存储曾被重复造过三代）。
概述
scansci-pdf 是一个 MCP 服务器，提供 17 个高层工具，覆盖学术论文的搜索、下载（开放获取 / 灰色源 / 机构渠道）、发现与队列准备、引文导出和诊断排障。下载引擎支持 13+ 数据源并行竞速、100+ 中国高校 WebVPN。
MCP 工具参考（17 个）
下载
| 工具 | 功能 | 关键参数 |
|---|---|---|
scansci_pdf_download |
单篇下载（OA/灰色源/机构级联） | identifier（必需）、strategy（可覆盖全局策略）、markdown/bibtex/download_si（可选） |
scansci_pdf_batch_download |
批量下载 | identifiers（必需）、scihub_enabled、batch_id（断点续传）、resume（默认 true） |
scansci_pdf_cache_clear |
清理下载缓存 | identifier（可选，省略清全部） |
identifier 格式：DOI（10.1038/nature12373）、DOI URL、arXiv ID（2301.00001）。
下载策略（download_strategy，全局配置或单次 strategy= 覆盖）：
| 策略 | 含义 |
|---|---|
fastest（默认） |
全部源并行竞速（含灰色源，若 scihub_enabled=true） |
oa_first |
OA 源优先，失败后回退灰色源 |
scihub_first |
灰色源优先，失败后回退合法源 |
scihub_only |
仅 Sci-Hub |
legal_only |
仅合法源（Unpaywall/出版商/OpenAIRE 等），不碰 Sci-Hub/LibGen |
来源授权不可被调度扩张：用户显式设置 scihub_enabled=false 或 legal_only 时，任何批量/车道调度都不会重新启用灰色源；只有显式 --scihub/scihub_enabled=true 或全局策略允许时才启用。
发现与队列准备
| 工具 | 功能 | 关键参数 |
|---|---|---|
scansci_pdf_find |
ScanSci Find 引擎：action=plan|estimate|smoke|calibrate 系统综述搜索协议 |
action、query、domain、depth、sample_size |
scansci_pdf_expand_citations |
引文追踪（Semantic Scholar/OpenCitations） | query、rounds（≤5）、citation_source |
scansci_pdf_prepare_queue |
准备下载队列：action=verify|resolve_oa|build|full |
candidates_json、query、limit |
scansci_pdf_search |
关键词/作者搜索（OpenAlex） | query/author/author_id、limit、year_from、year_to、sort |
scansci_pdf_parse_list |
解析论文列表文件（APA/BibTeX/DOI 列表/表格） | file_path（必需） |
scansci_pdf_citation |
导出引文 | identifier（必需）、format（bibtex/ris/endnote/metadata） |
scansci_pdf_zotero_push |
推送已下载论文到 Zotero | identifier（必需，需先下载） |
重要：verify/resolve_oa 是轻量操作，预算 45 秒内返回；超时会返回结构化错误（stage/timeout_seconds/retryable），不会无反馈地等 180 秒。resolve_oa 依赖 Unpaywall 邮箱配置（scansci_pdf_config(key='email', ...)），缺失时直接返回 blocked_configuration 而不是逐条失败。
配置、通道与诊断
| 工具 | 功能 | 关键参数 |
|---|---|---|
scansci_pdf_config |
读取/设置配置（值会脱敏） | key（可选）、value（可选） |
scansci_pdf_channel_status |
机构渠道状态：kind=webvpn|carsi|ezproxy|browser|webvpn_test |
kind、doi（仅测试） |
scansci_pdf_schools |
搜索/设置 WebVPN 高校 | action=search|set、query、school |
scansci_pdf_diagnostics |
健康/网络/来源/设置诊断 | check=health|network|sources|setup |
scansci_pdf_tor |
内嵌 Tor：action=install|start|stop |
action、use_bridges |
登录（机构渠道）
| 工具 | 功能 | 关键参数 |
|---|---|---|
scansci_pdf_login |
统一登录：kind=publisher|webvpn|carsi|ezproxy|custom|cookie_import |
kind（默认 publisher）、identifier、publisher、custom_url、cookie_file |
scansci_pdf_elsevier_setup |
Elsevier API Key 配置向导（免费，无需机构邮箱） | test（验证 key） |
工作流编排
流程 1：模糊研究查询 → 下载
1. scansci_pdf_find(action="plan"|"estimate", query="植物功能性状 气候变化")
或 scansci_pdf_search(query="plant functional traits climate change", limit=20, sort="cited_by_count")
2. scansci_pdf_prepare_queue(action="full", candidates_json=<candidates>)
→ 验证 DOI + 解析 OA 位置（45s 预算，超时给出结构化错误）
3. scansci_pdf_batch_download(identifiers=[...])
关键点：搜索后必须让用户确认，不要自动下载所有结果。
流程 2：论文列表全文下载
1. scansci_pdf_parse_list(file_path="papers.md") → 查看解析结果
2. scansci_pdf_batch_download(identifiers=entries)（或 resolve_and_download 的等价组合）
流程 3：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", doi="10.1038/nature12373") → 确认连通
5. scansci_pdf_download(identifier="...") → 自动走 WebVPN 渠道
流程 4：付费论文登录下载（出版社 SSO）
当下载返回 error_type="paywall" 和 action="login_required" 时：
1. scansci_pdf_download(identifier="10.1126/science.aec6396")
→ 返回 {"error_type": "paywall", "action": "login_required", ...}
2. scansci_pdf_login(identifier="10.1126/science.aec6396") # kind=publisher 默认
→ 打开浏览器到论文页 → 用户点 "Access through your institution" → 选择机构 → SSO → 关闭浏览器
3. scansci_pdf_download(identifier="10.1126/science.aec6396") → 用已保存 cookies 成功下载
要点：
- 任何有机构账号的用户都能用，无需预配置 WebVPN/CARSI
- Cookies 持久化，同一出版商登录一次即可
- 浏览器引擎为 CloakBrowser（Playwright 兼容反检测浏览器），能通过 Cloudflare Turnstile；出版社检测 TLS 指纹，Python HTTP 客户端即使带 cookies 也可能 403
流程 5：Elsevier API 快速通道（1-2 秒下载）
1. scansci_pdf_elsevier_setup → 浏览器注册指引 → 复制 API Key
2. scansci_pdf_config(key="elsevier_api_key", value="...")
3. scansci_pdf_elsevier_setup(test=true) → 验证
4. 后续 10.1016/ 开头 DOI 自动走 API 直接下载（无需 insttoken：校园网出口 + API key 即可）
NOT_ENTITLED 含义：未连校园网或学校未订阅该刊，不是缺 insttoken。
流程 6：内嵌 Tor（灰色源被墙时）
1. scansci_pdf_tor(action="install") # 首次下载 Tor Expert Bundle
2. scansci_pdf_tor(action="start") # 受限网络可 use_bridges=true
3. scansci_pdf_download(identifier="...", strategy="scihub_only")
能力边界
| 请求 | 处理方式 |
|---|---|
| 阅读/理解论文内容 | 不支持——只下载 PDF（可用 markdown=true 得 AI 可读文本层） |
| 翻译论文 | 需要其他工具 |
| 生成文献综述/摘要 | 需要 LLM 读取 PDF 后生成 |
| 下载非学术 PDF | 不支持 |
| 用户给了标题没有 DOI | 先 search 获取 DOI 再下载 |
| 批量 100+ 篇 | batch_download，并发数由 batch_workers 配置控制 |
| 需要机构权限的论文 | login 登录后重试下载 |
| 下载失败 | 结果含 error_type；paywall→登录流程，rate_limited→稍后重试，cloudflare_blocked→启动 CloakBrowser/配置代理 |
常见边界情况
- 科学符号（版权 ©、重音姓名）在 Markdown 导出中可能有质量告警（
markdown_warnings）——文本可读，罕见字符需人工核对。 - 批量任务无论成功、失败或超时都会在预算内退出并写
batch_results.json（原子写入）；挂住的源会被放弃而不是拖住整批。 scan_find未安装时，find/search/expand_citations会给出安装指引；verify/resolve_oa超时返回结构化错误。
环境安装引导
1. scansci_pdf_diagnostics(check="setup") → 环境状态
2. 按 readiness 处理：ready / partial / limited
3. 缺少组件时按建议安装（pymupdf4llm 用于 markdown、cloakbrowser 用于反爬登录）
快速安装
pip install -U scansci-pdf
pip install -U cloakbrowser # 反爬浏览器（Chromium 内核）
scansci-pdf doctor # 或 MCP: scansci_pdf_diagnostics(check="health")