/ref-downloader

name: ref-downloader
description: >
  Use when the user asks to batch-download academic PDFs with
  ref-downloader — either ALL references of one paper (Mode A: DOI or
  PDF input), OR a custom batch of papers (Mode B: DOI/title/arXiv-PMID
  list, or abstract query like "Author X's recent papers"). Not for
  one-off PDFs, paper search, or Zotero import.

Ref Downloader — Agent Runbook

> Slim entry for agent mode. The full 8-step manual runbook with code > snippets for Mode A debug + `PUBLISHER_MAP` extension procedure > lives in [references/agent-runbook.md](references/agent-runbook.md). > Human users see [../../README.md](../../README.md).

`<SKILL_DIR>` = this folder (`skills/ref-downloader` in the source repo, or wherever the user copied this skill — e.g. `~/.claude/skills/ref-downloader/`). Python scripts live in `<SKILL_DIR>/scripts/`; config files (`config.example.toml`, `config.local.toml`) live at `<SKILL_DIR>/`.

Mode router

This skill handles two flows. **Pick before running.**

• **Mode A — Reference-list download** (original use case). User

provides ONE paper (DOI or local PDF) and wants "all of its references". Pipeline: `extract_refs.py` → `validate_refs.py` → `download_refs.py`.

• **Mode B — Custom batch download**. User provides their own batch

of papers — DOIs, paper titles, non-DOI identifiers (arXiv / PMID / Semantic Scholar IDs), OR an abstract query ("Smith 在 Google Scholar 上的文章" / "Nature Energy 2023 papers"). The agent resolves whatever was given to DOIs, then runs `validate_refs.py` → `download_refs.py` directly. **Skip the wrapper** — `run_ref_downloader.py` assumes a parent DOI and will fail.

Both modes share install, config, per-publisher strategies, failure modes, output layout, and the CloakBrowser opt-in backend.

Trigger family

| User input shape | Mode | Sub-flow | |---|---|---| | One DOI/PDF + "all refs of" / "全部参考文献" / "把这篇引用都下了" | A | — | | ≥2 DOIs in input (any wrapping: bare / `{}` / `https://doi.org/…` / `dx.doi.org/…`; ASCII or full-width slashes) | B | B.1 (after canonicalize) | | Non-DOI IDs only: `arXiv:` / `PMID:` / `S2:` / `corpusId:` | B | B.0 normalize → B.1 | | Title list ("下载这几篇：title1, title2, …") | B | B.2 | | Abstract query (author / topic / journal+year / "Google Scholar 上 …") | B | B.3 | | Mixed (DOIs + titles + IDs + queries) | B | run each, merge | | Single DOI without "of refs" qualifier | B | B.1 single-item | | Title + author + year for ONE paper ("Smith 2024 Nature paper on X") | B | **B.2** (specific paper, lookup) | | Open-ended query for a corpus ("Smith 2024 之后所有的 Nature 文章") | B | **B.3** (discovery) | | **Insufficient resolvable content** ("上次给你的那 5 篇" / pure pronouns) | — | **Ask user to repaste / attach file**; do NOT guess | | Genuinely ambiguous A vs B | — | ask user |

**Key disambiguators**:

• *"refs OF a paper"* (Mode A) vs *"these papers themselves"* (Mode B).
• *Identifies a specific paper* (B.2) vs *describes a set to discover*

(B.3). If user names a specific paper with enough metadata to uniquely identify it (title + author + year), it's B.2 (lookup exact); if they describe a class of papers ("all Smith's 2024 Nature papers"), it's B.3 (discover then filter).

Mode A — Reference-list download

When to invoke

**Trigger phrases**:

• "帮我下载 [paper / DOI] 的参考文献" / "批量下载引用文献" / "把这篇论文的所有引用下载下来"
• "Download all refs of [paper / DOI]" / "Batch-download every reference"
• User provides a DOI (`10.x/y` form) or local PDF path and asks for

"all references" / "全部参考文献"

**Don't invoke for**:

• Downloading one arbitrary PDF (not a reference list) → user wants

one paper itself, route to Mode B as a single-item B.1

• Generic web scraping
• Paper search / Zotero import — different tools

Primary entry

python "<SKILL_DIR>/scripts/run_ref_downloader.py" <DOI_OR_PDF_PATH>

The wrapper handles DOI resolution (Zotero → fitz fallback), output-dir layout, sequential 3-stage pipeline (`extract_refs.py` → `validate_refs.py` → `download_refs.py`), and end-of-run cleanup.

**Useful flags**:

• `--yes` — non-interactive (CI/batch), overwrite prompts default-yes
• `--auto` — forwarded to `download_refs.py`: skip "press Enter"

confirm + shorter challenge wait + async retry queue for `manual_pending` refs (60s delay, single retry, max 3 concurrent). Use for CI / overnight runs; not for sessions where you want to drive captchas yourself.

• `--fail-fast` — terminate after first actionable unresolved ref

(useful in CI to surface real failures fast)

• `--output-dir <path>` — override default output location
• `--config <path>` — alternate TOML config (overrides

`config.local.toml`)

Pre-flight checklist (confirm before running)

1. **DOI correct?** Echo back to user: `即将下载参考文献：DOI=<doi>` 2. **Edge fully closed?** All `msedge.exe` processes killed (Task Manager check). The script claims the user's persistent Edge profile and needs exclusive access. (Cloak backend skips this.) 3. **Config set?** First-run users need `<SKILL_DIR>/config.local.toml` with `[crossref].mailto`. Missing config → wrapper prints a WARNING but continues with placeholder defaults. 4. **Output location agreed?** Default for DOI input: `<cwd>/<project_name>_refs/`. For PDF input: `<pdf_dir>/<pdf_stem>_refs/`. Override with `--output-dir`.

Mode B — Custom batch download

Input variability is the point. Don't refuse — route. The agent handles whatever shape the user gave (paste, file, prose, BibTeX, RIS, abstract query) and resolves it to a clean DOI list before handing off to the pipeline.

Step 0 — Canonicalize input (always runs first)

Before any extraction or routing, normalize the input string:

1. **Unwrap delimiters around DOIs**: strip leading/trailing `{}`, `<>`, `()`, `[]`, and quote marks. 2. **Strip URL prefixes**: `https://doi.org/`, `http://doi.org/`, `https://dx.doi.org/`, `http://dx.doi.org/` → bare DOI. 3. **Full-width / Unicode punct