literature-engineer

文献エンジニア（エビデンス収集担当）

トリガーとルーティング

• トリガー：エビデンス収集担当、文献エンジニア、文献扩充、多路召回、snowballing、cited by、references、元信息增强、provenance。
• 使用する場合：ワークフローで、固定された検索ポリシーに従って候補文献を拡充し、追跡可能なメタデータを補完する必要がある場合。

目標：後続の重複排除・順位付け、マッピング、メモ、引用、執筆に使用する、大規模で検証可能な候補プールを構築します。

このスキルは意図的にエビデンスを優先します。検証可能なIDや来歴を伴う状態で目標件数に到達できない場合、正しい対応は処理を停止し、追加のエクスポートの提供またはネットワークの有効化を求めることであり、捏造することではありません。

読み込み順序

必ず読み込んでください：

• references/domain_pack_overview.md — ドメインパックがトピック固有の動作をどのように決定するか

ドメインパック（トピックの一致に応じて読み込み）：

• assets/domain_packs/llm_agents.json — LLM エージェント関連トピック用に固定された古典的論文・サーベイ論文の arXiv ID

スクリプトの範囲

scripts/run.py は次の用途に限って使用してください：

• 複数の検索経路を通じたオフラインインポート、正規化、来歴のタグ付け
• arXiv／Semantic Scholar API によるオンライン検索
• スノーボール拡張と重複排除
• 検索レポートの生成

run.py を次の用途に使用しないでください：

• 固定された arXiv ID リストのハードコード（ドメインパックを使用してください）
• トピック検出ロジックのハードコード（ドメインパックを使用してください）

入力

• queries.md
  • keywords、exclude、max_results、time window
• オプションのオフラインソース（任意の組み合わせ。すべて統合されます）：
  • papers/import.(csv|json|jsonl|bib)
  • papers/arxiv_export.(csv|json|jsonl|bib)
  • papers/imports/*.(csv|json|jsonl|bib)
• オプションのスノーボール用エクスポート（オフライン）：
  • papers/snowball/*.(csv|json|jsonl|bib)

出力

• papers/papers_raw.jsonl
  • 1行につき1レコード。最低限必要なフィールド：
    • title（文字列）、authors（文字列のリスト）、year（整数または""）、url（文字列）
    • 安定した識別子：arxiv_id および／または doi
    • abstract（文字列。オフラインモードでは空の場合があります）
    • source（文字列）＋ provenance（辞書のリスト）
• papers/papers_raw.csv（目視確認用）
• papers/retrieval_report.md（検索経路ごとの件数、不足メタデータの統計、次のアクション）

ワークフロー（複数の検索経路）

1. オフライン優先の統合：利用可能なオフラインエクスポートをすべて取り込みます（ファイルごとに来歴を付与します）。
2. オンライン検索（任意）：有効な場合は、キーワード検索ごとに arXiv API 検索を実行します。
3. スノーボール検索（任意）：シード論文から参考文献・被引用文献をたどって拡張するか（オンライン）、オフラインのスノーボール用エクスポートを統合します。
4. 正規化＋重複排除：ID／URL を正規化し、重複レコードを統合して provenance をまとめます。
5. レポート：カバレッジの分類と不足メタデータの件数を含む簡潔な検索レポートを作成します。

品質チェックリスト

• 候補プールが、捏造することなく、現在のワークフローで宣言された検索下限を満たしている。retrieval_policy.minimum_records が設定されたワークフローではその値を使用します。サーベイ用プロファイルでは、代わりに core_size からより厳しい候補プールの目標件数を算出する場合があります。
• 各レコードに安定した識別子（arxiv_id または doi、および url）がある。
• 各レコードに、どの検索経路／ファイル／API から取得したかを示す来歴がある。

スクリプト

クイックスタート

• uv run python .codex/skills/literature-engineer/scripts/run.py --help

すべてのオプション

• uv run python .codex/skills/literature-engineer/scripts/run.py --help を参照してください。
• queries.md から検索設定を読み込みます。
• オフライン入力（存在する場合は統合）：papers/import.(csv|json|jsonl|bib)、papers/arxiv_export.(csv|json|jsonl|bib)、papers/imports/*.(csv|json|jsonl|bib)。
• オプションのオフライン・スノーボール入力：papers/snowball/*.(csv|json|jsonl|bib)。
• オンラインでの拡張にはネットワークが必要です。--online および／または --snowball を使用してください。
• オンライン検索はベストエフォートです。一部の環境では arXiv API が不安定な場合があるため、必要に応じてスクリプトは Semantic Scholar 経由の検索も試みます。
• LLM エージェント関連のトピックでは、キーワード検索で見つからない場合でも ref.bib に必須引用文献を含められるよう、スクリプトはベストエフォートで固定された arXiv の id_list 取得（ReAct／Toolformer／Reflexion／Voyager／Tree-of-Thoughts などの定番論文と、少数の先行サーベイ論文のシードセット）も実行します。
• 外部ドメインへの HTTPS/TLS 接続が不安定な場合、Semantic Scholar 経由の取得には r.jina.ai プロキシを使用するため、手動でエクスポートしなくてもパイプラインを自動的に起動できます。
• 一時的なネットワークエラーによりオンライン実行でレコードが 0 件になった場合は、再実行するだけで解決することがよくあります（パイプラインはデータを捏造しません）。

使用例

• オフラインのインポートのみ：

  • エクスポートを papers/imports/ に配置してから、次を実行します：
    • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace>

• オフライン入力を明示的に指定（複数の経路）：

  • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace> --input path/to/a.bib --input path/to/b.jsonl

• オンラインでの arXiv 検索（ネットワークが必要）：

  • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace> --online

• スノーボール検索（オフラインのスノーボール用エクスポートを指定しない場合はネットワークが必要）：

  • uv run python .codex/skills/literature-engineer/scripts/run.py --workspace <workspace> --snowball

トラブルシューティング

問題：現在の Workflow の候補プール目標に到達できない

症状：

• papers/papers_raw.jsonl の件数が、ロックされた Workflow で宣言された明示的またはプロファイルから導出された最小値を下回っています。

原因：

• 提供されたオフラインエクスポートが少量のみです。
• ネットワークがブロックされているため、オンライン検索／スノーボール検索を実行できません。

解決策：

• papers/imports/ に追加のエクスポートを配置します（複数の経路／クエリ）。
• papers/snowball/ にスノーボール用エクスポートを配置します。
• ネットワークを有効にして、--online --snowball を指定して再実行します。

問題：安定した ID がないレコードが多数ある

症状：

• レポートに、arxiv_id と doi が空のエントリが多数表示されます。

解決策：

• 安定した ID を含む arXiv／OpenReview／ACL のエクスポートを優先してください。
• ネットワークを利用できる場合は、--online を指定して再実行し、arXiv ID を補完します。
• 下流の引用生成の前に、ID のないエントリを除外してください。