nature-downloader

Nature 文献下载器

此技能通过合法的开放获取、出版商 API、CNKI 机构访问以及基于浏览器的机构访问提供商来路由文献。scripts/batch_download.mjs 是编排入口点；学校配置、出版商标凭据、元数据/OA 解析、提供商下载、内容校验和清单均为独立模块。

已验证的路由是示例，而非默认值。每个机构都应从用户实际的图书馆资源 URL 开始，因为资源门户、CAS 回调、EZproxy、WebVPN、IP 认证的数据库页面以及数据库详情页比学校名称更能可靠地揭示实时授权路径。

SI 确认关卡 —— 请先执行此操作。 在下载任何 PDF、CAJ、HTML、XML、压缩包或附件之前，询问用户是否需要 Supporting Information。明确要求 SI 视为需要；明确仅要求正文视为不需要。否则针对整个批次询问一次。使用 --si 或 --no-si 中的恰好一个运行下载器。若两者均未提供，脚本将返回 si_confirmation_required 并且不会创建输出目录。

主工作流。 在路由之前，先规范化 DOI/标题并识别语言和出版商。中文文献始终使用 CNKI。对于具有可用提供商标凭据的英文 Elsevier、Springer Nature 和 IEEE 文章，先尝试出版商 API，API 下载成功后无需再进行 OA 判定。若该 API 尝试失败，则自动检查合法的 OA 来源。其他英文出版商先检查 OA，当 OA 不可用时再使用机构 Web Access 路由。

规范化 DOI/题名并识别语言、出版商
├─ 中文文献：直接走 CNKI
└─ 英文文献
   ├─ Elsevier / Springer Nature / IEEE，且已配置有效 Key
   │  ├─ 优先通过出版商 API 下载
   │  ├─ API 下载成功：结束，不强制判断 OA
   │  └─ API 下载失败：检查文章级 OA，再走 PMC / Unpaywall / 合法仓储
   └─ 其他出版商
      ├─ 检查文章级 OA
      └─ OA 不可用：走 Web Access 机构授权

中文文献仅限 CNKI。 中文标题、zh 元数据语言、明确的 CNKI 源 URL 或 --route cnki 必须使用 CNKI，即使看似存在其他 OA 副本。复用用户当前 Chrome 的图书馆/CNKI 登录状态，并优先使用已配置的 discovery.cnki_url。切勿导出 Cookie 或收集机构密码。

出版商 API 回退。 有效的 API 密钥并不保证全文权限。当 Elsevier、Springer Nature 或 IEEE 的 API 尝试返回无权限或无可用全文时，先自动尝试合法的 OA 来源。只有在出版商 API 和 OA 路由均失败后，返回 api_fallback_confirmation_required 并询问一次是否使用 Web Access。不要自动切换到机构 Web Access。

浏览器状态原则。 授权下载依赖于用户已登录的确切浏览器配置文件。如果代理、CDP 会话或浏览器自动化工具打开了全新的配置文件或没有登录状态的其他浏览器，请不要将失败视为缺少图书馆权限。切换到复用用户活动浏览器会话的受控路径，或要求用户在受控浏览器实例中进行认证。

格式原则。 PDF、HTML 全文以及 CAJ 等数据库原生格式是不同的交付物。如果用户仅要求 PDF，则要求真实的 PDF 链接或 %PDF 响应，并在不存在时报告 no_authorized_pdf_found / pdf_fetch_failed。不要将 CAJ、HTML 或登录页面保存为 PDF。

下载受理与首次运行配置

对于每个下载请求，首先确定论文列表并询问：

是否同时下载这些文献的 Supporting Information（SI，补充材料）？

仅在需要识别所请求的论文时才在此问题之前进行元数据查找。在答案已知之前不要下载文件。仅当所选路由为 CNKI 或 Web Access 时配置图书馆。仅当所选英文文章属于 Elsevier、Springer Nature 或 IEEE 时配置出版商 API；在尝试已配置的提供商 API 之前无需进行 OA 判定。

付费图书馆资源配置

询问用户实际使用的图书馆资源 URL：

