Datasheet spec extractor

面向 AI Agent：把元器件 datasheet PDF 抽取为版本化、机读的结构化规格 JSON，缓存在项目本地，供原理图 / PCB / 仿真 / 热分析等下游分析器查询。提取本身由你（LLM）读取选定页完成，脚本只负责选页、缓存、打分、校验与对外查询。

何时使用

• 用户要求「提取 / 读取 / 核对某元器件规格书参数」，或问「MPN X 的规格是什么」「核对 U1 引脚名是否与 datasheet 一致」。
• 下游分析器需要可信 IC 知识（EN 引脚阈值、是否有 PG 输出、USB 外设速度、轨电压）才能跑 IC 感知检查，而 datasheets/extracted/ 为空。
• 刚下载完 datasheet PDF，或评审提示证据不足、trust_level: low，需要补提取把它抬到 mixed/high。

不该用边界：

• 不负责下载 PDF（由 digikey / mouser / lcsc / element14 等分销商技能负责）。
• 没有跨项目共享库，每个项目的提取只存在本项目 <project>/datasheets/extracted/。
• 不做电路仿真、不替代分析器本身的规则判定，只产出它们消费的数据。
• 任何 datasheet 未明确给出的字段一律填 null，不猜测、不插值。

步骤

1. 定位项目 datasheets/ 下的目标 PDF（按 MPN）。
2. 查缓存：若 extracted/<MPN>.json 已存在且不 stale（版本、PDF 哈希、分数、90 天时效都通过），直接复用。
3. 选页：对该 PDF 跑选页启发式，得到引脚表 / 绝对最大额定 / 推荐工作条件 / 电气特性 / 典型应用电路所在页。
4. 读取选定页，按 Schema（当前 EXTRACTION_VERSION = 2）填写结构化 JSON。
5. 打分：分数 >= MIN_SCORE (6.0) 才缓存；低分按 retry_count < MAX_RETRIES (3) 重试，重试时读 issues 定向补读相应章节，保留最高分版本。
6. 缓存写入并由缓存管理器自动补全 source_pdf_hash、extraction_date、extraction_version、score_breakdown。
7. 下游通过 datasheet_features.py 查询；如需核对原理图用法，跑校验。

指令

脚本是 Python 模块 API（import 调用，不是 CLI）。在 scripts/ 目录下：

# 1. 选页
from datasheet_page_selector import suggest_pages
pages = suggest_pages(pdf_path, mpn="TPS61023DRLR", category="switching_regulator")
# 页预算默认 10 页；MCU/FPGA/SoC 为 15 页；总是含第 1 页与最后一页

# 2. 打分（expected_pin_count 用 package 的引脚数，驱动引脚覆盖率扣分）
from datasheet_score import score_extraction
res = score_extraction(extraction, expected_pin_count=6)
# res: {"total":8.2,"pin_coverage":..,"voltage_ratings":..,"issues":[...],"sufficient":True}

# 3. 缓存
from datasheet_extract_cache import (
    resolve_extract_dir, get_cached_extraction, cache_extraction,
    is_extraction_stale, EXTRACTION_VERSION, MIN_SCORE)
extract_dir = resolve_extract_dir(project_dir="/path/to/project")
stale, reason = is_extraction_stale(extract_dir, mpn)   # reason: not_cached/schema_upgrade/pdf_changed/low_score/age
if res["sufficient"]:
    cache_extraction(extract_dir, mpn, extraction, source_pdf="TPS61023DRLR.pdf")

# 4. 下游消费
from datasheet_features import (
    get_regulator_features, get_mcu_features, get_pin_function, is_extraction_available)
feat = get_regulator_features("TPS61023DRLR")  # None 表示无可用提取 → 检测器发 INFO 并跳过
fn = get_pin_function("TPS61023DRLR", "EN")    # 'VIN'/'VOUT'/'EN'/'PG'/'SW'/'FB'/'GND'/... 或 None

