fulltext-retrieval

全文検索スキル

正規のOA APIのみを使用して、DOIリストからオープンアクセスの全文PDFを一括ダウンロードします。 ペイウォールで保護された論文は仕様上ダウンロードに失敗し、機関アクセスまたはILLが必要なものとして manual_needed.txt に記載されます。ペイウォールや出版社のアクセス制御を回避しないでください。

パイプライン

DOI → arXiv (10.48550/arXiv.* DOIs) → Unpaywall → PMC (Europe PMC / OA FTP / web) → OpenAlex → Crossref → landing page

各DOIは、有効なPDF（10 KB以上で、%PDF- ヘッダーがあるもの）が見つかるまで、以下のソースを順に処理します。 arXivのDOI（10.48550/arXiv.2401.01234、バージョン接尾辞付きのもの、旧形式の hep-th/9901001、またはarXiv:で始まるID）は、最初にarXiv PDFへ直接解決されます。

実行

Python 3.10以降（標準ライブラリのみ）と、連絡先メールアドレスが必要です。Unpaywallの利用規約で メールアドレスの登録が求められています。スクリプトはAPIのレート制限に合わせ、リクエストの間隔を 調整します（0.3～0.5秒の遅延）。

python "${CLAUDE_SKILL_DIR}/fetch_oa.py" dois.txt --output pdfs/ --email [email protected]

# Verbose mode for debugging (per-DOI source trace)
python "${CLAUDE_SKILL_DIR}/fetch_oa.py" dois.txt -o pdfs/ -e [email protected] --verbose

入力形式：

• プレーンテキスト — 1行につき1つのDOIを指定します。
• ヘッダー付きTSV／CSVまたはMarkdownのパイプテーブル — DOI列が必要です。PMID、Title、FirstAuthor（姓またはフルネーム）列は任意です。

PMIDがあると、PMCの検索精度が上がります（PMID → PMCID変換）。利用できる場合はTitleを指定してください。DOIのみのリストではPDFをダウンロードできますが、タイトルが一致するかどうかは確認できません。 FirstAuthorは追加の証拠として任意で指定できます。

出力

• PDFは{DOI_safe}.pdfとして保存されます（スラッシュはアンダースコアに置き換えられます）。
• pdfs/retrieval_report.json — DOIごとの構造化レポート（以下を参照）。--report PATHで保存先を変更できます。
• <output>/manual_needed.txt — OA経由で取得できなかったDOIが記載されます。PMCIDが解決された場合は、そのPMCIDと、ブラウザーで開くためのPubMed Central記事URLも各行に記載されます。
• arXiv／OA／PMC／失敗／スキップの件数を含むサマリー。

検索レポート（--report）

実行ごとにレポート（デフォルトは <output>/retrieval_report.json）が書き込まれます。スキーマ 2：

{
  "schema_version": 2,
  "generated_by": "fetch_oa.py",
  "counts": {"total": 4, "retrieved": 3, "not_retrieved": 1, "title_mismatch": 1,
             "source_identity": {"consistent": 1, "conflict": 1, "unresolved": 1, "unavailable": 1}},
  "items": [
    {"doi": "10.1000/synthetic.example", "pmid": "", "title": "Example title",
     "first_author": "", "status": "oa", "source": "unpaywall",
     "file": "10.1000_synthetic.example.pdf", "size_bytes": 482113, "page_count": 9,
     "file_sha256": "<SHA-256 of the downloaded file>", "title_match": "match",
     "source_identity": {"status": "consistent", "reason": "title_and_identifier_agree",
                         "text_scope": "first_page_front_matter", "title_match": "match",
                         "doi_match": "match", "observed_identifiers": ["10.1000/synthetic.example"],
                         "first_author_match": "unavailable"}}
  ]
}

status（arxiv | oa | pmc | skip | fail）、source、および counts.retrieved は、既存ファイル（skip）を含むリゾルバーの結果を表します。本人確認済みの論文数ではありません。 PDF が自動的に削除または却下されることはありません。page_count は Poppler の pdfinfo から取得され（利用できない場合は null）、記録されますが、判定には使われません。3 ページの「記事」や 4 ページの「書籍」も、開いてみる価値があります。