请发你平时进入图书馆电子资源/数据库的平台链接。
可以是资源门户、数据库列表、Web of Science 入口、某个数据库详情页，
或跳转到统一身份认证的登录链接。

然后在保存配置前，根据 URL 推断授权途径：

python3 scripts/configure_school.py infer "https://example.edu/library/resources"
python3 scripts/configure_school.py url "https://example.edu/library/resources"
python3 scripts/configure_school.py show
python3 scripts/configure_school.py health --force

分发的技能不包含学校预设。如果用户无法提供资源 URL，请让他们查找所在机构的图书馆／数据库入口，而不要猜测特定学校的域名。

默认配置路径为：

~/.config/lit-dl/school.json

对于测试或隔离的配置档，请设置：

LIT_DL_CONFIG_DIR=/path/to/configdir

下载器会自动读取此配置。如果存在 discovery.web_of_science_url，scripts/batch_download.mjs 会将其用作 Web of Science 入口；否则会回退到 https://www.webofscience.com/wos/woscc/basic-search。

对于中文文献，如果存在 discovery.cnki_url，下载器也会读取该配置。如果不存在，scripts/batch_download.mjs --title "<中文题名>" 会回退到 https://kns.cnki.net/kns8s/defaultresult/index。

优先使用 API 和开放获取回退方案

对于英文文章，请先确认其出版商，再决定何时解析文章级别的 OA：

1. 收集 DOI、PMID、准确标题、文章 URL 或明确的论文列表，然后规范化其元数据和出版商信息。

2. 如果文章属于 Elsevier、Springer Nature 或 IEEE，且已配置可用的服务商凭据，则优先尝试该出版商的 API。成功后，记录 accessMode: publisher_api 和 oa_status: not_checked_api_first；不要仅为了给文章标注而运行 OA 解析。

3. 如果出版商 API 失败，则自动搜索 PMC、Unpaywall、出版商 OA 页面、arXiv 及其他合法存储库或明确开放的 PDF URL 等合法 OA 来源。在清单中保留失败的 API 尝试记录。

4. 对于其他所有英文出版商，在使用 Web Access 前，先搜索这些合法 OA 来源。

5. 对于准确标题或明确要求仅限 OA 的请求，优先使用：

   node scripts/batch_download.mjs --title "<exact title>" --open-access --no-si --out "<project>"
   

   用户提供已知的合法 OA PDF URL 时，使用 --pdf-url。

6. 验证下载的文件并记录来源。将成功获取的 PDF 标记为 open_access_downloaded。

7. 如果未找到合法的 OA 全文，则标记为 oa_not_found。对于 API 已失败的受支持出版商，请在使用 Web Access 前征求确认。对于其他出版商，则继续使用 Web Access。如果明确请求了 --route open_access，则在得出 OA 结果后停止。

出版商 API 凭据

仅在路由首次需要凭据时再配置：

python3 scripts/configure_credentials.py set elsevier
python3 scripts/configure_credentials.py set springer_nature --service openaccess
python3 scripts/configure_credentials.py set springer_nature --service fulltext
python3 scripts/configure_credentials.py set springer_nature --service metadata
python3 scripts/configure_credentials.py set ieee --fulltext-endpoint 'https://issued-endpoint.example/articles/{doi}'
python3 scripts/configure_credentials.py set elsevier --stdin
python3 scripts/configure_credentials.py show
python3 scripts/configure_credentials.py validate <provider>
python3 scripts/configure_credentials.py validate springer_nature --service openaccess
python3 scripts/configure_credentials.py validate springer_nature --service fulltext
python3 scripts/configure_credentials.py validate springer_nature --service metadata
python3 scripts/configure_credentials.py delete <provider>
python3 scripts/configure_credentials.py contact-email [email protected]

向用户提供官方注册链接：Elsevier：https://dev.elsevier.com/，Springer Nature：https://dev.springernature.com/docs/quick-start/api-access/，或 IEEE：https://developer.ieee.org/member/register。

