papersearch 0.0.0-stage → 0.4.2

package/README.zh.md

@@ -0,0 +1,214 @@
+# PaperSearch
+
+简体中文 | [English](README.md)
+
+PaperSearch 是给 AI 工具和终端用的学术文献命令 `paper-search`，随包附带一份 Skill，教 Claude Code、Codex、Cursor 等 AI 工具怎么调用它。它能检索论文、核验 DOI/PMID、查施引文献和参考文献、查期刊影响因子和分区、在正文片段里找方法学写法，以及下载论文 PDF 和补充材料。输出默认是 JSON，方便 AI 和脚本读取。
+
+默认是开放版本：装好就能检索和下载开放获取的论文。需要用学校订阅下载时，可以另装机构下载扩展。
+
+![Node.js](https://img.shields.io/badge/node.js->=18.0.0-green.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Version](https://img.shields.io/badge/version-0.4.2-blue.svg)
+[![LinuxDo](https://img.shields.io/badge/LinuxDo-community-1f6feb)](https://linux.do)
+
+[整体逻辑](#整体逻辑) | [快速开始](#快速开始) | [两种下载方式](#两种下载方式) | [检索来源](#检索来源) | [配置](#配置) | [Agent Skill](#agent-skill) | [命令](#命令) | [排障](#排障)
+
+## 整体逻辑
+
+```text
+用户的文献请求
+│
+├─ 找论文、核验 DOI/PMID → paper-search search（Crossref、PubMed、OpenAlex 等）
+│    └─ 确认条目、需要全文 → 转到下面的“下载”
+├─ 查施引文献、参考文献 → paper-search run get_paper_citations / get_paper_references
+├─ 查影响因子、分区 → paper-search journal-metrics（需要 EasyScholar key）
+├─ 找 Methods 写法、参数 → paper-search run search_semantic_snippets（需要 Semantic Scholar key）
+│
+└─ 下载正文、补充材料 → paper-search download / run download_with_fallback / run download_batch
+     同一个下载命令，按顺序尝试：
+     ├─ ① 开放下载（默认就有）：来源自带的下载、PMC、Unpaywall、出版社接口
+     ├─ ② Sci-Hub 兜底（默认开启，可关闭）
+     ├─ ③ 机构下载（可选扩展）：浏览器经 CARSI 登录你的学校，在出版社网站取 PDF 和补充材料
+     ├─ 每一步拿到文件都核对首页的 DOI 和题名；通过就保存，后面的步骤不再试
+     └─ 都没拿到 → paper-search failures 说明原因
+```
+
+## 快速开始
+
+要求 Node.js 18 及以上和 npm。
+
+```bash
+npm install -g papersearch
+paper-search setup
+paper-search doctor --format text
+```
+
+`paper-search setup` 会依次问三件事：API key 和邮箱；要把 Skill 装到哪些 AI 工具（Claude Code、Codex、Cursor 等）；要不要安装机构下载扩展。每一步都可以跳过。`doctor` 显示现在能用哪些功能、还缺什么配置。
+
+Skill 是教 AI 工具调用 `paper-search` 的说明文件，用 AI 工具做文献任务时要装。跳过了可以随时补装，`--targets` 换成你用的工具（`claude`、`codex`、`cursor`、`gemini`、`agents`，或 `all`）：
+
+```bash
+paper-search skills update --targets claude
+```
+
+也可以把下面这段话发给你的 AI 工具，让它帮你装：
+
+```text
+请帮我安装 PaperSearch：运行 npm install -g papersearch，再运行 paper-search skills update --targets <你自己对应的目标：Claude Code 用 claude，Codex 用 codex，Cursor 用 cursor>，最后运行 paper-search doctor --format text，告诉我哪些功能能用、还缺哪些 key。API key 我会自己在终端运行 paper-search setup 输入，不要让我发到聊天里。
+```
+
+**从旧包 `paper-search-cli` 升级**：先运行 `npm uninstall -g paper-search-cli`，再 `npm install -g papersearch`。两个包提供同一个 `paper-search` 命令，不能同时装；配置、Skill、学校登录和下载记录都会保留。
+
+**以后升级**：`npm install -g papersearch@latest`。升级后第一次运行 `paper-search` 时，它会自动把你装过的 Skill 更新到新版本。
+
+试一下各个功能：
+
+```bash
+paper-search search "machine learning clinical prediction" --platform crossref --max-results 3 --pretty
+paper-search search "large language models" --sources no-key --max-results 5 --pretty
+paper-search run get_paper_citations --arg doi="10.1038/nature12373" --arg limit=5 --pretty
+paper-search journal-metrics "Nature" "BMJ" --pretty
+paper-search download PMC11466435 --platform pmc --save-path ./downloads
+paper-search run search_semantic_snippets --arg query="propensity score matching" --arg limit=3 --pretty
+```
+
+## 两种下载方式
+
+|  | 开放下载（默认） | 机构下载（可选扩展） |
+|---|---|---|
+| 能不能直接用 | 装好就能用 | 要另外安装：`paper-search carsi install` |
+| 能拿到什么 | 开放获取的正文 | 你的学校订阅的正文；部分出版社还能取补充材料 |
+| 怎么拿 | 程序直接下载，通常几秒，不用登录：来源自带的下载、元数据里的 PDF 地址、PubMed Central、Unpaywall、出版社接口（你自己的 Elsevier/Springer key）；最后是默认开启的 Sci-Hub 兜底 | 打开一个浏览器，经 CARSI 登录你的学校，在出版社网站上取 PDF |
+| 你要做的事 | 无 | 第一次在浏览器里输入学校账号密码、遇到人机验证时点一下；选学校由程序完成 |
+
+两种方式用同一个下载命令，不需要分开调用：先试开放下载，拿不到时，装了机构下载才继续用学校权限。
+
+```bash
+paper-search download "<DOI>" --platform crossref --save-path ./downloads
+paper-search run download_batch --json-args '{"items":[{"doi":"<DOI-1>"},{"doi":"<DOI-2>"}],"savePath":"./downloads"}'
+paper-search failures --format text
+```
+
+- 几十到几百篇用一次 `download_batch`；结束后 `paper-search failures` 把没下载到的篇目分成四类说明：没权限（附页面原话等依据）、需要你处理（登录、验证、等待）、暂不支持的网站、原因不明。
+- 不想用 Sci-Hub 时，在 `download_with_fallback` / `download_batch` 里设 `"useSciHub": false`。
+- 每个保存的 PDF 都核对首页的 DOI 和题名，不是这篇文章的不保存。
+
+### 机构下载扩展
+
+```bash
+paper-search carsi install
+paper-search carsi status --format text
+```
+
+- 安装时会问你的学校（CARSI 成员学校，中文名、英文名或域名都可以），并下载专用浏览器 Camoufox，共约 3 GB；macOS 上 `--browser ego` 改用 ego lite，约 0.5 GB。`--skip-school` 可以以后再选学校。
+- 目前用 CARSI（中国高校身份联盟）登录学校；出版社的机构列表里没有 CARSI 或你的学校时，程序会立即说明，建议在校园网或学校 VPN 下下载。
+- 下载时会出现进度窗口：可以跳过本篇、标记本刊或出版社无权限、终止整个任务，右上角齿轮可以调整等待时间。停在学校登录页默认最多等 3 分钟，停在其他页面（人机验证、出版社页面等）默认 1 分钟后结束这一篇。
+- `paper-search carsi update` 在 PaperSearch 升级后更新扩展，`paper-search carsi uninstall` 卸载（默认保留浏览器和学校配置）。
+- Windows：PowerShell 拦住 `npm.ps1` 时改用 `npm.cmd` 或命令提示符；下载要在桌面会话里运行，经 SSH 或系统服务启动时浏览器窗口打不开。
+
+### 补充材料
+
+`download_with_fallback` / `download_batch` 的 `content` 选择下载内容：`main`（默认，只要正文）、`both`（正文加补充材料）、`supplements`（只要补充材料）。补充材料只经机构下载取得，存在 `<保存目录>/<DOI>_supplements/`，附 `manifest.json` 写明每个文件的状态。
+
+各出版社能不能下正文、能不能下补充材料，见 [出版社支持表](skills/paper-search/references/publisher-support.md)。正文和补充材料都实测取得的有 Elsevier、Wiley、Springer Nature、OUP、Wolters Kluwer、Taylor & Francis、Sage、ACS、NEJM、ASCE、Dove 等；IEEE、Thieme 等目前只取正文；表里没有的网站按通用规则尝试。
+
+## 检索来源
+
+| 类别 | 来源 | 需要的配置 |
+|---|---|---|
+| 综合学术元数据 | Crossref、OpenAlex、Semantic Scholar、Google Scholar | 不需要；Semantic Scholar 的正文片段检索需要 key；Google Scholar 要明确指定 |
+| 生物医学 | PubMed、PubMed Central、Europe PMC | 可选 PubMed key |
+| 预印本和会议稿 | bioRxiv、medRxiv、OpenReview、IACR ePrint | 不需要 |
+| 计算机和工程 | DBLP、ACM、USENIX、IEEE Xplore | IEEE 需要 key |
+| 开放获取和仓储 | CORE、OpenAIRE、Unpaywall | Unpaywall 需要邮箱；CORE key 可选 |
+| 引文库和出版社 | Web of Science、Scopus、ScienceDirect、Springer Nature | 需要各自的 key；只提供元数据（Elsevier、Springer 的 key 也用于出版社接口取全文） |
+| 期刊指标 | EasyScholar | 需要 EasyScholar key |
+
+- 单个来源用 `--platform`，多个用 `--sources a,b,c`；`--sources no-key` 是不需要任何 key 的组合（Crossref、PubMed、Europe PMC、OpenReview）。
+- Google Scholar 是网页解析，容易触发验证，不在 `--sources all` 里；需要时用 `--platform googlescholar`。
+- Sci-Hub 不是检索来源，只在下载时按 DOI 兜底。
+
+## 配置
+
+多数免费来源不需要配置。建议先运行 `paper-search setup`，把 key 写入用户配置：
+
+```bash
+paper-search setup
+paper-search config list --pretty
+paper-search config set SEMANTIC_SCHOLAR_API_KEY <你的 key>
+```
+
+配置文件在 `~/.config/paper-search-cli/config.json`（权限 `0600`；文件夹沿用旧名，升级不丢设置），`config list` 和 `doctor` 会把 key 脱敏显示。
+
+| 配置项 | 用途 | 什么时候配置 |
+|---|---|---|
+| `SEMANTIC_SCHOLAR_API_KEY` | 正文片段检索，更稳定的 Semantic Scholar 请求 | 要查方法细节，或经常用 Semantic Scholar |
+| `UNPAYWALL_EMAIL` | 按 DOI 找开放获取 PDF | 推荐配置；填邮箱即可 |
+| `CROSSREF_MAILTO` | Crossref 优先通道 | 长任务或高频检索 |
+| `CORE_API_KEY` | CORE 仓储检索 | 经常用 CORE 或遇到限流 |
+| `EASYSCHOLAR_KEY` | 期刊指标 | 要查影响因子、分区；用 `paper-search setup EASYSCHOLAR_KEY` 隐藏输入 |
+| `PUBMED_API_KEY`、`NCBI_EMAIL` | PubMed 更高限额 | 经常用 PubMed |
+| `WOS_API_KEY`、`IEEE_API_KEY`、`ELSEVIER_API_KEY`、`SPRINGER_API_KEY` | 各自的元数据；Elsevier、Springer 的 key 也用于出版社接口取全文（权限跟随你的网络或 key） | 要用对应来源时 |
+| `ELSEVIER_INSTTOKEN` | 校外经 Elsevier 接口取全文 | 校外需要全文时；校园网不需要 |
+| `GOOGLE_SCHOLAR_PROXY_URL` | Google Scholar 的出口代理 | 直连反复被拦时，用有授权的代理 |
+| `PAPER_SEARCH_CARSI_ENABLED` | 机构下载扩展的开关 | `paper-search carsi install` 自动设置 |
+| `PAPER_SEARCH_SKILL_AUTO_UPDATE` | 设为 `false` 时，升级后不再自动更新已安装的 Skill | 默认开启，想自己管理 Skill 时设置 |
+
+申请入口：[EasyScholar](https://www.easyscholar.cc/console/user/open) · [Semantic Scholar](https://www.semanticscholar.org/product/api) · [Unpaywall](https://unpaywall.org/products/api) · [CORE](https://core.ac.uk/services/api) · [NCBI](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/) · [Web of Science](https://developer.clarivate.com/apis) · [IEEE Xplore](https://developer.ieee.org/docs/read/Searching_the_IEEE_Xplore_Metadata_API) · [Elsevier](https://dev.elsevier.com/apikey/manage) · [Springer Nature](https://dev.springernature.com/) · [OpenAIRE](https://develop.openaire.eu/)
+
+## Agent Skill
+
+Skill 随 npm 包发布（`skills/paper-search/`），全中文，开头有整体逻辑图，按需读这些参考文件：功能路由与开放下载的各个渠道、命令约定、机构下载的安装和使用、[出版社支持表](skills/paper-search/references/publisher-support.md)、排障。它只告诉 AI 怎么调用 `paper-search`，不保存 key、Cookie 或账号。
+
+```bash
+paper-search skills status --pretty
+paper-search skills update --targets claude
+```
+
+- 支持的目标：`agents`、`codex`、`claude`、`cursor`、`gemini`、`antigravity`、`all`。更新会覆盖包里管理的文件，保留你在 Skill 目录里自己加的文件。
+- **升级后自动更新**：升级 PaperSearch 后第一次运行 `paper-search`（`skills`、`setup` 除外）时，它把你已经装过的 Skill 更新到新版本：只更新原来装过的位置；被替换的旧文件备份在 `~/.local/share/paper-search-cli/skill-backups/`；并在 stderr 写一行说明。一个都没装时只提示一次怎么装。不想自动更新：`paper-search config set PAPER_SEARCH_SKILL_AUTO_UPDATE false`。
+- `paper-search doctor` 显示 Skill 装在哪里、是否最新。
+
+## 命令
+
+| 命令 | 用途 |
+|---|---|
+| `paper-search search` | 检索论文元数据 |
+| `paper-search journal-metrics` | 期刊指标（EasyScholar） |
+| `paper-search download` | 下载已核验论文的 PDF |
+| `paper-search run <工具>` | 精确调用某个工具，参数用 `--arg` 或 `--json-args` |
+| `paper-search failures` | 汇总下载失败的原因 |
+| `paper-search carsi` | 机构下载扩展的安装、状态、更新、卸载 |
+| `paper-search setup` / `config` | 配置 key、Skill 和扩展 |
+| `paper-search doctor` | 健康检查：配置、可用功能、Skill 和扩展的状态 |
+| `paper-search skills` | Skill 的状态、差异和更新 |
+| `paper-search smoke` | 离线或真实的自检 |
+| `paper-search tools` | 列出所有工具名和参数 |
+
+命令默认输出 JSON，`--pretty` 排版，`--format text` 输出给人看的报告。完整命令见 `paper-search tools --pretty` 或 [命令约定](skills/paper-search/references/cli-contract.md)。
+
+## 排障
+
+| 问题 | 怎么办 |
+|---|---|
+| 找不到 `paper-search` 命令 | `npm install -g papersearch` 重新安装 |
+| 安装时报 `EEXIST` | 旧包还在：先 `npm uninstall -g paper-search-cli` |
+| 某个功能不能用 | `paper-search doctor --format text` 看缺什么，再 `paper-search setup` 配置 |
+| 学校订阅的文章下载不到 | `paper-search carsi status --format text` 看扩展是否装好；`paper-search failures --format text` 看每篇的原因 |
+| 来源限流 | 减小 `--max-results`、配置对应 key，或换来源 |
+| Google Scholar 出验证页 | 等一会儿再试，或改用 `--sources no-key` |
+| AI 读到的 Skill 是旧的 | `paper-search skills status --pretty`，再 `paper-search skills update --targets <工具>`；新开一个 AI 会话 |
+
+## 使用边界
+
+部分来源受平台条款、机构订阅或当地法律约束，只在你有相应访问权时使用。机构下载用的是你自己的学校账号和订阅；结果里的来源标记只用于诊断，不能当作授权证明。
+
+## 项目来源
+
+- 感谢 [LinuxDo](https://linux.do) 社区：命令 + Skill 的路线和工作流改进来自社区交流与开源分享。
+- [openags/paper-search-mcp](https://github.com/openags/paper-search-mcp)：本项目参考了它的思路，并改成独立的命令行工具。
+- [Rimagination/scansci-pdf](https://github.com/Rimagination/scansci-pdf)（MIT）：机构下载后端（`carsi/`）由它裁出，只保留机构访问这一段（CARSI 等联盟登录、出版社网站抓取、会话复用、PDF 捕获），再逐家补充出版社规则；原项目的版权声明保留在 `carsi/NOTICE`。
+
+## License
+
+MIT

package/carsi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 scansci-pdf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/carsi/NOTICE

@@ -0,0 +1,5 @@
+paper-search-carsi
+Derived from scansci-pdf (https://github.com/Rimagination/scansci-pdf), MIT License,
+copyright (c) 2024-2026 scansci-pdf contributors. Base: upstream commit f3dbb66 plus the
+maintainer's single-download candidate patches of 2026-10-27/28. Only the institutional
+access phase was kept; public/OA/grey sources, search, batch, Tor and Zotero were removed.

package/carsi/README.md

@@ -0,0 +1,75 @@
+# paper-search-carsi
+
+PaperSearch 的机构授权 PDF 下载后端，从 scansci-pdf 裁出，只保留"机构访问"这一段：CARSI 等联盟入口、出版社浏览器抓取、会话复用、PDF 捕获。公开/OA 来源、灰色来源、搜索、批量、Tor、Zotero 都不在这里，那些由 PaperSearch 自己负责。WebVPN、EZProxy（经学校的网关或代理用学校 IP）也不在这里：代码暂存在仓库根目录 `campus-proxy/`，未接入。
+
+状态：**MCP server、编排和 CLI 已接通，PaperSearch `doctor` 握手通过；真实机构下载尚待逐出版社验收。**
+
+## 安装与浏览器后端
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[camoufox]"
+.venv/bin/python -m camoufox fetch     # 下载 Camoufox 浏览器本体（约 0.5 GB 压缩包）
+```
+
+`bin/paper-search-carsi` 优先使用仓库内的 `.venv`（可用 `CARSI_PYTHON` 指定其他解释器）。
+
+浏览器后端二选一，配置键 `browser_backend`：
+
+- `camoufox`（默认）：开源反指纹 Firefox，经 Playwright 自动化，全部浏览器路线都用它。持久化配置目录是原目录旁的 `-camoufox` 兄弟目录，首次使用需要重新登录一次机构。
+- `ego`（需要 agent 接手你正在用的浏览器时选用）：直接使用你日常运行的 ego-lite（Chromium 内核），Playwright 经 CDP 接管，沿用其中已有的登录；规则与适配器和 camoufox 同一套。在 ego 里打开 `chrome://inspect/#remote-debugging` 勾选 "Allow remote debugging for this browser instance"，勾选一次即保存在 ego 设置中，重启后仍有效；程序只操作并关闭自己开的标签页，不关闭浏览器，也不写入 Cookie。ego 的数据目录可用 `ego_user_data_dir` 指定；未安装 ego-lite 时自动回到 camoufox。
+
+旧值 `patchright`、`cloakbrowser` 会记一条警告并按 `camoufox` 处理。
+
+## 使用
+
+等待用户操作：停在学校登录页（以及没配置学校时的选校页）每篇最多 3 分钟（配置键 `browser_login_timeout`，秒，默认 180）；停在其他页面（人机验证、出版社页面、选机构页、取 PDF 时等待处理）连续超过 1 分钟就结束这一篇（`browser_page_wait_timeout`，默认 60）。两项和每家出版社每小时最多下载篇数都能在进度窗口右上角的设置（齿轮）里改。浏览器某一步 90 秒没有响应时，这一篇以 `browser_unresponsive` 结束。进度窗口的按钮：跳过本篇、本刊无权限、出版社无权限、终止任务（整批停下，剩余篇目记为 `batch_stopped`）、⚑ 报告问题。
+
+浏览器调用超过 4 分钟没有返回时，后端会取消它并把这一篇记为 `browser_unresponsive`（日志里记下是哪个调用、从哪里调用），批量继续下一篇。后端一直停着不动（CPU 为 0、进度不再更新）时，`kill -USR1 <后端进程号>` 会把它所有线程的 Python 调用栈追加到 `<数据目录>/logs/stacks-<日期>.txt`，用来看它在等哪个浏览器调用；进程不会因此退出。
+
+```bash
+# 1. 选择机构入口：用 --institution 配置自己的学校（CARSI 成员学校的中文名、英文名或域名，在 CARSI 学校列表里查找后保存中英文名和 entityID），之后各出版社的选校页由程序自动选中（只点与它对应的那一项）；不配置则在登录窗口里手选
+paper-search-carsi setup --carsi            # 或 --carsi --institution "学校名"
+paper-search-carsi setup --list-carsi-schools 关键词   # 查 CARSI 成员学校
+paper-search-carsi setup --check            # 环境检查：数据目录、浏览器后端、入口是否配置
+
+# 2. 在弹出的浏览器窗口完成一次机构登录（凭证只在窗口里输入，CLI 不经手）
+paper-search-carsi login --doi 10.1016/...           # 打开这篇文章的出版社页面，在出版社的机构登录里选学校（CARSI）
+paper-search-carsi login --publisher elsevier        # 没有 DOI 时打开出版社首页
+
+# 3. 让 PaperSearch 用它（专属数据目录与上面保持一致）
+paper-search config set PAPER_SEARCH_CARSI_EXECUTABLE /path/to/paper-search-carsi
+paper-search config set PAPER_SEARCH_CARSI_ENABLED true
+paper-search doctor --pretty
+
+# 另一个终端里查看当前任务进度（只读）
+paper-search-carsi progress --json --watch
+
+# 贡献者自检：跑一篇受限 DOI 并输出脱敏报告
+paper-search-carsi publisher-check --doi 10.1016/...
+```
+
+`CARSI_DATA_DIR` 决定数据目录；PaperSearch 默认用 `$XDG_DATA_HOME/paper-search-cli/carsi`，运行上面的 setup/login 时要导出同一个值。
+
+## 三级结构
+
+```text
+paper_search_carsi/
+├── publishers/      tier 1  声明式出版社规则：builtin/*.json + schema.json + 用户 publisher_profiles_file
+├── adapters/        tier 2  出版社适配器（Python）：一家一个目录，只写通用流程判断不了的钩子；platforms/ 是网站平台的共同规则（Atypon、Silverchair），出版社继承它；base.py 是基类与默认值
+├── engine/          tier 3  机构入口：bridge（调度）/ batch（出版社浏览器抓取，含 CARSI 选校）/ router
+├── browser/                 浏览器引擎、后端选择、登录等待、Cookie、预览
+├── extractors/              PDF 响应提取
+├── server.py                MCP stdio：download / cache_clear / list_publishers
+└── cli.py                   setup / login / publisher-check
+```
+
+谁可以贡献什么：
+
+| 层 | 需要会什么 | 合并条件 |
+| --- | --- | --- |
+| tier 1 `publishers/builtin/<name>.json` | 不需要写代码 | 通过 `schema.json` 校验；附脱敏页面快照到 `tests/fixtures/publishers/<name>/` |
+| tier 2 `adapters/<name>/` | Python，`PublisherAdapter` 子类 | 离线夹具测试；`publisher-check` 报告贴在 PR |
+| tier 3 `engine/` | 熟悉学校认证流程 | 维护者审核 |
+
+详见 CONTRIBUTING.md。

package/carsi/paper_search_carsi/__init__.py

@@ -0,0 +1,6 @@
+"""paper-search-carsi: institutional (publisher-authorized) PDF download backend for PaperSearch.
+
+Derived from scansci-pdf (MIT); only the institutional access phase is kept.
+"""
+
+__version__ = "0.1.0"

package/carsi/paper_search_carsi/_core/__init__.py

@@ -0,0 +1,26 @@
+"""Optional Cython-accelerated core modules.
+
+The .pyx sources live in this package and are MIT licensed. When Cython
+is available they are compiled to .pyd/.so at build time; pure Python fallbacks
+exist in the original modules.
+
+Usage in other modules:
+    try:
+        from .racing import run_parallel_race
+    except ImportError:
+        # Pure Python fallback is used inline
+"""
+
+# Individual compiled modules are imported directly by their callers via
+# try/except; there is intentionally no package-level re-export layer.
+
+def _check_availability() -> dict[str, bool]:
+    """Check which compiled modules are available."""
+    status = {}
+    for mod_name in ("racing", "scihub_core"):
+        try:
+            __import__(f"paper_search_carsi._core.{mod_name}")
+            status[mod_name] = True
+        except ImportError:
+            status[mod_name] = False
+    return status

package/carsi/paper_search_carsi/_core/racing.pyx

@@ -0,0 +1,280 @@
+# cython: language_level=3
+"""Tiered parallel racing download engine.
+
+This module implements the multi-source download strategy:
+- 5-tier download architecture with tuned timeouts
+- Fully parallel cross-tier racing with Event-based instant notification
+- Thread-safe result publication and batch orchestration
+"""
+
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+# Tier definitions with tuned timeouts (seconds)
+cdef int TIER_FLASH_TIMEOUT = 4
+cdef int TIER_FAST_TIMEOUT = 5
+cdef int TIER_OA_TIMEOUT = 8
+cdef int TIER_GREY_TIMEOUT = 25
+cdef int TIER_WEBVPN_TIMEOUT = 20
+
+# Batch download tuning
+cdef double BATCH_STAGGER_DELAY = 0.3
+cdef int DEFAULT_BATCH_WORKERS = 10
+
+
+def run_parallel_race(
+    list all_sources,
+    str doi,
+    object target_dir,
+    object output_path,
+    dict config,
+    bint use_tor,
+    int overall_timeout,
+    try_source_fn,
+    safe_filename_fn,
+    logger,
+) -> dict | None:
+    """Race all sources in parallel across tiers. First success wins.
+
+    Uses a shared result dict with threading.Event for instant notification
+    when any source succeeds, even from nested parallel calls.
+
+    Args:
+        all_sources: List of (fn, label, tier_label, timeout) tuples
+        doi: Paper DOI
+        target_dir: Directory for temp files
+        output_path: Final output path
+        config: Configuration dict
+        use_tor: Whether to use Tor
+        overall_timeout: Max seconds to wait
+        try_source_fn: Function to try a single source
+        safe_filename_fn: Function to create safe filename
+        logger: Logger instance
+    """
+    if not all_sources:
+        return None
+
+    cdef int n = len(all_sources)
+
+    # Single source - run directly without pool overhead
+    if n == 1:
+        fn, label, tier_label, timeout = all_sources[0]
+        src_output = target_dir / f"{safe_filename_fn(doi)}_{label}.pdf"
+        result = try_source_fn(fn, doi, src_output, config, label, use_tor=use_tor)
+        if result and result.get("success"):
+            _move_to_output(result, output_path)
+            return result
+        return None
+
+    # Shared state for cross-thread result publication
+    result_lock = threading.Lock()
+    success_event = threading.Event()
+    cancel_event = threading.Event()
+    all_done_event = threading.Event()
+    done_counter = [0]
+    done_counter_lock = threading.Lock()
+    shared_result = {"result": None}
+
+    def _try_and_publish(fn, label, src_output):
+        if cancel_event.is_set():
+            return None
+        result = try_source_fn(fn, doi, src_output, config, label, use_tor=use_tor)
+        if result and result.get("success"):
+            with result_lock:
+                if shared_result["result"] is None:
+                    shared_result["result"] = (result, label, src_output)
+                    cancel_event.set()
+                    success_event.set()
+        return result
+
+    def _wait_any(timeout):
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if success_event.is_set() or all_done_event.is_set():
+                return True
+            time.sleep(0.05)
+        return success_event.is_set() or all_done_event.is_set()
+
+    def _on_future_done(fut):
+        with done_counter_lock:
+            done_counter[0] += 1
+            if done_counter[0] >= n:
+                all_done_event.set()
+
+    logger.info(f"   Racing {n} sources across multiple tiers (parallel)...")
+
+    pool = ThreadPoolExecutor(max_workers=n)
+    futures = {}
+    try:
+        for fn, label, tier_label, tier_timeout in all_sources:
+            src_output = target_dir / f"{safe_filename_fn(doi)}_{label}.pdf"
+            fut = pool.submit(_try_and_publish, fn, label, src_output)
+            futures[fut] = (label, src_output)
+        for fut in futures:
+            fut.add_done_callback(_on_future_done)
+
+        # Wait for first success, all sources done, or the overall timeout.
+        # all_done lets a full fast-failure return immediately instead of
+        # burning the whole timeout + grace period.
+        _wait_any(overall_timeout + 5)
+
+        if shared_result["result"] is not None:
+            result, label, src_output = shared_result["result"]
+            _move_to_output(result, output_path)
+            logger.info(f"   OK {label}")
+            return result
+        if all_done_event.is_set():
+            logger.info("   All sources failed")
+            return None
+
+        # Timeout reached — give late-finishing threads a grace period.
+        # Visible browser login can take 60-300s (browser launch + SSO + redirect),
+        # so we wait much longer if browser-based sources are in the pool.
+        has_browser = any("Browser" in lbl for _, lbl, _, _ in all_sources)
+        has_carsi = any("CARSI" in lbl for _, lbl, _, _ in all_sources)
+        if has_carsi:
+            grace = 300
+        elif has_browser:
+            grace = 180
+        else:
+            grace = 15
+        logger.info(f"   Racing timed out after {overall_timeout + 5}s, waiting up to {grace}s for late results...")
+        _wait_any(grace)
+        if shared_result["result"] is not None:
+            result, label, src_output = shared_result["result"]
+            _move_to_output(result, output_path)
+            logger.info(f"   OK {label} (late)")
+            return result
+        if all_done_event.is_set():
+            logger.info("   All sources failed")
+            return None
+
+        # Final scan: check if any source wrote a valid PDF file despite timeout
+        for label, src_output in futures.values():
+            if src_output.exists():
+                _move_to_output({"success": True, "identifier": doi, "doi": doi,
+                                 "file": str(src_output), "source": label}, output_path)
+                if output_path.exists():
+                    logger.info(f"   OK {label} (file scan)")
+                    return {"success": True, "identifier": doi, "doi": doi,
+                            "file": str(output_path), "source": label}
+
+        logger.info("   All sources failed")
+    finally:
+        # Never block termination on sources that refuse to return: cancel
+        # pending futures and waive stragglers. Their own I/O deadlines
+        # (connect/read timeouts, stream deadline in pdf_utils) bound how long
+        # an abandoned worker thread can outlive the race.
+        alive = [f for f in futures if not f.done()]
+        if alive:
+            logger.info(f"   Racing finished with {len(alive)} source(s) still running (waived)")
+        pool.shutdown(wait=False, cancel_futures=True)
+        _cleanup_temps(futures, output_path)
+
+    return None
+
+
+cdef void _move_to_output(dict result, object output_path):
+    """Move downloaded file to final output path."""
+    final_path = Path(result.get("file", ""))
+    if final_path != output_path and final_path.exists():
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        if output_path.exists():
+            output_path.unlink()
+        final_path.rename(output_path)
+        result["file"] = str(output_path)
+
+
+cdef void _cleanup_temps(dict futures, object output_path):
+    """Remove temporary files from failed downloads."""
+    for _, other_path in futures.values():
+        if other_path != output_path and other_path.exists():
+            try:
+                other_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def build_tiers(
+    list publisher_fast,
+    list publisher_oa,
+    list tier3_libgen,
+    list tier4_scihub,
+    list tier5_instsci,
+    str strategy,
+) -> list:
+    """Build tier structure based on download strategy.
+
+    Returns list of (sources, label, timeout) tuples.
+    """
+    if strategy == "legal_only":
+        return [
+            (publisher_fast, "Flash", TIER_FLASH_TIMEOUT),
+            (publisher_oa, "OA", TIER_OA_TIMEOUT),
+        ]
+    elif strategy == "scihub_only":
+        return [(tier4_scihub, "Sci-Hub", TIER_WEBVPN_TIMEOUT)]
+    elif strategy == "oa_first":
+        return [
+            (publisher_fast, "Flash", TIER_FLASH_TIMEOUT),
+            (publisher_oa, "OA", TIER_OA_TIMEOUT),
+            (tier3_libgen + tier4_scihub, "Grey", TIER_GREY_TIMEOUT),
+        ]
+    else:
+        # "fastest" (default): all tiers race in parallel
+        tier2_fast = publisher_oa[:3] if len(publisher_oa) > 3 else publisher_oa
+        tier3_oa = publisher_oa[3:] if len(publisher_oa) > 3 else []
+        tiers = [
+            (publisher_fast, "Flash", TIER_FLASH_TIMEOUT),
+            (tier2_fast, "Fast", TIER_FAST_TIMEOUT),
+            (tier3_oa, "OA", TIER_OA_TIMEOUT),
+            (tier3_libgen + tier4_scihub, "Grey", TIER_GREY_TIMEOUT),
+        ]
+        if tier5_instsci:
+            tiers.append((tier5_instsci, "WebVPN", TIER_WEBVPN_TIMEOUT))
+        return tiers
+
+
+def batch_download(
+    list dois,
+    object output_dir,
+    dict config,
+    download_fn,
+    int workers = DEFAULT_BATCH_WORKERS,
+) -> list:
+    """Download multiple papers with staggered parallel execution.
+
+    Deduplicates DOIs, then runs downloads with rate-limiting stagger.
+    """
+    # Deduplicate preserving order
+    cdef list seen = set()
+    cdef list unique_dois = []
+    for doi in dois:
+        if doi not in seen:
+            seen.add(doi)
+            unique_dois.append(doi)
+
+    cdef list results = []
+    cdef double delay = BATCH_STAGGER_DELAY
+    stagger_lock = threading.Lock()
+
+    def _download_one(doi):
+        # Stagger start to avoid burst requests
+        with stagger_lock:
+            time.sleep(delay)
+        return download_fn(doi, output_dir, config=config)
+
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(_download_one, doi): doi for doi in unique_dois}
+        for future in as_completed(futures):
+            doi = futures[future]
+            try:
+                result = future.result()
+                results.append(result)
+            except Exception as e:
+                results.append({"doi": doi, "success": False, "error": str(e)})
+
+    return results

package/carsi/paper_search_carsi/adapters/__init__.py

@@ -0,0 +1,26 @@
+"""Per-publisher adapters for the publisher browser driver.
+
+The shared engine (``PublisherBatchDownloader``) owns navigation, waits for
+human verification, the PDF capture channels and the run records. An adapter
+answers only its publisher's questions: is this reader signed in, where is
+the institution entry, which URL is the article PDF, which links are its
+supplementary files. Every hook returns ``None`` for "no opinion", and the
+engine then applies its generic behaviour, so publishers without an adapter
+keep working unchanged.
+
+Each publisher, and each platform shared by several publishers (``atypon``,
+``silverchair``), has its own folder here: its rules in ``<name>/__init__.py``,
+and one more module per site type when it has several (``elsevier/``,
+``lww/``). ``base.py`` holds the shared base class and its defaults.
+
+Adding a publisher: subclass :class:`PublisherAdapter` in ``<name>/__init__.py``,
+decorate it with :func:`register`, and import the package below.
+"""
+
+from .base import PublisherAdapter, SupplementLink, adapter_class, adapter_for, register
+from . import (  # noqa: F401  (register the adapters)
+    acm, acs, aha_journals, ams, annual_reviews, aps, asce, bmj, copernicus, dovepress, elsevier, ieee, iop,
+    jama, karger, lww, mdpi, nejm, neurology, optica, oup, plos, pnas, rsc, sage, science, springer,
+    taylor_francis, thieme, wiley, world_scientific)
+
+__all__ = ["PublisherAdapter", "SupplementLink", "adapter_class", "adapter_for", "register"]