kanlac/paper-download

Paper Download Skill

学术论文检索与下载。检索和下载是两个独立阶段，用户没有明确要求下载时只做检索。

Browser Capability (Soft Dependency)

paper-download 不硬依赖 cdp-chrome 插件。Tier 1 HTTP/API 与大部分 Tier 2 headless 流程可以独立运行；Google Scholar、CNKI、CAPTCHA/登录态下载等 Tier 3 场景只需要“可人工接管的有头浏览器能力”。

可用 provider 包括但不限于：

• 已安装 chrome 插件并配置好的 cdp-chrome / mcp__cdp-chrome__* 工具；
• Codex 环境中的 Chrome/browser plugin；
• 当前 agent 原生 browser-use / headed browser 工具，前提是能保留登录态并允许用户手动完成 CAPTCHA。

开始检索前先检查当前会话是否已有可用 headed browser provider。只有在没有等价 provider 时，才建议用户安装/启用 chrome 并配置 cdp-chrome。

核心原则

1. 检索和下载分离 — 用户说"找/搜/检索"→ 只做阶段一；用户说"下载/下/get PDF"→ 做阶段一+二。不要自作主张进入下载阶段
2. 检索不回退 — 阶段一只用 CNKI 和 Google Scholar，遇到验证码让用户手动解决后继续，不要因为验证码就放弃该站点转用其他检索方式（如 OpenAlex、CrossRef 等不是检索工具）
3. 确保论文匹配 — 跨源下载必须校验：DOI 精确匹配 > 标题相似度 ≥ 0.4 > 弃用。永远不要无校验取 CrossRef top-1
4. 永远不主动付费 — 不点击任何付费按钮
5. 逐级升级 — 能用 HTTP 直链就不走浏览器

用户配置

路径：macOS/Linux ~/.config/steroids.json，Windows %APPDATA%\steroids.json

{ "paper-download": { "cnki_auto_download": false } }

• cnki_auto_download: 允许使用知网已有额度自动下载（遇付费页仍停止）

---

三层执行环境

下载站点按执行环境分层。Agent 根据 Tier 选择调用方式，逐层升级（1→2→3），不跳级也不回退。

| Tier | 执行环境 | 适用场景 | 并行 | |---|---|---|---| | 1 | HTTP（curl / API） | URL 已知、无 JS 渲染、无反爬 | 可并行，同域名限速 | | 2 | Headless 浏览器 | 需 JS 渲染或轻度反爬，不需登录态 | subagent 各起实例并行 | | 3 | Headed browser provider（如 mcp__cdp-chrome__*、Codex Chrome plugin、原生 browser-use） | 需登录态 / 需用户解 CAPTCHA | 通常串行（同一有头会话），同站点批量复用会话。使用当前环境已有 provider；缺失时再建议安装 chrome |

---

站点速查表

主力站点

| 站点 | 阶段 | Tier | 用途 | 备注 | |------|------|:---:|------|------| | Google Scholar | 检索 | 3 | 国际论文检索，顺带给出 OA 直链 | 反爬严，遇验证码要手动 | | CNKI 知网 | 检索+下载 | 3 | 中文论文检索与下载 | 检索免费；下载需账号额度 | | arXiv | 下载 | 1 | CS/ML/物理/数学预印本 | arxiv.org/pdf/{id}.pdf；API 限速 1 req/3s | | Unpaywall API | 辅助 | — | 查 OA 状态 + 找 PDF 直链 | 免费无 key；区分 gold/hybrid/closed | | CrossRef API | 辅助 | — | 标题 → DOI 查询 | 免费无 key，毫秒级 |

补充站点

| 站点 | 阶段 | Tier | 用途 | 备注 | |------|------|:---:|------|------| | Sci-Hub | 下载 | 2 | ≤2021 年非 OA 论文 | ≥2022 直接跳过；镜像：se → st → ru | | Anna's Archive | 下载 | 2 | Sci-Hub 备选 | ≤2021；可达性不稳定 | | LibGen | 下载 | 2 | 同上，偏书籍 | 同 Sci-Hub 停更于 2021 | | PMC | 下载 | 1 | 生物医学 OA 论文 | CS 方向基本用不到 | | 期刊官网 | 下载 | 2-3 | OA 期刊 PDF | 轻防护 Tier 2；ScienceDirect 等重防护 Tier 3 | | OpenAlex | 辅助 | — | 元数据补全、批量 OA 查询 | 全文搜索噪声大，不做检索主源 |

---

阶段一：检索

检索只用 CNKI 和 Google Scholar，不用其他站点替代。遇到验证码是正常的，提示用户在 Chrome 中手动完成，等用户确认后继续——不要放弃该站点。

Google Scholar（国际论文）

<当前 headed browser provider> → https://scholar.google.com，填入关键词/标题。provider 可以是 cdp-chrome、Codex Chrome plugin 或当前 agent 的原生 browser-use；按当前环境的工具名执行同等动作。 反爬较严，遇验证码提示用户手动完成，等用户确认后继续检索。同一会话内 reCAPTCHA 触发 3 次以上，说明代理节点 IP 信用低——停止让用户解，建议换节点/区域后重试。右侧 [PDF] 标记即 OA 直链，记录备用。