Springer 凭据按服务划分：metadata_api_key 会对 /meta/v2/json 进行验证，且无法启用下载；openaccess_api_key 使用 /openaccess/jats；fulltext_api_key 则需在 Full Text 协议下使用 /xmldata/jats。仅配置用户已启用的服务。如果帐户授予了相应服务权限，可明确将同一个密钥用于多个服务；不要假设密钥是共用的或彼此独立的。对于 Full Text，按帐户要求在隐藏提示词中或通过 --stdin 输入完整的已签发 KEY/METRIC 值。设置一个 Springer 服务不会影响其他服务。为保持兼容，旧版 api_key（包括不带 --service 的 set springer_nature）仍是 Full Text 凭据，绝不能推断为 Meta 或 OA 凭据。

Springer 下载会先尝试已配置的 Full Text 服务，失败后再尝试已配置的 OA 服务。仅有 OA 凭据时，会直接使用 OA 服务。仅有 Meta 凭据不符合优先通过 API 下载的条件。两种全文服务都会保留内容验证，并确保来源 URL 不含密钥。如果这些服务失败，则继续使用现有的通用 OA 和已确认的 Web Access 回退方案。验证默认使用 Full Text 服务；--service metadata 和 --service openaccess 只会探测所选服务及凭据。验证会检查 HTTP 响应，但不会确认文章访问权限。Meta 验证无法证明具有 OA 或 Full Text 访问权限；即使全文服务探测成功，也无法保证能访问某篇特定文章。官方服务参考：Meta、OA、Full Text。

不要主动要求用户将 API 密钥粘贴到聊天中。如果用户主动发送了出版商 API 密钥，应视为用户授权保存该密钥原文：不要拒绝、要求用户重新生成或将密钥复述给用户。将密钥传递给 configure_credentials.py set <provider> --stdin，避免将其放入命令行参数、日志、回复和清单中，然后只报告掩码后的确认信息和验证状态。如果用户尚未提供密钥，仍优先使用本地隐藏提示词。IEEE Metadata API 访问不等同于付费全文访问；只有在取得 Full-Text Access 端点／模板后，才能将 IEEE 视为可通过 API 下载。密钥存储在 ~/.config/lit-dl/credentials.json 中，文件权限为 0600。

资源 URL 分类

选择访问方式前，先对用户提供的 URL 进行分类：

cas.* / /authserver/login        CAS / SSO login page; inspect service= callback, then return to the service portal
idp/shibboleth / carsi           CARSI / Shibboleth institutional route
ezproxy / libproxy               EZproxy remote-access proxy
webvpn / vpn                     WebVPN route
metaersp / metaauth / uas        Library resource aggregation portal
webofscience / sciencedirect     Database or publisher entry; check whether it was reached through a portal

如果 URL 是带有 service= 参数的登录页面，应将回调主机视为资源服务，不要让登录页面成为整个工作流的终点。例如，https://login.university.example/authserver/login?service=https://resources.university.example/callback 表示身份服务会在身份验证后将用户带回其资源门户。

机构专属域名

根据用户地址栏中实际显示的内容进行确认；对各机构的相关信息进行修正，不要假设预设配置已涵盖所有情况。

Library home / aggregation:  library.example.edu, resources.example.edu
Discovery/database entry:    webofscience.com, clarivate.com, cnki.net, sciencedirect.com, provider.example.com
Unified identity / SSO:      sso.example.edu, cas.example.edu, idp.example.edu
Federation / WAYF:           ds.carsi.edu.cn, wayf.example.org, shibboleth/openathens hosts
Proxy / WebVPN:              ezproxy.example.edu, webvpn.example.edu

将已配置的机构登录、联合身份认证、代理和数据库登录主机视为登录流程中的阶段。不要将访问这些主机视为最终失败。

边界

仅使用用户合法的机构访问权限。不要绕过付费墙、DRM 或双因素身份验证。

**先验证规则：**当用户已通过身份验证的 Chrome 会话中出现可见的滑块、复选框、机器人验证或简单验证控件时，先在浏览器中尝试完成验证，再请用户介入。尝试次数应有限（同一标签页最多尝试两次），并确认验证挑战已消失；成功后继续在同一标签页中操作。

