scholar-deep-research

Scholar Deep Research

質問を引用付きの構造化レポートへと導く、エンドツーエンドの学術研究ワークフローです。深い調査を目的として構築されており、複数ソースの連携、透明性のあるランキング、引用の追跡に加え、レポートの公開前に必須の自己批評を行います。

使用する場面

明示的なトリガー：「文献レビュー」、「研究レポート」、「研究の最先端」、「分野を調査」、「X について何が分かっているか」、「Y の深掘り調査」、「システマティックレビュー」、「スコーピングレビュー」、「Z に関する論文の比較」。

先回りして使用するトリガー（依頼されていなくても使用）：

• ユーザーが、誠実に答えるなら「文献によります」となる事実に関する質問をする
• ユーザーが研究計画を立てており、背景セクションを必要としている
• ユーザーが論文の序論や関連研究を執筆しているが、まだ先行研究の範囲を定めていない
• ユーザーが手法を提案し、新規性があるか尋ねている

**使用しない場面：**質問への答えが既知の単一の論文に記載されている場合、ユーザーがサーベイではなくチュートリアルを求めている場合、またはコードのデバッグをしている場合。

基本方針

1. **感覚ではなくスクリプトを使います。**検索、重複排除、ランキング、エクスポートのすべての工程を scripts/ 内のスクリプトで実行します。同じ入力からは同じ出力が得られる必要があります。目視でランキングや件数を推測しないでください。
2. **ソースは単独ではなく、連携させます。**主要な基盤は OpenAlex です（無料、2億4,000万件以上の研究成果、API キー不要）。arXiv（CS／ML／物理学のプレプリント）、Crossref（DOI メタデータ）、PubMed（生物医学）、DBLP（CS の学会・ジャーナル）、bioRxiv（Europe PMC 経由の生命科学プレプリント）、Exa（オープンウェブ。EXA_API_KEY が必要）で不足を補います。Semantic Scholar もスクリプトで処理します。Phase 4 の中核となる経路は build_citation_graph.py --source s2|both で、OpenAlex よりも CS／arXiv／分野横断のカバレッジに優れています。2 つのグラフは予想以上に食い違います。asta MCP ツール（mcp__asta__*）と Brave Search は補助的な手段であり、関連性のランキングや学術以外の文脈を得るために必要に応じて使います。重要な工程では使いません。MCP がタイムアウトしても、調査は続行します。
3. **状態を永続化します。**すべての情報を research_state.json に記録します。実行したクエリ、確認した論文、決定事項、フェーズの進捗などが含まれます。これにより、調査を再開可能かつ監査可能にします。
4. **引用は飾りではなく、根拠です。**草稿中の重要な主張にはすべて、その id が state 内の論文に一致する [^id] を付けます。根拠のない主張は幻覚とみなされ、ゲートを通過できません。
5. **網羅ではなく、飽和を終了の合図とします。**新たな検索ラウンドで追加される新規論文が 20% 未満であり、かつ引用数が 100 件を超える新しい論文がない場合、そのフェーズを終了します。
6. **自己批評はチェック項目ではなく、独立したフェーズです。**Phase 6 では、草稿を批判的な意図を持って読みます。その出力をレポートの付録に含めます。

8 フェーズのワークフロー（Phase 0..7）

Phase 0: Scope       → decompose question, pick archetype, init state
Phase 1: Discovery   → multi-source search, dedupe
Phase 2: Triage      → rank, select top-N for deep read
Phase 3: Deep read   → extract evidence per paper
Phase 4: Chasing     → citation graph (forward + backward)
Phase 5: Synthesis   → cluster by theme, map tensions
Phase 6: Self-critique → adversarial review, gap finding
Phase 7: Report      → render archetype template, export bibliography

各フェーズは、次のフェーズに進む前に research_state.json に書き込みます。ユーザーが作業を中断した場合やセッションがクラッシュした場合は、次回の実行時に state を読み込み、最後に完了したフェーズから再開します。

フェーズ 0 — 範囲

何かを検索する前に、質問を分解します。

1. 質問を言い換え、1 文で示します。曖昧な点を明らかにします。
2. PICO 形式で分解（または、生物医学以外の分野では相当する形式を使用します）：
   • Population / Problem — どのシステム、種、状況、現象を扱いますか？
   • Intervention / Independent var — どの手法、要因、操作を扱いますか？
   • Comparison — どのベースラインや代替案と比較しますか？
   • Outcome — 何を測定または主張しますか？
3. ユーザーの意図に合ったアーキタイプを選びます（references/report_templates.md を参照）：
   • literature_review — X について何がわかっているか（デフォルト）
   • systematic_review — 1 つの限定的な問いについて、多数の研究を比較する厳密な PRISMA-lite
   • scoping_review — 何がどのように研究されているか（深さより幅を重視）
   • comparative_analysis — X と Y の直接比較
   • grant_background — 提案に向けた背景の説明と研究上のギャップ