source_identity.status	意味／対応
consistent	正規化された完全なタイトルと、互換性のある DOI／arXiv 識別子が、範囲を限定した最初のページの前付け部分に含まれており、そこに補足資料／序文／目次の見出し、または撤回／正誤表／訂正／修正／懸念表明の見出しがない状態です。任意で指定した著者も一致する必要があります。証拠は一致していますが、独立した出典確認や主張の検証を意味するものではありません。
conflict	タイトルと確認された識別子の両方が異なります。PDF と指定されたレコードを確認してください。
unresolved	証拠が不完全、または曖昧です。タイトルのみ、DOI のみ、著者の欠落、複数の識別子、別の DOI／バージョンが付いた一致タイトル、または作品名を挙げているもののその作品自体ではない補足資料／序文／目次ファイル（supplement_or_front_matter）が該当します。その範囲内に見出し行がある撤回通知、正誤表、訂正、修正、懸念表明も同様に unresolved（correction_or_retraction_notice）となります。証拠として使う前に確認してください。
unavailable	抽出可能なテキストがない、Poppler が利用できない、出力 PDF がない、または評価中に PDF が変更された状態です。現在の本人確認はできません。

証拠は、認識された抄録／本文／参考文献の見出しより前の最初のページに限定されます（最大 40 行／4,000 文字）。そのため、本文や参考文献で引用されたタイトルは該当しません。title_match が match となるには、最大 6 行連続で正規化された完全なタイトルが必要です。一部のみ一致する場合は unavailable、一致度が低い場合は参考情報として mismatch となります。表紙、一般的でない読み取り順序、短縮または変更されたタイトル、この範囲外にある DOI のフッターは、未解決のままになることがあります。PDF のメタデータとファイル名だけでは本人確認の証拠になりません。明示された arXiv のバージョンは一致する必要があります。プレプリントと出版版の DOI の違いは、自動却下ではなく確認が必要です。

後続のレポートでは source_identity と file_sha256 を保持し、未解決の項目を表示したままにして、ハッシュが引き続き使用中のファイルを示していることを確認する必要があります。本人確認の証拠がない古いレポートは未評価のままです。retrieved または title_match=match から本人確認を推測しないでください。全文変換を行っても、本人確認に関する警告は解消されません。

PDF を Zotero に添付する（「利用可能な PDF を検索」）

OA リゾルバーでは見つからない、ライセンスはあるもののペイウォールで保護された論文については、references/find_available_pdf.js は、Zotero の ツール → 開発者 → JavaScript を実行 でユーザーが実行するスニペットです（コードを使わない場合は、右クリック →「利用可能な PDF を検索」）。Zotero 自体の addAvailablePDF／addAvailablePDFs を呼び出すため、ユーザーの OpenURL リゾルバー／機関プロキシの設定が再利用されます。認証情報、プロキシホスト、機関識別子がハードコードされたり、Zotero クライアントの外部に送信されたりすることはありません。 ユーザーが開始する操作で、稼働中の Zotero セッションに依存するため、結果は手動で記録してください。再現可能な CI 証拠ではありません。/lit-sync Phase 2.7 は両方の経路を調整し、レポート内で結果を照合します。

PDF から Markdown への変換（任意）

同じ論文を繰り返し読む場合（k≥5 件の研究からのデータ抽出、メタ分析パイプライン）には、ダウンロードした PDF を Markdown に変換します。1 回限りのスクリーニングでは、PDF を直接読んでください。

# Install (one-time)
pip install pymupdf4llm

# Convert all PDFs in a directory (.md files land alongside the .pdf files)
python "${CLAUDE_SKILL_DIR}/pdf_to_md.py" pdfs/ -v

# Custom output directory
python "${CLAUDE_SKILL_DIR}/pdf_to_md.py" pdfs/ -o markdown/

# First 10 pages only (useful for long supplements)
python "${CLAUDE_SKILL_DIR}/pdf_to_md.py" pdfs/ --pages 0-9

# Overwrite existing conversions
python "${CLAUDE_SKILL_DIR}/pdf_to_md.py" pdfs/ --force

画像はスキップされるため、図はキャプションのテキストとしてのみ残ります。スキャンのみの PDF（テキストレイヤーがないもの）は、うまく変換できません。pdf_to_md.py には pymupdf4llm（AGPL-3.0）が必要です。これは任意の依存関係です。fetch_oa.py は標準ライブラリのみを使用します。