datasheets

データシートスキル

関連スキル

スキル	関係
digikey / mouser / lcsc / element14	提供元 — このスキルが抽出するPDFを <project>/datasheets/ にダウンロードします
kicad	主な利用元 — VM-001/PU-001/FS-001/PP-001/LR-001/XT-001 と Phase 4b の検索検出器（AM-001/OV-001/TJ-001/FT-001/EX-001）が、検証済みICの情報を得るため lookup(mpn) 経由で抽出データを照会します
emc	利用元 — スイッチング周波数、パッケージのRθ_JA、動作電圧のデータがEMCヒューリスティクスを強化します
spice	利用元 — SPICEモデルの有無とIBISデータが、シミュレーション準備状況のチェックに利用されます
thermal	利用元 — パッケージのRθ_JAと接合温度の上限値が、Tj推定（TS-001..TJ-001）の基準になります
bom	間接利用 — 構造化された抽出データの網羅性が、BOM検証の信頼度に影響します

引き継ぎのガイダンス： このスキルは、利用元を支えるインフラです。一般的なフローは ディストリビュータースキルがPDFをダウンロード → datasheetsスキルが抽出 → 解析スキルが照会 です。（a）ユーザーが特定のMPNの抽出または検証を依頼した場合、（b）解析スキルが trust_level: low を報告し、その原因がMPNごとの抽出品質にある場合、または（c）新しいMPNがBOMに追加され、下流の検出器で検証済み仕様を利用できるようにする場合は、このスキルを直接使用してください。ユーザーが設計レビューだけを求めている場合は、このスキルを単独で実行せず、代わりにkicadワークフローの「データシートを同期」ステップから呼び出してください。

目的

コンポーネントのデータシートPDFから構造化された機械可読な仕様を抽出し、解析スキルから利用できるようにします。<project>/datasheets/ にダウンロードされたPDF（ダウンロードは digikey、mouser、lcsc、element14 などのディストリビュータースキルが担当）を対象とします。

対象範囲

このスキルが担当するもの：

• 抽出スキーマ — MPNごとの仕様を表す標準的なJSON構造です。v1.4には、schemas/ に6つのJSON Schema Draft 2020-12スキーマ（base、pinout、spec_value、regulator、extraction、manifest）と、5つのv1.4カテゴリ拡張（diode、transistor、opamp、mcu、crystal）が含まれます。v1.3のキャッシュ形式（scripts/datasheet_extract_cache.py の EXTRACTION_VERSION）も互換性のため引き続き読み込まれます。
• 型付きアクセスレイヤー（v1.4） — datasheet_types/ パッケージは、DatasheetFacts、SpecValue、Pin、Pinout、lookup()、best()、trusted()、has_data() を公開します。新しい利用元にはすべて、この利用が推奨されます。
• PDFページの選択 — ピン配置、電気特性、用途、SPICEモデルが含まれる可能性の高いページを選ぶためのヒューリスティクスです。
• 品質スコアリング — v1.4では3つの側面からなる評価基準（ピン配置の完全性、基本情報の完全性、カテゴリ拡張の完全性、0～100のスケール）を使用します。従来のキャッシュには、v1.3の5つの側面に基づく加重評価基準が引き続き適用されます。
• 利用元向けAPI — v1.4の型付きアクセスには scripts/datasheet_lookup.py、v1.3の辞書形式ヘルパー（get_regulator_features、get_mcu_features、get_pin_function）には scripts/datasheet_features.py を使用します。v1.3のヘルパーはv1.4のキャッシュも読み込み、従来の検出器コード向けにv1.3の辞書形式へ変換します。廃止はv1.6を予定しています。
• 検証 — datasheet_verify.py（v1.3、スキーマと使用箇所の相互チェック）と datasheet_verify_v14_extraction（v1.4、power_domain参照の解決、recommended ≤ absolute、レギュレーターピン参照の存在確認）です。

対象外

• PDFのダウンロードはしません。 これはディストリビュータースキル（digikey、mouser、lcsc、element14）が担当します。
• グローバルライブラリはありません。 各プロジェクトの抽出データは <project>/datasheets/extracted/ に保存されます。プロジェクト間で共有されるキャッシュはありません。

キャッシュの場所

<project>/
  design.kicad_sch
  datasheets/
    TPS61023DRLR.pdf        # downloaded by distributor skills
    extracted/
      manifest.json         # extraction manifest (legacy name: index.json)
      TPS61023DRLR.json     # structured extraction (this skill's output)

リファレンスガイド

• references/extraction-schema.md — 正式なスキーマと各フィールドの定義
• references/field-extraction-guide.md — 一般的なベンダー（TI、ST、NXP、Espressif、Microchip）のデータシートから各フィールドを見つける方法
• references/quality-scoring.md — 評価基準の詳細とスコアのしきい値
• references/consumer-api.md — kicad/emc/spice/thermal が抽出データを利用する方法
• references/cache-layout.md — v1.4 キャッシュディレクトリの規約（MPN ごとのファイル、_families/ の予約、古さの判定ルール）

エントリーポイントスクリプト

