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 — 特別是在第 9 版中再次變更的圖層序數。切勿混合語系：在 v8/v9 標頭內使用 v6/v7 時代的 (tstamp ...) 或 v6 的 (width ...) 圖形，是導致檔案無法載入的最常見原因。
不可妥協事項
- 每個檔案只能使用一個語系。 標頭
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 | 所有階段皆就緒 | local |
Termux / 無 KiCad 的容器；gh 已認證；有已推送的乾淨儲存庫 | pcbnew/kicad-cli 缺失 | CI |
| 無本機工具且無可用的 CI | 缺失 | local，會失敗並顯示缺失工具清單 |
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 會檢出推送的修訂版，否則會設計錯誤的電路板。請先提交並推送規格、設定檔、 schema、指令碼和工作流程。gh 必須已安裝並認證（pkg install gh，然後 gh auth login）。僅在調度非當前儲存庫的工作流程時才使用 --ci-repo owner/name。CI 執行預設會受到監控，以便退出碼反映 professional_claim；加上 --no-ci-watch 可在調度後立即返回。
階段命令（build、route、check、fab）在本機執行，因為 CI 看不到未提交的階段檔案；請使用 all --backend ci 進行端到端的 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 | Token 語法、引號、筆觸、效果、UUID、焊墊/圖形/區域基元、版本敏感的 Token |
references/practical-rules.md | 疊構、佈局、繞線、電流/寬度、SI/PI/EMI、阻抗、熱管理、機械、DFM/DFA、預設值 |
assets/minimal-2layer.kicad_pcb | 經驗證器清理過的空白雙層電路板（複製此檔案作為起點） |
assets/example-led.kicad_pcb | 經驗證器清理過的繞線範例：THT 接頭、SMD 電阻/LED、導孔、禁置區、安裝孔 |
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/reference 連結；純電路板設計應在適當位置標記為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禁置區，並可選地包含F.Fab和 3D 模型。 - 按功能放置：先放置連接器、電源輸入和 MCU；將相關電路分組；分離類比/數位/雜訊域。
- 將去耦電容放在每個 IC 的電源/接地引腳旁，並使迴路面積最小化；值/封裝應符合資料表或說明的假設條件。
- 遵守禁置區和裝配間距；保持參考編號可讀，並標記有極性元件。
- 使用完整的嵌入封裝定義：
-
繞線連通性。
- 使用
segment作為走線，via作為換層，arc作為弧形走線。KiCad 8/9 的走線使用(uuid ...)，而不是(tstamp ...)（v6/7 仍然使用tstamp）。 - 根據電流/疊構意圖設定每條走線的
width；電源走線應比訊號走線寬。網路類別存在於專案/設計規則檔案中，而非.kicad_pcb中。 - 保持走線短而直接，偏好 45° 彎角，並最小化高速路徑上的導孔。
- 保留回返路徑：不要在跨平面間隙上繞高速/敏感走線。對易受串擾影響的平行走線應用約 3W 間距。
- 阻抗/差分對走線：使用
(net_class ...)約束條件（在設計規則檔案中）或手動寬度/間距/參考平面一致性。 - 在每個 IC 引腳和電源/接地網路處放置導孔；電源平面（如果使用）應在區域中定義。
- 使用
(zone ... (net N) ... (fill ...))定義銅箔區域；優先使用filled_polygon進行熱緩解。設定(min_thickness 0.254)並啟用(thermal_gap ...)。
- 使用
-
驗證和修正。
- 使用
scripts/check_pcb.py。它會在不調用 pcbnew 的情況下，對.kicad_pcb進行結構、幾何和網路一致性驗證。 - 修正任何結構錯誤（例如，遺失的 UUID、不正確的圖層序數、斷開的走線、未連接的網路）並重複執行，直到檢查器通過。
- 確認所有銅箔區域都已填入；使用標準的阻焊層和鋼板層。
- 使用
-
當完成後：
- 報告使用的語言："KiCad 9"（如果手動編寫）或指明自動化路徑。
- 列出人為假設條件（間距、線寬、疊構、網路指派）。
- 對於手動編輯的電路板："此電路板已通過結構檢查器，但尚未通過完整的報告閘道。若要獲得一份專業的發佈報告，請將此
.kicad_pcb餵給管道。" - 對於管線生成的電路板：附加網址並提供報告摘要。
指示限制（設計規格）
避免在規格中嵌入不需要的抽象層。 設計規格 (specs/<name>.json) 的目的是作為直接對應到 KiCad 模型的資料容器。它不是電路板的功能描述。不要添加中間模型（元件清單類型、拓撲描述）或要求對通用電氣功能（"濾波器"、"穩壓器"）進行推斷。管線工具不接受此類輸入。強烈偏好簡單的 specs/led-blinky.json 模型。
驗證和使用者問題
- 檢查器是強制性的。 在提供
.kicad_pcb之前，始終透過scripts/check_pcb.py執行它。如果檢查器失敗，請修正它。不要提供已知有結構問題的電路板。 - 在浮動假設條件時提問。 如果某個參數不清楚且無法合理預設，請提問。"我假設 FR-4 疊構，1.6mm 總厚度，1oz 外層/0.5oz 內層。這對您的應用程式可以嗎？" 避免列出一長串問題；根據您的模型進行合理的陳述。
- 不要製造。 不要聲稱已經生成了一塊可以點擊"立即訂購"按鈕的電路板。"我已經生成了 Gerber 檔案。請在您選擇的製造商處驗證疊構和阻抗。"
能力聲明
我可以產生可由廠商製造的專業級 PCB 檔案，但我無法取代人為的電子工程審查。 我可以在規格層級設計控制器、電源、收發器和運算放大器電路，但對於 RF 前端、EMC 濾波器臨界值、電源供應器環路穩定性或熱點，我不會提供深厚的專業知識。請將我的輸出視為由經驗豐富的佈局工程師從規範和草圖中創建的第一版佈局。通過自動化管線的審查和迭代，可以在數小時而不是數天內達到類似的品質。