用 KiCad 分析脚本做硬件设计评审：从原理图/PCB/G…

当需要审查、调试、比对或验证 KiCad 原理图、PCB、Gerber 或 PDF 参考设计时，用一套 Python 分析器提取结构化数据并按固定契约完成设计评审。

适用场景

解决思路

1. 先扫描项目目录，找出所有 .kicad_sch、.kicad_pcb、.kicad_pro、Gerber 目录以及 .net/.xml 网表文件。
2. 在读取任何分析器输出之前先同步数据手册：检查项目下是否存在 datasheets/ 目录，若不存在且可用 DigiKey API key（DIGIKEY_CLIENT_ID），主动提出先同步数据手册；用户拒绝或无 key 则继续，但后续验证只能算一致性检查。
3. 若分析器输出中出现 DS-001 发现（severity high，detector audit_datasheet_coverage），停止并选择：(a) 通过 digikey/mouser/lcsc/element14 同步数据手册，(b) 在 BOM 上补齐 MPN，(c) 在报告中明确声明所有引脚级、电气和稳压器发现仅为一致性检查，禁止使用 verified/confirmed/per datasheet 等措辞；DS-002、DS-003 为较软的同类变体。
4. 运行核心分析器：有原理图则运行 analyze_schematic.py，有 PCB 则运行 analyze_pcb.py --full，有 Gerber 则运行 analyze_gerbers.py，尽量并行执行；统一使用 --analysis-dir analysis/ 让所有输出落在同一 run 目录并由 manifest 跟踪。
5. 当原理图和 PCB 分析都存在时，运行 cross_analysis.py --schematic sch.json --pcb pcb.json，检查连接器电流容量（CC-001）、ESD 防护缺口（EG-001）、去耦充分性（DA-001）、原理图/PCB 同步（XV-001..003）。
6. 当原理图和 PCB 分析都存在时，运行 EMC 预合规分析：python3 <emc-skill-path>/scripts/analyze_emc.py --schematic sch.json --pcb pcb.json（脚本在 emc skill 下），覆盖地平面完整性、去耦、开关谐波、PDN 阻抗、差分对偏斜、ESD 路径等 44 项规则检查。
7. 运行 SPICE 仿真：先执行 which ngspice ltspice xyce，若任一仿真器已安装则必须运行 spice skill 的 simulate_subcircuits.py sch.json；若原理图和 PCB 分析都存在，再运行 extract_parasitics.py pcb.json --output parasitics.json（需 --full 的 PCB JSON）并以 --parasitics parasitics.json 传入，用于高阻电路（>100K 反馈分压、LC 滤波、RF 匹配）。
8. 当原理图和 PCB 分析都存在时，运行 analyze_thermal.py --schematic schematic.json --pcb pcb.json，按封装 θJA 与 PCB 热过孔修正估算结温。
9. 当有网络访问和 MPN 覆盖时，用 analyze_schematic.py --lifecycle 运行生命周期审计，通过分销商 API 检查元件停产状态。
10. 直接读取 .kicad_pro 项目文件（JSON 格式），获取设计规则、net class 和 DRC/ERC 设置。
11. 检查是否存在既往评审文件（*review*.md、*design-review*.md），读取最近一份；若 auto_diff 启用且有历史 run，运行 diff_analysis.py 对比当前与上一次并纳入 Previous Review Delta 章节。
12. 在把数据写进报告前逐项验证分析器输出：用 grep 统计 (symbol (lib_id 块数量（减去电源符号）核对元件数；逐元件核对引脚到网络的映射；核对物理正确性而非仅一致性；端到端追踪电源轨和关键信号网络；检查稳压器 vout 的 vref_source 字段（lookup 为数据手册验证，heuristic 为猜测）；多层图纸核对子图连接。
13. 对晶体管等存在多种引脚排列的封装做物理正确性检查：SOT-23 BJT 至少有 6 种引脚排列（BEC/BCE/EBC/ECB/CBE/CEB），SOT-23 MOSFET 有 GDS/GSD/SGD/DSG；无 MPN 时标记#为关键歧义，有 MPN 时对照数据手册引脚图核对符号的引脚到焊盘分配。
14. 无法验证时评估合理性而非止步于 unverified：用领域知识判断该选择是否符合常见惯例（如 SOT-23 NPN 最常见为 BCE、10kΩ I2C 上拉正常、100Ω 上拉可疑），并报告置信度。
15. 对 PCB 输出做验证：核对封装数量与板框尺寸是否与原始 .kicad_pcb 一致；对照原理图引脚到网络映射核对 IC 封装的焊盘到网络分配，以捕获库封装焊盘编号与符号引脚不符的错误。
16. 检查 zone 填充是否为最新：铜存在性分析依赖 KiCad 的填充多边形数据（用户执行 Edit → Fill All Zones 后写入文件），若 fill_ratio 异常或 is_filled: false 说明可能未填充。
17. 区分 zone outline 与实际铜：outline_bbox 是用户绘制边界，filled_bbox 是扣除间隙/keepout/优先级切割后的实际铜；用 copper_presence 判断对层铜存在，而非从 zone 轮廓推断。
18. 对铜敏感元件（电容触摸板、天线）做更深检查：确认存在显式 keepout zone（rule area）作为 DRC 规则强制无铜区，测量同层 GND 间隙并与控制器应用笔记最小值比较，对触摸板比较各通道走线长度对称性，并报告焊盘尺寸、位置、间隙、走线宽/长等物理细节。
19. 运行 Deep Review pass：对每个 IC 先取数据手册事实（优先 datasheets/extracted/<MPN>.json 缓存，其次直接读 PDF，两者皆无则记录 info 发现 <REF> unverified — no datasheet available 并跳过），再与原理图实际用法对比（供电电压 vs 额定值、引脚功能 vs 连接、必需外围元件 vs 实际、热环境），需要计算时在 analysis/helpers/ 下写一次性辅助脚本读取分析器 JSON 并打印数值作为证据，最后把发现写入 analysis/deep_review.json（schema 见 skills/kicad/review/schemas/deep_review.schema.json），每条发现需含至少一个设计锚点（元件/网络/引脚）和至少一个来源（数据手册引用和/或计算）。
20. 检查相互作用的成对元件：共享电源轨（时序、合并负载）、总线伙伴（电压电平、上拉归属）、热邻居；鼓励自由挖掘可疑之处。
21. 报告前运行校验门：python3 skills/kicad/review/scripts/deep_review_gate.py analysis/deep_review.json --analysis-dir analysis/，它会校验引用、打上 finding_id，并把失败项移入 quarantined[] 并附原因；修复或接受被隔离项，报告中将其渲染为未验证声明。
22. 重审时若 analysis/deep_review.json 已存在，先 cp 为 analysis/deep_review.prev.json，完成新一轮 pass 和 gate 后用 diff_analysis.py 对比，在 Previous Review Delta 章节报告已修复/仍存在/新增项。
23. BOM 很大时按子系统分块，或按 IC 分组用子代理并行；analysis/design_context.json（若存在）用于调整优先级（如汽车级收紧降额关注），可选且绝不阻塞。
24. 生成统一报告前先读 references/report-generation.md，报告需覆盖原理图分析、PCB 布局分析、跨域发现、EMC 风险评估、仿真验证、热热点和交叉引用发现。
25. 在报告中显式披露所有评审缺口：若热分析、生命周期、Gerber、数据手册提取或既往评审 delta 未执行，添加简短的 Not performed / limits 章节，而不是静默省略。
26. 对完整设计评审逐项核对 Minimum Review Checklist：datasheets/ 是否存在/已同步/已声明缺口、analyze_schematic.py、analyze_pcb.py --full、cross_analysis.py、analyze_emc.py、已安装仿真器时的 SPICE、原理图与 PCB JSON 都存在时的 analyze_thermal.py、存在制造输出时的 analyze_gerbers.py、网络与 MPN 允许时的生命周期审计、既往评审 delta 检查、关键元件的原始文件抽查升级为完整验证、以及 blocker/验证依据/误报/跳过分析的显式章节；不适用则说明原因，跳过则说明原因，失败则说明如何限制置信度。
27. 分析 PDF 原理图（参考设计、开发板、评估板、应用笔记、数据手册典型应用电路）时：视觉阅读 PDF 页面 → 识别元件与连接 → 提取结构化数据 → 转换为 KiCad 符号与网络 → 对照数据手册验证；完整方法见 references/pdf-schematic-extraction.md，深度验证见 references/schematic-analysis.md。
28. 读取分析器 JSON 时直接读，不要另写临时提取脚本；遇到意外形状（AttributeError、字段为 None）先运行 --schema 打印各顶层键的准确字段名与类型，再写第二次提取。
29. 按 JSON 字段速查表读取：网络引脚用 nets[<name>].pins[].component/.pin_number/.pin_name/.pin_type；未命名网络显示用 nets[<name>].display_name；IC 引脚图用 ic_pin_analysis[]（列表，含 .reference 和 .pins[]）；晶体管引脚图用独立的 transistor_pin_analysis[]；检测到的电路在 findings[] 中用 finding_schema.get_findings(data, Det.*) 过滤，不要读 subcircuits[]；zone 网络 pcb.zones[].net 是整数 ID；zone 层读 .layers（复数）；封装位置用 pcb.footprints[].x/.y；焊盘网络用 pcb.footprints[].pad_nets{}；tracks 是 dict 摘要，仅 --full 填充 tracks.segments[]/arcs[]；power_net_routing 是列表；findings[] 是扁平列表。
30. 输出格式化用 f-string 或 json.dumps()，绝不用 %s 配非字符串类型；--full 模式下 connectivity_graph 的顶层键就是网络名本身（如 cg['GND']），不是 per_net 包装。
31. 用 --stage（schematic/layout/pre_fab/bring_up）和 --audience（designer/reviewer/manager）过滤输出；JSON 始终包含全部发现，--stage 会为每条发现添加 stages 和 in_active_stage 字段及 stage_filter 摘要，audience_summary 始终计算三种视图。
32. 用 summarize_findings.py 汇总一次 run 中的发现：--top N（默认 20）、--severity 过滤、--run 指定 run ID、--json 机器可读输出。
33. 用 what_if.py 做参数扫描：单值修改、逗号列表或对数范围扫描、容差角分析（如 R5=4.7k+-5%）、反解求解（--fix voltage_dividers[0] --target 3.3，带 E 系列吸附）、EMC 影响预览（--emc）、SPICE 重仿真（--spice）、导出修补后 JSON（--output patched.json）。
34. 用 diff_analysis.py 比较两次分析输出：自动识别分析器类型，报告元件新增/删除/值/封装/MPN 变化、信号分析参数偏移、BOM 行项变化、连接性/ERC 变化、EMC 发现变化、SPICE 状态转换，并按 none/minor/major/breaking 分级。
35. 用 lifecycle_audit.py 检查元件生命周期与温度：--temp-range 支持 commercial/industrial/extended/automotive/military 预设或自定义 -40,105，--only 限定分销商，--suggest-alternatives 搜索替代料，--output 保存结果；先查数据手册提取缓存中的温度数据再发 API 请求。
36. 探测分析器 JSON 时，每次探测前用一句话说明在检查什么（如 Checking whether U3's EN pin is tied to +BATT directly or through a divider），让用户只读叙述即可理解评审流程。
37. 对 JSON 形状不确定时用防御性写法：切片前检查类型（dict 用 list(x.values())[:3]）、min()/max() 前检查非空（用 default=None 或 if items:）、可选章节用 .get("key", default)、区分 list 与 dict、字段可能是字符串列表或字典列表时两种都处理、pad.get("abs_x") 可能为 None 需先判空。
38. 探测原始 .kicad_sch/.kicad_pcb 文件时用 scripts/sexp_parser.py：parse(text) 和 parse_file(path) 返回嵌套 Python 列表，find_all(node, kw)、find_first(node, kw)、get_value(node, kw) 用于导航。
39. 按快速检查清单核对原理图：每个 IC 的 VCC/GND 对都有去耦电容、I2C 上拉、复位引脚电路、未连接引脚有 no-connect 标记、跨图纸网络命名一致、外部连接器有 ESD 防护、电源时序（EN/PG）、足够的体电容。
40. 按快速检查清单核对 PCB：电源走线宽度满足电流（IPC-2221）、过孔电流容量、高压爬电/间隙、去耦电容靠近 IC 电源引脚、连续地平面（信号下方无分割）、受控阻抗走线（USB/DDR）、板框为闭合多边形、丝印可读、每个外露焊盘 IC 的热过孔数量与数据手册推荐范围对比、铜敏感元件的 keepout zone 强制、差分对长度差与协议特定容差对比并引用规范、所有 IC/晶体管/连接器的焊盘到网络交叉引用。
41. 按板卡杀手级常见 bug 排序排查：IC 引脚互换（库符号 vs 数据手册引脚图，DRC/ERC 不可见）、晶体管引脚歧义（无 MPN 的 SOT-23）、封装焊盘编号错误、原理图→PCB 未同步导致的缺失网络、封装变体错误（SOT-23 vs SOT-23-5）、浮空数字输入、缺失体电容、极性反接、反馈分压值错误、晶振负载电容错误、USB 阻抗不匹配、QFN 热焊盘缺过孔、连接器引脚错误、非常见无源值。
42. 比较两个设计时 diff：元件数量/类型、net class/设计规则、走线宽度/过孔尺寸、板尺寸/层数、电源拓扑、KiCad 版本差异。
43. 在 Flatpak 安装的 KiCad 上，kicad-cli 不在 PATH，需用 flatpak run --command=kicad-cli org.kicad.KiCad <args> 调用；其沙箱无法读取宿主 /tmp，导出和网表要写到项目目录或 $HOME 下其他位置。

适用边界 · 注意事项

• 没有 KiCad 项目文件或 PDF 原理图时（本技能只处理 .kicad_sch/.kicad_pcb/.kicad_pro/Gerber/PDF 原理图）。
• 只需要 BOM 富化、定价、下单或元件搜索时，应转交 bom/digikey/mouser/lcsc/element14 技能。
• 只需要 PCB 制造下单或 DFM 规则验证时，应转交 jlcpcb/pcbway 技能。