| name | paper-download |
| description | Use when the user asks to "download a paper", "find a paper",
"get PDF for DOI", "下载论文", "找论文", "知网下载",
or mentions academic paper retrieval needs.
|
| version | 1.0.0 |
| user-invocable | true |
| allowed-tools | Bash, Read, Write, WebFetch |
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。
核心原则
- 检索和下载分离 — 用户说"找/搜/检索"→ 只做阶段一；用户说"下载/下/get PDF"→ 做阶段一+二。不要自作主张进入下载阶段
- 检索不回退 — 阶段一只用 CNKI 和 Google Scholar，遇到验证码让用户手动解决后继续，不要因为验证码就放弃该站点转用其他检索方式（如 OpenAlex、CrossRef 等不是检索工具）
- 确保论文匹配 — 跨源下载必须校验：DOI 精确匹配 > 标题相似度 ≥ 0.4 > 弃用。永远不要无校验取 CrossRef top-1
- 永远不主动付费 — 不点击任何付费按钮
- 逐级升级 — 能用 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 次以上 → 停止让用户解，建议换代理节点。