• 滑块/拖动挑战（包括 CNKI 拼图滑块）：估算可见的滑动距离，并模拟逐步拖动。
• ScienceDirect 机器人验证、受管理的 Turnstile 和 reCAPTCHA 复选框阶段：尝试勾选可见的复选框一次。
• 简单的 Continue、Verify 或同类可见控件：点击一次，然后重新检查页面状态。

**移交给用户：**仅在有限次数的尝试失败后，或页面需要输入秘密信息或可识别个人身份的信息（如图像选择答案、二维码确认、短信/OTP、通行密钥、硬件密钥或双因素身份验证）时，立即请用户介入。保持受挑战的标签页处于打开状态，绝不要让用户在聊天中粘贴凭据或验证码。

避免不受限制或不加区分地下载。只处理用户确认的明确论文清单，按照对服务提供方友好的节奏操作，并清楚记录下载了哪些内容、从哪里下载，以及是否找到了补充信息。

不要让用户在聊天或终端中粘贴机构密码、数据库密码、OTP 码、恢复码或会话令牌。如果用户主动提供此类可识别身份的秘密信息，应予以拒绝，并改用移交登录工作流。出版商 API 密钥遵循上述单独的收到后保存规则。

已保存的机构登录页面例外：如果用户明确表示浏览器已填入凭据，并授权点击可见的登录/确认按钮，Agent 可以在预期的机构 SSO / CAS / CARSI / Shibboleth 页面上点击该按钮一次，无需读取、复制或输入任何凭据。此例外不适用于 CAPTCHA、二维码登录、短信/OTP、出版商机器人验证、同意/安全警告，或预期机构登录流程以外的任何页面。

不要检查或导出 Cookie、密码、本地存储、浏览器配置文件或会话文件。仅使用浏览器中已通过身份验证的页面上下文。

前置条件

在尝试下载之前，确认适用于所选访问分支的条件。

对于仅 OA 分支，确认目标论文标识符/列表、输出文件夹、Node.js 22+，以及在 PDF 验证需要时的 Python 3。不要要求图书馆配置或机构浏览器登录。

对于付费图书馆分支，确认以下条件：

1. 保存用户图书馆/数据库登录状态的浏览器已在用户机器上打开。
2. 学校配置存在且有效。
   • 运行 python3 scripts/configure_school.py show。
   • 如果缺失，运行 python3 scripts/configure_school.py preset "<school name>" 或通过 src/wizard.py 引导用户。
3. 用户已在同一浏览器中亲自登录其机构/图书馆入口，并且可以访问图书馆聚合服务、目标数据库或发现入口。
4. 浏览器控制路径可以复用同一已登录的浏览器配置文件。
   • 对于 Chrome CDP，请用户打开 chrome://inspect/#remote-debugging 并为当前浏览器实例启用远程调试。
   • 如果 CDP 附加到过期的浏览器、临时配置文件或其他浏览器，请使用能够复用用户活动会话的浏览器控制通道，而不是启动新的配置文件。
5. 环境可以运行 Node.js 22+。
   • 尝试 node --version。
   • 如果 node 不在 Codex Desktop 的 PATH 中，尝试 %LOCALAPPDATA%\OpenAI\Codex\bin\node.exe。
6. 环境可以运行 Python 3 以进行配置和 PDF 文本验证。
   • 尝试 python3 --version。
   • 在需要时使用 pip install -r requirements.txt 安装 Python 辅助工具。
7. Web 访问 CDP 代理可用或可以启动。
   • 典型 Claude Code 路径：%USERPROFILE%\.claude\skills\web-access-main\scripts\check-deps.mjs。
   • 典型共享 Agent 路径：%USERPROFILE%\.agents\skills\web-access-main\scripts\check-deps.mjs。
   • 在仅 Codex 的设置中，还要检查 %USERPROFILE%\.codex\skills\web-access-main\scripts\check-deps.mjs。
8. 用户已批准目标输出文件夹。

如果 Claude Code 提示此技能未安装，请将其安装或复制到：

$env:USERPROFILE\.claude\skills\nature-downloader

