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 进行元器件搜索和数据手册获取。交接给 jlcpcb/pcbway 进行制造订购和 DFM 规则验证。始终运行 spice 在设计评审期间进行仿真验证（如果已安装任何 SPICE 仿真器 — 使用 which ngspice ltspice xyce 检查）。始终运行 emc 在设计评审期间进行 EMC 预合规风险分析（当原理图和 PCB 分析均可用时）。这些不是可选的 — 跳过它们会导致价值计算错误和 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 覆盖率不完整）是其较温和的变体，对它们引用的元器件具有相同的含义。
原理图生成（绘制与重绘）
当用户要求创建、添加、重绘或重新设计原理图风格时使用此工作流 — 例如“添加 5V/5A TPS54560 电路”、“把原理图画成可读风格”、“生成降压原理图”、“重画这块电源”。
- 首先阅读标准。 在创建或编辑任何原理图之前，必须先阅读
references/schematic-drawing-standards.md。它定义了 LM5013 风格的电源总线布局、GND 总线、标签策略、KiCad 9 布线约束（在连接点处分割导线；不允许引脚到引脚的单独导线；在共享节点处使用标签）以及验证关口。 - 根据数据手册设计。 获取/读取 IC 数据手册；提取引脚排列、Vref、绝对最大额定值和典型应用。使用数据手册中的公式计算数值（反馈分压器、RT/频率、电感、电容、补偿）并在绘图前列出这些数字。
- 在 1.27 mm 网格上规划模块，镜像规范的 LM5013 结构：一条连续的电源总线
INPUT → IC → SW → L → OUTPUT，底部 GND 总线，控制元件以有序的带状分布在 IC 下方（每个功能一列）。在写入导线前验证符号引脚位置和旋转语义。 - 生成。 直接编辑
.kicad_schS-表达式或使用生成器脚本。每条导线必须终止于引脚、连接点、标签或电源符号；在每一个连接点处将电源轨分割成段。对于 EasyEDA Pro，使用相同的标准交接给easyeda-schematic-draw技能。 - 使用 KiCad 本身进行验证 — 在报告成功之前，此步骤是强制性的：
kicad-cli sch erc→ 0 个错误 / 0 个警告kicad-cli sch export netlist→ 引脚级与设计意图匹配- 运行原理图分析器，修正启发式 Vout 估计值以匹配数据手册 Vref
- 几何检查：无符号主体重叠，无标签位于 IC 主体内部
- PDF/PNG 渲染 + 视觉检查：一条连续的电源总线，可读的控制带，无元件堆叠
- 报告设计值及方程、验证证据以及您已修正的任何分析器限制。
下面的分析和设计评审工作流同样适用于生成的内容。
设计评审合约
当用户要求进行设计评审、完整报告、可制造性评估或任何等效内容时，不要仅运行一两个分析器并总结其发现项就停止。此技能中的设计评审有更严格的合约：
- 阅读此
SKILL.md中的完整工作流，而不仅仅是分析器命令部分。 - 在撰写报告之前阅读
references/report-generation.md。 - 为项目中存在的文件运行所有适用的分析器，然后明确说明哪些已运行，哪些未运行。
- 在声称任何内容“已验证”之前，执行原始文件和数据手册交叉验证。
- 在将分析器误报升级为阻塞项之前，对其进行筛选分类。
- 如果某个必需步骤无法完成，则将其作为评审缺口声明，而不是静默忽略。
将此视为最低标准。仅靠分析器 JSON 不能构成最终评审。
最低评审清单
对于完整的设计评审，在报告中明确说明以下每个项目：
datasheets/存在、已同步，或已声明验证缺口analyze_schematic.pyanalyze_pcb.py --fullcross_analysis.pyanalyze_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 — 设置时，为 __unnamed_N 网络提供一个 Ref.PinName 提示，该网络的唯一命名 IC 引脚说明了其作用（例如 __unnamed_36 → U1.VBOOT）。缺失意味着分析器无法消除歧义。 | 忽略 display_name 并将原始 __unnamed_36 粘贴到报告中 |
| IC 引脚映射 | ic_pin_analysis[] 是一个 IC 条目列表；每个条目包含 .reference 和 .pins[]，后者包含 .pin_number / .pin_name / .pin_type / .net / .connected_to[] | 将其视为 {ref: {...}} 或 pins[].number |
| 检测到的电路 | 每个模式匹配的电路（电源稳压器、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.footprints[].x / .y 位于顶层（没有 .position 包装器） | footprints[].position.x |
| 发现项 | 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 # 一次性，无缓存
输出结构化 JSON（约 60-220KB，取决于电路板复杂度），包含：
- 元件和 BOM：带有参考编号、值、封装、lib_id、类型分类、MPN、数据手册的库存清单；去重 BOM 及数量
- 网络：完整的连接图，包含引脚到网络映射、导线数量、未连接点
- 检测到的子电路（模式匹配电路 — 全部作为
findings[]条目发出，带有匹配的Det.*检测器；使用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 保护覆盖审计、调试接口（SWD/JTAG 及 MCU 追踪）、电源路径（负载开关/理想二极管/USB PD 控制器）、ADC 信号调理（外部 ADC + 电压基准及抗混叠交叉引用）、复位/监控电路（电压监控器/看门狗/RC 复位网络）、时钟分布（时钟发生器/PLL/振荡器输出追踪）
- 电源稳压器 — LDO/开关/反相拓扑，通过数据手册验证的 Vref 查找（约 60 个系列）进行 Vout 估计，带有启发式回退和固定输出后缀解析，