datasheets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Datasheets Skill

Datasheets 技能

Related Skills

Skill	Relationship
`digikey` / `mouser` / `lcsc` / `element14`	Producers — download the PDFs under `<project>/datasheets/` that this skill extracts from
`kicad`	Primary consumer — VM-001/PU-001/FS-001/PP-001/LR-001/XT-001 + Phase 4b lookup detectors (AM-001/OV-001/TJ-001/FT-001/EX-001) query extractions via `lookup(mpn)` for verified-IC knowledge
`emc`	Consumer — switching-frequency, package-Rθ_JA, and operating-voltage data sharpen EMC heuristics
`spice`	Consumer — SPICE model presence + IBIS data feed simulation-readiness checks
`thermal`	Consumer — package Rθ_JA + junction temperature limits drive Tj estimates (TS-001..TJ-001)
`bom`	Indirect — coverage of structured extractions affects BOM verification confidence

技能	关联关系
`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和结温限值用于驱动结温估算（TS-001..TJ-001）
`bom`	间接关联 — 结构化提取结果的覆盖范围会影响BOM验证的置信度

Purpose

目标

Extract structured, machine-readable specifications from component datasheet PDFs and make them available to analyzer skills. Works on whatever PDFs are downloaded under

<project>/datasheets/

(downloads are owned by distributor skills like

digikey

mouser

lcsc

element14

从元件数据手册PDF中提取结构化、机器可读的规格信息，并提供给分析器技能使用。处理所有下载至

<project>/datasheets/

路径下的PDF文件（PDF下载由

digikey

、

mouser

、

lcsc

、

element14

等分销商技能负责）。

Scope

职责范围

This skill owns:

Extraction schemas — canonical JSON structures for per-MPN specs. v1.4 ships 6 JSON Schema Draft 2020-12 schemas under
```
schemas/
```
(
```
base
```
,
```
pinout
```
,
```
spec_value
```
,
```
regulator
```
,
```
extraction
```
,
```
manifest
```
) plus 5 v1.4 category extensions (diode, transistor, opamp, mcu, crystal). v1.3 cache format (
```
EXTRACTION_VERSION
```
in
```
scripts/datasheet_extract_cache.py
```
) is still read for compat.
Typed access layer (v1.4) —
```
datasheet_types/
```
package exposes
```
DatasheetFacts
```
,
```
SpecValue
```
,
```
Pin
```
,
```
Pinout
```
,
```
lookup()
```
,
```
best()
```
,
```
trusted()
```
,
```
has_data()
```
. Recommended for all new consumers.
PDF page selection — heuristics to pick pages most likely to contain pinouts, e-chars, applications, SPICE models.
Quality scoring — v1.4 uses a three-dimension rubric (pinout completeness, base completeness, category-extension completeness, 0–100 scale). v1.3 5-dimension weighted rubric still applies to legacy caches.
Consumer APIs —
```
scripts/datasheet_lookup.py
```
for v1.4 typed access;
```
scripts/datasheet_features.py
```
for the v1.3 dict-shaped helpers (
```
get_regulator_features
```
,
```
get_mcu_features
```
,
```
get_pin_function
```
) — the v1.3 helpers dual-read v1.4 caches and translate to v1.3 dict shape for legacy detector code. Sunset planned for v1.6.
Verification —
```
datasheet_verify.py
```
(v1.3, schema-vs-usage cross-check) plus
```
datasheet_verify_v14_extraction
```
(v1.4, power_domain references resolve, recommended ≤ absolute, regulator pin references exist).

本技能负责：

提取Schema — 针对每个MPN规格的标准JSON结构。v1.4版本在
```
schemas/
```
目录下提供6个JSON Schema Draft 2020-12 Schema（
```
base
```
、
```
pinout
```
、
```
spec_value
```
、
```
regulator
```
、
```
extraction
```
、
```
manifest
```
），以及5个v1.4分类扩展（二极管、晶体管、运算放大器、微控制器、晶体）。为兼容旧版本，仍支持读取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版本，Schema与使用情况交叉检查）以及
```
datasheet_verify_v14_extraction
```
（v1.4版本，电源域引用解析、推荐值≤绝对值、调节器引脚引用存在性验证）。

Non-goals

非目标

No PDF downloading. That is owned by distributor skills (
```
digikey
```
,
```
mouser
```
,
```
lcsc
```
,
```
element14
```
).
No global library. Each project's extractions live in
```
<project>/datasheets/extracted/
```
. There is no shared cross-project cache.

不负责PDF下载。该功能由分销商技能（
```
digikey
```
、
```
mouser
```
、
```
lcsc
```
、
```
element14
```
）负责。
不提供全局库。每个项目的提取结果存储在
```
<project>/datasheets/extracted/
```
路径下，不提供跨项目共享缓存。

Cache location

缓存位置

<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)

<project>/
  design.kicad_sch
  datasheets/
    TPS61023DRLR.pdf        # 由分销商技能下载
    extracted/
      manifest.json         # 提取清单（旧版名称：index.json）
      TPS61023DRLR.json     # 结构化提取结果（本技能的输出）

Reference guides

参考指南

```
references/extraction-schema.md
```
— canonical schema, every field defined
```
references/field-extraction-guide.md
```
— how to find each field in datasheets from common vendors (TI, ST, NXP, Espressif, Microchip)
```
references/quality-scoring.md
```
— rubric details, score thresholds
```
references/consumer-api.md
```
— how kicad/emc/spice/thermal consume extractions
```
references/cache-layout.md
```
— v1.4 cache directory convention (per-MPN files,
```
_families/
```
reservation, staleness rules)

```
references/extraction-schema.md
```
— 标准Schema文档，定义所有字段
```
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/
```
预留目录、过期规则）

Entry-point scripts

入口脚本

```
scripts/datasheet_extract_cache.py
```
— v1.3 cache manager, resolver, indexer
```
scripts/datasheet_page_selector.py
```
— page selection heuristics (used by both v1.3 and v1.4 pipelines)
```
scripts/datasheet_score.py
```
— v1.3 extraction quality scoring
```
scripts/datasheet_verify.py
```
— cross-check extraction vs schematic usage (v1.3 + v1.4
```
verify_v14_extraction
```
mode)

scripts/datasheet_lookup.py

— v1.4 typed

lookup(mpn) → DatasheetFacts

facade with staleness detection

```
scripts/datasheet_features.py
```
— v1.3 consumer helper API (dual-reads v1.4 caches via
```
_derive_*_v14
```
translators)
```
scripts/plan_extraction.py
```
— v1.4 orchestration plan generator (Phase 3 extraction pipeline)
```
scripts/merge_results.py
```
— v1.4 per-task result validator + merger

datasheet_types/

— v1.4 typed access layer package (

DatasheetFacts

SpecValue

Pin

Pinout

lookup

best

trusted

has_data

)

```
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