4. キーワードクラスターの草案を作成します。同義語、略語、異なる綴りを含む、3〜5 個のブールクラスターを作成します。除外する用語の「ネガティブ」クラスターも含めます。
5. 状態を初期化します。

   python scripts/research_state.py --state research_state.json init \
     --question "<restated question>" \
     --archetype literature_review
   

   （--state はトップレベルのオプションであり、すべてのサブコマンドに適用されます。init 自体には --question、--archetype、および任意の --force を指定します。）

アーキタイプに迷った場合は、ユーザーに確認してください。この選択が以降のすべての作業に影響します。

Phase 1 — 発見

利用可能なすべてのソースを検索します。ソース側が対応している場合は並列で実行してください。OpenAlex を主要なソースとし、ほかのソースで不足分を補います。

並列化が実際に効果を発揮する場所。 適切な並列化の対象は Phase 3 です（論文ごとにエージェントを割り当て、PDF を並行して読み取ります。references/agent_prompts/phase3_deep_read.md を参照）。Phase 1 のボトルネックはローカルの計算処理ではなく上流 API であり、同じソースに対する並列処理では、主に 429 エラーや長引くクールダウンが発生するだけです。このスキルでは、ソース間では並列、同一ソース内では逐次処理を基本とします。具体的には次のとおりです。

• 並列処理に適したソース：OpenAlex（polite-pool を利用し、非常に寛容）、Crossref（polite-pool）、Exa（有料クォータ）、bioRxiv（Europe PMC）。
• 逐次処理（自動、ファイルロックあり）：arXiv（リクエスト間隔 ≥3 秒）、PubMed（NCBI_API_KEY がない場合はリクエスト間隔 ≥0.34 秒、ある場合は ≥0.10 秒）、DBLP（SSL EOF の一時的なエラーを避けるために 1 秒のバッファー）。

逐次処理を行うソースでは、${SCHOLAR_CACHE_DIR:-.scholar_cache}/rate/<source>.lock にソースごとのファイルロックを使用するため、同じエージェントから search_arxiv.py を N 個並列で実行しても、自動的にキューに入り、適切な間隔だけ待機します。エージェント側で調整する必要はありませんが、並列呼び出しをしてもこれらのソースの処理は速くならず、エラーも発生しないというだけです。

# Primary (no API key, always available)
python scripts/search_openalex.py --query "<cluster 1>" --limit 50 --state research_state.json
python scripts/search_openalex.py --query "<cluster 2>" --limit 50 --state research_state.json

# Domain-specific (use when relevant)
python scripts/search_arxiv.py    --query "<cluster>" --limit 50 --state research_state.json  # CS/ML/physics preprints
python scripts/search_dblp.py     --query "<cluster>" --limit 50 --state research_state.json  # CS gold-standard bibliography (no abstracts)
python scripts/search_pubmed.py   --query "<cluster>" --limit 50 --state research_state.json  # biomedical (PubMed)
python scripts/search_biorxiv.py  --query "<cluster>" --limit 50 --state research_state.json  # life-sci preprints (bioRxiv + medRxiv via Europe PMC)
python scripts/search_crossref.py --query "<cluster>" --limit 50 --state research_state.json  # DOI-backed metadata

# Open-web coverage (optional, requires EXA_API_KEY) — finds material the
# scholarly APIs miss: lab sites, institutional PDFs, conference mirrors,
# preprints parked outside arXiv, NGO/government reports.
python scripts/search_exa.py --query "<cluster>" --limit 50 --state research_state.json

# Dedupe across sources (DOI-first, title-similarity fallback)
python scripts/dedupe_papers.py --state research_state.json

MCP による補強（任意、利用可能な場合に実行）： mcp__asta__search_papers_by_relevance と mcp__asta__snippet_search を呼び出し、結果を scripts/research_state.py ingest で取り込みます。MCP 呼び出しでエラーが発生したり、タイムアウトしたりした場合は、再試行せずに次へ進んでください。

反復します。 状態ファイルを読み取ります。キーワードに不足はありますか？ 3 回以上登場している著者のうち、ほかの著作をまだ取得していない人はいますか？ もう一巡実行してください。飽和に達したら停止します。最後にクエリしたソースだけでなく、すべてのソースを確認してください。

python scripts/research_state.py saturation --state research_state.json
# Returns { "per_source": {...}, "overall_saturated": true/false, ... }

overall_saturated が true になるのは、クエリしたすべてのソースで --min-rounds（デフォルトは 2）以上のラウンドが実行され、かつ各ソースがそれぞれ新規論文の割合と新規引用数のしきい値を下回った場合に限られます。一度しかクエリされていないソースは飽和と判定されないため、検索結果が少ないソースが 1 つあるだけで発見プロセス全体が誤って終了する事態を防げます。ソースを 1 つだけ個別に確認するには、--source openalex を使います。

