fetch-paper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fetch Paper

获取论文

Resolves one DOI or arXiv ID to a legal open-access copy (PDF URL, arXiv HTML rendering, landing page) and optionally downloads it for transient reading. This is the fetch layer that

find-papers

literature-review

study-exemplars

, and

draft-related-work

build on.

将单个DOI或arXiv ID解析为合法的开放获取版本（PDF链接、arXiv HTML渲染页面、着陆页），并可选择下载以供临时阅读。这是

find-papers

、

literature-review

、

study-exemplars

和

draft-related-work

等工具所依赖的获取层。

When to use

使用场景

The user has a DOI, doi.org URL, arXiv ID, or arxiv.org URL and wants the paper.
Another skill needs full text for a paper it found (lit review, exemplar study).
The user asks "is there an open-access version of this paper?"
NOT for topic/title/venue search — run
```
find-papers
```
first to get the identifier.

用户拥有DOI、doi.org链接、arXiv ID或arxiv.org链接，并想要获取对应论文。
其他工具需要为已找到的论文获取全文（如文献综述、范例研究）。
用户询问“这篇论文有没有开放获取版本？”
不适用于主题/标题/会议搜索——请先运行
```
find-papers
```
获取标识符。

Inputs

输入参数

Exactly one identifier per fetch: a DOI (
```
10.1145/3589132.3625571
```
,
```
https://doi.org/...
```
) or an arXiv ID (
```
2403.12345
```
,
```
arXiv:2403.12345v2
```
,
```
cs/0309136
```
, or any arxiv.org URL). arXiv-issued DOIs (
```
10.48550/arXiv.*
```
) are auto-converted.
```
UNPAYWALL_EMAIL
```
(or
```
CONTACT_EMAIL
```
) env var — a real address; Unpaywall rejects placeholders with HTTP 422. The script prompts if unset.

每次获取仅支持一个标识符：可以是DOI（如
```
10.1145/3589132.3625571
```
、
```
https://doi.org/...
```
）或arXiv ID（如
```
2403.12345
```
、
```
arXiv:2403.12345v2
```
、
```
cs/0309136
```
，或任何arxiv.org链接）。arXiv颁发的DOI（
```
10.48550/arXiv.*
```
）会自动转换。
```
UNPAYWALL_EMAIL
```
（或
```
CONTACT_EMAIL
```
）环境变量——需为真实邮箱地址；Unpaywall会拒绝占位符并返回HTTP 422错误。若未设置，脚本会提示输入。

Process

操作流程

Resolve the identifier. Run:
```
python3 scripts/resolve_oa.py <DOI-or-arXiv-ID> --json
```
The script handles everything deterministic: identifier normalization, Unpaywall
```
best_oa_location
```
lookup, arXiv PDF/HTML URLs, the post-2026 ACM DL open-access fallback for
```
10.1145/*
```
DOIs, rate limiting, 429 backoff, and response caching under
```
.cache/fetch-paper/
```
. Never hand-roll these API calls.
Interpret the result (exit codes: 0 = OA found, 3 = no legal OA copy, 2 = bad input/config, 1 = network failure):
- Prefer
```
html_url
```
  (arXiv HTML) when present — easiest to read directly.
- Otherwise use
```
pdf_url
```
  . Read the meaning of
```
oa_status
```
  ,
```
version
```
  , and
```
license
```
  in references/oa-sources.md.
- ```
version: submittedVersion
```
  means a preprint — warn the user that the published version may differ before they quote or cite page numbers.
Fetch the full text transiently. Either read the URL directly, or:
```
python3 scripts/resolve_oa.py <ID> --download
```
which saves the PDF to a fresh temp directory (never the repo). Read it, extract what the task needs, then delete it.
```
dl.acm.org
```
blocks scripted downloads — give the user the URL to open in a browser instead.
If exit code is 3 (no legal OA copy): relay the script's suggestions — author homepages / institutional repositories (search via
```
find-papers
```
), arXiv by title, the user's library access, or emailing the authors. Never suggest Sci-Hub, LibGen, or any shadow library, and never try to bypass a paywall. Full rules: references/copyright-and-politeness.md.
Process, don't persist. Quote at most short excerpts in your analysis. Never write paper text, abstracts, or the PDF into the repository or any committed file. Metadata (DOI, title, BibTeX fields) is always fine.

