pubmed-database

PubMed API

前提条件

1. uv：uv のスキルを読み、セットアップ手順に従って、uv がインストールされ、PATH に設定されていることを確認してください。
2. ユーザーへの通知：ワークスペースのルートディレクトリに .licenses/pubmed_database_LICENSE.txt がまだ存在しない場合は、（1）https://pubmed.ncbi.nlm.nih.gov/disclaimer/ と https://www.ncbi.nlm.nih.gov/home/about/policies/ の利用条件を確認し、このスキルで取得した論文に制限がないか、必ずライセンスを確認するようユーザーに目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。
3. .env ファイル：ホームディレクトリに .env ファイルが存在することを確認してください。存在しない場合は作成してください。
4. NCBI_API_KEY（任意）：NCBI E-utilities のレート制限を毎秒 3 件から 10 件に引き上げます。このスキルはキーがなくても動作しますが、ユーザーが多数のクエリを予定している場合や 429 エラーが発生した場合は、キーの使用を推奨します。https://www.ncbi.nlm.nih.gov/account/settings/ で無料のキーを登録できます。このスキルがユーザーのリクエストに関連すると判断した場合、キーの有無を確認し、必要に応じて取得を依頼するために、credentials スキルの安全な認証情報プロトコルを必ず使用してください。
5. USER_EMAIL（任意）：NCBI に呼び出し元を識別させます（NCBI の利用規約で推奨されています）。このスキルがユーザーのリクエストに関連すると判断した場合、この認証情報の有無を確認し、必要に応じて取得を依頼するために、credentials スキルの安全な認証情報プロトコルを必ず使用してください。

このスキルは、scripts/pubmed_api.py を介して NCBI PubMed および PubMed Central API に CLI でアクセスします。検索、取得、リンク、全文、スペルチェック、探索、引用文献の照合、キャッシュを網羅する 10 個の機能を備えた単一の CLI です。

基本ルール

• API の使用：レート制限を自動管理し、API の不正利用を防ぐ、付属のラッパー scripts/pubmed_api.py を必ず使用してください。NCBI_API_KEY 環境変数を設定すると、レート制限が毎秒 3 件から 10 件に引き上げられます。その他の方法（curl、wget、手書きのコードなど）で API にクエリを送信することは、厳禁です。
• JSON の処理：幻覚やコンテキストのあふれを防ぐため、jq を使用して JSON 出力をフィルタリングおよび変換してください（jq が利用できない場合は python の同等機能を使用してください）。
• 一時ファイル：JSON ファイルで作業ディレクトリを散らかさないよう、現在のディレクトリ内に一時ディレクトリを使用してください。複数のエージェントやタスクを並行して実行する場合は、ファイルの衝突を避けるため、それぞれに一意のサブディレクトリ名（例：tmp_$TASK_ID/）を使用してください。
• 通知：このスキルを使用した場合は、その旨を出力に記載し、出力の作成に使用したすべての論文の URL を列挙してください。

スキルフォルダーの構成

• SKILL.md - このファイル
• scripts/pubmed_api.py - スキルの CLI
• references/ - 詳細な機能仕様を含むディレクトリ
  • advanced-linking.md
  • advanced-search.md
  • bulk-workflows.md
  • citation-matching.md
  • cross-database-linking.md
  • fetch-and-resolve.md
  • search-and-discovery.md
  • utilities.md

CLI の使用方法

uv run scripts/pubmed_api.py <output_file> <function_name> <required_args> [--flag value ...]

• 位置引数：引数は位置引数です。リスト引数は、スペースを入れずにカンマ区切りの文字列として渡します（例： "35113657,31234568"）。
• フラグオプション：オプションの引数は、位置引数の代わりに --flag value として渡せます。
• 出力の処理：成功時は、JSON が output_file に書き込まれます。エラー時は、プロセスはゼロ以外のコードで終了し、出力ファイルは書き込まれません。

使用例

uv run scripts/pubmed_api.py ./search_results.json search_pubmed "BRCA1" --max_results 5
cat ./search_results.json | jq '.[]' -r
uv run scripts/pubmed_api.py ./abstracts.json fetch_article_abstracts "35113657"
cat ./abstracts.json | jq '.[0].title' -r

