markwkiehl/fritzing

從程式碼產生 Fritzing 草圖

此技能提供給你的功能

• 一種將網路清單（接腳連接列表）轉換為單一 .fzz 檔案的方法，檔案包含三個視圖：麵包板、電路圖和 PCB。
• 兩個已實作的生成器範例。複製其中一個，然後修改零件和網路。
  • scripts/build_fzz_battery_led.py 僅使用 Fritzing 內建零件：電池座、按鈕開關、電阻和 LED。從這裡開始。
  • scripts/build_fzz_header_led.py 示範如何將自訂零件（一個 .fzp 檔案和四個 SVG 檔案）寫入草圖中。
• 零件檢查工具 scripts/check_core_part.py。它可以告訴你核心零件是否具備所有圖片檔案。
• 無頭檢查工具 scripts/fritzing_export.py。它會在 Fritzing 中載入草圖，並將三個視圖匯出為 SVG 檔案。
• 視窗檢查工具 scripts/fritzing_gui_shot.ps1（Windows）。它會對 Fritzing 視窗進行截圖，讓你讀取狀態列資訊。
• 檔案格式說明文件，位於 references/fz-file-format.md。在撰寫任何 .fz XML 之前，請務必閱讀此文件。

測試狀況

• 已測試：Windows 11 搭配 Fritzing 1.0.x，安裝在 C:\Program Files\Fritzing。examples/ 中的兩個範例草圖皆可成功建置、匯出為 SVG、在 Fritzing 視窗中開啟且三個視圖均顯示「Routing completed」，並通過 PCB 設計規則檢查。測試日期為 2026-11-07。
• 未測試：macOS、Linux、非 1.0.x 的 Fritzing 版本、自動繞線以及超過少數零件的電路。

對 Claude 的規則

• 不要猜測零件的接腳。請閱讀其 .fzp 檔案，列出其連接器。在建置前，將其與網路清單進行比對。
• 在使用任何核心零件前，先用 scripts/check_core_part.py 檢查。缺少圖片檔案的零件會繪製成空白。
• 未經使用者同意，請勿下載任何檔案，除非使用者提供了連結。請說明檔案名稱、來源和大小。將每個下載項目存放在各自的新空資料夾中。不要執行其中的任何內容。
• 不要因為生成器成功執行就說草圖「可運作」。Fritzing 必須能載入它，且每個視圖都必須顯示所有零件。請說明你未檢查的事項。
• 最後的檢查由真人執行：他們在 Fritzing 視窗中開啟檔案，並描述他們看到的內容。請修正生成器，不要手動修正檔案。
• 每次都要寫出每個檔案和零件的完整名稱。

工作流程

尋找 Fritzing 及其零件庫

• Windows（已測試）：Fritzing 位於 C:\Program Files\Fritzing\Fritzing.exe。零件庫位於 C:\Program Files\Fritzing\fritzing-parts。範例草圖位於 C:\Program Files\Fritzing\sketches\core。請閱讀它們以複製 Fritzing 寫入的確切 XML。
• Linux（此儲存庫未測試）：Fritzing AppImage 可使用 --appimage-extract 選項解壓縮到一個新的空資料夾中。零件庫隨後位於 squashfs-root/fritzing-parts。
• macOS（未測試）：零件庫位於 Fritzing 應用程式內部。請尋找名為 fritzing-parts 的資料夾。
• 腳本會從使用者自己安裝的 Fritzing 中讀取零件庫。請將環境變數 FRITZING_PARTS 設定為該資料夾。

檢查零件

• 列出你需要的零件，然後逐一查詢：python scripts\check_core_part.py "C:\Program Files\Fritzing\fritzing-parts" <零件名稱>。加上 --all battery 可列出標題中包含「battery」的所有核心零件。
• 它會為每個零件輸出 OK 或 MISSING、連接器數量以及模組 ID。顯示 MISSING 的零件在缺少圖片的視圖中會繪製成空白。
• 2026-11-07 測試安裝的範例：核心零件 screw_terminal_2_100mil 缺少其電路圖和 PCB 圖片，而核心零件 Battery block 9V 缺少其 PCB 封裝（jumper_2_100mil_pcb.svg）。核心零件 4 x AAA Battery Mount 則是完整的。
• 如果沒有合適的核心零件，請自行繪製一個。scripts/build_fzz_header_led.py 有一個範例：一個 .fzp 檔案和四個 SVG 檔案。
• 如果來自其他來源的零件缺少接腳，請複製該零件，賦予其新的 moduleId，然後加入連接器。將該接腳加入麵包板 SVG、電路圖 SVG 和 PCB SVG 中。

建置

• 複製 scripts/build_fzz_battery_led.py。修改零件、孔位名稱、座標和網路。
• 將網路寫成成員列表。腳本會在所有三個視圖中根據該列表檢查自身的接線，並檢查 PCB 走線間距。
• 先決定麵包板的佈局，然後是電路圖，最後是 PCB。關於孔位名稱、比例、圖層名稱和變換，請參考 references/fz-file-format.md。
• 對於可彎曲引腳的零件，請從 Fritzing 範例草圖中複製引腳 XML。不要自行猜測（請參閱「曾經出錯的情況」）。

檢查