予算上限と広範なトピック向けの調整方法。 Phase 1 には、エージェントの処理が際限なく続くのを防ぐための厳格な上限が 2 つあります。SCHOLAR_PHASE1_MAX_ROUNDS（デフォルトはソースごとに 10 ラウンド）と SCHOLAR_PHASE1_MAX_REQUESTS_PER_SOURCE（デフォルトはソースごとに 20 回の取り込み）です。どちらかの上限に達すると、next: のヒントとともに phase1_budget_exhausted が返されます。複数のサブフィールドにまたがる非常に広範なトピック（複数のキーワードクラスターを含む CS-ML のトピックなど）では、デフォルト値のままでは飽和のしきい値に達しないこともあります。その場合は、SCHOLAR_SATURATION_NEW_PCT（デフォルトは 20.0）、SCHOLAR_SATURATION_MAX_CITATIONS（デフォルトは 100）、SCHOLAR_SATURATION_NEW_AUTHORS_PCT／SCHOLAR_SATURATION_NEW_VENUES_PCT を調整してください。これらの環境変数は python scripts/research_state.py saturation と G2 ゲートの両方で適用されるため、値を上げると、デフォルトのしきい値に到達できないトピックでも、十分な範囲をカバーした状態でゲートを通過できるようになります。

フェーズ 2 — トリアージ

重複を除いたコーパスに順位を付け、精読する上位 N 件を選びます。

python scripts/rank_papers.py \
  --state research_state.json \
  --question "<phase 0 question>" \
  --alpha 0.4 --beta 0.3 --gamma 0.2 --delta 0.1 \
  --top 20

計算式は透明です。スクリプトは計算式を出力し、各要素を state に書き込むため、レポートで独自の手法を引用できます。

score = α·relevance + β·log10(citations+1)/3 + γ·recency_decay(half-life=5yr) + δ·venue_prior

デフォルトは文献レビューを想定しています。スコーピングレビューでは、α（関連性）を高く、β（引用数）を低く設定してください。狭い問いを対象とするシステマティックレビューでは、αを低く、βを高く設定してください。

上位 N 件の選択結果を state に書き込みます。

python scripts/research_state.py select --state research_state.json --top 20

次に進む前に、選択した論文を精読／斜め読み／保留の各ティアにトリアージしてください。 フェーズ 3 のファンアウトは、ワークフローで最もコストのかかる段階です。選択した論文すべてに、エージェントによる完全な処理を割り当てる必要はありません。

python scripts/skim_papers.py --state research_state.json \
  --deep-ratio 0.5 --skim-ratio 0.5

デフォルトでは、上位 N 件を均等に分割します。上位半分は deep（フェーズ 3 でエージェントに割り当て）、下位半分は skim（抄録から作成したエビデンスの仮データを自動入力し、depth=shallow に設定）です。予算をさらに抑える場合は、--deep-ratio 0.3 --skim-ratio 0.5 を使用してください。残りの 20% は tier=defer となり、selected_ids から除外されます（引用追跡の候補として引き続きクエリできます）。

スクリプトは data.deep_tier_preview を出力します。この一覧には、triage_score 順に精読ティアの論文が表示されます。次に進む前に、これをユーザーに提示してください。 エージェントをファンアウトする前に、ユーザーが手動で上書きできます（異なる比率で再実行するか、state で順位を手動変更してください）。G3 の合格にはトリアージが必須です。ゲートの triage_applied チェックを満たさないと、先に進めません。

任意ですが推奨 — エージェントをファンアウトする前に、精読ティアの PDF を事前取得します。

python scripts/prefetch_pdfs.py --state research_state.json \
  --tier deep --concurrency 4

paper-fetch（Unpaywall フォールバック付き）を使って、精読ティアのすべての論文の PDF を ${SCHOLAR_CACHE_DIR:-.scholar_cache}/pdfs/<id-hash>/ に並列処理で取得し、論文ごとに pdf_path／pdf_status／pdf_source／pdf_bytes を書き込みます。これにより、フェーズ 3 のエージェントは各自でダウンロードを実行せず、ローカルファイルを直接読み込めます。エージェントのコンテキストを、ペイウォールへの再試行ではなく、読解と推論に集中させられます。

取得に失敗した場合は、pdf_failure_code（paper_fetch_error、no_open_access_pdf、pdf_download_failed など）を設定して pdf_status='failed' とします。DOI のない論文は pdf_status='no_doi' となります。フェーズ 3 のエージェントは、まず pdf_path を確認し、事前取得したパスが見つからない場合に限り extract_pdf.py --doi にフォールバックします。事前取得は再実行しても負担が小さく、ディスク上に既存の pdf_path がある論文はスキップされます（pdf_status='cached'）。

ペイウォール対応のヒューマン・イン・ザ・ループ。 自動取得に失敗した場合（ペイウォール、OA の取得経路を使い切った場合、DOI がない場合）は、--emit-manifest を使って、手動取得する論文の一覧をユーザーに提示してください（読み取り専用）。

python scripts/prefetch_pdfs.py --state research_state.json --emit-manifest
# Returns { needs_user_download: [{id, doi, title, drop_at, alt_urls}, ...] }

