kicad

KiCad 项目分析技能

相关技能

技能	用途
bom	BOM 提取、补充信息、订购和导出工作流
digikey	在 DigiKey 上搜索元器件（原型采购）
mouser	在 Mouser 上搜索元器件（备用原型采购来源）
lcsc	在 LCSC 上搜索元器件（量产采购，JLCPCB）
element14	搜索 Newark/Farnell/element14（国际采购，数据手册可靠）
jlcpcb	PCB 制造与装配订购
pcbway	备用 PCB 制造与装配
spice	对检测到的子电路进行 SPICE 仿真验证
emc	EMC 预兼容性风险分析——使用原理图和 PCB 分析器的输出

交接指南： 使用此技能解析原理图/PCB 并提取结构化数据。将 BOM 补充信息、定价和订购工作交给 bom。将元器件搜索和数据手册获取工作交给 digikey/mouser/lcsc/element14。将制造订购和 DFM 规则验证工作交给 jlcpcb/pcbway。如果安装了任何 SPICE 仿真器，在设计审查期间**务必运行 spice进行仿真验证（使用 which ngspice ltspice xyce 检查）。如果原理图和 PCB 分析结果都可用，在设计审查期间务必运行 emc**进行 EMC 预兼容性风险分析。这些步骤不可省略——跳过会导致未发现数值计算错误和 EMC 风险。

分析前： 当用户要求分析或审查 KiCad 项目时，检查项目中是否存在 datasheets/ 目录。如果不存在，并且有可用的 DigiKey API 密钥（DIGIKEY_CLIENT_ID），请提出先同步数据手册：「我可以在分析前下载元器件的数据手册——这样便能根据制造商规格进行引脚级验证和去耦验证。要我同步吗？」如果用户拒绝或未设置 API 密钥，则在没有数据手册的情况下继续——分析仍可进行，但不会提供数据手册验证结果。

如果分析器输出中出现 DS-001 结果（严重性为 high，检测器为 audit_datasheet_coverage），则审查无法做出任何经过验证的结论。请停止，并选择以下任一操作：(a) 通过 digikey / mouser / lcsc / element14（选择具有凭据/库存的来源）同步数据手册；(b) 为 BOM 元器件补充 MPN；或 (c) 在报告中明确说明，所有引脚级、电气和稳压器相关结果都只是一致性检查——全文不得使用「已验证」「已确认」或「根据数据手册」等措辞。DS-002（缺少数据手册，但已设置 MPN）和 DS-003（MPN 覆盖不完整）是程度较轻的变体，但对其中提及的元器件同样有此限制。

设计审查约定

当用户要求进行设计审查、提供完整报告、评估是否已满足制造准备条件或提出任何类似要求时，不要只运行一两个分析器并总结其结果。此技能中的设计审查有更严格的要求：

1. 阅读本 SKILL.md 中的完整工作流，而不只是分析器命令部分。
2. 编写报告前阅读 references/report-generation.md。
3. 对项目中存在的文件运行所有适用的分析器，然后明确说明哪些已运行、哪些未运行。
4. 在声称任何内容「已验证」之前，进行原始文件和数据手册的交叉验证。
5. 在将可能的分析器误报升级为阻塞项之前，先进行筛查。
6. 如果无法完成某个必需步骤，应将其列为审查缺口，不得悄然省略。

请将此视为最低要求。仅有分析器 JSON 不是最终审查结果。

最低审查清单

进行完整设计审查时，请在报告中明确说明以下每一项：

• 是否存在 datasheets/、是否已同步，或说明验证缺口
• analyze_schematic.py
• analyze_pcb.py --full
• cross_analysis.py
• analyze_emc.py
• 安装了任何仿真器时进行 SPICE 仿真
• 原理图和 PCB JSON 均存在时运行 analyze_thermal.py
• 存在制造输出文件时运行 analyze_gerbers.py
• 网络访问和 MPN 覆盖率允许时进行生命周期审计
• 检查与先前审查／先前运行结果的差异
• 对关键元件，将原理图／PCB 原始数据抽查提升为完整验证
• 报告中明确包含阻碍项、验证依据、误报和跳过的分析等章节

如果某项不适用，请说明原因。如果跳过了某项，请说明原因。如果某项失败，请说明这会如何影响置信度。

常见审查失误

本规范旨在防止以下失误：

• 在完成原理图、PCB 和 EMC 输出检查后便停止，并称之为完整审查
• 报告分析器的发现，却未检查它们是否属于预期的布局特征
• 未提供直接数据手册证据或结构化提取证据，却声称“已验证”
• 未说明便省略热分析、生命周期、先前审查差异或 Gerber 检查
• 报告缺少结论、阻碍项表格、验证依据或跳过分析的说明
• 只阅读了本技能的前半部分，遗漏文件后半部分的设计审查工作流

PDF 原理图分析

此技能也支持 PDF 原理图——参考设计、开发板原理图、评估板文档、应用笔记和数据手册中的典型应用电路。常见用途：

• 分析制造商的参考设计，了解电路
• 提取子电路（电源、USB 接口、传感器前端），以整合到自己的 KiCad 设计中
• 将 PDF 参考设计与自己的原理图进行比较
• 从 PDF 原理图中提取完整 BOM
• 根据最新数据手册验证 PDF 中的元件值

**工作流：**目视阅读 PDF 页面 → 识别元件和连接 → 提取结构化数据 → 转换为 KiCad 符号和网络 → 根据数据手册进行验证。

如需了解完整方法——元件提取、标注约定、网络映射、子电路提取、KiCad 转换和验证——请阅读 references/pdf-schematic-extraction.md。

如需深入验证提取的电路是否符合数据手册（验证数值、检查模式、检测错误），请使用 references/schematic-analysis.md 中的方法。

分析脚本

此技能包含 Python 脚本，可通过一次运行从 KiCad 文件中提取全面的结构化 JSON。请先运行这些脚本，再分析输出。

请直接阅读分析器生成的 JSON 输出，而不要编写临时提取脚本。JSON 架构包含特定字段名（下文和 references/output-schema.md 中有说明），自定义代码很容易用错。若要提取特定部分：python3 -c "import json; d=json.load(open('file.json')); print(json.dumps(d['key'], indent=2))"。

如果 JSON 令你意外——出现 AttributeError、结构与预期不同，或字段返回了“本应”有值的 None——请停止操作，并在编写第二次提取尝试前运行 --schema。它会输出每个顶层键的确切字段名和类型：

python3 <skill-path>/scripts/analyze_schematic.py --schema
python3 <skill-path>/scripts/analyze_pcb.py --schema
python3 <skill-path>/scripts/analyze_gerbers.py --schema

JSON 字段速查表——手动读取分析器输出时最常见的错误：

你要查找的内容	正确路径和字段	常见错误
网络上的引脚	nets[<name>].pins[].component / .pin_number / .pin_name / .pin_type	ref、pin、type、number
未命名网络的美观显示名称	nets[<name>].display_name — 设置后，对于唯一一个命名 IC 引脚能说明情况的 __unnamed_N 网络，会显示 Ref.PinName 提示（例如 __unnamed_36 → U1.VBOOT）。若不存在，则表示分析器无法消除歧义。	忽略 display_name，并在报告中直接粘贴原始的 __unnamed_36
IC 引脚映射	ic_pin_analysis[] 是一个 IC 条目列表；每个条目都有 .reference 和 .pins[]，其中包含 .pin_number / .pin_name / .pin_type / .net / .connected_to[]。范围：仅限 type 为 {ic, connector, crystal, oscillator} 的条目。	将其当作 {ref: {...}} 或使用 pins[].number
晶体管引脚映射	transistor_pin_analysis[] — 针对 type=transistor（MOSFET、BJT、FET）的独立列表，每个条目的结构与 ic_pin_analysis[] 相同。使用它验证半桥／栅极驱动器引脚。	在 ic_pin_analysis[] 中查找 Q1 — 晶体管不在其中
检测到的电路	每个通过模式匹配检测到的电路（电源稳压器、RC 滤波器、晶体振荡器、电桥，……）都位于 findings[] 中 — 使用 finding_schema.get_findings(data, Det.POWER_REGULATORS) 等进行筛选。不要从 subcircuits[] 读取：它是 IC 邻近元件分组（{center_ic, ic_value, neighbor_components, …}），不是分类检测索引	查找 subcircuits.power_regulators、subcircuits.rc_filters 或任何 subcircuits[type] 键 — 这些键从未存在于 v1.3 输出中
区域网络	pcb.zones[].net 是整数网络 ID，不是字符串。请使用 f"{net!r}" 或先进行转换	f"{net:20s}" — 会因 ValueError: Unknown format code 's' for object of type 'int' 而崩溃
区域图层	pcb.zones[].layers（复数形式）是规范图层列表。多层区域中的 zones[].layer（单数形式）保留未用／值为 None — 始终读取 .layers。	读取 zones[].layer 后得到 None
封装位置	顶层的 pcb.footprints[].x / .y（没有 .position 封装层）	footprints[].position.x
封装上每个焊盘的网络信息	pcb.footprints[].pad_nets{pad_number: {net, pin}} 是以焊盘编号为键的字典。connected_nets[] 提供与该封装相连的去重网络列表。	footprints[].pads[] — 输出中不存在此键
布线摘要	pcb.tracks 是一个字典（Tracks 封装对象）：{segment_count, arc_count, layer_distribution{}, width_distribution{}}。只有使用 --full 时才会填充内部的 tracks.segments[] 和 tracks.arcs[] 数组。线段字段：{x1, y1, x2, y2, width, layer, net} — net 是整数 ID（通过顶层的 nets / net_name_to_id 映射）。	未使用 --full 时执行 for t in tracks: ... — tracks 是摘要字典，不是列表；seg.get("x") / seg.get("start") — 键名错误，且 .get() 的默认值会导致静默的 0.0 错误
电源网络布线	pcb.power_net_routing 是按网络列出的条目列表 [{net, track_count, total_length_mm, ...}, ...]，不是以网络为键的字典。	power_net_routing["VCC"] → TypeError
检测结果	findings[] 是扁平列表 — 每项都有 rule_id、detector、severity、summary、report_context。使用 finding_schema.get_findings(data, Det.*) 或 group_findings(data) 筛选	查找 signal_analysis.power_regulators[] 之类的键控字典（v1.3 之前的格式，已移除）

