PCB 设计 (KiCad 8/9)
创建可制造、语法有效的 KiCad PCB 文件，并将其输出为 .kicad_pcb s-expression 文件。KiCad 是主要框架。 不要依赖内存中的文件格式——请使用 KiCad 开发者文档和随附的、经过验证器清洗的资源作为事实来源。
目标版本：KiCad 9 ((version 20241229))）。支持 KiCad 8 (20240108)，差异详见 references/pcb-file-format.md#version-dialect-matrix——特别是层的序数，在 v9 中再次发生了变化。切勿混用版本：v6/v7 时代的 (tstamp ...) 或 v6 的 (width ...) 图形位于 v8/v9 文件头内是导致文件无法加载的最常见原因。
不可妥协项
- 每个文件一个版本。 文件头的
version、generator_version、走线 UUID、笔划语法和封装字段必须全部与声明的版本一致。 - 一个板是一个完整的文件，不是一个片段。 它必须在 KiCad 中打开并通过以下结构检查器。
- 连接性是几何的。 一条具有正确网络编号但未接触焊盘或其他走线的走线仍被视为未布线。
- 无静默电气猜测。 引脚到网络的映射、极性、封装选择和安全间距必须作为假设陈述或主动询问。
- 未经验证的制造限制，不得声称可制造。 制造参数与层叠和制造商相关。
- 无通过的报告，不得声称可发布。 只有当
report/design-report.json中的professional_claim为true时，才认为电路板已达到可发布状态。否则，列出失败的检查项和缺失的签字确认。
自动设计流水线（新板首选）
当流水线可以完成时，不要手动编写发布板。该流水线将设计规范转化为具有真实 KiCad 库封装的电路板，使用 Freerouting 进行布线，运行 KiCad DRC + DFM + 网表一致性检查，导出 Gerber/钻孔/位置/STEP/IPC-D-356 文件，并编写检查报告。profile.fab_outputs 中列出的每个输出都是一个硬性检查项。仅使用手动编写来审查或修补生成的电路板。
# 1. 验证意图（无需 KiCad）
python3 scripts/design_spec.py validate specs/led-blinky.json
# 2. 全自动设计。当本地存在 KiCad 9 pcbnew、Java 25 和 Freerouting 2.5.0 时自动选择本地运行，否则调度 GitHub Actions。
python3 scripts/design_pipeline.py all specs/led-blinky.json
# 电气事实来源是原理图或网表；规范提供机械/规则。
python3 scripts/design_pipeline.py all specs/led-blinky.json --schematic design.kicad_sch
python3 scripts/design_pipeline.py all specs/led-blinky.json --netlist design.net
# 现有板：进行布线/检查/导出，无需重建。
python3 scripts/design_pipeline.py all specs/led-blinky.json --board existing.kicad_pcb --skip-build
# 仅执行特定阶段
python3 scripts/design_pipeline.py build specs/led-blinky.json -o build/led-blinky
python3 scripts/design_pipeline.py route build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json
python3 scripts/design_pipeline.py check build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/check
python3 scripts/design_pipeline.py fab build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/fab
规范输入。 specs/<name>.json 是自动路径的事实来源。使用 schemas/design-spec.schema.json 和 specs/led-blinky.json 作为模型。对于自然语言请求，首先编写规范，在 assumptions[] 中陈述假设，然后运行流水线。对于 KiCad 原理图/网表，网表对元件/焊盘网络具有权威性；规范覆盖层提供电路板尺寸、层叠、规则、放置和布线。
电路板等级配置文件。 配置文件选择规则集和发布检查项：
| 配置文件 | 自动化程度 | 必需的签字确认 |
|---|---|---|
2layer-low-speed | 完整：构建、放置、布线、DRC、DFM、制造输出 | 无 |
4layer-impedance / 6layer-impedance | 门控：层叠 + 阻抗 + 长度匹配检查 | stackup, impedance |
rf-mixed-signal | 辅助；RF 网络应手动重新布线 | rf, emc, thermal |
flex-rigid | 辅助 | mechanical, flex_bend, assembly |
high-voltage | 门控；间隙/爬电检查 | safety, creepage |
professional_claim 仅当每个硬性检查项都通过且每个必需的签字确认都列在 signoff.completed 中时才为 true。RF、EMC、热性能、安全和柔性疲劳无法由流水线认证；请如此说明，不要夸大其词。在 signoff.reviewer 中记录审查者。
后端选择：本地或 CI（自动）。 完全自动化需要 pcbnew（KiCad 9 Python）、kicad-cli、Java 25 和 freerouting-2.5.0.jar（Freerouting 2.5.0 为 Java 25 构建）。--backend auto 是默认选项：它会探查当前环境，当每个请求的阶段都有其工具时在本地运行，否则会调度 .github/workflows/design.yml。该工作流在官方的 kicad/kicad:9.0 容器中运行，安装 JRE 25，下载 Freerouting，运行整个流水线，并上传 design-output + design-report。
| 环境 | 探查结果 | 选定的后端 |
|---|---|---|
| 装有 KiCad 9 + Java 25 + jar 的真实 PC | 所有阶段就绪 | 本地 |
无 KiCad 的 Termux/容器；gh 已认证；已推送的干净仓库 | pcbnew/kicad-cli 缺失 | CI |
| 无本地工具且无可用的 CI | 缺失 | 本地，失败并显示缺失工具列表 |
python3 scripts/env_probe.py # 此机器能运行什么？
python3 scripts/env_probe.py --json # 机器可读的探查结果
python3 scripts/design_pipeline.py all specs/led-blinky.json # 自动
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend local
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend ci --ci-download build/ci
CI 调度是保守的：它会拒绝未提交的树或领先于上游的分支，因为 Actions 会检出推送的修订版本，否则会设计错误的电路板。请先提交并推送规范、配置文件、模式、脚本和工作流。必须安装并认证 gh（pkg install gh，然后 gh auth login）。仅当调度与当前仓库不同的仓库时，才使用 --ci-repo owner/name。默认情况下会监视 CI 运行，因此退出代码反映 professional_claim；添加 --no-ci-watch 可在调度后立即返回。
阶段命令（build、route、check、fab）在本地运行，因为 CI 无法看到未提交的阶段文件；如需完整的端到端 CI 运行，请使用 all --backend ci。在 GitHub Actions 内部，流水线始终保持在本地，因此 CI 运行永远不会重新调度自身。
迭代规则。 当某个检查项失败时，更改规范（放置、线宽、间隙、层叠、网络类别分配）并重新生成。请不要编辑生成的电路板，然后声称报告仍然适用；报告会记录确切的已解析规范（<name>.spec.json）。
检索来源（猜测前请先使用）
| 资源 | URL | 用途 |
|---|---|---|
| S-Expression 介绍（通用语法） | https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html | 语法、引号、坐标、层、封装、焊盘、图形、区域、组 |
| 板文件格式 | https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/index.html | .kicad_pcb 顶层部分、文件头、层、设置、网络、走线、区域 |
| 封装库格式 | https://dev-docs.kicad.org/en/file-formats/sexpr-footprint/index.html | .kicad_mod 上下文和封装字段 |
| KiCad 文件格式索引 | https://dev-docs.kicad.org/en/file-formats/index.html | 当需要匹配的原理图时使用的原理图/符号格式 |
| KiCad DRC 文档 | https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#design-rule-checking | 真实的 DRC 检查内容以及哪些规则可配置 |
| KiCad 自定义设计规则 | https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#custom-design-rules | .kicad_dru 语法和规则表达式 |
| JLCPCB 能力 | https://jlcpcb.com/capabilities/pcb-capabilities | 当前的制造限制（使用前请验证） |
| IPC-2221 / IPC-2152 | https://www.ipc.org/ | 走线宽度/电流、间隙和爬电基础知识 |
开发者文档在某些地方滞后于应用程序（它们仍描述 v7 之前的 (width ...) 图形和 (tstamp ...) 走线）。当文档与目标 KiCad 版本的真实文件冲突时，请遵循真实文件并记录差异。
本地参考和资产
| 路径 | 内容 |
|---|---|
references/pcb-file-format.md | 版本矩阵、章节、层序数、设置/层叠、封装、焊盘、走线、区域、检查清单 |
references/sexpr-primitives.md | 标记语法、引号、笔划、效果、UUID、焊盘/图形/区域原语、版本敏感的标记 |
references/practical-rules.md | 层叠、放置、布线、电流/宽度、SI/PI/EMI、阻抗、热性能、机械、DFM/DFA、默认值 |
assets/minimal-2layer.kicad_pcb | 经过验证器清洗的空白 2 层电路板（作为起点复制此文件） |
assets/example-led.kicad_pcb | 经过验证器清洗的已布线示例：THT 连接器、SMD 电阻/LED、过孔、 courtyards、安装孔 |
assets/example.kicad_dru | 自定义规则示例（网络类别宽度、高压间隙） |
schemas/design-spec.schema.json | 规范的自动设计规范（电路板、规则、网络、放置、层叠、检查项） |
profiles/*.json | 电路板等级规则集和发布检查项 |
specs/led-blinky.json | 自动流水线的参考规范 |
scripts/design_spec.py | 无依赖的规范验证器、网表导入器、阻抗/电流计算、检查报告 |
scripts/pcb_build.py | 使用真实库封装将规范转换为 KiCad 电路板（pcbnew） |
scripts/pcb_route.py | DSN 导出 → Freerouting → SES 导入 → 区域填充 |
scripts/pcb_check.py | 结构、DRC、DFM、网表一致性和长度匹配检查项 |
scripts/pcb_fab.py | Gerber、钻孔、位置、STEP、IPC-D-356 和制造 README |
scripts/design_pipeline.py | 编排整个自动设计并编写发布报告；--backend auto 选择本地或 CI |
scripts/env_probe.py | 检测 pcbnew、kicad-cli、Java 25、Freerouting、gh/git 并推荐本地还是 CI |
scripts/ci_dispatch.py | 调度 .github/workflows/design.yml，可选地监视并下载工件 |
scripts/check_pcb.py | 无依赖的结构/几何预检查器 |
.github/workflows/design.yml | CI：在 KiCad 9 容器中构建、布线、DRC/DFM、制造导出和报告 |
在获取整个文档页面之前，请在这些参考中使用搜索词：version、generator_version、layers、stackup、setup、net、footprint、property、attr、pad、stroke、segment、via、zone、keepout、filled_polygon、Edge.Cuts、embedded_fonts、remove_unused_layers、courtyard、impedance、differential、3W、return path、DFM、trace width。
手动/审查工作流
请优先使用自动流水线。此工作流用于审查生成的电路板、修补规范无法表达约束的设计，或在流水线工具不可用的环境中工作。
-
澄清设计意图（不要静默猜测关键约束）。
- 电路板功能、元件、连接器、电源/地网络、目标尺寸和机械约束。
- 制造假设：层数（默认为 2）、单位（mm）、铜厚、层叠、表面处理、组装工艺。
- 目标 KiCad 版本。除非用户另有说明，否则默认为 KiCad 9。
- 如果需求未详细说明，则在响应中明确陈述假设，并在文件中编码合理的默认值。
-
首先建模电气网表。
- 在项目引用它们之前定义
(net 0 "")加上每个命名的网络。保持序数稳定且唯一。 - 确保每个焊盘、走线、过孔和区域的
net序数都存在；确保焊盘的(net N "NAME")名称与网络表完全匹配。 - 如果存在匹配的原理图，封装需要
path/参考链接；仅限电路板的设计应在适当位置标记为board_only。
- 在项目引用它们之前定义
-
定义机械、层和层叠。
- 从
assets/minimal-2layer.kicad_pcb开始，并保持其文件头/层/设置有效。 - 使用规范名称和正确的序数设置
layers部分（请参阅references/pcb-file-format.md中的表格；B.CrtYd/F.CrtYd不是连续的）。 - 设置
(general (thickness 1.6) (legacy_teardrops no))、(paper "A4")，如果层叠重要，则设置一个真实的stackup。 - 提供一个闭合的
Edge.Cuts边界（直线/弧线或一个矩形/圆形/多边形）。使铜箔远离边缘。
- 从
-
放置封装。
- 使用完整的嵌入式封装定义：
layer、uuid、at、property字段（Reference/Value）、attr smd|through_hole、焊盘、丝印、F.CrtYd/B.CrtYd的 courtyard，并可选择F.Fab和 3D 模型。 - 按功能放置：先放置连接器、电源入口和 MCU；对相关电路进行分组；分离模拟/数字/噪声区域。
- 在每个 IC 的电源/地引脚处放置去耦电容，并具有最小的回路面积；值/封装请参阅数据表或陈述的假设。
- 遵守 courtyards 和组装间距；保持参考编号可读，并标记有极性元件。
- 使用完整的嵌入式封装定义：
-
布线连接。
- 使用
segment表示走线，via表示层间切换，arc表示弯曲走线。KiCad 8/9 的走线使用(uuid ...)，而不是(tstamp ...)（v6/7 仍使用tstamp）。 - 根据电流/层叠意图为每个项目设置
width；电源走线宽于信号走线。网络类别存在于项目/设计规则文件中，而不是在.kicad_pcb中。 - 保持走线短而直接，优先使用 45° 弯角，尽量减少高速路径上的过孔。
- 保护回路路径：不要在平面间隙上布线高速/敏感走线。对易产生串扰的平行走线应用约 3W 间距。
- 阻抗/差分对：使用
via段致密的差分或单端受控阻抗布线，保持参考平面不间断。 - 对于高压走线：使用符合间隙/爬电规范要求的安全间距的直线段；如果需要防护走线，请使用与保护网络连接的相同宽度/间距进行布线。
- 使用
-
添加区域和填充。
- 电源/地网络通常使用区域（
zone）。在setup/stackup中定义(layer "")上的填充区域，如果需要热缓解，则使用(net N)和(fill solid)或(hatch) + (connect_pads (relief ...))。 - 不要在不相邻的层上放置重叠的实心区域（这会造成非功能焊盘问题）。对于内部平面，优先使用
(fill solid)。 - 对于 RF 区域：使用
keepout在 RF 部分下方禁止铜箔，或者添加带有一系列过孔的防护带。
- 电源/地网络通常使用区域（
-
运行 DRC / DFM / 结构检查并修复问题。
- 结构检查器（
check_pcb.py）可以捕获许多格式错误。在每一步之后运行它。KiCad 本身的 DRC 捕获电气/间隙/规则违规。 - 常见的 DRC 问题：非闭合的 Edge.Cuts、冲突的 courtyards、重叠的铜箔区域、孤立的铜箔、过孔/焊盘间隙不足、未连接的网络。
- 对于高压设计：由 KiCad 自定义规则和
check_pcb.py中的检查强制执行间隙/爬电规则。 - DFM 检查（来自
pcb_check.py，以及制造商的指南）：最小走线宽度/间距、最小钻孔尺寸、环形环要求、丝印到焊盘间隙、阻焊层开窗。
- 结构检查器（
-
生成制造输出。
- 用于 Gerber/钻孔/位置/STEP/IPC-D-356 的
pcb_fab.py。如果你不能运行该脚本，请手动导出。 - 提供每个输出层的列表、阻焊层/丝印设置以及在制造注意事项中标记的任何特殊说明。
- 用于 Gerber/钻孔/位置/STEP/IPC-D-356 的
-
记录假设并完成发布检查清单。
- 明确陈述：层叠、材料、铜重、表面处理、公差以及关于制造商的假设。
- 在发布报告中将完成的每个检查项标记为已完成。
- 如果流水线产生了通过的报告，则可以声明
professional_claim: true。
故障排除备注
- “Board file not found” — 检查路径是否正确。确保
.kicad_pcb文件存在。 - “Invalid sexpr” — 在
validator中运行文件，或检查缺少右括号、引号不匹配、版本/生成器版本不匹配（很可能是混合使用了tstamp和uuid语法）。 - “Net xxx not declared” — 所有
(net ...)定义必须出现在块中的任何引用之前。序数必须唯一且连续。 - “Copper area not filled” — 在放置/布线后进行区域填充。在 KiCad GUI 中按
B，或使用pcb_fab.py。 - “DRC violation: clearance” — 增加间距，更改网络类别，或调整区域填充设置（例如，从
solid改为hatch可能意味着更少的铜，更多的空间）。