为什么选择这个 Skill
一个确定性的、仅合法的 "帮我找 PDF" 替代方案。
5 源回退链
Unpaywall → Semantic Scholar → arXiv → PubMed Central → bioRxiv/medRxiv。命中即停，都失败时输出元数据提示走馆际互借。
全学科支持
不只是生命科学或计算机。Unpaywall + Semantic Scholar 覆盖人文、社科、化学、物理、经济 —— 任何 Crossref DOI。
始终合法
绝不使用 Sci-Hub 或任何付费墙绕过服务。没有 OA 版本时如实报告失败，返回标题 + 作者信息便于发起 ILL 请求。
零依赖
纯 Python 3.8+ 标准库。无需 pip install，无需虚拟环境，无需 Node.js —— clone 下来就能跑。
批量模式
通过 --batch dois.txt 传入 DOI 列表。自动命名为 作者_年份_标题.pdf，便于文献库统一管理。
Agent 原生输出
stdout 输出稳定的 JSON 信封，stderr 输出 NDJSON 进度事件，退出码分类（0/1/3/4），提供机器可读的 schema 子命令，批量部分失败时返回带 next 重试提示的 ok: "partial" 信封，--idempotency-key 支持幂等重试。Agent-native CLI rubric 得分 28/28。
DOI 解析流程
按顺序尝试每个来源，第一个返回有效 PDF 的源即停止。
Unpaywall
查询 api.unpaywall.org/v2/{doi}，读取 best_oa_location.url_for_pdf。覆盖所有出版社在机构知识库中的 OA 版本。需要 UNPAYWALL_EMAIL（可选，未设置时跳过）。
Semantic Scholar
查询 api.semanticscholar.org/graph/v1/paper/DOI:{doi}，读取 openAccessPdf 字段和 externalIds（arXiv、PMC）。跨领域学术图谱。
arXiv
若论文有 arXiv ID，从 arxiv.org/pdf/{arxiv_id}.pdf 下载。覆盖物理、数学、CS、统计、定量金融、经济和电气工程。
PubMed Central OA
若论文有 PMCID，从 ncbi.nlm.nih.gov/pmc/articles/{pmcid}/pdf/ 下载。仅生物医学 OA 子集。
bioRxiv / medRxiv
若 DOI 前缀为 10.1101，查询 api.biorxiv.org/details/{server}/{doi} 获取最新版本的 PDF URL。生物和医学预印本。
学科覆盖
适用于所有学科，不只是生命科学或计算机。能否拿到取决于 OA 可用性，而非学科本身。
| 来源 | 学科范围 |
|---|---|
| Unpaywall | 全学科 —— 覆盖每一个 Crossref DOI（人文、社科、物理、化学、经济……） |
| Semantic Scholar | 全学科 —— 跨领域学术图谱 |
| arXiv | 物理、数学、CS、统计、定量金融、经济学、电气工程 |
| PubMed Central | 仅生物医学 |
| bioRxiv / medRxiv | 仅生物 / 医学预印本 |
实际使用中，仅 Unpaywall + Semantic Scholar 两个源就足以覆盖化学、材料、经济、心理学、人文社科等任何领域的 OA 论文 —— 它们会自动命中机构知识库、SSRN、RePEc 以及出版商自托管的 OA 版本。arXiv/PMC/bioRxiv 只是针对各自领域的额外回退。若论文确实没有任何合法 OA 版本，skill 会如实报告失败 —— 按设计绝不绕过付费墙，任何学科都一视同仁。
对比原生智能体
使用本 skill 与直接让 LLM "找这篇 PDF" 的区别。
| 功能 | 原生智能体 | 本 Skill |
|---|---|---|
| DOI 解析策略 | 临时网络搜索 | ✓ 确定性 5 源链 |
| Unpaywall 集成 | ✗ | ✓ OA 命中率最高 |
| arXiv / PMC / bioRxiv 回退 | 手动 | ✓ 自动 |
| 批量下载 | ✗ | ✓ --batch dois.txt 或 --batch -（stdin） |
| 统一文件命名 | ✗ | ✓ author_year_title.pdf |
| Agent 原生 JSON 输出 | ✗ | ✓ 稳定信封 + stderr NDJSON 进度 |
| 机器可读 schema | ✗ | ✓ fetch.py schema |
| 幂等重试 | ✗ | ✓ --idempotency-key 复用原信封 |
| 退出码分类 | ✗ | ✓ 0/1/3/4 确定性路由失败 |
| 预览模式 | ✗ | ✓ --dry-run 解析不下载 |
| 域名白名单安全 | ✗ | ✓ 仅限已知 OA 域名 |
| 50 MB 大小限制 | ✗ | ✓ 防止异常大文件 |
| PDF 头校验 | ✗ | ✓ 拒绝 HTML 落地页 |
| 合法来源保证 | 无 | ✓ 硬性拒绝付费墙绕过 |
| 依赖 | 各异 | ✓ 仅 Python 标准库 |
| 跨学科支持 | 不确定 | ✓ 任何领域 |
安装
选择你的平台，10 秒搞定。无需 pip install。
# 全局安装（所有项目可用） git clone https://github.com/Agents365-ai/paper-fetch.git ~/.claude/skills/paper-fetch # 项目级安装 git clone https://github.com/Agents365-ai/paper-fetch.git .claude/skills/paper-fetch # 可选：设置 Unpaywall 联系邮箱以获得最高命中率 export UNPAYWALL_EMAIL=you@example.com
# 通过 ClawHub 安装 clawhub install paper-fetch # 手动安装 git clone https://github.com/Agents365-ai/paper-fetch.git ~/.openclaw/skills/paper-fetch
# 用户级安装 git clone https://github.com/Agents365-ai/paper-fetch.git ~/.pimo/skills/paper-fetch
# 用户级安装 git clone https://github.com/Agents365-ai/paper-fetch.git ~/.agents/skills/paper-fetch # 项目级安装 git clone https://github.com/Agents365-ai/paper-fetch.git .agents/skills/paper-fetch
# 安装到 research 分类
git clone https://github.com/Agents365-ai/paper-fetch.git ~/.hermes/skills/research/paper-fetch
# 或在 ~/.hermes/config.yaml 中配置
skills:
external_dirs:
- ~/myskills/paper-fetch
# 通过 SkillsMP CLI skills install paper-fetch
使用
直接命令行调用，或用自然语言让 agent 执行。
# 单个 DOI（自动识别 TTY：管道时 JSON，终端时文本）
python scripts/fetch.py 10.1038/s41586-020-2649-2
# 强制人类可读格式
python scripts/fetch.py 10.1038/s41586-020-2649-2 --format text
# 预览模式 —— 只解析不下载
python scripts/fetch.py 10.1038/s41586-020-2649-2 --dry-run
# 批量模式 —— 每行一个 DOI
python scripts/fetch.py --batch dois.txt --out ~/papers
# 从管道读入 DOI
echo 10.1038/s41586-021-03819-2 | python scripts/fetch.py --batch -
# 可安全重试的批量下载（重试时复用原信封，零网络 I/O）
python scripts/fetch.py --batch dois.txt --out ~/papers \
--idempotency-key monday-review-batch
# Agent 发现 —— 机器可读的 CLI schema
python scripts/fetch.py schema --pretty
或者直接对 agent 说： "帮我把 AlphaFold2 那篇论文下到 ~/papers。"