Codex 和其他 Agent 设置可能改用 .codex\skills 或 .agents\skills；将这三个位置视为安装目标，而不是不同的技能版本。

批处理范围

支持确定的 DOI/标题/PMID 列表，没有固定的每批论文数量建议。

操作保障措施：

• 为每个提供商适当调整请求节奏，并在整个批处理过程中维护清单
• 首先尝试可见的验证控制；在最多两次失败尝试后、机构登录过期时，或出现异常/安全敏感的提示时停止

不要将宽泛的关键词搜索变成无限制的自动下载。不要下载整期期刊、卷或大型结果集。

状态分类

将每篇论文归入以下状态之一，并将状态保留在清单中：

downloaded
downloaded_with_si
open_access_downloaded
full_text_html_available
available_not_downloaded
native_fulltext_downloaded
si_confirmation_required
credentials_missing
credentials_invalid
api_not_entitled
api_fulltext_unavailable
api_fallback_confirmation_required
oa_not_found
oa_resolution_inconclusive
metadata_ambiguous
carsi_waiting_user
carsi_resolved_retry_needed
publisher_verification_waiting_user
sciencedirect_robot_check
retry_after_user_verification
verification_auto_passed
verification_auto_failed
do_not_auto_retry
url_needs_repair
library_no_permission
no_full_text_link
publisher_blocked_waiting_user
no_authorized_pdf_found
failed_after_retry

当技能成功通过自动 CAPTCHA/滑块/机器人检查，且随后下载正常进行时，使用 verification_auto_passed。

当尝试了自动验证但无法通过挑战时，使用 verification_auto_failed。这是需要用户接手的状态，而非最终失败。

仅当浏览器明显处于机构 SSO / CAS / CARSI-Shibboleth / OpenAthens / 数据库认证页面时，才使用 carsi_waiting_user。不要将此视为最终失败。

当出版商页面显示验证挑战但无法进行任何自动交互时，使用 publisher_verification_waiting_user 或 sciencedirect_robot_check。当进行了有界的自动尝试但失败时，改用 verification_auto_failed。这些都不是最终的下载失败。

当 PMC、出版商的 OA PDF、arXiv 或其他合法的开放 PDF 来源等正规开放获取途径在无需机构授权的情况下提供已下载的 PDF 时，使用 open_access_downloaded。

对于成功的 API 优先下载，记录 oa_status: not_checked_api_first；这意味着有意跳过了 OA 解析，而非该文章为非 OA。仅当受支持的出版商 API 尝试及其自动 OA 回退均失败后，才使用 api_fallback_confirmation_required。

当图书馆/全文解析器授予对可读 HTML 全文的访问权限，但没有可用的有效 PDF 链接或 %PDF 响应时，使用 full_text_html_available。这是成功的全文访问结果，而非 PDF 下载。如果用户需要该文章，请保存 HTML/文本，并明确告知用户通过当前授权途径无法获取 PDF。

当图书馆门户、SFX/OpenURL 解析器、数据库或出版商页面明确表示用户所属机构对该论文无全文权限时，使用 library_no_permission。明确告知用户当前图书馆资源没有此文章的权限。不要将直接访问出版商重试当作临时网络问题来处理。

启动浏览器控制

当 web-access CDP 代理能够连接到用户正在使用的同一已登录浏览器实例时，请使用它。如果任务依赖于现有登录状态，而 CDP 打开的是空白/新的配置文件，请优先选择复用用户当前浏览器会话的浏览器控制通道。

在 Windows PowerShell 上：

$node = "node"
if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
  $node = "$env:LOCALAPPDATA\OpenAI\Codex\bin\node.exe"
}
$checkDepsCandidates = @(
  "$env:USERPROFILE\.claude\skills\web-access-main\scripts\check-deps.mjs",
  "$env:USERPROFILE\.agents\skills\web-access-main\scripts\check-deps.mjs",
  "$env:USERPROFILE\.codex\skills\web-access-main\scripts\check-deps.mjs"
)
$checkDeps = $checkDepsCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if (-not $checkDeps) { throw "web-access-main/scripts/check-deps.mjs not found" }
& $node $checkDeps