• scripts/datasheet_extract_cache.py — v1.3 キャッシュマネージャー、リゾルバー、インデクサー
• scripts/datasheet_page_selector.py — ページ選択のヒューリスティクス（v1.3 と v1.4 の両パイプラインで使用）
• scripts/datasheet_score.py — v1.3 抽出品質スコアリング
• scripts/datasheet_verify.py — 抽出データと回路図での使用状況の相互確認（v1.3、および v1.4 の verify_v14_extraction モード）
• scripts/datasheet_lookup.py — v1.4 型付きの lookup(mpn) → DatasheetFacts ファサードと古さの検出
• scripts/datasheet_features.py — v1.3 コンシューマーヘルパー API（_derive_*_v14 トランスレーターを介して v1.4 キャッシュも読み込み）
• scripts/plan_extraction.py — v1.4 オーケストレーション計画ジェネレーター（フェーズ 3 抽出パイプライン）
• scripts/merge_results.py — v1.4 タスクごとの結果バリデーターとマージャー
• datasheet_types/ — v1.4 型付きアクセスレイヤーパッケージ（DatasheetFacts、SpecValue、Pin、Pinout、lookup、best、trusted、has_data）

抽出ワークフロー

python3 skills/datasheets/scripts/plan_extraction.py <project> を実行してオーケストレーション計画を生成し、その後 merge_results.py を実行してタスクごとの出力を検証、マージします。scout→plan→dispatch→merge の全手順については、references/extraction-pipeline.md を参照してください。

抽出データの利用（v1.4 型付き API）

推奨されるコンシューマー向けインターフェースは、型付きの lookup(mpn, cache_dir=...) ファサードと、datasheet_types の信頼度判定ヘルパーです。次のようにインポートします。

import sys, pathlib
sys.path.insert(0, str(pathlib.Path(__file__).parent.parent / "datasheets"))
from datasheet_types import lookup, has_data, best, trusted

# Returns Optional[DatasheetFacts]. None on cache miss / stale PDF / low quality.
facts = lookup("TPS61023DRLR", cache_dir=pathlib.Path("datasheets/extracted"))
if facts is None:
    return  # heuristic-only path; no datasheet evidence available

# Field-level trust gating — every SpecValue list runs through has_data() / best() / trusted().
pu_range = facts.base.recommended_pullup_range  # Optional[list[SpecValue]]
if has_data(pu_range):
    # Most-trusted single value (first SpecValue meeting threshold, preserves extractor order).
    rec = best(pu_range, min_confidence="medium")  # Optional[SpecValue]
    if rec is not None and rec.min is not None:
        ...  # use rec.min, rec.max, rec.typ, rec.unit, rec.evidence.{page,section,confidence}

# All SpecValues at threshold (for multi-value fields like absolute_max).
hi_conf = trusted(facts.base.absolute_max.get("VDD", []), min_confidence="high")

防御的なパターン（kicad/SKILL.md §「Probing Analyzer JSON」と同様）：

• lookup() は、キャッシュミス、PDF が古い場合（PDF が抽出データより新しい場合）、または品質スコアが設定済みの下限を下回る場合に None を返します。必ず if facts is None: return でガードしてください。
• カテゴリー拡張は DatasheetFacts では任意です。その部品が regulator カテゴリーに属さない場合、facts.regulator は None です。参照を解除する前に確認してください。
• SpecValue のリストは None（フィールド未抽出）、[]（抽出済みだが空）、または list[SpecValue] のいずれかです。has_data() は最初の 2 つを False にまとめます。信頼度を判定するには、best() / trusted() と組み合わせてください。
• SpecValue.min / .max / .typ はそれぞれ Optional[float] です。.typ のみを持ち（範囲を持たない）SpecValue に対して .min / .max を使った > / < 比較を行うと TypeError が発生します。数値にアクセスするたびに、明示的な is not None の連鎖でガードしてください。
• confidence は "low" / "medium" / "high" のいずれかです。これ以外の文字列を指定して best() / trusted() を呼び出すと、ValueError が発生します。

v1.3 互換シム

レガシー検出器は、引き続き scripts/datasheet_features.py の get_regulator_features(mpn) / get_mcu_features(mpn) / get_pin_function(mpn, pin) を呼び出します。これらは v1.4 キャッシュも読み込み、v1.3 の辞書形式に変換します。提供終了は v1.6 を予定しています。新しいコードでは lookup() を直接使用してください。

このスキルを実行するタイミング

• sync_datasheets_digikey.py、sync_datasheets_lcsc.py、または同等の方法でデータシートをダウンロードした直後です。抽出しないと、IC を考慮したチェック（VM-001 レール電圧、PS-001 パワーグッド、PR-004 USB、DP-002 USB 速度の分類）は、未知の IC に対するヒューリスティックにフォールバックします。
• データシートはあるものの datasheets/extracted/ が空の新しいプロジェクトで、アナライザーを実行する前です。アナライザー自身が抽出処理を行うことはありません。
• メーカーの根拠が不足しているため、レビューで信頼レベルが低いと指摘された場合です。電源レギュレーター、MCU、高速周辺機器が参照する IC を抽出すると、通常 trust_level: low から mixed または high に変わります。
• ユーザーがピンの検証を求めた場合です（「U1 のピン名がデータシートと一致するか確認してください」）。このスキルのキャッシュ済みの抽出結果が、信頼できる情報源です。