ユーザーは各 PDF をダウンロードし（機関の VPN、ResearchGate など）、一覧に記載された drop_at のパスに配置します（そのサブディレクトリ内であれば、ファイル名は任意の *.pdf で構いません）。次回 prefetch_pdfs.py を通常実行すると、配置されたファイルは再取得されず、pdf_source='user_provided' として自動的に取り込まれます。

paper-fetch がインストールされておらず、Unpaywall へのアクセスも避けたい場合は、事前取得を完全に省略してください。その場合、フェーズ 3 のエージェントがそれぞれのコンテキスト内で論文ごとにダウンロードします（遅く、ノイズも増えますが、機能的には同じです）。

フェーズ 3 — 詳細な読み込み（エージェントを並列に展開）

フェーズ 3 はティアごとに分かれます。

• tier=skim — apply_triage() によって、すでにアブストラクトから導出した depth=shallow のエビデンスの仮レコードが書き込まれています。追加の対応は不要です。
• tier=deep — 論文ごとにエージェントを 1 つ割り当て、8～10 件ずつの波で並列に実行します。各エージェントは PDF を読み、構造化されたエビデンスを状態に書き戻し、JSON 行を 1 行返します。ホストのメインコンテキストが PDF 全文を参照することはありません。

エージェントのプロンプトテンプレートは references/agent_prompts/phase3_deep_read.md にあります。これを一度読み込み、論文ごとにインスタンス化して、すべての N 件の tool_use 呼び出しを 単一のメッセージ でディスパッチし、並行して展開します。エージェントごとの契約は次のとおりです。

• 入力： paper_id、doi、pdf_url、abstract、question、state_path
• アクション： extract_pdf.py --doi <doi> --output <tmp> → テキストを読む → evidence --depth full を書き込む
• 出力： {"paper_id": "...", "status": "ok"|"evidence_unavailable", ...} の 1 行

状態 CLI は排他的ロックを使用するため、N 個のエージェントによる並行した evidence 呼び出しは自動的に直列化され、調整は不要です。

# After all wave(s) complete, verify deep-tier coverage:
python scripts/research_state.py advance --state research_state.json \
  --to 4 --check-only

deep_tier_full_evidence が失敗した場合は、不足している ID のみを対象にフォローアップの波をディスパッチします。論文の全文に本当にアクセスできない場合（ペイウォール、OA チェーンの試行回数上限到達など）、エージェントはプロンプトの失敗時の動作に関するセクションに従い、method が evidence_unavailable: で始まる depth=shallow のレコードを書き込む必要があります。このレコードは、ディープティアの網羅率を水増しすることなく、depth_marks_valid を満たします。

手動での代替手順（エージェントを利用できない場合）。 並列エージェントをディスパッチできないホスト（CC 以外の一部のプラットフォームなど）では、メインセッション内でフェーズ 3 を逐次実行できます。各 tier=deep 論文について、extract_pdf.py --doi <doi> を実行し、続けて research_state.py evidence --id <pid> --depth full ... を実行します。時間がかかり、より多くのコンテキストを消費しますが、ゲートのロジックは同じです。

フェーズ 4 — 引用をたどる

ランキング上位の論文から 5～10 件を選び、グラフを拡張します。

# Preview the request count first — this is the most expensive command
python scripts/build_citation_graph.py \
  --state research_state.json \
  --seed-top 8 --direction both --depth 1 --dry-run

# Run with an idempotency key so a retry after a network blip is free
python scripts/build_citation_graph.py \
  --state research_state.json \
  --seed-top 8 --direction both --depth 1 \
  --idempotency-key "chase-$(date -u +%Y%m%dT%H%M)"

このスクリプトは、後方参照（この論文が引用した文献）と前方引用（この論文を引用した文献）を取得し、既存の状態と照合して重複を除外したうえで、discovered_via: citation_chase を付けて新たな候補論文を書き込みます。新たに追加された論文のうちスコアの高いものについて、再度ランキングと詳細な読み込みを実行します。

二重バックエンド。 --source openalex|s2|both（デフォルトは both）。OpenAlex はほとんどの分野を十分にカバーします。Semantic Scholar（S2）は、CS／arXiv／学際分野のカバー範囲がより優れています。2 つのグラフは予想以上に異なるため、両方を実行してから ID で重複を除外すると、実際の網羅性の不足が明らかになります。S2 ではシードごとに DOI／arXiv ID／PMID が必要です（OpenAlex ID は受け付けません）。これらを持たないシードは S2 バックエンドをスキップします。S2_API_KEY 環境変数を設定すると S2 のクォータが増えます。設定しない場合は、公開クォータの約 1 リクエスト／秒が適用されます。

冪等性。 --idempotency-key <k> を設定すると、最初に成功した実行で {response, signature} が .scholar_cache/<hash>.json に書き込まれます。同じキーで再試行すると、OpenAlex に再リクエストしたり状態を再変更したりすることなく、キャッシュされたレスポンスを再生します。異なる引数で同じキーを再利用すると、古いデータを黙って返すのではなく idempotency_key_mismatch が返されます。キャッシュディレクトリ：SCHOLAR_CACHE_DIR 環境変数。デフォルトは .scholar_cache/ です。