这样可以避免格式字符串错误和字段名称错误。请使用 f 字符串或 json.dumps() 格式化输出 — 绝不要对非字符串类型使用 %s。完整架构及常见提取模式请参阅 references/output-schema.md。

在以下所有命令中，<skill-path> 指此技能的基础目录（加载时显示在本文件顶部）。

原理图分析器

python3 <skill-path>/scripts/analyze_schematic.py <file.kicad_sch> --analysis-dir analysis/
python3 <skill-path>/scripts/analyze_schematic.py <file.kicad_sch> --analysis-dir analysis/ --compact
python3 <skill-path>/scripts/analyze_schematic.py <file.kicad_sch> --output analysis.json  # one-off, no cache

输出结构化 JSON（大小约为 60-220KB，具体取决于电路板复杂度），包含：

• 元件与 BOM：包含位号、值、封装、lib_id、类型分类、MPN 和数据手册的清单；包含数量的去重 BOM
• 网络：完整的连接关系图，包含引脚到网络的映射、导线数量和未连接项
• 检测到的子电路（通过模式匹配识别的电路——均作为匹配的 Det.* 检测器对应的 findings[] 条目输出；使用 get_findings(data, Det.POWER_REGULATORS) 等进行获取）：
  • 电源稳压器——LDO/开关/反相拓扑；通过数据手册验证的 Vref 查找表（约 60 个系列）估算 Vout，并提供启发式回退和固定输出后缀解析；包含 vref_source（lookup/heuristic/fixed_suffix）和 vout_net_mismatch 字段
  • 分压器、RC/LC 滤波器（截止频率）、反馈网络、晶振电路（负载电容分析、基于 IC 引脚的检测）
  • 运放电路（配置、增益、积分器/补偿器）、晶体管电路（感知网络名称的负载分类：电机/加热器/风扇/电磁阀/阀门/泵/继电器/扬声器/蜂鸣器/灯；FET 电平转换拓扑）
  • 桥式电路（H 桥、三相、跨页检测）、保护器件（ESD/TVS）、电流检测、去耦分析
  • 特定领域：RF 链路、RF 匹配网络、BMS、以太网（通过 BFS 从 PHY 追踪到连接器）、HDMI/DVI 接口、存储器接口、按键矩阵（基于网络名称和拓扑）、隔离屏障、可寻址 LED 链（WS2812/SK6812/APA102）、电池充电器（TP4056/MCP73831/BQ2404x）、电机驱动器（A4988/TMC2209/DRV8301）、ESD 保护覆盖审计、调试接口（带 MCU 追踪的 SWD/JTAG）、电源路径（负载开关/理想二极管/USB PD 控制器）、ADC 信号调理（外部 ADC + 电压基准，并交叉参考抗混叠）、复位/监控电路（电压监控器/看门狗/RC 复位网络）、时钟分配（时钟发生器/PLL/振荡器输出追踪）、显示/触摸接口（SSD1306/ILI9341/ST7789/FT6236/GT911）、传感器融合（IMU/环境传感器/磁力计，含中断验证和总线聚类）、电平转换器（基于 IC + 分立 BSS138，含电源域映射）、音频电路（放大器/编解码器，支持 I2S/class-D 检测）、LED 驱动器 IC（PWM/矩阵/恒流）、RTC 电路（备用电池/晶振配对）、LED 照明审计（限流验证）、热电偶/RTD 接口（MAX31855/MAX31865）、电源时序验证（电源树/使能链/PG 菊花链分析）
• IC 引脚分析：引脚级连接关系、IC 功能分类（三级：库前缀、料号关键词、描述回退）
• 电源分析：PDN 阻抗（1kHz–1GHz，含 MLCC 寄生参数）、电源预算、电源时序（EN/PG 链）、睡眠电流审计（电阻路径 + 稳压器 Iq，并检测 EN）、电压降额、浪涌电流估算
• 设计分析：ERC 警告、电源域、总线检测（I2C/SPI/UART/CAN/RS-485，含 COPI/CIPO/SDI/SDO）、差分对（针对 USB/LVDS/以太网/HDMI/MIPI/PCIe/SATA/CAN/RS-485 进行后缀配对）、跨电源域信号（电压等效性）、BOM 优化、测试覆盖率、装配复杂度、USB 合规性
• 质量检查：注释完整性、标签验证、PWR_FLAG 审计、封装筛选器验证、采购审计、属性模式审计、通用晶体管符号检测（标记 Q_NPN_/Q_PNP_/Q_NMOS_/Q_PMOS_ 符号，并检查数据手册是否可用）
• 结构分析：MCU 复用引脚摘要、接地域分类、总线拓扑、导线几何、空间聚类、引脚覆盖率、层次标签验证

支持现代 .kicad_sch（KiCad 6+）和旧版 .sch（KiCad 4/5）。层次化设计会递归解析。 旧版格式： 对于 KiCad 5 旧版 .sch 文件，分析器会解析 .lib 文件（缓存库和项目库）以填充引脚数据。只要 .lib 文件可用，引脚到网络的映射、信号分析和子电路检测都能正常工作。覆盖率通常为 92–100%——缺少 .lib 文件的元件（仓库中没有的 KiCad 标准系统库）将缺少引脚数据。内置回退方案涵盖 40 多种常见符号（R、C、L、D、LED、晶体管、MOSFET、晶振、开关、有极性电容、最多 20 引脚的连接器、电阻阵列），支持以 mil 为单位的引脚偏移，并能自动修正版本不匹配造成的引脚位置偏差。

旧版设计的补充数据

当 analyze_schematic.py 返回的数据不完整时（由于 .lib 文件不可用，部分元件缺少引脚），可使用其他项目文件恢复完整的分析能力。最有价值的来源是 .net 网表文件，它提供明确的引脚到网络映射，可弥补剩余缺失的数据。

有关详细的解析说明、数据恢复工作流，以及补充数据源（网表、缓存库、PCB 交叉引用、PDF 导出文件）的优先级矩阵，请参阅 references/supplementary-data-sources.md。

请对照实际情况验证分析器的输出。 分析器可能会悄无声息地产生看似合理、实则错误的结果——例如错误的电压估算、缺失的 MPN、错误的引脚到网络映射。这些问题不会导致脚本报错，只会产生错误数据并流入报告。在对多个电路板进行测试时，每个项目都至少出现了一项误导性的分析器输出。请与原始 .kicad_sch 文件交叉核对：