CNKI（中文论文）

详细操作流程见 references/cnki-workflow.md。 使用高级检索 https://kns.cnki.net/kns8s/AdvSearch，支持来源过滤（CSSCI/核心期刊）、多字段组合、框内运算符。 搜索、摘要、关键词、作者等元数据无需登录即可获取（共享 Chrome profile 自带 cookie，通常不会触发验证码）。检索阶段不需要确保已登录。

遇到安全验证/滑块验证码时：提示用户在 Chrome 窗口中手动完成，等用户确认后继续。这是知网的正常行为，不是错误，不要因此放弃知网。

结果输出

检索完成后必须生成一个 Excel 文件（.xlsx），不论结果数量多少。字段：

| 列 | 说明 | |---|---| | 标题 | 论文标题 | | 作者 | 第一作者 + et al. | | 期刊/会议 | 发表来源 | | 年份 | 发表年份 | | DOI | 如有 | | OA 状态 | Open Access / Closed / 未知 | | 链接 | 论文详情页 URL（知网/Scholar） | | PDF 直链 | 检索阶段发现的 OA 直链（如有） | | 摘要 | 如已获取 |

生成后告知用户文件路径，并在终端简要列出前几条结果。检索到此为止——不要自动进入下载阶段，除非用户明确要求了下载。

---

阶段二：下载（仅在用户明确要求时执行）

输出目录

每次下载创建独立批次目录：batch_<主题>_<YYYY-MM-DD>/，内含 pdfs/（交付物）和 _workspace/（中间脚本、日志、快照）。报告 xlsx 放批次目录顶层。

OA 分流（下载前必做）

下载前先用 Unpaywall 批量查有 DOI 论文的 OA 状态，按结果预分流到对应 Tier，避免盲试：

• OA 有直链（gold/green）→ Tier 1
• 非 OA + CS/物理/数学 → 先用 arXiv API 查预印本（标题/DOI 反查，相似度 ≥ 0.4），命中则 Tier 1
• 非 OA + ≤2021 → Tier 2（Sci-Hub）
• 非 OA + ≥2022 → 跳过 Sci-Hub/LibGen/Anna's Archive（已停更），直接标记「需付费」

预分流后，Tier 1 先批量处理，失败的降级到 Tier 2，仍失败的降级到 Tier 3。

Tier 1: HTTP 直链（curl / API，可并行）

• arXiv: https://arxiv.org/pdf/{id}.pdf（并发加 3s delay）
• Scholar OA 直链（检索阶段已获取）
• Unpaywall OA 直链: GET https://api.unpaywall.org/v2/{doi}?email={user_email} → best_oa_location.url_for_pdf
• PMC: ncbi.nlm.nih.gov/pmc/articles/{pmcid}/pdf/（生物医学）

下载：curl -L -C - --retry 3 -o "{path}" "{url}" 命名：作者_短标题_年份.pdf 校验：文件前 4 字节为 %PDF 且 ≥ 50KB。低于此阈值视为失败（stub 文件、HTML 伪装、登录页 PDF 化均低于 50KB，真实学术 PDF 最小也有数百 KB）

Tier 2: Headless 解析（需 JS 渲染，不需登录）

• Sci-Hub（≤2021 年才尝试，≥2022 直接跳过）: 镜像 sci-hub.se/{doi} → .st → .ru，PDF 在 <iframe>/<embed> src
• 出版商页面（轻度反爬）: 解析 DOI 重定向 → 找 PDF 直链
• Anna's Archive / LibGen（≤2021，可达性不稳定）

没有 DOI 时先用 CrossRef API 查询：GET https://api.crossref.org/works?query.title={title}&rows=3（取结果前必须做标题相似度校验）

Tier 3: Headed browser provider（需登录态 / CAPTCHA，串行）

同站点批量处理：解一次 CAPTCHA 后立即顺序处理同站点其他论文，复用会话（约 30 分钟有效）。

• 期刊官网重防护（ScienceDirect 多层 Cloudflare、Sage 等）
• CNKI 下载（需 cnki_auto_download: true + 已登录）：下载前必须告知用户篇数并确认，会消耗账号额度。详见 references/cnki-workflow.md。跳转到付费页则立即停止

下载结果标记

完成后更新 Excel 中的下载状态列。

| 状态 | 含义 | |------|------| | ✓ 已下载 | PDF 已保存，标注本地文件名 | | ✗ 需付费 | 附论文页链接 | | ✗ 需手动 | 验证码等需人工 | | ✗ 未找到 | 所有渠道均失败 |

---

Error Escalation

所有无法解决的问题立即用中文告知用户，不静默重试超过一次，不在验证码上循环。 知网遇滑块验证码 → 提示用户在 Chrome 中手动完成；登录失效 → 提示重新登录。 Google Scholar reCAPTCHA 3 次以上 → 停止让用户解，建议换代理节点。