特別なケース — 被引用数が非常に多いにもかかわらず、一度も異議を唱えられていない論文。 ランキングで論文の被引用数がトップ 3 なのに、コーパス内に批判が見つからない場合は、"<first author> <year>" critique OR limitations OR reanalysis OR failed replication を明示的に検索します。これは確証バイアスを防ぐためのバックストップです。

フェーズ 5 — 統合

ここではスクリプトを使いません。エージェントの真価が問われる段階です。分類して構成します。

1. テーマ別クラスタリング。 上位N件を、レポートのアウトラインに対応する3〜6個のテーマに分類します。テーマは互いに独立させます。論文は、主として1つのテーマに属し、副次的には多くてももう1つのテーマに属するようにします。
2. 対立関係の整理。 論文間で見解が異なる点はどこでしょうか。対立ごとに、該当する論文、対立している内容、そしてその対立が実証的（データの違い）、方法論的（ツールの違い）、理論的（枠組みの違い）のいずれかを記録します。
3. 時系列。 該当する場合は、先駆的な論文 → 統合 → 精緻化 → 現在の最前線という時系列の流れを示します。
4. ベン図／ギャップ。 十分に研究されている領域、一部しか研究されていない領域、まったく研究されていない領域は何でしょうか。ギャップはフェーズ 7への転換点になります。

フェーズ 6 — 自己批評

これは必須です。 assets/prompts/self_critique.md を読み込み、未公開の草稿に対してチェックリストをすべて実行します。チェックリストの項目は次のとおりです。

• 単一ソースに基づく主張（1本の論文だけが裏付けている主張はないか？）
• 引用／新しさの偏り（直近2年間の範囲をカバーしているか？）
• 掲載先の偏り（コーパスが特定のジャーナルや掲載先に偏っていないか？）
• 著者の偏り（特定の研究室が引用の大半を占めていないか？）
• 未検証の高被引用論文（批評を読まずに引用している論文はないか？）
• 見落とされた矛盾（フェーズ 5で挙げた対立を曖昧にしていないか？）
• 類型との適合性（構成は選択した類型に合っているか？）
• 根拠のない主張（[^id] アンカーのない記述はないか？）

所見を research_state.json の self_critique に記録し、フェーズ 7の前に重大な問題を修正します。所見はレポートの付録にそのまま掲載します。読者には、調査プロセスが何を疑問視したのかを知る権利があります。

フェーズ 7 — レポート

状態から類型のひな形を生成し、エージェントが文章を埋める箇所を記入して、アンカーを検証します。

# Generate the scaffold — fills header, themes, tensions, methodology
# appendix, self-critique appendix, and bibliography anchor index from
# state. Leaves `` placeholders for prose.
python scripts/render_report.py --state research_state.json
# → reports/<slug>_<YYYYMMDD>.md by default; pass --output PATH to override.

# After filling in the prose, lint every [^id] anchor against
# state.papers. Catches typo'd anchors before the report ships.
python scripts/render_report.py --state research_state.json \
  --lint reports/<slug>_<YYYYMMDD>.md

# Export bibliography in the user's preferred format
python scripts/export_bibtex.py --state research_state.json --format bibtex --output refs.bib
python scripts/export_bibtex.py --state research_state.json --format csl-json --output refs.json

ひな形の本文では [^id] アンカー（状態に含まれる論文ID）を使います。末尾の参考文献セクションには、選択した論文ごとに定義を1つ記載します。Lintモードでは unknown_anchors_used（誤記）と undefined_in_text（脚注定義のないアンカー）が検出され、どちらも重大な問題として扱われます。unused_definitions は参考情報です。これは、選択したものの本文中では引用されなかった論文を示します。

保存先の規則： reports/<slug>_<YYYYMMDD>.md。ユーザーがパスを指定しない限り、このスキルは作業ディレクトリの外には書き込みません。

HTML／PDFでの提供。 このパイプラインは、設計上Markdownを出力します。これは render_report.py --lint が検証する契約であり、後続のエージェントが再処理できる形式です。人に見せるための仕上げ済み成果物が必要な場合は、reports/<slug>_<YYYYMMDD>.md と .bib をホスト側のコーディングエージェントに渡し、「これをPIに共有できる、見栄えのよいHTMLページとしてレンダリングしてください。本文はセリフ体、本文幅は約70文字、サイドバーに目次、フェーズ 6の批評は <details> ブロックに入れ、引用にカーソルを合わせると参考文献エントリを表示してください」 のように指示します。視覚的なスタイル設定は、スキルの正確性を保証する範囲外です。

レポートの類型を選択する

