scansci-pdf

Files (1)

• SKILL.md

SKILL.md (first lines)

# scansci-pdf — 学术论文下载 MCP 服务


## ⚠️ 修改反爬/嗅探/镜像相关代码前必读

先读 [`docs/PLAYBOOK.md`](../docs/PLAYBOOK.md)：镜像健康唯一存储（domain_db wall_state 表）、
结构性失败签名表、节奏参数、已知死镜像清单、以及六条铁律（含"造轮子前先 grep 家底"——
镜像健康存储曾被重复造过三代）。
## 概述

scansci-pdf 是一个 MCP 服务器，提供 **20 个高层工具**，覆盖学术论文的搜索、下载（开放获取 / 灰色源 / 机构渠道）、Sciverse 语义检索、发现与队列准备、引文导出和诊断排障。下载引擎支持 20+ 数据源并行竞速、100+ 中国高校 WebVPN。

> 工具名可能带宿主的 MCP 命名空间前缀（`mcp__<server>__<tool>`）；以当前工具列表中实际注册的名称为准。

## MCP 工具参考（20 个）

### 下载

| 工具 | 功能 | 关键参数 |
|------|------|----------|
| `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；中文并入 NCPSSD；配置 Key 后并入 Sciverse） | `query`/`author`/`author_id`、`limit`、`year_from`、`year_to`、`sort` |
| `scansci_pdf_sciverse` | Sciverse 全能力分发：`search`（agentic 片段）/ `content`（读全文）/ `meta_search`（元数据）/ `relations`（引文图谱）/ `catalog`（字段目录）/ `resource`（图表附件） | `query`、`doc_id`、`unique_id`、`relation`、`top_k`、`page`/`page_size`、`offset`/`limit`、`file_name`、`filters_json`、`sort_json`、`fields`、`enrich_dois`、年份/语言/期刊/主题/作者/DOI/引用数字段 |
| `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` 而不是逐条失败。

**Sciverse 能力**：配置 `sciverse_api_key`（https://sciverse.space/tokens）后，`scansci_pdf_search` 会自动并入 agentic-search 证据片段和 meta-search 元数据（记录带 `doc_id`/`unique_id`/`evidence`/页码）；需要原始 chunk、精确元数据、引文图谱或图表时用 `scansci_pdf_sciverse`。**分场景**：统一 `search` 默认补 DOI（多 1 次 doc_id 定向 meta-search）；单独 `action="search"` 默认不补，需要下载时传 `enrich_dois=true`。`action="relations"` 的 `REFERENCES` 可能只返回 OpenAlex ID、标题为空；实测这些 ID 在 OpenAlex 不可解析，保留 ID 由调用方处理。`meta-search` 的 `total_count` 到 10000 是上限，返回 `total_count_capped=true`。agentic 的 `filters_json` 是对象（字段间 AND、同字段列表内 OR，`doc_ids` 硬范围 ≤1000）；meta-search 的 `filters_json` 是 `{field, operator, value}` 数组，算子用 `FILTER_OP_*`。`sciverse_meta_search_enabled=false` 可省掉每次 search 的第二路 Sciverse 配额（同时关闭统一 search 的 DOI 补全）。

### 配置、通道与诊断

| 工具 | 功能 | 关键参数 |
|------|------|----------|
| `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） |
| `scansci_pdf_springer_setup` | Springer TDM 全文 API Key 配置与权益探测 | `test`（验证 key / 机构订阅） |
| `scansci_pdf_sciverse_setup` | Sciverse API Token 配置向导（打开控制台、保存并验证；启用语义证据/元数据/引文图谱/图表） | `token`、`test` |

## 工作流编排

### 流程 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 的等价组合）
```

### 流程 2.5：先定机构认证方式与浏览器（流程 3/4/5 的前置判断）

机构失败大多不是"下不下来"，而是这两件事没定：

**① 浏览器**：`scansci_pdf_login` 打开的是工具自带的可见反检测浏览器，**cookie 是从那个上下文抓取并落盘的**——用户在自带的 Safari/Edge/日常 Chrome 里登录、或用无头模式，登录态都拿不到。要求：`browser_headless=false`（机构登录/CAPTCHA/Cloudflare 都需要可见窗口）；后端用 `camoufox` 或 `cloakbrowser`（`patchright` 1.56~1.61 有 Turnstile 空白页 bug）。用户坚持用自己的浏览器时不必硬拦，两条兜底：`config-cmd browser_executable "<他的 Chrome 路径>"` 把内核指过去；或 `scansci_pdf_login(kind="cookie_import", cookie_file="cookies.txt")` 导入 Netscape cookie（CARSI 另会自动读本机 Chrome 的 cookie 库）。

**② 出口 IP**：出版商（尤其 Elsevier）按请求源 IP 判权益。机器一旦开系统/全局代理，**工具与浏览器的出口就变成代理出口，机构授权当场失效**——典型症状是 `pdf.sciencedirectassets.com` 返回 "There was a problem providing the content you requested"（带 `CPE` 码，页面上会打印它看到的 IP）。**先拿那个 IP 核对是否属于机构网段，再判断"学校没订阅"。** 工具只认 `network_proxy`/`SCANSCI_PDF_PROXY`，**忽略** `HTTP_PROXY`/`HTTPS_PROXY`。

| 你的情况 | 走哪条 | 怎么配 |
|---|---|---|
| 在校内（IP 认证） | 直连 | `is_campus_network=true` |
| 校外 + 出版商支持联邦认证 | **CARSI 优先于 WebVPN** | `config-cmd carsi_idp_name <学校>` |
| 校外 + 学校有 WebVPN 网关 | WebVPN | 流程 3 |
| 学校只给 EasyConnect/aTrust | SOCKS5 连接器 | `network_proxy=socks5://…`；自签名证书需 `institutional_allow_self_signed` |
| 学校给图书馆代理 | EZProxy | `ezproxy_login_url`（前缀式 / 域名重写式） |
| 有 Elsevier/Springer key | API 车道，1–2 s/篇且无需浏览器 | 流程 5 / Springer TDM |

**不要替用户猜学校名**——`scansci_pdf_schools(action="search")` 让他确认；项目策略明确"不要默认任何学校"。

### 流程 3：WebVPN 机构代理

```
1. scansci_pdf_schools(action="search", query="清华") → 找到学校
2. scansci_pdf_schools(action="set", school="清华大学")

From Rimagination/scansci-pdf, MIT.

More from Rimagination/scansci-pdf