解析标识符。运行：
```
python3 scripts/resolve_oa.py <DOI-or-arXiv-ID> --json
```
该脚本会处理所有确定性操作：标识符标准化、Unpaywall
```
best_oa_location
```
查询、arXiv PDF/HTML链接获取、2026年后ACM数字图书馆开放获取 fallback、速率限制、429错误重试，以及在
```
.cache/fetch-paper/
```
下缓存响应。请勿手动编写这些API调用。
解读结果（退出码：0 = 找到开放获取版本，3 = 无合法开放获取版本，2 = 输入/配置错误，1 = 网络故障）：
- 若存在
```
html_url
```
  （arXiv HTML页面），优先使用——直接阅读最便捷。
- 否则使用
```
pdf_url
```
  。请查看references/oa-sources.md中
```
oa_status
```
  、
```
version
```
  和
```
license
```
  的含义。
- 若
```
version: submittedVersion
```
  表示这是预印本——在用户引用或标注页码前，需提醒用户已发表版本可能存在差异。
临时获取全文。可直接访问链接，或运行：
```
python3 scripts/resolve_oa.py <ID> --download
```
该命令会将PDF保存到新的临时目录（绝不会保存到仓库）。阅读后提取任务所需内容，然后删除文件。
```
dl.acm.org
```
会阻止脚本式下载——请将链接提供给用户，让其在浏览器中打开。
若退出码为3（无合法开放获取版本）：转达脚本的建议——作者个人主页/机构知识库（可通过
```
find-papers
```
搜索）、按标题查找arXiv版本、用户所在机构的图书馆访问权限，或联系作者。绝不能推荐Sci-Hub、LibGen或任何影子图书馆，也不能尝试绕过付费墙。完整规则请查看references/copyright-and-politeness.md。
仅处理，不持久化。在分析中最多引用简短摘录。绝不能将论文文本、摘要或PDF写入仓库或任何已提交的文件。元数据（DOI、标题、BibTeX字段）始终可以保留。

Output

输出结果

A resolution report (human-readable, or JSON with
```
--json
```
):
```
is_oa
```
,
```
oa_status
```
,
```
license
```
,
```
version
```
,
```
pdf_url
```
,
```
html_url
```
,
```
landing_url
```
,
```
source
```
, plus notes.
With
```
--download
```
: a transient PDF in a temp directory, path printed to stderr.
Nothing is ever written into the repository.

解析报告（可读格式，或使用
```
--json
```
输出JSON格式）：包含
```
is_oa
```
、
```
oa_status
```
、
```
license
```
、
```
version
```
、
```
pdf_url
```
、
```
html_url
```
、
```
landing_url
```
、
```
source
```
以及备注信息。
使用
```
--download
```
时：临时PDF文件会保存到临时目录，路径会打印到标准错误输出。
任何内容都不会写入仓库。

Guardrails

约束规则

One identifier per invocation — never loop this script over a list of DOIs for bulk harvesting (ACM ToU and arXiv policy both prohibit it). For a handful of papers in a session, run it one at a time and let the built-in rate limits breathe.
Legal sources only; transient processing only; no storage, no redistribution.
Cite the published DOI, not the preprint, when both exist — and verify every citation with
```
verify-citations
```
before it lands in a bibliography.
Never submit anything to any system on the user's behalf.

每次调用仅处理一个标识符——绝不能循环运行该脚本批量获取DOI列表（ACM服务条款和arXiv政策均禁止此操作）。若在一个会话中需要处理少量论文，请逐个运行脚本，并遵守内置的速率限制。
仅使用合法来源；仅进行临时处理；不存储、不重新分发。
若同时存在已发表版本的DOI和预印本，请引用已发表版本的DOI——并在将引用加入参考文献前，使用
```
verify-citations
```
进行验证。
绝不能代表用户向任何系统提交内容。

References

参考资料

references/oa-sources.md — Unpaywall fields and errors, arXiv URL patterns, ACM DL open access, troubleshooting.
references/copyright-and-politeness.md — what is safe to keep vs. transient-only, politeness contract.

references/oa-sources.md — Unpaywall字段与错误、arXiv链接格式、ACM数字图书馆开放获取、故障排查。
references/copyright-and-politeness.md — 可保留内容与仅临时处理内容的界定、合规使用约定。