類型	使用する場面	主な出力形式
literature_review	あるトピックについて何が確立されているかをユーザーが知りたい場合	テーマ別セクション＋統合＋ギャップ
systematic_review	問いが限定的で、研究が多く、厳密な比較が必要な場合	PRISMA-liteのフロー＋抽出表＋統合結果
scoping_review	幅広いトピックについて、「何が研究されてきたか」を調べる場合	カバレッジマップ＋手法の一覧＋研究ギャップ
comparative_analysis	手法、モデル、アプローチの「A対B」を比較する場合	比較軸＋軸ごとの評価＋推奨
grant_background	研究提案の序論に使う説明が必要な場合	問題の重要性＋既知のこと＋不足していること＋アプローチの必要性

テンプレートは assets/templates/<archetype>.md にあります。必要なものだけを読み込みます。

スクリプトリファレンス

スクリプト	目的
research_state.py	状態ファイルの初期化、読み取り、書き込み、クエリを行います。すべてのフェーズの中核です。
search_openalex.py	主要な検索（キー不要、2億4,000万件の論文、被引用数）。
search_arxiv.py	arXiv API — プレプリントおよびコンピューターサイエンス／機械学習／物理学。
search_crossref.py	Crossref REST — 信頼性の高い DOI メタデータ。
search_pubmed.py	NCBI E-utilities — MeSH に対応した生物医学コーパス。
search_dblp.py	DBLP — 信頼性の高いコンピューターサイエンス文献目録（会議録＋ジャーナル、著者の曖昧性を適切に解消）。コンピューターサイエンスのレビューでは OpenAlex／arXiv を補完します。抄録／被引用数はありません。
search_biorxiv.py	Europe PMC ゲートウェイ経由で bioRxiv と medRxiv のプレプリントを検索します（CSHL DOI プレフィックス 10.1101/）。PubMed の索引に登録される数週間から数か月前の生命科学プレプリントを見つけられます。
search_exa.py	Exa ニューラルウェブ検索（任意、キーが必要）— 学術 API では見つからないオープンウェブを検索します。
list_sources.py	機能（分野、索引の種類、更新の遅延、認証要件など）を含む、すべての search_*.py ソースのレジストリです。オーケストレーターが質問に適したソースを選べるよう、--domain、--auth、--index-type、または --needs-relevance-filter で絞り込めます。スキーマは _search_meta.py で定義されています。
dedupe_papers.py	ソース間で DOI を正規化し、タイトルの類似性に基づいて統合します。
rank_papers.py	透明性のあるスコアリング式です。式と論文ごとの構成要素を出力します。
skim_papers.py	フェーズ 3 のトリアージです。安価で決定論的なシグナルに基づき、選択した論文を deep／skim／defer の階層に分け、selected_ids を調整し、skim 階層のエビデンスの仮入力を自動的に埋めます。フェーズ 2 の終了時、G3 の前に実行します。
prefetch_pdfs.py	任意です。フェーズ 3 のエージェントへの振り分け前に、paper-fetch（利用できない場合は Unpaywall）を使って deep 階層の PDF を安定したキャッシュに取得します。並行処理（--concurrency）に対応し、再実行しても冪等で、論文ごとに失敗を許容します。論文ごとに pdf_path／pdf_status を書き込み、エージェントが再ダウンロードせずにローカルファイルを読み取れるようにします。
build_citation_graph.py	OpenAlex 経由で前向き／後ろ向きのスノーボール検索を行います。
extract_pdf.py	全文を抽出します。--engine auto（デフォルト）は最初に pypdf を試し、pypdf の結果がスキャン画像のように見える場合や内容が疎な場合は、自動的に docling（Markdown 出力、レイアウト認識、スキャン領域の OCR）に切り替えます。pip install docling でインストールしてください。--engine pypdf|docling で指定できます。--ocr-backend {auto,rapidocr,ocrmac,easyocr,tesseract,none} と --ocr-lang <list> で docling の OCR を調整できます（言語の語彙はバックエンドごとに異なります。--help を参照してください）。--input、--url、または --doi を受け付けます。DOI モードでは、インストール済みの場合は paper-fetch スキルを使って解決し、利用できない場合は Unpaywall にフォールバックします。--idempotency-key は抽出済みテキストをキャッシュするため、再試行時に再抽出を省略できます。
export_bibtex.py	state から BibTeX／CSL-JSON／RIS 形式でエクスポートします。
render_report.py	フェーズ 7 — state.themes／state.tensions／state.queries／state.ranking／state.self_critique からアーキタイプのひな形をレンダリングし、散文用の `` スロットを設けます。--lint <report.md> は、すべての [^id] アンカーが state.papers に存在することを検証します。

すべてのスクリプトは --help と --schema を受け付け、構造化された JSON エンベロープを標準出力に出力し、単一の信頼できる情報源として research_state.json を使用します。すべてのスクリプトは状態ファイルに対して冪等です（ネットワーク層の冪等性は P1 の作業項目です）。

CLI コントラクト、環境変数、状態スキーマ