facade，带过期检测

```
scripts/datasheet_features.py
```
— v1.3消费者辅助API（通过
```
_derive_*_v14
```
转换器兼容读取v1.4缓存）
```
scripts/plan_extraction.py
```
— v1.4 编排计划生成器（Phase 3提取流水线）
```
scripts/merge_results.py
```
— v1.4 任务结果验证与合并工具

datasheet_types/

— v1.4 类型化访问层包（

DatasheetFacts

、

SpecValue

、

Pin

、

Pinout

、

lookup

、

best

、

trusted

、

has_data

）

Extraction workflow

提取工作流

Run

python3 skills/datasheets/scripts/plan_extraction.py <project>

to generate an orchestration plan, then

merge_results.py

to validate and merge per-task outputs. Full scout→plan→dispatch→merge procedure:

references/extraction-pipeline.md

运行

python3 skills/datasheets/scripts/plan_extraction.py <project>

生成编排计划，然后运行

merge_results.py

验证并合并各任务输出。完整的侦察→计划→调度→合并流程详见：

references/extraction-pipeline.md

。

Consuming extractions (v1.4 typed API)

使用提取结果（v1.4类型化API）

The recommended consumer surface is the typed

lookup(mpn, cache_dir=...)

facade plus the trust-gating helpers from

datasheet_types

. Import like:

python

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

推荐使用类型化的

lookup(mpn, cache_dir=...)

facade以及

datasheet_types

中的信任控制辅助函数。导入方式如下：

python

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.

返回Optional[DatasheetFacts]。缓存未命中/PDF过期/质量分数过低时返回None。

facts = lookup("TPS61023DRLR", cache_dir=pathlib.Path("datasheets/extracted")) if facts is None: return # heuristic-only path; no datasheet evidence available

facts = lookup("TPS61023DRLR", cache_dir=pathlib.Path("datasheets/extracted")) if facts is None: return # 仅使用启发式算法路径；无数据手册证据可用

Field-level trust gating — every SpecValue list runs through has_data() / best() / trusted().

字段级信任控制 — 所有SpecValue列表需经过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}

pu_range = facts.base.recommended_pullup_range # Optional[list[SpecValue]] if has_data(pu_range): # 可信度最高的单个值（第一个满足阈值的SpecValue，保留提取器顺序）。 rec = best(pu_range, min_confidence="medium") # Optional[SpecValue] if rec is not None and rec.min is not None: ... # 使用rec.min、rec.max、rec.typ、rec.unit、rec.evidence.{page,section,confidence}

All SpecValues at threshold (for multi-value fields like absolute_max).

所有满足阈值的SpecValue（适用于absolute_max等多值字段）。

hi_conf = trusted(facts.base.absolute_max.get("VDD", []), min_confidence="high")


**Defensive patterns** (mirrors `kicad/SKILL.md` § "Probing Analyzer JSON"):

- `lookup()` returns `None` on cache miss, stale PDF (PDF newer than extraction), or quality score below the configured floor. Always guard with `if facts is None: return`.
- Category extensions are optional on `DatasheetFacts`. `facts.regulator` is `None` when the part isn't in the `regulator` category — check before dereferencing.
- SpecValue lists can be `None` (field not extracted), `[]` (extracted but empty), or `list[SpecValue]`. `has_data()` collapses the first two to `False`; pair with `best()` / `trusted()` for confidence gating.
- `SpecValue.min` / `.max` / `.typ` are each `Optional[float]`. A SpecValue carrying only `typ` (no range) makes `>` / `<` comparisons against `.min` / `.max` raise `TypeError` — guard with explicit `is not None` chains on every numeric access.
- `confidence` is one of `"low"` / `"medium"` / `"high"`. Calling `best()` / `trusted()` with any other string raises `ValueError`.