papersearch 0.4.0 → 0.4.3

package/README.md

@@ -1,41 +1,48 @@
 # PaperSearch
 
-[简体中文](README.zh.md) | English
+简体中文 | [English](README.en.md)
 
-PaperSearch is `paper-search`, an academic literature command for AI tools and the terminal, with a bundled Skill that teaches Claude Code, Codex, Cursor and other AI tools how to call it. It searches papers, verifies DOIs and PMIDs, expands citations and references, looks up journal impact factors and quartiles, finds Methods wording in body snippets, and downloads paper PDFs and supplementary files. Output is JSON by default, for AI tools and scripts.
+**让 AI 帮你查文献、核对引用、下载全文和补充材料。**
 
-It is the open version by default: once installed it searches and downloads open-access papers. To download through your school's subscriptions, add the optional institutional download extension.
+PaperSearch 提供 `paper-search` 命令和一份随包 Skill。装好后，Claude Code、Codex、Cursor、Kimi Code、Qwen Code、CodeBuddy、TRAE 等支持本机命令调用的 AI 工具，就能替你检索 20 多个学术数据源、核对 DOI，把论文的 PDF 和补充材料下载下来并整理好。你也可以在终端或脚本里直接使用，输出默认是 JSON。
 
-![Node.js](https://img.shields.io/badge/node.js->=18.0.0-green.svg)
+- **开放获取直接下载**：PubMed Central、Unpaywall、出版社接口等渠道，装好就能用。
+- **学校订阅也能下**：可选的机构下载扩展经 CARSI 登录你的学校，批量获取学校有权限的论文和补充材料；支持自动过验证，放行后继续下载。
+- **每一篇都核对过**：逐个核对 PDF 首页的 DOI 和题名，不是这篇文章的不算成功。
+- **结果直接能用**：按“期刊_年份_标题”建文件夹，正文和补充材料放在一起；没下到的篇目说明原因。
+
+[![npm](https://img.shields.io/npm/v/papersearch)](https://www.npmjs.com/package/papersearch)
+![Node.js](https://img.shields.io/node/v/papersearch)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)
 [![LinuxDo](https://img.shields.io/badge/LinuxDo-community-1f6feb)](https://linux.do)
 
-[How it works](#how-it-works) | [Quick start](#quick-start) | [Two ways to download](#two-ways-to-download) | [Search sources](#search-sources) | [Configuration](#configuration) | [Agent Skill](#agent-skill) | [Commands](#commands) | [Troubleshooting](#troubleshooting)
+[效果](#效果) | [快速开始](#快速开始) | [常见任务](#常见任务) | [工作方式](#工作方式) | [机构下载扩展](#机构下载扩展) | [检索来源](#检索来源) | [配置](#配置) | [Agent Skill](#agent-skill) | [命令](#命令) | [排障](#排障)
+
+## 效果
+
+对 AI 工具说一句话，例如：
 
-## How it works
+> 找 2020 年以来 SGLT2 抑制剂治疗心力衰竭的随机对照试验，核对 DOI，把全文和补充材料下载到 ./downloads
+
+AI 会调用 PaperSearch 检索、核验、下载，最后告诉你哪些拿到了、哪些没拿到以及原因。下面是一次实际下载的结果：
 
 ```text
-A literature request
-│
-├─ Find papers, verify DOI/PMID → paper-search search (Crossref, PubMed, OpenAlex, ...)
-│    └─ Entries confirmed, full text needed → go to "Download" below
-├─ Citing papers, references → paper-search run get_paper_citations / get_paper_references
-├─ Impact factor, quartiles → paper-search journal-metrics (EasyScholar key)
-├─ Methods wording, parameters → paper-search run search_semantic_snippets (Semantic Scholar key)
-│
-└─ Download main text, supplementary files → paper-search download / run download_with_fallback / run download_batch
-     One download command, tried in order:
-     ├─ ① Open downloading (built in): the source's own download, PMC, Unpaywall, publisher APIs
-     ├─ ② Sci-Hub fallback (on by default, can be turned off)
-     ├─ ③ Institutional download (optional extension): a browser signs in to your school through CARSI and takes the PDF and supplementary files from the publisher's site
-     ├─ Every file is checked against the DOI and title on its first page; once one passes it is saved and the rest are not tried
-     └─ Nothing found → paper-search failures says why
+downloads/
+├── papers/
+│   ├── Nutrients_2026_α-Ketoglutarate Alleviates the Pathogenesis…_0b6e0203de/
+│   │   ├── Nutrients_2026_α-Ketoglutarate Alleviates the Pathogenesis….pdf
+│   │   └── supplements/
+│   │       └── nutrients-18-03600-s001.zip       补充材料保留原文件名
+│   └── arXiv_2017_Attention Is All You Need_a1a0262a54/
+│       └── arXiv_2017_Attention Is All You Need.pdf    预印本会标明
+└── diagnostics/                                   运行记录、附件清单、截图
 ```
 
-## Quick start
+<!-- 截图：机构下载的进度窗口。图片放在 docs/ 以外（例如 assets/progress-window.png），docs/ 不随公开仓库发布 -->
 
-Requires Node.js 18 or later and npm.
+## 快速开始
+
+要求 Node.js 18 及以上和 npm。
 
 ```bash
 npm install -g papersearch
@@ -43,168 +50,242 @@ paper-search setup
 paper-search doctor --format text
 ```
 
-`paper-search setup` asks three things in turn: API keys and email; which AI tools to install the Skill into (Claude Code, Codex, Cursor, ...); and whether to install the institutional download extension. Each can be skipped. `doctor` shows what works now and what is still missing.
+`paper-search setup` 会依次问三件事：API key 和邮箱；Skill 安装到通用目录还是工具专用目录；要不要安装机构下载扩展。每一步都可以跳过。`doctor` 显示现在能用哪些功能、还缺什么配置。
 
-The Skill is the instruction file that teaches an AI tool to call `paper-search`; install it when you use an AI tool for literature work. If you skipped it, install it any time, with `--targets` set to your tool (`claude`, `codex`, `cursor`, `gemini`, `agents`, or `all`):
+Skill 是教 AI 工具调用 `paper-search` 的说明文件，用 AI 工具做文献任务时要装。跳过了可以随时补装，`--targets` 换成你用的工具（`claude`、`codex`、`cursor`、`gemini`、`agents`，或 `all`）：
 
 ```bash
 paper-search skills update --targets claude
 ```
 
-You can also send this to your AI tool and let it do the install:
+Kimi Code、Qwen Code 使用 `--targets agents`，将 Skill 安装到共享目录。TRAE、CodeBuddy 的接入方式见下方 [Agent Skill](#agent-skill)。
+
+也可以把下面这段话发给你的 AI 工具，让它帮你装：
 
 ```text
-Please install PaperSearch for me: run npm install -g papersearch, then paper-search skills update --targets <your own target: claude for Claude Code, codex for Codex, cursor for Cursor>, then paper-search doctor --format text, and tell me which features work and which keys are missing. I will enter API keys myself with paper-search setup in a terminal; do not ask me to paste them into the chat.
+请帮我安装 PaperSearch：运行 npm install -g papersearch，再按 README 的 Agent Skill 说明为你自己安装随包 Skill（Kimi Code、Qwen Code 用 agents，Claude Code 用 claude，Codex 用 codex，Cursor 用 cursor；TRAE、CodeBuddy 使用各自的 Skill 目录），最后运行 paper-search doctor --format text，告诉我哪些功能能用、还缺哪些 key。API key 我会自己在终端运行 paper-search setup 输入，不要让我发到聊天里。
 ```
 
-**Coming from the old package `paper-search-cli`**: run `npm uninstall -g paper-search-cli`, then `npm install -g papersearch`. Both provide the same `paper-search` command and cannot be installed together; your configuration, Skill, school login and download records stay.
+**从旧包 `paper-search-cli` 升级**：先运行 `npm uninstall -g paper-search-cli`，再 `npm install -g papersearch`。两个包提供同一个 `paper-search` 命令，不能同时装；配置、Skill、学校登录和下载记录都会保留。
 
-**Later upgrades**: `npm install -g papersearch@latest`. The first `paper-search` run after an upgrade brings the Skill you installed up to the new version.
+**以后升级**：`npm install -g papersearch@latest`。升级后第一次运行 `paper-search` 时，它会自动把你装过的 Skill 更新到新版本。
 
-Try the features:
+## 常见任务
 
 ```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
+# 检索论文（不需要任何 key 的来源组合）
+paper-search search "machine learning clinical prediction" --sources no-key --max-results 5 --pretty
+
+# 指定一个来源，例如 PubMed
+paper-search search "SGLT2 inhibitor heart failure" --platform pubmed --max-results 10 --pretty
+
+# 核验一个 DOI
+paper-search run get_paper_by_doi --arg doi="10.1038/nature12373" --pretty
+
+# 施引文献；参考文献把 get_paper_citations 换成 get_paper_references
 paper-search run get_paper_citations --arg doi="10.1038/nature12373" --arg limit=5 --pretty
+
+# 期刊影响因子和分区（需要 EasyScholar key）
 paper-search journal-metrics "Nature" "BMJ" --pretty
-paper-search download PMC11466435 --platform pmc --save-path ./downloads
+
+# 在正文里找 Methods 写法（需要 Semantic Scholar key）
 paper-search run search_semantic_snippets --arg query="propensity score matching" --arg limit=3 --pretty
+
+# 下载一篇
+paper-search download "<DOI>" --platform crossref --save-path ./downloads
+
+# 批量下载正文和补充材料（只要正文去掉 content；只要补充材料用 "supplements"）
+paper-search run download_batch --json-args '{"items":[{"doi":"<DOI-1>"},{"doi":"<DOI-2>"}],"savePath":"./downloads","content":"both"}'
+
+# 没下到的篇目和原因
+paper-search failures --format text
 ```
 
-## Two ways to download
+## 工作方式
 
-|  | Open downloading (default) | Institutional download (optional extension) |
+```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 和补充材料
+     ├─ ④ arXiv 预印本：前面都没拿到正式发表版时才用，并标明是预印本
+     ├─ 每一步拿到文件都核对首页的 DOI 和题名；通过就保存，后面的步骤不再试
+     └─ 都没拿到 → paper-search failures 说明原因
+```
+
+### 两种下载方式
+
+|  | 开放下载（默认） | 机构下载（可选扩展） |
 |---|---|---|
-| Available | As soon as PaperSearch is installed | After `paper-search carsi install` |
-| Gets | Open-access main text | Main text your school subscribes to; supplementary files from the publishers with rules for them |
-| How | Direct downloads, usually seconds, no login: the source's own download, PDF links in the metadata, PubMed Central, Unpaywall, publisher APIs (your own Elsevier/Springer keys); last, the Sci-Hub fallback, on by default | A browser signs in to your school through CARSI and takes the PDF from the publisher's site |
-| What you do | Nothing | The first time, type your school account and password in the browser and click any human check; the program picks the school |
+| 能不能直接用 | 装好就能用 | 要另外安装：`paper-search carsi install` |
+| 能拿到什么 | 开放获取的正文 | 你的学校订阅的正文；有规则的出版社还能取补充材料 |
+| 怎么拿 | 程序直接下载，通常几秒，不用登录：来源自带的下载、元数据里的 PDF 地址、PubMed Central、Unpaywall、出版社接口（你自己的 Elsevier/Springer key）；最后是默认开启的 Sci-Hub 兜底 | 打开一个浏览器，经 CARSI 登录你的学校，在出版社网站上取 PDF |
+| 你要做的事 | 无 | 在浏览器里登录学校；程序自动过验证，需要人工接管时再按提示操作 |
 
-Both use the same download command: open downloading first, and when it finds nothing, the institutional download if it is installed.
+两种方式用同一个下载命令：先试开放下载，拿不到时，装了机构下载才继续用学校权限。
 
-```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` 把没下到的篇目分成四类：没权限（附页面原话等依据）、需要你处理（登录、验证、等待）、暂不支持的网站、原因不明。
+- arXiv 论文先找正式发表版，都没拿到才下载预印本；结果里写 `version: "preprint"`，已知时附正式版 DOI。
+- 不想用 Sci-Hub 时，在 `download_with_fallback` / `download_batch` 里设 `"useSciHub": false`。
+- 每个 PDF 都核对首页的 DOI 和题名；对不上的不算成功，单独留待核查。
+
+### 下载结果
 
-- For dozens to hundreds of papers, use one `download_batch`; afterwards `paper-search failures` sorts the papers not downloaded into four classes: no access (with the evidence, such as the page's own words), needs you (login, human check, waiting), site not supported yet, and cause unknown.
-- To leave out Sci-Hub, set `"useSciHub": false` in `download_with_fallback` / `download_batch`.
-- Every saved PDF is checked against the DOI and title on its first page; a file of another article is not kept.
+下载目录分两部分：`papers/` 放论文，每篇一个文件夹，正文按“期刊_年份_标题”命名，补充材料在该篇的 `supplements/` 里并保留原文件名；`diagnostics/` 放运行记录、附件清单和截图，查问题时用。文件夹名末尾的短标识用来区分同名论文。缺少期刊或年份时写“未知期刊”“未知年份”。旧版本下载的文件不会自动搬动，命令返回的 JSON 里写着每个文件的实际位置。
 
-### Institutional download extension
+## 机构下载扩展
 
 ```bash
 paper-search carsi install
 paper-search carsi status --format text
 ```
 
-- Installing asks for your school (a CARSI member school, by Chinese name, English name or domain) and downloads the dedicated Camoufox browser, about 3 GB in all; on macOS, `--browser ego` uses ego lite instead, about 0.5 GB. `--skip-school` leaves the school for later.
-- Schools sign in through CARSI (the Chinese university identity federation). When a publisher's institution list has no CARSI or no entry for your school, the program says so at once; download on campus or through your school's VPN instead.
-- `paper-search carsi update` updates the extension after a PaperSearch upgrade; `paper-search carsi uninstall` removes it (keeping the browser and the school settings by default).
-- Windows: if PowerShell blocks `npm.ps1`, use `npm.cmd` or Command Prompt; downloads must run in a desktop session, as a browser window cannot open from SSH or a system service.
+- 安装时会问你的学校（CARSI 成员学校，中文名、英文名或域名都可以），并下载专用浏览器 Camoufox，共约 3 GB；macOS 上 `--browser ego` 改用 ego lite，约 0.5 GB。`--skip-school` 可以以后再选学校。
+- 目前用 CARSI（中国高校身份联盟）登录学校；出版社的机构列表里没有 CARSI 或你的学校时，程序会立即说明，建议在校园网或学校 VPN 下下载。
+- 自动过验证：程序自动定位并点击验证框，网站放行后继续下载。每次验证等待最多尝试 3 次，两次至少间隔 3 秒；自动阶段结束后仍未放行时，进度窗口会提示人工接管。
+- 下载时会出现进度窗口：可以跳过本篇、标记本刊或出版社无权限、终止整个任务，右上角齿轮可以调整等待时间。停在学校登录页默认最多等 3 分钟，停在其他页面（人机验证、出版社页面等）默认 1 分钟后结束这一篇。
+- 能取哪些出版社的正文和补充材料，见 [出版社支持表](skills/paper-search/references/publisher-support.md)。正文和补充材料都实测取得的有 Elsevier、Wiley、Springer Nature、OUP、Wolters Kluwer、Taylor & Francis、Sage、ACS、NEJM、ASCE、Dove 等，另支持 MDPI、Frontiers 的补充材料和论文关联的 Figshare 附件；IEEE、Thieme 等目前只取正文；表里没有的网站按通用规则尝试。
+- `paper-search carsi update` 在 PaperSearch 升级后更新扩展，`paper-search carsi uninstall` 卸载（默认保留浏览器和学校配置）。
+- Windows：PowerShell 拦住 `npm.ps1` 时改用 `npm.cmd` 或命令提示符；下载要在桌面会话里运行，经 SSH 或系统服务启动时浏览器窗口打不开。
 
-### Supplementary files
+## 检索来源
 
-`content` in `download_with_fallback` / `download_batch` picks what to download: `main` (default, main text only), `both` (main text and supplementary files), or `supplements` (supplementary files only). Supplementary files come only through the institutional download; they are saved under `<save path>/<DOI>_supplements/`, with a `manifest.json` giving each file's status.
+| 类别 | 来源 | 需要的 API key |
+|---|---|---|
+| 综合学术元数据 | Crossref、OpenAlex、Semantic Scholar、Google Scholar | 不需要（Semantic Scholar 的正文片段检索需要） |
+| 生物医学 | PubMed、PubMed Central、Europe PMC | 不需要（PubMed key 可提高限额） |
+| 预印本和会议稿 | arXiv、bioRxiv、medRxiv、OpenReview、IACR ePrint | 不需要 |
+| 计算机和工程 | DBLP、ACM、USENIX | 不需要 |
+| 开放获取和仓储 | CORE、OpenAIRE、Unpaywall | Unpaywall 填邮箱；CORE、OpenAIRE 可选 |
+| 出版社和引文库 | ScienceDirect、Scopus、Springer Nature、IEEE Xplore、Web of Science | 需要各自的 key（ScienceDirect、Scopus 共用 Elsevier key） |
+| 期刊指标 | EasyScholar | 需要 |
 
-What each publisher supports, main text and supplementary files, is in the [publisher support table](skills/paper-search/references/publisher-support.md) (Chinese). Main text and supplementary files have both been fetched from Elsevier, Wiley, Springer Nature, OUP, Wolters Kluwer, Taylor & Francis, Sage, ACS, NEJM, ASCE, Dove and others; IEEE, Thieme and others give the main text only for now; sites not in the table are tried with the shared rules.
+- 不需要 key 的来源已经收录了各大出版社的论文；配了 key，多的是出版社自己的检索入口。
+- 单个来源用 `--platform`，多个用 `--sources a,b,c`；`--sources no-key` 是不需要任何 key 的组合（Crossref、PubMed、Europe PMC、arXiv、OpenReview）。
+- Google Scholar 是网页解析，容易触发验证，不在 `--sources all` 里；需要时用 `--platform googlescholar`。
+- 多个来源返回同一篇论文时按 DOI 合并；arXiv 预印本和正式发表版有明确 DOI 关联时，保留正式发表记录。
+- Sci-Hub 不是检索来源，只在下载时按 DOI 兜底。
 
-## Search sources
+## 配置
 
-| Kind | Sources | Configuration |
-|---|---|---|
-| General academic metadata | Crossref, OpenAlex, Semantic Scholar, Google Scholar | None; Semantic Scholar body snippets need a key; Google Scholar must be asked for by name |
-| Biomedicine | PubMed, PubMed Central, Europe PMC | Optional PubMed key |
-| Preprints and conference papers | bioRxiv, medRxiv, OpenReview, IACR ePrint | None |
-| Computer science and engineering | DBLP, ACM, USENIX, IEEE Xplore | IEEE needs a key |
-| Open access and repositories | CORE, OpenAIRE, Unpaywall | Unpaywall needs an email; CORE key optional |
-| Citation databases and publishers | Web of Science, Scopus, ScienceDirect, Springer Nature | Each needs its key; metadata only (Elsevier and Springer keys also serve the publisher API for full text) |
-| Journal metrics | EasyScholar | EasyScholar key |
+PaperSearch 有两套配置，各管各的，都可以不配：
 
-- One source with `--platform`, several with `--sources a,b,c`; `--sources no-key` needs no keys at all (Crossref, PubMed, Europe PMC, OpenReview).
-- Google Scholar is read from its web pages and often meets human checks, so it is not in `--sources all`; use `--platform googlescholar` when you need it.
-- Sci-Hub is not a search source; it only serves as a DOI fallback when downloading.
+|  | API key | CARSI（机构下载扩展） |
+|---|---|---|
+| 用来做什么 | 部分来源的检索、期刊指标、正文片段检索；Elsevier、Springer 的 key 还能经出版社接口取全文 | 登录你的学校，按学校订阅下载全文和补充材料 |
+| 怎么配 | `paper-search setup`，或 `paper-search config set` | `paper-search carsi install`，安装时选学校 |
+| 不配时 | 用免费来源检索；“检索来源”里需要 key 的来源和功能不可用 | 下载只走开放下载渠道（见[两种下载方式](#两种下载方式)） |
 
-## Configuration
+### API key 与配置文件
 
-Most free sources need nothing. Run `paper-search setup` first to save keys in your user configuration:
+多数免费来源不需要配置。建议先运行 `paper-search setup`，把 key 写入用户配置：
 
 ```bash
 paper-search setup
 paper-search config list --pretty
-paper-search config set SEMANTIC_SCHOLAR_API_KEY <your key>
+paper-search config set SEMANTIC_SCHOLAR_API_KEY <你的 key>
 ```
 
-The configuration file is `~/.config/paper-search-cli/config.json` (mode `0600`; the folder keeps its old name, so upgrades keep your settings). `config list` and `doctor` show keys masked.
+配置文件在 `~/.config/paper-search-cli/config.json`（权限 `0600`；文件夹沿用旧名，升级不丢设置），`config list` 和 `doctor` 会把 key 脱敏显示。
 
-| Key | Use | When |
+| 配置项 | 用途 | 什么时候配置 |
 |---|---|---|
-| `SEMANTIC_SCHOLAR_API_KEY` | Body snippet search; steadier Semantic Scholar requests | For Methods details, or frequent Semantic Scholar use |
-| `UNPAYWALL_EMAIL` | Open-access PDFs by DOI | Recommended; an email is enough |
-| `CROSSREF_MAILTO` | Crossref's polite pool | Long or frequent searches |
-| `CORE_API_KEY` | CORE repository search | Frequent CORE use, or rate limits |
-| `EASYSCHOLAR_KEY` | Journal metrics | For impact factors and quartiles; `paper-search setup EASYSCHOLAR_KEY` hides the input |
-| `PUBMED_API_KEY`, `NCBI_EMAIL` | Higher PubMed limits | Frequent PubMed use |
-| `WOS_API_KEY`, `IEEE_API_KEY`, `ELSEVIER_API_KEY`, `SPRINGER_API_KEY` | Their metadata; Elsevier and Springer keys also serve the publisher API for full text (access follows your network or key) | When you use those sources |
-| `ELSEVIER_INSTTOKEN` | Elsevier full text off campus through its API | Off campus; not needed on a campus network |
-| `GOOGLE_SCHOLAR_PROXY_URL` | Egress proxy for Google Scholar | When direct requests keep being challenged; use a proxy you are allowed to use |
-| `PAPER_SEARCH_CARSI_ENABLED` | Switch for the institutional download extension | Set by `paper-search carsi install` |
-| `PAPER_SEARCH_SKILL_AUTO_UPDATE` | `false` stops upgrades from updating the installed Skill | On by default; set it to manage the Skill yourself |
-
-Where to get keys: [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/)
+| `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/)
+
+### CARSI
+
+安装和使用见 [机构下载扩展](#机构下载扩展)。它不用任何 API key，也不提供检索。
 
 ## Agent Skill
 
-The Skill ships in the npm package (`skills/paper-search/`). It is written in Chinese, opens with the same overall diagram, and points the AI to focused references as needed: routing and the open download channels, the command contract, installing and using the institutional download, the [publisher support table](skills/paper-search/references/publisher-support.md), and troubleshooting. It only tells the AI how to call `paper-search`; it keeps no keys, cookies or accounts.
+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
 ```
 
-- Targets: `agents`, `codex`, `claude`, `cursor`, `gemini`, `antigravity`, `all`. Updating overwrites the files the package manages and keeps files you added to the Skill directory.
-- **Auto-update after upgrades**: the first `paper-search` run after an upgrade (other than `skills` and `setup`) brings the Skill you installed up to the new version: only where it was installed; replaced files are backed up under `~/.local/share/paper-search-cli/skill-backups/`; one line on stderr says what changed. With no Skill installed anywhere, it says once how to install it. To turn it off: `paper-search config set PAPER_SEARCH_SKILL_AUTO_UPDATE false`.
-- `paper-search doctor` shows where the Skill is installed and whether it is current.
+国内 AI 工具可以按以下方式加载同一份 Skill：
+
+| 工具 | 接入方式 |
+|---|---|
+| [Kimi Code](https://www.kimi.com/code/docs/kimi-code-cli/customization/skills.html)、[Qwen Code](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/skills.md) | 运行 `paper-search skills update --targets agents`，安装到它们共同支持的 `~/.agents/skills/paper-search/` |
+| [TRAE](https://docs.trae.ai/ide/skills?_lang=zh) | 将随包 Skill 文件夹复制到项目的 `.trae/skills/paper-search/` |
+| [CodeBuddy](https://www.codebuddy.ai/docs/zh/ide/Features/Skills) | 将随包 Skill 文件夹复制到项目的 `.codebuddy/skills/paper-search/` |
+
+`npm root -g` 可查看全局 npm 目录；随包 Skill 位于其下的 `papersearch/skills/paper-search/`。复制时保留完整文件夹及 `references/`，更新时从新版本复制。安装后新开 AI 会话即可使用。
+
+- 支持的目标：`agents`、`codex`、`claude`、`cursor`、`gemini`、`antigravity`、`all`。更新会覆盖包里管理的文件，保留你在 Skill 目录里自己加的文件。
+- **升级后自动更新**：通过内置目标安装的 Skill，会在升级 PaperSearch 后第一次运行 `paper-search`（`skills`、`setup` 除外）时更新到新版本：只更新原来装过的位置；被替换的旧文件备份在 `~/.local/share/paper-search-cli/skill-backups/`；并在 stderr 写一行说明。一个都没装时只提示一次怎么装。不想自动更新：`paper-search config set PAPER_SEARCH_SKILL_AUTO_UPDATE false`。
+- `paper-search doctor` 显示内置安装目标中的 Skill 位置和版本状态。
 
-## Commands
+## 命令
 
-| Command | Use |
+| 命令 | 用途 |
 |---|---|
-| `paper-search search` | Search paper metadata |
-| `paper-search journal-metrics` | Journal metrics (EasyScholar) |
-| `paper-search download` | Download the PDF of a verified paper |
-| `paper-search run <tool>` | Call one tool exactly, with `--arg` or `--json-args` |
-| `paper-search failures` | Why downloads failed, summarized |
-| `paper-search carsi` | Install, check, update or remove the institutional download extension |
-| `paper-search setup` / `config` | Configure keys, the Skill and the extension |
-| `paper-search doctor` | Health check: configuration, available features, Skill and extension status |
-| `paper-search skills` | Skill status, differences and updates |
-| `paper-search smoke` | Offline or live self-check |
-| `paper-search tools` | All tool names and their arguments |
-
-Commands print JSON by default; `--pretty` formats it and `--format text` prints a report for people. All commands: `paper-search tools --pretty`, or the [command contract](skills/paper-search/references/cli-contract.md) (Chinese).
-
-## Troubleshooting
-
-| Problem | What to do |
+| `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` not found | Reinstall with `npm install -g papersearch` |
-| `EEXIST` while installing | The old package is still there: `npm uninstall -g paper-search-cli` first |
-| A feature does not work | `paper-search doctor --format text` shows what is missing; then `paper-search setup` |
-| Subscribed articles do not download | `paper-search carsi status --format text` for the extension; `paper-search failures --format text` for each paper's reason |
-| A source rate-limits | Lower `--max-results`, configure its key, or switch sources |
-| Google Scholar shows a human check | Wait and retry, or use `--sources no-key` |
-| The AI reads an old Skill | `paper-search skills status --pretty`, then `paper-search skills update --targets <tool>`; start a new AI session |
+| 找不到 `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 会话 |
+
+## 路线图与参与
+
+- 接下来的重点：批量下载更稳、新电脑安装更顺；在 PDF 之外交付全文包（原始 XML/HTML、Markdown 和正文图片）。详见 [路线图](docs/ROADMAP.zh.md)。
+- 想了解原理和代码结构：[架构说明](docs/ARCHITECTURE.zh.md)。
+- 下载失败或想要支持某家出版社：在 Issues 里附上 `paper-search failures --format text` 的输出（先删掉不想公开的信息）。
+- 想自己加出版社规则：见 [carsi/CONTRIBUTING.md](carsi/CONTRIBUTING.md)。
 
-## Use responsibly
+## 使用边界
 
-Some sources are subject to platform terms, institutional subscriptions or local law; use them only where you have access. The institutional download uses your own school account and subscriptions; the source labels in results are for diagnosis and are not proof of entitlement.
+部分来源受平台条款、机构订阅或当地法律约束，只在你有相应访问权时使用。机构下载用的是你自己的学校账号和订阅；结果里的来源标记只用于诊断，不能当作授权证明。
 
-## Origins
+## 项目来源
 
-Thanks to the [LinuxDo](https://linux.do) community, where the command-plus-Skill approach and workflow improvements came from discussion and open sharing. The project draws on ideas from [openags/paper-search-mcp](https://github.com/openags/paper-search-mcp), reworked into a standalone command; the institutional download backend was carved out of scansci-pdf, see `carsi/NOTICE`.
+- 感谢 [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
 

package/carsi/README.md

@@ -1,6 +1,6 @@
 # paper-search-carsi
 
-PaperSearch 的机构授权 PDF 下载后端，从 scansci-pdf 裁出，只保留"机构访问"这一段：CARSI 等联盟入口、出版社浏览器抓取、会话复用、PDF 捕获。公开/OA 来源、灰色来源、搜索、批量、Tor、Zotero 都不在这里，那些由 PaperSearch 自己负责。WebVPN、EZProxy（经学校的网关或代理用学校 IP）也不在这里：代码暂存在仓库根目录 `campus-proxy/`，未接入。
+PaperSearch 的机构授权下载后端，负责 CARSI 等联盟登录、出版社页面交互、会话复用、正文 PDF 与补充材料获取。公开来源、检索和批量编排由 PaperSearch CLI 负责。WebVPN、EZProxy（经学校的网关或代理用学校 IP）也不在这里：代码暂存在仓库根目录 `campus-proxy/`，未接入。
 
 状态：**MCP server、编排和 CLI 已接通，PaperSearch `doctor` 握手通过；真实机构下载尚待逐出版社验收。**
 
@@ -23,7 +23,9 @@ python3 -m venv .venv
 
 ## 使用
 
-等待用户操作（学校登录、人机验证）每篇累计最多 5 分钟，从第一次等待算起（配置键 `browser_login_timeout`，秒，默认 300）。超时后结果为 `login_timeout`（学校登录）或 `download_timeout`（人机验证）。工具参数 `user_wait: "short"`（PaperSearch 批量里有一篇等满时限后传给后面的篇目）表示用户多半不在：每次等待最多 60 秒，登录页 60 秒没有变化也结束，登录框里有人输入则照常等。
+遇到 Cloudflare/Turnstile 验证框时，程序先等待网站自动检查，再自动定位并点击复选框，网站放行后继续下载。每次验证等待最多尝试 3 次，两次至少间隔 3 秒，复用当前浏览器和原等待时限；自动阶段结束后仍未放行时提示人工接管。学校登录及二次验证由本人在浏览器完成。浏览器兼容设置随机构下载扩展安装，在新电脑上同样生效。
+
+等待用户操作：停在学校登录页（以及没配置学校时的选校页）每篇最多 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`，用来看它在等哪个浏览器调用；进程不会因此退出。
 
@@ -53,6 +55,8 @@ paper-search-carsi publisher-check --doi 10.1016/...
 
 ## 三级结构
 
+目录保留两层外壳：`carsi/` 是后端构建根（安装声明、测试和工具），`paper_search_carsi/` 是可导入、可安装的 Python 包。出版社各自保留独立文件夹，便于增加网站类型和专有规则；不因暂时只有一个 `__init__.py` 就改成单文件。目录是否精简按实际职责和明确扩展用途判断，核对记录见 `目录层级核对`。
+
 ```text
 paper_search_carsi/
 ├── publishers/      tier 1  声明式出版社规则：builtin/*.json + schema.json + 用户 publisher_profiles_file
@@ -72,4 +76,6 @@ paper_search_carsi/
 | tier 2 `adapters/<name>/` | Python，`PublisherAdapter` 子类 | 离线夹具测试；`publisher-check` 报告贴在 PR |
 | tier 3 `engine/` | 熟悉学校认证流程 | 维护者审核 |
 
-详见 CONTRIBUTING.md。
+详见 CONTRIBUTING.md。后端在契约之外的行为（浏览器预览、出版社规则扩展文件）见仓库的 `docs/dependencies/carsi-backend-notes.zh.md`。当前模块职责见同一后端说明中的“浏览器内部模块边界”。
+
+PaperSearch 调用后端时可以传入独立的 `diagnostics_dir`：浏览器记录、截图和附件清单放在该目录；正文及 `supplements/` 附件仍写入 `output_dir`。期刊、年份、标题命名由 CLI 的统一输出模块完成。

package/carsi/paper_search_carsi/__init__.py

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

package/carsi/paper_search_carsi/adapters/__init__.py

@@ -19,7 +19,7 @@ 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,
+    acm, acs, aha_journals, ams, annual_reviews, aps, asce, bmj, copernicus, dovepress, elsevier, frontiers, ieee, iop,
     jama, karger, lww, mdpi, nejm, neurology, optica, oup, plos, pnas, rsc, sage, science, springer,
     taylor_francis, thieme, wiley, world_scientific)
 

package/carsi/paper_search_carsi/adapters/base.py

@@ -14,6 +14,8 @@ class SupplementLink:
 
     url: str
     label: str = ""
+    # Discovery failures are recorded alongside downloaded files.
+    error: str = ""
 
 
 class PublisherAdapter:

package/carsi/paper_search_carsi/adapters/frontiers/__init__.py

@@ -0,0 +1,45 @@
+"""Frontiers supplementary files on the article's own download panel."""
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import unquote, urlparse
+
+from ..base import PublisherAdapter, SupplementLink, register
+
+_SUPPLEMENT_ROWS_JS = """() => ({
+    doi: document.querySelector('meta[name="citation_doi"]')?.content || '',
+    rows: [...document.querySelectorAll('#supplementaryMaterial a[href], #supplementary-material a[href]')].map(a => ({
+        href: a.href,
+        label: (a.closest('li')?.innerText || a.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 240)
+    }))
+})"""
+
+
+def supplement_links_from_page(data: Any, doi: str) -> list[SupplementLink]:
+    """The panel, citation DOI and file's article ID must all agree."""
+    article = re.fullmatch(r"10\.3389/[a-z0-9]+\.\d{4}\.(\d+)", doi, re.I)
+    if (not article or not isinstance(data, dict)
+            or str(data.get("doi", "")).strip().lower() != doi.lower()):
+        return []
+    article_id = article.group(1)
+    links: list[SupplementLink] = []
+    seen: set[str] = set()
+    for row in data.get("rows", []):
+        target = urlparse(str(row.get("href") or ""))
+        url = target._replace(fragment="").geturl()
+        if (target.scheme == "https"
+                and re.fullmatch(r"public-pages-files(?:-\d{4})?\.frontiersin\.org", target.hostname or "")
+                and unquote(target.path).startswith(f"/articles/{article_id}/file/")
+                and url not in seen):
+            seen.add(url)
+            links.append(SupplementLink(url, str(row.get("label") or "")))
+    return links
+
+
+@register
+class FrontiersAdapter(PublisherAdapter):
+    publisher = "frontiers"
+
+    def supplement_links(self, page: Any, doi: str) -> list[SupplementLink]:
+        return supplement_links_from_page(page.evaluate(_SUPPLEMENT_ROWS_JS), doi)

package/carsi/paper_search_carsi/adapters/mdpi/__init__.py

@@ -5,8 +5,37 @@ from the DOI for the journals whose codes are known.
 """
 from __future__ import annotations
 
+import re
+from typing import Any
+from urllib.parse import unquote, urlparse
+
 from ...engine.router import _append_mdpi_candidates
-from ..base import PublisherAdapter, register
+from ..base import PublisherAdapter, SupplementLink, register
+
+_SUPPLEMENT_ROWS_JS = """() => ({
+    doi: document.querySelector('meta[name="citation_doi"]')?.content || '',
+    rows: [...document.querySelectorAll('a[href]')].map(a => ({
+        href: a.href,
+        label: (a.closest('.html-p')?.innerText || a.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 240)
+    }))
+})"""
+
+
+def supplement_links_from_page(data: Any, doi: str) -> list[SupplementLink]:
+    """MDPI's DOI-bound /sN links redirect to the original supporting files."""
+    if not isinstance(data, dict) or str(data.get("doi", "")).strip().lower() != doi.lower():
+        return []
+    pattern = re.compile(r"/article/" + re.escape(doi) + r"/s[1-9][0-9]*", re.I)
+    links: list[SupplementLink] = []
+    seen: set[str] = set()
+    for row in data.get("rows", []):
+        target = urlparse(str(row.get("href") or ""))
+        url = target._replace(fragment="").geturl()
+        if (target.scheme == "https" and target.hostname in {"www.mdpi.com", "mdpi.com"}
+                and pattern.fullmatch(unquote(target.path)) and url not in seen):
+            seen.add(url)
+            links.append(SupplementLink(url, str(row.get("label") or "")))
+    return links
 
 
 @register
@@ -18,3 +47,6 @@ class MDPIAdapter(PublisherAdapter):
         urls: list[str] = []
         _append_mdpi_candidates(urls, doi, source_url)
         return urls
+
+    def supplement_links(self, page: Any, doi: str) -> list[SupplementLink]:
+        return supplement_links_from_page(page.evaluate(_SUPPLEMENT_ROWS_JS), doi)