然后测试：

Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:3456/targets" -TimeoutSec 10

如果此操作挂起或失败：

• 请用户确认远程调试复选框。
• 检查 %TEMP%\cdp-proxy.log。
• 如果出现目标但数据库/图书馆页面未认证，在怀疑缺少图书馆权限之前，先怀疑 CDP 端点过期、浏览器错误或浏览器配置文件是全新的。
• 不要尝试读取 Chrome 会话文件。

快速批处理路径（2 篇及以上论文的默认方式 — 快速且节省 token）

对于任何超过单篇论文的情况，请运行 scripts/batch_download.mjs，而不是逐步驱动浏览器。OA 和出版商 API 无需 CDP 即可运行；CNKI、Web Access 和请求的 SI 会按需附加到已认证的浏览器。大型 DOM 和文件字节始终保留在脚本内部。

该脚本会自动读取 ~/.config/lit-dl/school.json。当配置中包含 discovery.web_of_science_url 时，该 URL 将用作 Web of Science 入口；否则脚本会回退到其编译时的默认 Web of Science URL。

# by topic (collects N records from Web of Science Core Collection):
node scripts/batch_download.mjs --topic "rice blast resistance gene" --count 10 --no-si --out "<project>"
# by explicit DOIs:
node scripts/batch_download.mjs --dois "10.1007/s00122-021-03957-1,10.1111/pbi.14066" --no-si --out "<project>"
# by exact open-access title (arXiv fallback, useful for DOI-less papers):
node scripts/batch_download.mjs --title "Attention Is All You Need" --open-access --no-si --out "<project>"
# by Chinese exact title (default CNKI route):
node scripts/batch_download.mjs --title "乡村振兴背景下数字治理研究" --no-si --out "<project>"
# by Chinese exact title, PDF only:
node scripts/batch_download.mjs --title "乡村振兴背景下数字治理研究" --cnki-format pdf --no-si --out "<project>"
# by Chinese exact title with a library-provided CNKI entry:
node scripts/batch_download.mjs --title "乡村振兴背景下数字治理研究" --cnki-url "https://kns.cnki.net/kns8s/defaultresult/index" --no-si --out "<project>"
# by known PDF URL:
node scripts/batch_download.mjs --pdf-url "https://arxiv.org/pdf/1706.03762" --title "Attention Is All You Need" --no-si --out "<project>"
# replace --no-si with --si only after the user explicitly requests SI

输出包含 { summary, manifest, results }。脚本会写入 <project>/manifest.json，其中包含路由、OA 证据、访问模式、格式、MIME、字节数、SHA-256、SI 选择以及类型化失败；疑似机密的字段会被递归移除。PDF 存放在 PDFs/ 下，原生 HTML/XML 存放在 FullText/ 下，CAJ 存放在 CNKI/ 下，补充材料存放在 SupportingInformation/ 下。

Token 纪律（适用于所有路径）： 绝不要将整个页面 DOM、搜索结果或 PDF/SI 字节 eval 回 Agent 上下文。将大型数据保留在 Node/scripts/*.mjs 内部，只暴露紧凑的状态信息。交互式 /eval + cdp_open_url.mjs 仅保留用于下面的单篇论文路径，或在批处理运行后诊断某篇卡住的论文。

高级浏览器与交付路径

保持此路由紧凑，仅在其条件适用时才加载详细的操作参考：

• 当合法的 OA 和适用的出版商 API 路径已穷尽，且任务需要 Web of Science、机构授权的浏览器会话、出版商验证、身份验证交接或浏览器上下文 PDF 传输时，加载 references/institutional-browser-workflow.md。
• 当用户请求补充材料、下载的文件需要最终验证和命名，或访问尝试达到类型化失败或重试状态时，加载 references/delivery-verification-and-failures.md。

当加载任一参考时，此路由中的边界、SI 确认门、浏览器状态原则、状态语义和 token 纪律仍然具有强制性。不要将参考视为绕过访问控制或暴露凭据、cookie 或会话数据的许可。