スクリプトを実行して JSON エンベロープを読むことでエージェントが把握する詳細が 3 つあります。コンテキストを節約するため、本文からは省いてあります。必要に応じて読み込んでください。

• references/cli_contract.md — 成功／失敗時のエンベロープ形式、終了コード、--schema によるイントロスペクション、冪等性キャッシュの仕様。
• references/env_vars.md — 信頼境界に関わる環境変数（SCHOLAR_*、NCBI_API_KEY、EXA_API_KEY、S2_API_KEY、PAPER_FETCH_SCRIPT）。エージェントはこれらを設定しないでください。スクリプトから不足していると報告された場合は、ユーザーに伝えてください。
• references/state_schema.md — research_state.json の形式。最新の機械可読バージョンを確認するには、python scripts/research_state.py --schema を優先してください。

完了ゲート

各フェーズの遷移にはゲート（G1..G7）があります。次に進む方法は、次の操作のみです。

python scripts/research_state.py --state <path> advance          # advance by 1
python scripts/research_state.py --state <path> advance --check-only   # preview only

ゲートの判定条件は scripts/_gates.py で適用されます。直接 set --field phase を指定すると拒否されます。phase フィールドは設定できなくなりました。ゲートを通過できない場合、エンベロープに未達のチェック項目が名前付きで列挙されるため、不足している内容を正確に確認できます。

対象	ゲート（適用される条件）
G1 (→ 1)	質問セット、アーキタイプが有効、状態が初期化済み。≥3 keyword clusters はホスト側でチェックされます。
G2 (→ 2)	検索したすべてのソースで overall_saturated == true、かつ state.queries に異なるソースが 3 つ以上あること。
G3 (→ 3)	state.ranking が記録済み、selected_ids が空でない、選択された論文すべてに score_components がある、state.triage_complete=true（skim_papers.py を実行）。
G4 (→ 4)	選択された論文すべてで depth ∈ {full, shallow} であること。さらに、tier=deep の論文はすべて、(a) depth=full、または (b) depth=shallow で、かつ evidence.method が文書化された 2 つのエスケープハッチ用プレフィックスのいずれかで始まる必要があります。evidence_unavailable:（PDF にアクセス不可 — ペイウォール、OA チェーンを使い切った、スキャン画像）または topic_mismatch:（PDF を最後まで読んだがトピックに合致しない — フェーズ 2 のランキングで誤検出）。スキムティアの depth=shallow は仕様どおりであり、ブロックされません。
G5 (→ 5)	source に citation_chase を含み（バックエンドの構成は問いません — openalex_citation_chase、s2_citation_chase、またはデフォルトのデュアル構成 openalex_s2_citation_chase）、かつ hits > 0 のクエリが 1 つ以上あること。
G6 (→ 6)	len(themes) ≥ 3、かつ len(tensions) ≥ 1、または「tensions がない」と言及する批評の指摘があること。
G7 (→ 7)	state.self_critique.appendix が空でなく、len(resolved) ≥ len(findings) であること。

MCP ツールによる補完

Semantic Scholar のカバレッジは、これらの補完手段には含まれません。スクリプト経由（build_citation_graph.py --source s2|both）で利用でき、フェーズ 4 の主要なバックエンドであり、補完機能ではありません。以下の MCP ツールは、真の意味での表層レイヤーです。タイムアウトしたり、名前が変更されたり、完全に利用できなくなったりする可能性があり、どのフェーズの出力もこれらに依存しません。

セッションで asta または Brave Search の MCP ツールを利用できる場合は、補完に使用してください。

• mcp__asta__search_papers_by_relevance — スクリプト検索の結果に対して、関連度を細かくランキングするのに適しています
• mcp__asta__get_citations — 1 件のシード論文をスポットチェックする場合、build_citation_graph.py より軽量です
• mcp__asta__snippet_search — アブストラクトを対象にした grep のような検索
• Brave Search — 非学術的な情報源（ブログ記事、プレスリリース、プレプリントに関する議論）

MCP ツールは設計上、信頼できないものとして扱ってください。タイムアウトしたり、利用できなかったりする場合があります。フェーズに不可欠な手順を MCP 呼び出しに依存させないでください。スクリプトが中核であり、MCP は表層です。

ホストネイティブの Web ツールによる情報の補強

ホストのランタイムによっては、設定不要で動作する Web ツールが組み込まれています。MCP サーバーも API キーも環境変数も必要ありません。上記の MCP ツールと併用するか、代わりに使って情報を補強してください。 MCP と同じルールを守り、補助入力としてのみ使い、クリティカルパスには決して含めないでください。

既知の環境（実際に利用できるツールはホストによって異なり、ツール名も変わるため、必ず確認してください）：

ホスト	Web 検索	Web 取得	備考
Claude Code	WebSearch	WebFetch	設定不要で、API キーも必要ありません
OpenCode	webfetch	webfetch	取得には単一のツールで対応します。検索には MCP が必要な場合があります
Codex CLI	バージョンによって異なります	バージョンによって異なります	ツールセットは Codex のプロファイルとプラグインによって異なります
OpenClaw / Hermes / pi-mono / Manus	環境によって異なります	環境によって異なります	これらのホストは通常、設定済みの MCP サーバー経由で処理します。上記の asta／Brave を参照してください

