datasheets

Datasheets Skill

相关技能

技能	关系
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）通过 lookup(mpn) 查询提取结果，以获取经过验证的 IC 知识
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) BOM 中添加了新的 MPN，下游检测器应获取其已验证规格。如果用户只是想进行设计评审，不要单独运行此技能——应在 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 使用三维评分标准（引脚布局完整度、基础完整度、类别扩展完整度，0–100 分）。旧版缓存仍使用 v1.3 的五维加权评分标准。
• 使用方 API — scripts/datasheet_lookup.py 提供 v1.4 类型化访问；scripts/datasheet_features.py 提供 v1.3 字典格式辅助函数（get_regulator_features、get_mcu_features、get_pin_function）——v1.3 辅助函数可双向读取 v1.4 缓存，并转换为 v1.3 字典格式，以供旧版检测器代码使用。计划在 v1.6 弃用。
• 验证 — datasheet_verify.py（v1.3，交叉检查架构与用法）以及 datasheet_verify_v14_extraction（v1.4，确保 power_domain 引用可解析、推荐值 ≤ 绝对值、稳压器引脚引用存在）。

非目标

• 不下载 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 §「探测 Analyzer JSON」类似）：

• lookup() 在缓存未命中、PDF 已过期（PDF 比提取结果更新）或质量评分低于配置下限时返回 None。务必使用 if facts is None: return 进行保护。
• DatasheetFacts 上的类别扩展是可选的。如果器件不属于 regulator 类别，facts.regulator 就是 None——访问其内容前应先检查。
• SpecValue 列表可能是 None（字段未提取）、[]（已提取但为空）或 list[SpecValue]。has_data() 会将前两种情况都归为 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 的引脚名称是否与数据手册一致”）——此技能缓存的提取结果是权威来源。