基本的なレシピ

次の呼び出し用に PMID を結合する（最も一般的な連鎖パターン）：

cat ./search_results.json | jq -r 'join(",")'

抄録を重要なフィールドに絞り、長い抄録を切り詰める：

cat ./abstracts.json | jq '[.[] | {pmid, title, snippet: (.abstract // "")[:500]}]'

キーワードでフィルタリングする（null 安全）：

cat ./abstracts.json | jq '[.[] | select((.title // "") | contains("Review"))]'

コンテキスト管理と精度

大規模な検索結果（抄録が10件を超える場合）を処理する際は、次の手順に従ってください。

1. 早めに絞り込む：JSON 全体をコンテキストに読み込む前に、jq を使って抄録内のキーワードを確認します。
2. 簡潔化：特に指示がない限り、title フィールドと abstract フィールドのみを抽出します。著者一覧やメタデータはノイズになります。
3. 一括操作（N > 10）：ID を1件ずつ取得したり処理したりするのは避けます。API と History Server は一括取得を想定して設計されています。データを単一のターンですべて取得し、シェルパイプラインで結果を簡潔化してからコンテキストに読み込みます。これにより、ターンの使い切りとコンテキストのオーバーフローを防げます。
4. 根拠の明示：検索結果が見つからない場合、内部知識を使って特定の識別子（PMID、CID、Gene ID）を提示してはいけません。現在のデータベースの状態に基づいた結果となるよう、ツールの出力を正確に報告します。
5. 検索の終了：存在しない可能性のある論文を探すよう依頼された場合は、質が高く多様な検索クエリを3～5件に絞って調査します。明示的に網羅的な調査を指示されていない限り、これらの試行後に該当する結果がなければ、条件を満たす論文はないと結論づけ、それ以上の検索を続けません。

関数

⚠️ 必須：関数グループ内の関数を呼び出す前に、必ずそのグループにリンクされているリファレンスファイルを読んでください。以下の表では、各関数が「何を」するかだけを説明しており、「どのように」呼び出すかは説明していません。引数名、引数の順序、フラグ、出力スキーマは、リファレンスファイルにのみ記載されています。関数名から引数を推測してはいけません。 リファレンスを読まずに関数を呼び出すと、誤った呼び出しになります。

検索

• search_pubmed：自由形式または構造化された NCBI クエリに一致する PMID を検索します。
• global_database_discovery：すべての NCBI データベースを対象に、クエリに一致するレコード数を数えます。

取得と解決

• fetch_article_abstracts：複数の PMID のメタデータと抄録を取得します。
• get_full_text_pmc：PMC からオープンアクセスの全文を取得します。
• fetch_database_summary：任意の NCBI データベースの不透明な UID を、人が読めるメタデータに変換します。

データベース間のリンク

• find_linked_biological_data：ソースレコードにリンクされた、他の NCBI データベース内のレコードを検索します。
• discover_available_links：指定したレコードで利用可能な ELink のリンク名をすべて一覧表示します。

一括ワークフロー

PMID が約10件を超える場合は、ID を1件ずつ処理するのは避けてください。cache_results_history を使って PMID を NCBI History Server にアップロードし、セッションハンドル（webenv + query_key）を取得します。その後、そのハンドルを fetch_article_abstracts または find_linked_biological_data に渡して、1回の呼び出しで一括処理します。jq のシェルパイプラインと連携させて、結果を簡潔化してからコンテキストに読み込みます。これにより、ターンの使い切りとコンテキストのオーバーフローを防げます。完全なワークフローのレシピ（検索→取得、データベース間の調査、引用の解決、データを簡潔化した一括取得）については、リファレンスを参照してください。

• cache_results_history：一括取得用に PMID を NCBI History Server にアップロードします。

ユーティリティ

• verify_medical_spelling：検索前に生物医学用語のスペルをチェックします。
• match_raw_citations：不完全な書誌引用を PMID に解決します。