これらのツールが見つからない場合は、MCP の選択肢を利用してください。どちらも使えない場合でもワークフローは続行できます。スクリプト検索だけで十分な結果が得られるように設計されています。

8 フェーズのワークフローで、特に効果を発揮する場面：

1. フェーズ 1 — 時間に敏感な情報の補強。 過去 30 日間に答えが変わったトピックについては、学術情報源と並行してホストネイティブの Web 検索を実行します。arXiv／bioRxiv の遅れは 1〜3 日、OpenAlex／PubMed は約 1 週間です。WebSearch を使えば、プレプリントになる前のブログ／Twitter／プレスリリースの最新情報を見つけられます。
2. フェーズ 3 — PDF 取得の最終手段。 extract_pdf.py --doi/--url がすべて失敗した場合は、evidence_unavailable と記載する前に、WebFetch(landing_url_for_paper) を試して、出版社の HTML ページから抄録／知見を取得します。references/agent_prompts/phase3_deep_read.md の手順（d）を参照してください。
3. フェーズ 6 — 最新情報の確認。 自己批評の際に論文タイトルを WebSearch で検索し、論文の公開日より後に発表された撤回、訂正、再現失敗がないか確認します。

Web の検索結果を apply_ingest に渡さないでください。 ホストネイティブの検索結果は構造化されておらず（DOI／著者／掲載誌／情報源の帰属情報がありません）、research_state.json の論文レコードには追加せず、文章の文脈やファクトチェックに使います。コーパスの監査可能性を保ちます。

落とし穴（簡易リスト。詳細は references/pitfalls.md を参照してください）

1. 検索結果の最初のページを「文献」そのものと見なす — 複数のキーワードクラスターで検索し、引用文献をたどってください。
2. 根拠のない主張 — レポート内の重要な記述にはすべて、状態内の論文を示す [^id] が必要です。
3. 確証バイアス — 被引用数の多い主要論文に対する批判を積極的に検索してください。フェーズ 4 の特別なケースを参照してください。
4. プレプリントの混同 — arXiv／bioRxiv はプレプリントです。レポートではそのようにタグ付けし、証拠の重み付けにも反映してください。Lint に安全な表記規則：アンカーとマーカーは別々に記述します。[^id, preprint] ではなく [^id] *(preprint)* としてください（脚注の角括弧内のカンマは Markdown の解析と render_report.py --lint のチェックに失敗します）。
5. 掲載誌の偏り — 上位 N 件の 60% 超が 1 つのジャーナル／掲載先に集中している場合は、情報源を広げてください。
6. 著者の偏り — 単一の研究室や著者への集中についても同様です。
7. 最新情報の不足 — 「最先端」の枠組みでは直近 2 年が重要です。明示的に網羅できているか確認してください。
8. 古い MCP ツール名 — MCP サーバーはツール名を変更することがあるため、名前を決めつける前に、必ず利用可能なツールを一覧表示してください。スクリプトのパスは安定していますが、MCP の名前は変わります。
9. 一度きりの検索 — クラスターごとに 1 回ではなく、3 回以上の検索を見込んでください。
10. 自己批評を省く — きれいな草稿をそのまま提出したくなるときこそ、フェーズ 6 が最も多くの問題を見つけます。

やり取りの例

DMD の CRISPR 塩基編集を扱った一連の実行例（フェーズ 0 の質問の言い換えからフェーズ 7 のレポートと参考文献まで）は references/example_run.md にあります。ワークフロー全体が適切に実行された場合の例を確認したいときに一度読んでください。通常のセッションで不可欠なものではありません。

参考資料

必要な場合にのみ読み込まれるモジュール式ドキュメント：

• references/search_strategies.md — ブール検索クラスター、PICO、スノーボーリング、飽和度の計算
• references/source_selection.md — 質問ごとに使用するデータベース
• references/quality_assessment.md — CRAAP、ジャーナルの格付け、撤回確認、プレプリントの扱い
• references/report_templates.md — 5 つのアーキタイプとセクションごとのガイダンス
• references/pitfalls.md — 落とし穴の一覧を例とともに詳しく説明
• references/cli_contract.md — JSON エンベロープの形式、終了コード、--schema によるイントロスペクション、冪等性キャッシュ
• references/env_vars.md — 信頼境界の設定（SCHOLAR_*、NCBI_API_KEY、EXA_API_KEY、S2_API_KEY、PAPER_FETCH_SCRIPT）
• references/state_schema.md — research_state.json の形式と ID 正規化のルール
• references/example_run.md — エンドツーエンドの実行例（DMD の CRISPR 塩基編集）
• references/agent_prompts/phase3_deep_read.md — Phase 3 でエージェントを並列に展開する際に使う論文ごとのプロンプト