# 5. 校验提取 vs 原理图用法
from datasheet_verify import run_datasheet_verification
report = run_datasheet_verification(analysis, project_dir="/path/to/project")

Schema 顶层字段：mpn / manufacturer / category / package / description / topology / pins[] / features / peripherals / absolute_maximum_ratings / recommended_operating_conditions / electrical_characteristics / application_circuit / spice_specs / extraction_metadata。详见 references/extraction-schema.md。

示例

提取 TI TPS61023DRLR（升压转换器，SOT-23-6）：

{
  "mpn": "TPS61023DRLR",
  "manufacturer": "Texas Instruments",
  "category": "switching_regulator",
  "package": "SOT-23-6 (6-pin)",
  "topology": "boost",
  "pins": [
    {"number":"1","name":"EN","function":"EN","type":"digital","direction":"input",
     "threshold_high_v":1.2,"threshold_low_v":0.4,
     "required_external":"Connect to VIN for always-on, or logic control. Do not float."},
    {"number":"4","name":"SW","function":"SW","type":"power","voltage_abs_max":6.0,
     "required_external":"Connect to inductor (0.47-2.2uH recommended)"}
  ],
  "features": {"has_pg": false, "has_soft_start": true, "iss_time_us": 12.5},
  "recommended_operating_conditions": {"vin_min_v":0.5,"vin_max_v":5.5,"temp_min_c":-40,"temp_max_c":85},
  "electrical_characteristics": {"vref_v":0.595,"switching_frequency_khz":1200},
  "application_circuit": {"topology":"boost","inductor_recommended":"1uH, Isat > 3.6A",
     "vout_formula":"Vout = 0.595 * (1 + R1/R2)"},
  "spice_specs": {"vref": 0.595},
  "extraction_metadata": {"source_pdf":"TPS61023DRLR.pdf","extracted_from_pages":[1,5,6,9]}
}

打分：引脚覆盖 35% + 电压额定 25% + 应用信息 20% + 电气特性 10% + SPICE 10%，加权求和到 0–10；该例 total ≈ 9.1，>= 6.0 故缓存。

注意事项

• 选不同值：vref_v / switching_frequency_khz 取 Typ；阈值电压、静态电流、传播延迟取 Max；dropout_mv 取最坏（Min 余量）；SPICE 参数取 Typ。
• 绝对最大额定 ≠ 工作条件，二者勿混；逐引脚电压限值进 pins[].voltage_abs_max，供电/温度进顶层 absolute_maximum_ratings。
• category 必须用 Schema 列出的精确字符串（如 switching_regulator），它决定打分规则与下游分类。
• required_external 是设计审查自动化最关键字段，尽量用 datasheet 原文，带数值与布局约束。
• MPN 不可截断（TPS61023 与 TPS61023DRLR 规格可能不同）；族系 datasheet 注意只取对应型号那一行。
• None 契约：整个返回为 None = 无提取（检测器发 INFO 跳过）；字段为 None = datasheet 未给（未知）；False = 明确没有该特性；0 = 数值零。四者不可混淆。
• category、features、peripherals.usb、pins[].function 为 v2 新增；旧版本提取被视为不可用，需重提。
• 阈值若以 VDD 分数给出（如 0.7×VDD），description 记原式，字段存按额定电压算出的绝对值。

互见

• references/field-extraction-guide.md：各厂商（TI / ST / NXP / Microchip / Espressif / ADI）章节命名与逐字段定位、常见陷阱。
• references/quality-scoring.md：五维扣分细则、阈值、staleness 判定。
• references/consumer-api.md：下游 datasheet_features.py 与直连缓存访问、INFO 跳过模式、质量门。
• references/extraction-schema.md：完整字段、category 取值、版本历史。

---

本条采编自 aklofas/kicad-happy（MIT），为面向 AI Agent 消费的中文适配重写，非逐字翻译。