• 執行 python scripts\fritzing_export.py "C:\Program Files\Fritzing\Fritzing.exe" <草圖.fzz> <新的空資料夾>。閱讀每一行輸出。它會寫入 <名稱>_breadboard.svg、<名稱>_schematic.svg 和 <名稱>_pcb.svg。
• 以圖片方式檢視這些 SVG 檔案。在 Windows 上的一種方法是：撰寫一個包含 <img> 並指向 SVG 檔案的 HTML 頁面，然後執行 msedge.exe --headless --window-size=W,H --screenshot=<輸出.png> file:///<頁面.html>。檢視產生的 PNG 檔案。匯出的結果僅顯示銅箔，而不顯示絲印外框。若要取得包含外框的 PCB 圖片，請使用 scripts\fritzing_gui_shot.ps1 在 Fritzing 視窗中對 PCB 視圖進行截圖，並裁切出電路板（examples/ 中的 PCB 圖片即是這樣製作的）。
• 針對每個零件，檢查三件事：它是否被畫出、其接腳是否位於孔位上、以及每條導線的末端是否接觸到接腳。
• SVG 匯出不會繪製 ratsnest 線（顯示未繞線連接的細線）。因此它無法證明 Fritzing 已註冊這些連接。請在 Fritzing 視窗中開啟草圖。
• 在 Windows 的真實 Fritzing 視窗中：
  • 使用 Start-Process 啟動 Fritzing.exe "<草圖.fzz>"。等待 25 秒。
  • 執行 scripts\fritzing_gui_shot.ps1 -Out <png> 取得目前視圖的截圖，然後使用 -Keys "^3" 取得電路圖視圖，使用 -Keys "^4" 取得 PCB 視圖。檢視每個 PNG 檔案。
  • 在每個視圖的狀態列中尋找「Routing completed」，並尋找綠色的連接點。
  • 對於設計規則檢查，在 PCB 視圖中使用 -Keys "^+d" -Wait 5 執行腳本。一個乾淨的草圖會顯示「Your sketch is ready for production: there are no connectors or traces that overlap or are too close together.」
  • 關閉對話方塊並執行 Stop-Process -Name Fritzing。

回報

• 說明你檢查了哪些項目以及如何檢查。說明你未檢查哪些項目。寫出你寫入的檔案及其完整路徑。
• 告訴使用者如何開啟該檔案：在 Fritzing 中，檔案 → 開啟。

曾經出錯的情況

• 安裝的核心零件缺少圖片檔案。 零件會繪製成空白。在使用零件前，請執行 scripts/check_core_part.py。
• 零件繪製成空白。 當麵包板 SVG 沒有 <g id="breadboard"> 群組時，Fritzing 1.0.x 不會繪製任何東西。請將全部內容包裹在該群組中。
• 導線末端看起來正確但實際上未連接。 .fz 檔案必須在兩個項目中都列出每個連接。每對連接請撰寫一個 link() 呼叫，並發出雙方的兩端。
• 具有可彎曲引腳的零件（LED、電阻、二極體、電池座）。 在 .fz 檔案中，連接器的 <geometry x y> 是 SVG 中引腳線條本體側的端點，乘以比例。<leg> 的第二個點是尖端，相對於該點。對於 5 mm LED，尖端偏移量為 (0, 30.5172)。對於電池座，則為 (6.25, 0)。Fritzing 自己的範例草圖說明了這一點。
• 錯誤的比例。 一個場景單位為 1/90 英寸。使用 in 單位的 SVG 按 90 × width_in / viewBox_width 進行縮放。使用普通 px 單位的 Illustrator SVG 計為 72 dpi，因此需乘以 1.25。
• 找不到電路圖端子。 某些電路圖 SVG 檔案將端子隱藏在 <g> 元素內，有些則完全沒有端子。請讀取 SVG 檔案，並取用引腳線條的外側端點。LED 電路圖 led.svg 的陰極端點在 (9.9005, 21.8165)，陽極端點在 (9.9005, 0.2165)，使用 72 dpi。
• 旋轉後的零件偏離其孔位。 請使用參考檔案中的變換公式。根據一個接腳的位置來放置零件，而不是根據其角落。
• 走線交叉。 請將兩條走線放在不同的圖層上。貫穿孔焊盤會連接兩個圖層，因此不需要導孔。
• Python。 這些腳本僅使用標準函式庫。無需安裝任何套件。

此技能中的檔案

• SKILL.md：本檔案。
• references/fz-file-format.md：.fzz 和 .fz 格式，包含 XML 範例、比例、圖層名稱和公式。
• scripts/build_fzz_battery_led.py：僅使用核心零件的生成器（電池座、按鈕開關、電阻、LED）。
• scripts/build_fzz_header_led.py：同時寫入自訂零件（一個 2 針腳排針）的生成器。
• scripts/check_core_part.py：檢查核心零件是否具備所有圖片檔案。
• scripts/fritzing_export.py：無頭載入並匯出檢查工具。
• scripts/fritzing_gui_shot.ps1：啟動 Fritzing 視窗、可傳送按鍵並儲存截圖（Windows）。
• examples/battery_led.fzz 和 examples/header_led.fzz：兩個生成器寫入的草圖，以及每個視圖的圖片。