1. 元件数量 — 搜索 (symbol (lib_id 块，并减去电源符号。结果必须与分析器的计数完全一致。
2. 引脚到网络的映射 — 对照原始原理图，逐个元件核实分析器给出的引脚到网络映射。读取符号块，追踪导线／标签以确认连接。对照制造商数据手册中的引脚表，交叉核对 IC 引脚分配。这是价值最高的验证步骤——引脚映射错误会导致电路板无法正常工作，而且 DRC/ERC 无法发现。
3. 物理正确性（而不只是保持一致） — 一致性检查（原理图 = PCB = 分析器，三者结果一致）是必要条件，但并不充分。它们只能确认设计内部自洽，却不能确认设计与现实中的元件相符。最危险的情况是：晶体管符号编码了引脚排列假设（例如，Q_NPN_BEC = 引脚 1=B、2=E、3=C），但实际元件并非如此。一致性检查全部通过，电路板却是错的。为发现这类问题：
   • 对于采用 SOT-23、SOT-223、TO-252 等类似封装的晶体管（BJT/MOSFET），KiCad lib_id 的后缀会编码引脚顺序假设。SOT-23 BJT 至少有 6 种引脚排列变体（BEC、BCE、EBC、ECB、CBE、CEB）；SOT-23 MOSFET 则有 GDS、GSD、SGD、DSG 等排列。如果未指定 MPN，就无法验证这一假设——应将其标记为关键歧义。
   • 指定了 MPN 时，应对照该特定封装的数据手册引脚排列图，核实符号的引脚到焊盘分配。
   • 这一原则不止适用于晶体管——对于同一封装存在多种引脚顺序的任何元件（引脚分配不同的稳压器、引脚排列因供应商而异的连接器），都需要在 MPN 层面进行验证。
   • 无法验证时，评估其合理性。 未经验证的选择并非风险相同。有些选择符合强势惯例（最常见的 SOT-23 NPN 引脚排列是 BCE；采用 SOT-23 封装的 2N2222 几乎总是 BCE）；另一些则不符合惯例，或确实存在歧义（SOT-23 MOSFET 没有占主导地位的标准）。当缺少 MPN 且无法验证时，应运用领域知识——例如该类器件及封装的典型引脚排列、制造商惯例，以及该类别中大多数元件的做法——评估假定的引脚排列是很可能正确、较为少见，还是完全无法判断。报告置信度：「符合最常见惯例」与「两种情况都有可能」并不相同。相同的推理也适用于无源元件的取值（4.7kΩ 是否是该总线常见的上拉值？）、电路拓扑（这是否是标准应用电路？）和元件选型（该元件是否常用于此用途？）。
4. 网络追踪 — 沿导线／标签端到端追踪电源轨和关键信号网络。核实分析器列出的每个网络的引脚是否完整。
5. 稳压器 Vout — 检查 vref_source 字段。"lookup" 表示已通过数据手册验证（约 60 个系列）；"heuristic" 表示这是一个需要人工验证的估值。vout_net_mismatch 字段会标记估算的 Vout 与输出电源轨名称中的电压相差超过 15% 的情况。
6. 层次化连通性 — 对于多页设计，核实子页连接已反映在网络数据中。

完整的验证清单见 references/schematic-analysis.md 第 2 步。如果脚本失败或返回意外结果，请参阅 references/manual-schematic-parsing.md，了解完整的备用方法。

PCB 布局分析器

python3 <skill-path>/scripts/analyze_pcb.py <file.kicad_pcb> --analysis-dir analysis/
python3 <skill-path>/scripts/analyze_pcb.py <file.kicad_pcb> --analysis-dir analysis/ --proximity  # add crosstalk analysis
python3 <skill-path>/scripts/analyze_pcb.py <file.kicad_pcb> --output pcb.json --schematic analysis/schematic.json  # one-off; cross-ref + power-rail auto-detect

输出结构化 JSON（约 50-300KB，具体取决于电路板复杂度），包括：

• 核心：封装清单（焊盘、Courtyard、网络分配、扩展属性、原理图交叉引用）、走线/过孔统计、覆铜区摘要、电路板轮廓/尺寸、布线完成度
• 覆铜区与铜箔分布：覆铜区轮廓与填充多边形边界框、填充率、每个焊盘的跨层铜箔分布（哪些元件在另一层有覆铜、哪些没有）、同层异网络覆铜区检测
• 过孔分析：类型分类（通孔/盲孔/微孔）、环宽检查、焊盘内过孔检测、BGA/QFN 扇出模式、电流承载能力、缝合过孔识别、阻焊覆盖情况
• 信号完整性：每个网络的走线长度、层间转换跟踪（接地回流路径）、走线间距/串扰（使用 --proximity）
• 电源与热分析：每个网络的电流承载能力、电源网络布线摘要、接地分区识别（AGND/DGND）、覆铜区缝合过孔密度、热焊盘检测与过孔计数
• 制造：布局分析（Courtyard 重叠、边缘间距）、去耦电容距离、DFM 评分（JLCPCB 标准/高级等级）、立碑风险（0201/0402 热不对称）、热焊盘过孔适用性、丝印文档审查

添加 --full 可包含各个走线/过孔的坐标、每段走线的阻抗（根据叠层计算微带线 Z0）、焊盘到焊盘的布线路径距离、回流路径连续性分析和过孔残桩长度。--full 输出可供 spice 技能的寄生参数提取工具（extract_parasitics.py）使用，以进行 PCB 感知仿真。支持 KiCad 5 旧版格式。

覆铜区填充必须是最新的。 铜箔分布分析使用 KiCad 的填充多边形数据，该数据会在用户运行“编辑” → “填充所有覆铜区”（快捷键 B）时计算，并存储在 .kicad_pcb 文件中。如果电路板在上次填充后经过修改，填充多边形数据可能已过时，导致铜箔分布结果不准确。检查铜箔分布数据时，注意 fill_ratio 是否合理——填充面积为 0 或 is_filled: false 的覆铜区可能尚未填充。

覆铜区轮廓 ≠ 实际铜箔。 覆铜区的 outline_bbox 是用户绘制的边界；filled_bbox 则表示经过间距、禁布区和优先级切割后，铜箔实际存在的区域。copper_presence 部分会显示哪些元件在另一层有覆铜——应使用此信息分析电容触摸焊盘隔离、天线禁布区和热特性，而不是根据覆铜区轮廓推断铜箔是否存在。

对铜箔敏感的元件需要更深入的检查。 对于电容触摸焊盘和天线，确认“另一层没有铜箔”是必要条件，但还不够。铜箔缺失可能是意外造成的——布线更改后重新填充一次覆铜区，就可能添加铜箔，导致触摸灵敏度下降或天线失谐。检查是否有明确的禁布区（规则区域）通过 DRC 规则强制保持该区域无铜箔。此外，还要测量触摸焊盘周围同层 GND 的间距，并与控制器应用说明中的最小值进行比较。对于触摸焊盘，比较所有焊盘的走线长度——明显的不对称会导致各通道的基线读数偏移。报告所有对铜箔敏感元件的物理细节（焊盘尺寸、位置、间距、走线宽度/长度）。完整检查清单请参见 references/pcb-layout-analysis.md → Copper-Sensitive Components。

每次运行后都要验证： 对照原始 .kicad_pcb 文件，确认封装数量和电路板轮廓尺寸。根据原理图的引脚到网络映射，验证 IC 封装的焊盘到网络分配情况——这可以发现焊盘编号与符号引脚排列不一致的库封装错误。如果脚本失败，请参见 references/manual-pcb-parsing.md 中的备用方法。

PCB 丰富格式与装配检查

现在，所有 PCB 分析部分都会以丰富格式输出发现项（detector、rule_id、category、severity、confidence、summary、recommendation、report_context）。此外，还会自动运行 7 项新的装配/DFM 检查：

• FD-001：基准标记是否存在（每个 SMD 面 >= 3 个）
• TE-001：信号网络的测试点覆盖率
• OR-001：无源元件方向一致性
• SK-001：丝印文字是否与裸露焊盘重叠
• VP-001：焊盘内过孔未盖油（--full 模式）
• BV-001：过孔与板边的间距（--full 模式）
• KO-001：禁布区违规
• CP-001：元件下方同层存在非所属区域。若非所属区域属于非接地网络，或元件没有 GND 焊盘，则严重级别为 warning；若非所属区域属于 GND，且元件有 GND 焊盘（常见情况：旁路电容位于接地铜皮上方——这是预期布局，不是间距问题），则严重级别为 info。

跨域分析

运行原理图和 PCB 分析器后，运行跨域分析器。 将 --schematic 和 --pcb 指向当前运行的 JSON 文件，并传入 --analysis-dir analysis/，使结果写入同一运行文件夹 并由清单跟踪：

# Recommended: integrate into the current run
python3 <skill-path>/scripts/cross_analysis.py \
    --schematic analysis/<run_id>/schematic.json \
    --pcb analysis/<run_id>/pcb.json \
    --analysis-dir analysis/

# One-off (bypasses the cache)
python3 <skill-path>/scripts/cross_analysis.py \
    --schematic schematic.json --pcb pcb.json --output cross_analysis.json

检查项：CC-001 连接器电流容量、EG-001 ESD 保护缺失、DA-001 去耦充分性、XV-001..003 原理图/PCB 同步。PCB JSON 可选。

机械交叉验证（PCB 与原理图几何）：python3 <skill-path>/scripts/cross_verify.py --help。

连通性图（--full 模式）

使用 PCB 分析器的 --full 选项时，输出会包含 connectivity_graph 部分，其中通过对焊盘、走线、过孔和区域填充进行并查集分析，提供逐网络的铜箔连通性分析。这使 cross_analysis.py 能够确定性地检测平面分割并验证回流路径。connectivity_graph 的顶层键就是网络名称，例如 cg['GND']、cg['Net-(D2-K)']、cg['+3V3']，而不是 per_net 包装层。每个网络条目都会显示孤岛数量、元件到孤岛的映射（{component:pad: island_id}）、间隙位置和未连接的焊盘对。

Gerber 与钻孔分析器

# Recommended: integrate into the current run
python3 <skill-path>/scripts/analyze_gerbers.py <gerber_directory/> --analysis-dir analysis/

# One-off
python3 <skill-path>/scripts/analyze_gerbers.py <gerber_directory/> --output gerber.json

输出内容：层识别（X2 属性）、元件/网络/引脚映射（KiCad 6+ TO 属性）、光圈功能分类、走线宽度分布、板尺寸、钻孔分类（过孔/元件/安装孔）、层完整性、对齐验证、焊盘类型摘要（SMD/THT 比例）。添加 --full 可输出完整的引脚到网络连通性转储。约 10KB JSON。

Gerber 分析器会生成 findings 列表，其中包含丰富格式的发现项：GR-001 缺少层、GR-002 对齐问题、GR-003 钻孔问题、GR-004 锡膏光圈不匹配、GR-005 板框未闭合。

如果脚本失败或返回意外结果，请参阅 references/manual-gerber-parsing.md，了解直接解析原始 Gerber/Excellon 文件的完整备用方法。

默认情况下，所有脚本都会将 JSON 输出到 stdout。建议使用 --analysis-dir analysis/ 将输出纳入下文“分析缓存约定”所述的运行文件夹规范中——这样，单次会话中的每个分析器都会将结果放在同一 analysis/<run_id>/ 文件夹内，并由清单跟踪。 只有在临时运行且不希望缓存结果时，才使用 --output file.json。添加 --compact 可输出单行 JSON。

值得保留分析器 JSON——重新生成这些文件成本很高（大型原理图需要耗费时间）。--analysis-dir 会保留每次运行的结果，也是下游工具（diff_analysis、what_if）所需的格式。它们不值得提交到 git，但在分析步骤之间不要删除。

统一输出格式

所有分析器都会生成统一的输出封装：

{
    "analyzer_type": "schematic|pcb|emc|cross_analysis|thermal|gerber|lifecycle|spice",
    "schema_version": "1.4.0",
    "summary": {
        "total_findings": 42,
        "by_severity": {"error": 3, "warning": 15, "info": 24}
    },
    "findings": [
        {"rule_id": "...", "detector": "...", "severity": "...", "confidence": "...", "evidence_source": "...", "summary": "...", ...}
    ],
    "trust_summary": {
        "total_findings": 42,
        "trust_level": "high|mixed|low",
        "by_confidence": {"deterministic": 20, "heuristic": 18, "datasheet_backed": 4},
        "by_evidence_source": {"datasheet": 4, "topology": 10, "heuristic_rule": 18, ...},
        "provenance_coverage_pct": 96.5
    }
}

findings 列表是所有发现的唯一权威来源。使用 finding_schema.get_findings() 或 finding_schema.group_findings()，按检测器、规则前缀或类别筛选。检测器名称以常量形式定义在 finding_schema.Det 中。严重级别为 error、warning 或 info；置信度为 deterministic、heuristic 或 datasheet-backed。

所有分析器都支持 --text，用于生成便于阅读的输出；支持 --analysis-dir，用于生成集成的运行文件夹输出（推荐）；支持 --output，用于将原样输出写入指定文件（单次使用）。同时传入两者时，以显式指定的 --output 路径为准；每次调用请选择一种方式。

按阶段和受众筛选

所有分析器都支持 --stage 和 --audience 标志：

阶段： schematic、layout、pre_fab、bring_up 受众： designer（默认）、reviewer、manager

# Show only layout-relevant findings for a reviewer
python3 <skill-path>/scripts/analyze_pcb.py board.kicad_pcb --stage layout --audience reviewer --text

# Manager summary of schematic review readiness
python3 <skill-path>/scripts/analyze_schematic.py design.kicad_sch --audience manager --text

# Pre-fab checklist for cross-domain analysis
python3 <skill-path>/scripts/cross_analysis.py -s sch.json -p pcb.json --stage pre_fab --text

JSON 输出始终包含所有发现。--stage 会为每项发现添加 stages 和 in_active_stage 字段，并添加 stage_filter 汇总信息。始终会根据设计师、审核者和经理视角计算 audience_summary。--text 输出会遵循这两个标志的设置。

生成的文件

分析输出保存在 analysis/ 中，带时间戳的运行文件夹由 analysis_cache.py 管理。清单（analysis/manifest.json）会跟踪所有运行记录。

文件类型	位置	可重新生成？	提交到 git？
分析器 JSON	analysis/<timestamp>/*.json	是（耗时较长）	由 .kicad-happy.json 中的 track_in_git 配置（默认：否）
清单	analysis/manifest.json	是	始终提交（默认跟踪）
设计审查报告	用户选择的路径	是	可选

创建设计审查时，请检查清单中是否有先前的运行记录。如果启用了 auto_diff 且存在先前的运行记录，请自动使用 diff_analysis.py 对比当前结果与之前的结果，并将差异纳入“Previous Review Delta”部分。

另请参阅 bom 技能中有关数据手册、订单 CSV 和备份的清理部分。

分析缓存配置

.kicad-happy.json 中的 analysis 部分用于控制共享的分析输出目录：

{
  "analysis": {
    "output_dir": "analysis",
    "retention": 5,
    "auto_diff": true,
    "track_in_git": false,
    "diff_threshold": "major"
  }
}

字段	默认值	描述
output_dir	"analysis"	分析目录路径，相对于项目根目录
retention	5	保留的未固定运行记录数量上限。0 = 不限
auto_diff	true	在设计审查中自动加入差异部分
track_in_git	false	为 false 时，JSON 文件会被 git 忽略，但清单仍会被跟踪
diff_threshold	"major"	触发创建新时间戳文件夹的严重级别：minor、major、breaking

所有字段均为可选。缺失字段将使用默认值。

输出 JSON 架构速查

原理图分析器顶层键：

analyzer_type, schema_version, summary, findings, trust_summary,
file, kicad_version, file_version, title_block, statistics,
bom, components, nets, subcircuits, ic_pin_analysis, transistor_pin_analysis,
design_analysis, connectivity_issues, hierarchy_context, hierarchy_warning, net_classifications, rail_voltages

可选（非空时出现）：pdn_impedance、sleep_current_audit、power_budget、power_sequencing、bom_optimization、test_coverage、assembly_complexity、usb_compliance、inrush_analysis、sheets（仅限多页原理图）、missing_info、bom_lock、project_settings 关键嵌套结构：

• statistics：{total_components, unique_parts, dnp_parts, total_nets, total_wires, total_no_connects, component_types, power_rails, missing_mpn, ...}
• bom[]：{reference, references[], value, footprint, mpn, manufacturer, datasheet, quantity, dnp, ...}
• components[]：{reference, value, footprint, lib_id, lib_name, type, category, mpn, datasheet, dnp, in_bom, parsed_value, ...}
• nets{net_name}：{pins[], wires, labels[], ...} — 每个引脚：{component, pin_number, pin_name, pin_type, ...}（不是 ref 或 pin）
• subcircuits[]：IC 邻近分组（{center_ic, ic_value, neighbor_components, ...}），不是分类检测索引 — 请参阅本文件顶部的 JSON 字段速查表。
• 检测到的子电路位于 findings[] 中 — 电源稳压器、分压器、RC/LC 滤波器、反馈网络、运放/晶体管/桥式/晶振电路、电流检测、去耦、保护、蜂鸣器/扬声器、以太网/HDMI/存储器接口、RF 链路/匹配、BMS、按键矩阵、隔离屏障、可寻址 LED 链以及设计观察结果，都会作为 findings 输出，并带有匹配的 Det.* 检测器。使用 get_findings(data, Det.POWER_REGULATORS) 等获取这些结果。v1.3 之前的 signal_analysis 包装器及其顶层检测列表已移除。

PCB 分析器顶层键：

analyzer_type, schema_version, summary, findings, trust_summary,
file, kicad_version, file_version, statistics, layers, setup,
nets, net_name_to_id, board_outline, component_groups, footprints,
tracks, vias, zones, keepout_zones, connectivity, net_lengths

可选：power_net_routing、decoupling_placement、ground_domains、layer_transitions、silkscreen、board_metadata、dimensions、groups、net_classes、dfm_summary、placement_density、copper_presence_summary、board_thickness_mm、trace_proximity（需使用 --proximity）。此前位于顶层的部分（thermal_analysis、thermal_pad_vias、tombstoning_risk、placement_analysis、current_capacity、copper_presence、dfm）现位于 findings[] 中。使用 --full 时，输出还会包含 connectivity_graph 部分（请参阅上方的“Connectivity Graph”）。

关键嵌套结构：

• net_lengths 是列表（不是字典）：[{net, net_number, total_length_mm, segment_count, via_count, layers{}}, ...]，按长度降序排列
• power_net_routing 是列表：[{net, track_count, total_length_mm, min_width_mm, max_width_mm, widths_used[]}, ...]
• footprints[]：{reference, value, footprint, layer, pads[], sch_path, sch_sheetname, sch_sheetfile, connected_nets[], ...}
• statistics：{footprint_count, copper_layers_used, smd_count, tht_count, zone_count, via_count, routing_complete, ...}

Gerber 分析器顶层键：

analyzer_type, schema_version, summary, findings, trust_summary,
directory, generator, layer_count, statistics, completeness, alignment,
drill_classification, pad_summary, board_dimensions, gerbers, drills

工作流：分析 KiCad 项目时，扫描项目目录中的所有可用文件类型，并运行所有适用的分析器，而不只是用户提到的分析器。完整分析会使用所有可用数据。对所有分析器使用 --analysis-dir analysis/，以便共用一个由清单跟踪的运行文件夹。对于不需要缓存跟踪的单次运行，请改用 --output file.json。

**开始执行以下设计审查工作流之前：**请先阅读 references/report-generation.md。其中的报告结构、验证依据规则、跳过分析的披露要求以及误报分类处理要求，都是审查工作流的一部分，并非最后才添加的可选润色。

1. 扫描项目目录，查找 .kicad_sch、.kicad_pcb、.kicad_pro、Gerber 目录，以及 .net/.xml 网表文件。
2. 同步数据手册（参见下方“数据手册获取”）——这是验证的前提，不可省略。没有数据手册，后续所有验证都只能检查内部一致性——确认设计与自身一致，而非确认设计正确。读取任何分析器输出前，先运行同步。如果同步失败或没有可用的 API 密钥，请使用备用方法（数据手册属性中的 URL、通过 digikey skill 单独下载、询问用户）。如果无法获取关键 IC 的数据手册，请在报告中醒目标明这一验证缺口。
3. 运行核心分析器。 如果存在原理图，运行 analyze_schematic.py。如果存在 PCB，运行 analyze_pcb.py --full。如果存在 Gerber 文件，运行 analyze_gerbers.py。条件允许时并行运行。
4. 运行跨领域分析——如果原理图和 PCB 分析结果都存在，运行 cross_analysis.py --schematic sch.json --pcb pcb.json。此操作可捕获危险的跨领域问题（连接器电流与走线宽度、ESD 间隙、去耦是否充分、原理图/PCB 是否同步）。
5. 运行 EMC 预合规检查——如果原理图和 PCB 分析结果都存在，运行 python3 <emc-skill-path>/scripts/analyze_emc.py --schematic sch.json --pcb pcb.json（该脚本位于 emc skill 中，而非此 skill 的 <skill-path> 下）。设计评审期间必须运行 EMC skill，不可省略。EMC skill 会执行 44 项规则检查，涵盖接地平面完整性、去耦、开关谐波、PDN 阻抗、差分对偏斜、ESD 路径等。将结果纳入报告的 EMC 部分。
6. 运行 SPICE 仿真——先运行 which ngspice ltspice xyce。如果安装了任意一种仿真器，必须在撰写报告前运行 SPICE。交由 spice skill 处理：python3 <spice-skill-path>/scripts/simulate_subcircuits.py sch.json。此操作会根据实际仿真结果验证滤波器频率、分压比、运放增益等。SPICE 在大多数电路板上耗时不到 1 秒，可发现静态分析器无法发现的数值计算错误（例如电阻比错误、截止频率对应的电容错误）。如果原理图和 PCB 分析结果都存在，运行 python3 <spice-skill-path>/scripts/extract_parasitics.py pcb.json --output parasitics.json（需要 --full PCB JSON）；对于高阻抗电路（反馈分压器 >100K、LC 滤波器、RF 匹配网络），传入 --parasitics parasitics.json——这是路径参数，不是单独的标志。将结果纳入报告的“仿真验证”部分。**输出架构：**顶层键为 summary、simulation_results、workdir、total_elapsed_s、simulator。simulation_results[] 中的每个条目包含：subcircuit_type、components（元件参考标号列表，例如 ["R5", "C3"]）、reference（拼接后的参考标号，例如 "R5/C3"）、status（pass/warn/fail/skip）、expected（指标值字典）、simulated（测量值字典）、delta（误差百分比字典）。
7. 运行热分析——如果原理图和 PCB 分析结果都存在，运行 analyze_thermal.py --schematic schematic.json --pcb pcb.json。根据封装 θJA 和电路板热修正估算结温。将结果纳入报告的“热热点”部分。
8. 运行生命周期审查（具备网络访问能力且有 MPN 时）——通过 analyze_schematic.py --lifecycle 标志调用。通过分销商 API 检查元件的过时状态。将结果纳入报告的“元件生命周期”部分，或注明“未执行生命周期审查——[原因：无 API 密钥 / 无网络 / 无 MPN]”。
9. 直接读取 .kicad_pro 项目文件（它是 JSON），查看设计规则、网络类以及 DRC/ERC 设置。
10. 检查先前的设计评审——扫描项目目录，查找现有评审文件（*review*.md、*design-review*.md）。如果找到，请读取最新的一份。如果启用了 auto_diff 且存在先前运行结果，请对当前和先前的运行结果执行 diff_analysis.py，并将差异纳入“先前评审差异”部分。
11. 使用数据前，根据原始文件和数据手册验证每项输出。
12. 生成统一报告，涵盖原理图分析、PCB 布局分析、跨领域发现、EMC 风险评估、仿真验证、热热点和交叉引用发现。报告模板参见 references/report-generation.md。
13. 明确披露所有评审缺口——如果未执行热分析、生命周期审查、Gerber 分析、数据手册提取或先前评审差异分析，请在报告中添加简短的“未执行 / 限制”部分，不要默默省略。 组合的数据源越多，分析结果就越可靠。只审查原理图会遗漏布局问题；只审查 PCB 会遗漏设计意图。始终使用所有可用信息。

分析深度

除非用户要求快速审查，否则默认进行全面分析。原因在于：导致电路板报废的 bug，往往乍看之下都很正常。抽查可能确认 5 个 IC 正确无误，却漏掉第 6 个 IC 的 3、4 脚接反——而这正是导致电路板无法工作的那个。全面分析的原则：

• 核查所有元件，而不是抽查。 “简单”元件上的引脚与网络连接错误（如二极管反接、分压器中的电阻值错误、连接器引脚顺序错误），致命程度不亚于 IC 引脚接反。检查整个设计。
• 以数据手册为准，而不是以 KiCad 库符号为准。 分析器、原始原理图和 KiCad 库文件都能告诉你设计 写了什么——只有制造商提供的 PDF 数据手册能告诉你设计 应该是什么样。引脚映射错误的库符号是最危险的一类 bug，正是因为所有内容在内部都一致：原理图、PCB 和分析器结果彼此吻合，但电路板无法工作。对照 .kicad_sym 文件核对引脚分配无异于循环论证——它本身就是潜在错误的来源。开始核查前先下载数据手册（参见下文“获取数据手册”），打开每个 IC 的实际 PDF，提取引脚功能表，并在报告核查结果时注明页码和章节号。
• 评估合理性，而不只是能否核实。 如果某项内容无法核实（缺少 MPN 或数据手册），不要止步于“未核实”。运用领域知识，判断设计选择是否符合常见惯例，或看起来是否异常。10kΩ 的 I2C 上拉电阻很常见；即使没有数据手册可供核对，100Ω 的 I2C 上拉电阻也值得进一步检查。采用 BCE 引脚排列的 SOT-23 NPN 符合最常见的惯例；采用 CEB 排列则比较少见，足以标记出来。目标是区分“未核实但很可能没问题”和“未核实且可疑”。这适用于引脚排列、无源元件值、电路拓扑和元件选型。
• 思考分析器检测范围之外的问题。 分析器只能找到它被编程用于检测的模式。如果某部分没有自动化数据，要考虑是因为设计不需要（没问题——简要说明即可），还是因为分析器无法检测（手动推理）。并非每个部分都需要一段说明——“不适用：电池供电，无市电输入”就足够了。但不要让空白数据导致忽略特定设计中的重要问题。

获取数据手册

开始深度审查前，先检查数据手册是否可用：提取缓存（datasheets/extracted/）是最快的途径；磁盘上的 PDF（datasheets/）是备用方案——直接读取即可。如果某些元件两者都没有，请先提出同步数据手册（使用 digikey / lcsc / mouser / element14 技能），再开始无数据手册的审查。提取结果附有质量标记——低质量信息会明确标出，而不会被隐藏；请自行判断是否可信，或重新读取 PDF。

数据手册是区分一致性检查与正确性检查的关键。没有数据手册，你可以确认设计内部一致，却无法确认设计是否符合实际元件的规格。应在工作流早期获取数据手册。

自动同步（首选）： 在工作流早期运行数据手册同步脚本。这些脚本会将所有具有 MPN 的元件的数据手册下载到共享的 datasheets/ 目录，并附带 manifest.json 清单。先运行首选来源；如果部分元件下载失败，再尝试其他来源——它们共用同一目录，并会跳过已下载的文件。

python3 <digikey-skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch>
python3 <lcsc-skill-path>/scripts/sync_datasheets_lcsc.py <file.kicad_sch>
python3 <element14-skill-path>/scripts/sync_datasheets_element14.py <file.kicad_sch>
python3 <mouser-skill-path>/scripts/sync_datasheets_mouser.py <file.kicad_sch>

DigiKey 最佳（提供直接 PDF URL）。element14 可靠（没有机器人防护）。LCSC 适用于仅由 LCSC 供应的元件。Mouser 是最后选择（经常会阻止下载）。 **检查是否已有数据手册：**下载前，请查找：

• <project>/datasheets/ 中的 manifest.json（来自之前的同步）
• <project>/docs/ 或 <project>/documentation/
• 项目目录中名称包含 MPN 的 PDF 文件
• KiCad 符号中嵌入的 Datasheet 属性 URL

自动同步不可用或遗漏元件时的备用方法：

1. 使用原理图符号中的 Datasheet 属性 URL——许多 KiCad 库都包含直接的 PDF 链接
2. 使用 digikey 技能按 MPN 搜索并下载各个数据手册
3. 使用网页搜索查找制造商的数据手册页面
4. 询问用户——如果无法自动找到关键元件的数据手册，请告知用户缺少哪些元件的数据手册，并请他们提供。不要因为没有数据手册就默默跳过验证。例如：“我找不到 U3（XYZ1234）和 U7（ABC5678）的数据手册。你能提供这些资料吗？我需要它们来验证引脚配置和应用电路。”

**结构化数据手册提取（适用于大型设计或重复审查）：**将数据手册规格预先提取到缓存的 JSON 中，以便更快、更一致地验证引脚。对于包含 10 个以上 IC 的设计，这尤其有用，因为每次都从头重新阅读 PDF 会很慢。

python3 <skill-path>/scripts/datasheet_page_selector.py <pdf_path> --mpn <mpn> --category <category>

阅读选定页面并生成提取 JSON 后，使用 datasheet_score 和 datasheet_extract_cache 模块为其评分并缓存。提取结果存储在 datasheets/extracted/<MPN>.json 中，并在后续审查中重复使用。完整的提取流程（架构、页面选择、评分标准、使用方 API）由 datasheets 技能负责——请参阅 skills/datasheets/SKILL.md 及其参考指南。

每份数据手册需提取的内容（请记录页码／章节／图号／公式编号，以便引用）：

• 引脚功能表（引脚编号 → 名称 → 功能）
• 绝对最大额定值（电压、电流、温度——包括 VCC/GND 引脚可承受的最大连续电流，因为它会限制浪涌电流）
• 推荐应用电路及所需外部元件
• 所需元件值（以及推导这些值的公式）
• 热特性

**对于无源元件：**通常不需要单独查阅电阻器／电容器的数据手册，但应根据指定这些元件的 IC 数据手册核实元件值。IC 数据手册可能写着“使用 10µF 输入电容”——请确认原理图中对应位置实际使用的是 10µF，而不是 1µF。

**反面模式：不查阅数据手册就进行验证。**设计审查中最常见的失败原因，是根据 KiCad 库符号而非制造商数据手册来验证元件连接。这会形成循环验证——如果库符号的引脚映射有误，那么原理图、PCB 和分析器输出都会彼此一致（并且都与错误的引脚配置一致）。只有数据手册才能揭示错误。对于自定义／社区库符号（例如 sacmap:TPS61023），尤其要警惕，因为没有上游 KiCad 库可作为辅助检查。如果你发现自己正在通过阅读 .kicad_sym 文件或分析器的引脚数据来验证引脚配置，并确认其与原理图一致——请停下来。这只是进行一致性检查，并非正确性检查。打开实际的 PDF 数据手册，找到引脚功能表并据此核验。在报告中注明数据手册的页码／章节／图号，方便设计人员确认你的工作。

原理图 + PCB 交叉核对

如果两个文件都存在，请对它们进行交叉核对。这能发现代价最高的错误——引脚接反、网络缺失和封装不匹配。这些问题可能通过 DRC/ERC 检查，却会导致电路板无法正常工作。

1. 元件数量：比较原理图中的元件数量（不包括电源符号）与 PCB 封装数量。
2. 网络一致性：确认原理图中的网络名称出现在 PCB 网络声明中。网络缺失可能表示布线不完整或更改尚未同步。
3. 引脚-网络分配：比较原理图中的引脚到网络映射与 PCB 中焊盘到网络的映射。不匹配可能表明引脚接反或库有误。风险较高的情况包括：
   • 自定义／社区库符号（可能与数据手册中的引脚排列不符）
   • 多单元符号（运算放大器、门阵列）——单元到引脚的分配错误
   • QFN/BGA 封装——焊盘编号错误
   • 未标注 MPN 的晶体管——引脚排列不明确（参见验证步骤 3）
   • 有极性元件——阳极／阴极方向
   • 连接器——1 脚方向
4. 封装匹配：原理图中的 Footprint 属性与实际 PCB 封装是否一致（例如，SOT-23 与 SOT-23-5）。
5. DNP 一致性：原理图中的 DNP 元件在 PCB 上不应有布线。
6. 数值／MPN 一致性：原理图与 PCB 属性中的数值和 MPN 是否一致。

每个封装中的 PCB 分析器字段 sch_path、sch_sheetname 和 sch_sheetfile 可用于自动交叉核对。

基于差异的设计比较

比较两份分析 JSON 输出，查看设计修订之间的变化（例如，基础分支与 PR、v1 与 v2）。当用户提出“比较设计”“有哪些变化”“比较我的原理图”“显示相对于 main 的变化”或“比较 base 与 head”等要求时使用。完整参考文档：references/diff-analysis.md。

# Compare two schematic analysis outputs (JSON to stdout)
python3 <skill-path>/scripts/diff_analysis.py base.json head.json

# Human-readable text output
python3 <skill-path>/scripts/diff_analysis.py base.json head.json --text

# Write to file, custom threshold (ignore <2% deltas)
python3 <skill-path>/scripts/diff_analysis.py base.json head.json --output diff.json --threshold 2.0

# Ignore small percentage changes (e.g., rounding noise)
python3 <skill-path>/scripts/diff_analysis.py base.json head.json --threshold 5.0 --text

自动检测分析器类型（原理图、PCB、EMC、SPICE）。报告包括：

• 元件：新增、移除、数值／封装／MPN 变更
• 信号分析：按检测类型列出参数变化，由 detection_schema.SCHEMAS 中的标识字段和值字段驱动
• BOM：新增／移除的明细项、数量变化
• 连通性／ERC：新增／已解决的单引脚网络、悬空网络、多驱动网络、ERC 警告
• EMC 发现：新增／已解决的发现项及其严重程度、风险评分变化量、各网络的评分变化
• SPICE 结果：状态转换（通过->失败的回退、失败->通过的修复）、蒙特卡洛关注项变化
• 严重性分类：none（无变化）、minor（仅统计数据变化）、major（元件／信号／发现项变化）、breaking（SPICE 回退、新增 CRITICAL EMC 发现项、新增 ERC 警告）

analysis_cache.should_create_new_run() 也会以编程方式使用此功能，判断新的输出是否需要创建带时间戳的新运行文件夹。

热点温度估算

结合原理图功耗数据与 PCB 热设计基础设施（铜箔铺铜、热过孔、封装类型），估算耗散功率元件的结温。当用户提到“检查热设计”“热分析”“会不会过热”“结温”“功耗”或“热设计”时使用。

# Recommended: integrate into the current run
python3 <skill-path>/scripts/analyze_thermal.py \
    -s analysis/<run_id>/schematic.json \
    -p analysis/<run_id>/pcb.json \
    --analysis-dir analysis/

# Human-readable text report
python3 <skill-path>/scripts/analyze_thermal.py -s schematic.json -p pcb.json --text

# Custom ambient temperature (default: 25°C), one-off output file
python3 <skill-path>/scripts/analyze_thermal.py -s schematic.json -p pcb.json --ambient 40 -o thermal.json

将每个功率元件（LDO、开关稳压器、采样电阻）建模为点热源。计算公式为 Tj = T_ambient + P_diss × Rθ_JA_effective，其中 Rθ_JA 来自封装查找表（SOT-223：60°C/W，QFN-5x5：25°C/W 等），并根据 PCB 热过孔和铜箔铺铜情况进行修正。规则：

规则	条件	严重程度
TS-001	Tj 超过绝对最大额定值	严重
TS-002	Tj 距绝对最大额定值不足 15°C	高
TS-003	Tj > 85°C（可能影响附近的无源元件）	中
TS-004	P > 0.5W 且没有热过孔	中
TS-005	功耗较大，但仍在安全范围内	信息
TP-001	MLCC 距发热元件 10mm 以内	低
TP-002	电解电容距发热元件 10mm 以内	中

热设计发现和评估包含丰富格式的封装（detector、rule_id、summary、evidence_source、report_context）。规则 ID：TS-001..005（安全性）、TP-001..002（邻近性）、TH-DET（评估）。

交互式“假设分析”参数扫描

无需重新运行完整分析器，即可即时查看元件取值变化对电路行为的影响。当用户提到“如果我更改”“如果……会怎样”“试试其他取值”“将 R5 换成 4.7k”“参数扫描”“哪个取值能让我得到 X”，或想探索设计权衡时使用。完整参考： references/what-if.md 。

# Single value change
python3 <skill-path>/scripts/what_if.py analysis.json R5=4.7k --text

# Sweep: comma list or log range
python3 <skill-path>/scripts/what_if.py analysis.json R5=1k,2.2k,4.7k,10k --text
python3 <skill-path>/scripts/what_if.py analysis.json R5=1k..100k:10 --text

# Tolerance corner analysis (±5% worst-case)
python3 <skill-path>/scripts/what_if.py analysis.json R5=4.7k+-5% C3=100n+-10% --text

# Find the right value: inverse solver with E-series snapping
python3 <skill-path>/scripts/what_if.py analysis.json --fix voltage_dividers[0] --target 3.3 --text
python3 <skill-path>/scripts/what_if.py analysis.json --fix rc_filters[0] --target 1000 --text

# EMC impact preview
python3 <skill-path>/scripts/what_if.py analysis.json C3=1u --emc --text

# SPICE re-simulation on affected subcircuits
python3 <skill-path>/scripts/what_if.py analysis.json R5=4.7k --spice --text

# Export patched JSON for further analysis (EMC, thermal, diff)
python3 <skill-path>/scripts/what_if.py analysis.json R5=4.7k --output patched.json

在分析器 JSON 中修改元件取值，重新计算派生字段（滤波器截止频率、分压比、运放增益、晶振负载、电流检测范围、稳压器 Vout），并显示更改前后的对比及百分比变化。支持单项更改、多点扫描（逗号分隔或对数范围）、容差极限分析、采用 E 系列取值的反向修正建议、EMC 影响预览、PCB 寄生参数分析（自动发现或通过 --pcb 指定）以及 SPICE 再验证。

发现摘要

汇总一次运行中所有分析器的发现。当用户需要前 N 项列表、按严重程度筛选的视图，或无需读取单个 JSON 文件即可获取机器可读的汇总信息时使用。从 analysis/manifest.json 读取当前运行数据。

# Top findings from the current run (default: top 20)
python3 <skill-path>/scripts/summarize_findings.py analysis/

# Limit to top 10 high-severity findings
python3 <skill-path>/scripts/summarize_findings.py analysis/ --top 10 --severity high

# JSON output for programmatic consumption
python3 <skill-path>/scripts/summarize_findings.py analysis/ --json

# Summarise a specific run by ID
python3 <skill-path>/scripts/summarize_findings.py analysis/ --run <run_id>

标志：--top N（默认值为 20）、--severity（筛选 critical/high/warning/info）、--run（指定运行 ID，而非最新运行）、--json（机器可读输出）。

元器件生命周期与温度审计

查询分销商 API，检查元器件的生命周期状态（在产、NRND、EOL、已停产）和工作温度范围覆盖情况。当用户说“检查是否有已停产的元器件”“生命周期审计”“是否有元器件已停产”“温度审计”“这能否适用于工业温度范围”，或进行生产就绪评审时使用。

# Basic lifecycle check
python3 <skill-path>/scripts/lifecycle_audit.py analysis.json

# With temperature range validation (preset or custom)
python3 <skill-path>/scripts/lifecycle_audit.py analysis.json --temp-range industrial
python3 <skill-path>/scripts/lifecycle_audit.py analysis.json --temp-range="-40,105"

# Query specific distributors only
python3 <skill-path>/scripts/lifecycle_audit.py analysis.json --only digikey,lcsc

# Search for replacement parts when EOL/NRND found
python3 <skill-path>/scripts/lifecycle_audit.py analysis.json --suggest-alternatives

# Save results
python3 <skill-path>/scripts/lifecycle_audit.py analysis.json --output lifecycle.json

读取分析器 JSON BOM 部分，提取唯一 MPN，并查询分销商（LCSC 无需身份验证、DigiKey、element14、Mouser）以获取生命周期状态和工作温度。温度预设：commercial（0/70°C）、industrial（-40/85°C）、extended（-40/105°C）、automotive（-40/125°C）、military（-55/125°C）。调用 API 前还会检查数据手册提取缓存中的温度数据。

生命周期审计会生成详细格式的问题：LC-001（已停产/停止供货）、LC-002（最后采购）、LC-003（NRND）、LC-004（状态未知）、LC-005（单一来源）、LC-006（交期较长）、LT-001（温度不符合要求）。未传入 --lifecycle 时（默认情况），analyze_schematic.py 会生成一条 LC-007 信息级问题，注明已跳过审计——这样报告的问题列表会明确显示这一缺项，而不是悄然遗漏。

需要网络访问——与核心分析器不同，此脚本会调用分销商 API。需要的环境变量与分销商技能相同（DIGIKEY_CLIENT_ID/SECRET、MOUSER_SEARCH_API_KEY、ELEMENT14_API_KEY）。LCSC 无需凭据。

原理图分析器规则 ID

所有原理图规则问题都会出现在 findings[] 中。以下规则 ID 由原理图分析器生成：

规则	检测器	条件	严重性
SS-001	audit_sourcing_gate	MPN 覆盖率 < 50%	high
SS-002	audit_sourcing_gate	MPN 覆盖率 50–80%	warning
SS-003	audit_sourcing_gate	MPN 覆盖率 80–100%	info
NT-001	analyze_connectivity	单引脚网络：信号引脚	warning
NT-001	analyze_connectivity	单引脚网络：power_out 或 passive 引脚	info
RS-001	audit_rail_sources	电源轨没有声明的电源（没有 power_out 引脚、PWR_FLAG、桥接跳线或稳压器输出）	warning
RS-002	audit_rail_sources	电源轨依赖用户闭合一个断开的跳线	high
RS-003	audit_rail_sources	电源轨通过默认桥接的焊接跳线或铁氧体间接供电——功能正常，但建议添加 PWR_FLAG	info
LB-001	detect_label_aliases	网络有 >= 2 个不同的全局/分层标签（电源网络除外）	info
PP-001	audit_power_pin_dc_paths	IC 电源输入引脚只能通过电容连接到电源轨（2 跳 BFS）	high
SP-001	detect_shorted_two_pin_components	两引脚无源元件或二极管的两个引脚连接到同一网络（跳线、网络连接器、0R、DNP 除外）；同一网络上 >= 5 个时合并为一条网络级问题	warning

SS-001 是制造前阻断项——应在下单前解决的 high 级问题。NT-001 的严重性取决于引脚类型：信号引脚（数字 I/O、双向）为 warning；power_out 和 passive 引脚为 info。RS-001 专用于“完全没有电源”这一情况（warning）；较轻的“通过桥接跳线/铁氧体供电”情况由独立规则 ID RS-003（info）处理，以便评审人员和 CI 门禁分别筛选两者。PP-001 使用 2 跳 BFS 遍历网络图，并排除电容边，以确认从电源轨到每个 IC 电源输入引脚都有直接直流通路。对于模块内部的 LDO 电源轨（VDDPLL_*、VDDA_INT_*、VDDCORE_*、VCAP、VDDREG），仅通过去耦连接属于正确拓扑，因此 PP-001 会降为 info。

深度审查阶段

分析器运行后，执行深度审查阶段：逐个 IC 将实际用法与数据手册要求进行比较。分析器提供事实；此阶段才进行判断。

对于设计中的每个 IC：

1. 获取其数据手册事实——优先使用提取缓存（datasheets/extracted/<MPN>.json），找不到时再查看 PDF（直接阅读）。如果两者都不存在，记录一条信息级发现“ 未验证——没有可用的数据手册”，然后继续。
2. 将实际用法与分析器 JSON 中的信息进行比较：电源电压与额定值、引脚功能与连接、所需外部元件（电感、电容、电阻）与原理图中的元件，以及热环境。根据数据手册推导检查项——每种元件都有各自的检查项。
3. 如果需要计算限值，在 analysis/helpers/ 下编写一次性辅助脚本，读取分析器 JSON 并输出数值。将脚本和结果作为证据引用。
4. 将发现记录到 analysis/deep_review.json（结构见：skills/kicad/review/schemas/deep_review.schema.json）。每条发现都需要一个证据块：至少包含一个设计锚点（元件/网络/引脚）和一个来源（数据手册引文和/或计算结果）。

然后检查相互作用的元件对：共用电源轨（时序、总负载）、总线搭档（电压电平、上拉归属）、热邻近元件。鼓励自由探索——追查任何看起来有问题的地方。

报告前进行验证：

python3 skills/kicad/review/scripts/deep_review_gate.py \
    analysis/deep_review.json --analysis-dir analysis/

门禁会验证引用、生成 finding_ids，并将失败项连同原因移至 quarantined[]。修正或接受隔离项；报告会将其呈现为未经验证的声明。

重新审查：如果先前的审查已生成 analysis/deep_review.json，先将其复制到别处，并在新一轮审查开始时查看差异——在“Previous Review Delta”部分报告已修复、仍未解决和新增的问题：

cp analysis/deep_review.json analysis/deep_review.prev.json
# ... run the pass, then the gate ...
python3 skills/kicad/scripts/diff_analysis.py \
    analysis/deep_review.prev.json analysis/deep_review.json --text

BOM 较大时：按子系统分块，或使用子 Agent 按 IC 分组并行审查。各类元件的比较启发式、成对检查模式和辅助脚本约定，请参阅 references/deep-review.md。analysis/design_context.json（如果存在）可用于调整优先级——例如，汽车应用会提高对降额的关注。此项为可选；切勿因此阻塞流程。

参考文件

详细的方法和格式文档位于参考文件中。按需阅读——其中包含脚本不会自动输出的深入内容。

参考文件	行数	阅读时机
deep-review.md	—	深度审查：按部件类别进行比较的启发式方法、成对检查、辅助脚本约定、扇出
schematic-analysis.md	1133	原理图深度审查：数据手册验证、设计模式、错误分类、公差叠加、GPIO 审查、电机控制、电池续航、供应链
pcb-layout-analysis.md	447	高级 PCB 分析：阻抗计算、差分对、回流路径、铜箔平衡、边缘间距、对铜箔敏感的元件（电容式触摸、天线）、自定义分析脚本
output-schema.md	293	完整的分析器 JSON 架构，包含字段名称、类型和常见提取模式
file-formats.md	379	手动检查文件：S 表达式结构、所有 KiCad 文件类型的逐字段文档、版本检测
gerber-parsing.md	729	Gerber/Excellon 格式详情、X2 属性、分析技术
pdf-schematic-extraction.md	315	PDF 原理图分析：提取工作流、符号约定、KiCad 转换
supplementary-data-sources.md	288	恢复旧版 KiCad 5 数据：网表解析、缓存库、PCB 交叉引用
net-tracing.md	120	手动追踪网络：坐标计算、Y 轴反转、旋转变换
manual-schematic-parsing.md	289	原理图脚本失败时的备用方案
manual-pcb-parsing.md	467	PCB 脚本失败时的备用方案
manual-gerber-parsing.md	621	Gerber 脚本失败时的备用方案
report-generation.md	614	报告模板（关键发现置顶）、分析器输出字段参考（原理图/PCB/Gerber）、严重性定义、撰写原则、特定领域的重点、已知分析器局限性
standards-compliance.md	638	IPC/IEC 标准表：导线间距（IPC-2221A 表 6-1）、载流能力（IPC-2221A/IPC-2152）、环宽、孔径、阻抗、过孔防护（IPC-4761）、爬电距离/电气间隙（ECMA-287/IEC 60664-1）。适用于所有电路板；对于专业/工业设计、高压、市电输入或安全隔离设计，应自动触发查阅。
oshwa-certification.md	—	OSHWA 开源硬件认证准备情况：可编辑的 KiCad 源文件、公开文档、许可、版本注册、认证标志使用。用户询问 OSHWA 认证或开源硬件发布时阅读——这是包含明确审批关卡的文档/许可审查，而非电气检查
design-intent.md	—	设计意图解析，以及会影响特定上下文中问题判定的目标市场/认证/电源限制
diff-analysis.md	—	diff_analysis.py 如何比较两次分析器运行结果并生成按严重性排序的变更报告
what-if.md	—	what_if.py 如何修改元件值、重新计算派生字段，并为反馈分压器/晶振负载电容/电容降额提供修复建议
config-reference.md	—	.kicad-happy.json 架构——用于分析缓存、抑制项、设计意图和风险评分的项目配置
datasheet-verification.md	—	根据结构化数据手册提取结果，自动交叉检查原理图连接（引脚电压、必需的外围元件、去耦是否充分）

有关脚本内部实现、数据结构、信号分析模式和批量测试套件文档，请参阅 scripts/README.md。

文件类型快速参考

扩展名	格式	用途
.kicad_pro	JSON	项目设置、网络类、DRC/ERC 严重级别、BOM 字段
.kicad_sch	S-expr	原理图页（符号、导线、标签、层级）
.kicad_pcb	S-expr	PCB 布局（封装、走线、过孔、区域、板框）
.kicad_sym	S-expr	符号库（带引脚和图形的原理图符号）
.kicad_mod	S-expr	单个封装（位于 .pretty/ 目录中）
.kicad_dru	自定义	自定义设计规则（DRC 约束）
fp-lib-table / sym-lib-table	S-expr	库路径表
.sch / .lib / .dcm	旧版	KiCad 5 原理图、符号库、描述
.net / .xml	S-expr/XML	网表导出、BOM 导出
.gbr / .g* / .drl	Gerber/Excellon	制造文件（铜箔、阻焊层、丝印、板框、钻孔）

如需检测版本并了解各字段的详细格式说明，请阅读 references/file-formats.md。在 Flatpak 版 KiCad 中，kicad-cli（用于生成原生 DRC/ERC 报告、导出文件）不在 PATH 中；请通过 flatpak run --command=kicad-cli org.kicad.KiCad <args> 调用。其沙盒无法读取主机的 /tmp，因此请将导出文件/网表写入项目目录（或 $HOME 下的其他位置）。

分析策略

深入分析原理图

如需基于数据手册全面审查原理图——识别子电路、获取数据手册、根据制造商建议验证元件值、与常见设计模式进行比较、检测错误并提出改进建议——请阅读 references/schematic-analysis.md。当用户要求深入审查、验证或分析原理图时，请使用此参考资料。

获取数据手册：分析需要数据手册资料时，优先使用 DigiKey API 作为数据源（参见 digikey 技能）——它通过 DatasheetUrl 字段直接返回 PDF URL，无需网页抓取。根据原理图元件属性中的 MPN 搜索。仅当 DigiKey 上没有相关元件时，才改用网络搜索。

深入分析 PCB

如需进行超出 PCB 分析器脚本能力的高级布局分析——基于叠层参数计算阻抗、编写 DRC 规则、电力电子设计审查技巧、差分对验证、回流路径分析、铜箔平衡评估、板边间距规则，以及手动编写脚本的模式——请阅读 references/pcb-layout-analysis.md。

大多数常规 PCB 分析（过孔类型、环宽、布局、连通性、散热过孔、电流承载能力、信号完整性、DFM 评分、墓碑效应风险、散热焊盘过孔）由 analyze_pcb.py 自动处理。更深入的手动调查请参阅该参考资料。

设计意图

如需解读自动检测的设计意图，并根据产品类别和目标市场（业余爱好、消费、工业、医疗、汽车、航空航天）调整审查严重程度，请阅读 references/design-intent.md。查看分析输出中的 design_intent 对象以了解设计背景。

探查 Analyzer JSON

审查过程中，你经常会临时运行 python3 -c "import json; ..." 探查，以检查分析器的输出（引脚网络、电源轨电压、特定发现的内容等）。以下两种做法能显著提升用户跟进过程的体验：

每次探查前都说明要检查什么。 在脚本前用一句简洁的话说明——不要放在脚本之后，也不要写在脚本注释里。用户只看文字说明，就应能理解审查流程，而无需打开每次工具调用。

• 不佳：[Bash] python3 -c "import json; d = json.load(open('analysis/.../schematic.json')); print([...])"，没有任何说明文字。
• 较好：“检查 U3 的 EN 引脚是直接连接到 +BATT，还是通过分压器连接。”然后运行探查。
• 较好：“验证检测到的 TPS61023 拓扑是否符合数据手册（预期为升降压）。”然后运行探查。

对那些调查为何某项看起来有问题的探查，文字说明尤其重要——用户在这些时候最容易失去上下文。

应对 JSON 结构不确定性的防御性做法。 分析器输出的结构各不相同（字典列表、以引用标识符为键的字典、可选字段、嵌套路径）。如果脚本假设了错误的结构，就会在探查过程中崩溃。

• 切片前先检查类型：对字典执行 x[:3] 会触发 KeyError: slice(None, 3, None)。字典应使用 list(x.values())[:3] 或 list(x.items())[:3]。
• 调用 min() / max() 前先检查是否非空：min([]) 会触发 ValueError: min() iterable argument is empty。可以使用 min(items, default=None)，或先用 if items: 检查。
• 如果某个字段可能不存在（许多字段取决于分析器发现的内容，因而是可选的），应使用 .get("key", default)，而不是 ["key"]。
• isinstance(x, list) 与 isinstance(x, dict)——components 是字典列表，nets 是以网络名称为键的字典。遍历前请先查看架构参考。
• 如果某个发现字段可能是字符串列表，也可能是字典列表（少见，但旧版结构中会出现），请兼容两种情况：r = c if isinstance(c, str) else c.get("reference", "")。
• 焊盘或元件可能缺少数据：pad.get("abs_x") 可能为 None；进行算术运算前请先检查。

少量投入，大幅减少阻碍。

若要探查原始 .kicad_sch / .kicad_pcb 文件本身（而非分析器 JSON），请使用 <skill-path>/scripts/sexp_parser.py：parse(text) 和 parse_file(path) 会将文档作为嵌套 Python 列表返回；find_all(node, kw)、find_first(node, kw) 和 get_value(node, kw) 可用于遍历文档。

快速检查清单

原理图 — 验证：每个 IC 的 VCC/GND 引脚对都配有去耦电容、I2C 上拉电阻、复位引脚电路、未连接引脚带有未连接标记、各工作表中的网络命名一致、外部连接器上有 ESD 保护、电源时序（EN/PG）正确、总线电容充足。

PCB — 验证：电源走线宽度符合电流要求（IPC-2221）、过孔载流能力、适用于高压的爬电距离/电气间隙、去耦电容靠近 IC 电源引脚、接地平面连续（信号下方没有分割）、受控阻抗走线（USB/DDR）、板框为闭合多边形、丝印清晰易读、每个带裸露焊盘的 IC 的散热过孔数量（报告数量，并与数据手册建议范围比较——这是最常见的 QFN/DFN 布局错误之一）、对铜敏感元件（触摸焊盘和天线）落实禁布区——仅确认没有铺铜并不足够，因为也可能只是意外未铺铜；请检查禁布区是否存在并设为 DRC 规则、差分对长度差符合协议特定容差（计算长度差并引用规范——仅看原始长度，无法判断是否存在问题）、在 PCB 层面交叉核对所有 IC/晶体管/连接器的焊盘与网络（可发现 DRC/ERC 无法检测到的库封装引脚编号错误——这是最危险的一类 PCB 错误）。可参考 references/standards-compliance.md 中的 IPC/IEC 标准值——导线间距和载流能力与大多数电路板相关；爬电距离/电气间隙和过孔保护适用于连接市电或具有安全隔离要求的设计。

常见错误（按可能导致电路板失效的程度排序）：IC 引脚互换（库符号与数据手册引脚排列不符——DRC/ERC 无法检测）、晶体管引脚排列不明确（没有 MPN 的 SOT-23——符号假定的引脚顺序可能与实际元件不符；无法验证时，根据常见惯例评估其合理性）、封装焊盘编号错误、原理图未同步到 PCB 导致网络缺失、封装型号错误（SOT-23 与 SOT-23-5 混淆）、数字输入悬空、缺少总线电容、极性接反、反馈分压器数值错误、晶振负载电容错误、USB 阻抗不匹配、QFN 散热焊盘缺少过孔、连接器引脚排列错误、被动元件数值异常（数值在技术上有效，但对于该应用并不常见——例如，非标准的上拉电阻值或不常见的去耦电容值）。

报告生成

撰写设计审查报告时，请阅读 references/report-generation.md，了解标准报告模板、严重程度定义、写作原则和特定领域的重点。报告格式涵盖：概述、元件摘要、电源树、分析器验证（抽查）、信号/电源/设计分析审查、质量与制造、按优先级排列的问题表、积极发现以及已知的分析器局限。报告问题之前，务必将分析器输出与原始原理图交叉核对。

设计对比

比较两种设计时，比较：元件数量/类型、网络类别/设计规则、走线宽度/过孔尺寸、板尺寸/层数、电源拓扑、KiCad 版本差异。

安全架构

所有分析脚本都会处理不可信输入（用户提供的 KiCad 文件、第三方 PDF 数据手册、分销商 API 响应）。解析架构可缓解提示词注入和代码执行风险：

• 确定性解析器：S 表达式文件（.kicad_sch、.kicad_pcb）由专用的递归下降解析器（sexp_parser.py）解析，而非使用 eval()、exec() 或任何代码执行原语。解析器只会生成 Python 列表和字符串。
• 结构化 JSON 边界：所有分析器输出均为采用固定架构的结构化 JSON。外部内容（元件值、网络名称、数据手册文本）均作为数据字段处理，绝不作为指令或代码。
• PDF 处理：数据手册 PDF 由 pdftotext 处理（外部二进制程序，使用列表形式的参数，不存在 shell 注入风险），页面内容会传递给 LLM 进行结构化提取。提取的数据会在缓存前根据 5 维质量标准进行验证。
• 不根据输入执行 shell 命令：任何分析器都不会根据文件内容构造 shell 命令。子进程调用一律使用列表形式的参数。
• 默认只读：分析脚本绝不会修改输入文件。写回 BOM 需要显式指定 --write 标志。
• 分销商 API 范围：网络请求仅限于用于下载数据手册和查询元件的已知分销商 API（DigiKey、Mouser、LCSC、element14）。仅发送 MPN，不会有设计数据离开本地计算机。