Ccm

bodesign

語言：繁體中文 · English

bodesign 是一個 AI 電路設計（PCB）副駕，以獨立的 MCP server 形式交付。 它由對談與原始輸入檔驅動，走完整個 KiCad 設計生命週期——原理圖 → 佈局 → 製造—— 產出可送廠的文件包，並以展示可靠度（對照已知良品的交叉檢核＋KiCad/SPICE/EMC） 而非「宣稱」可靠度。

它與宿主無關、可獨立對外營運：任何支援 MCP 的客戶端（IDE、agent，或你自己的 HTTP 呼叫端） 都能透過 MCP Streamable HTTP 驅動它，不需要任何宿主外殼。正式服務部署在 DockerLab CT105 （http://192.168.100.141:8177/mcp/，經 nginx ingress，POST /invoke 一律 403）；容器內部的 TCP port 從不直接對外 publish（BR_20260730d）。

它做什麼

• 匯入整個專案資料夾（datasheet、原理圖、BOM、Gerber），唯讀。
• 規劃需求：把自然語言規格轉成結構化計畫（並反問釐清），並把 C00 PRD 產出為帶樣式的 .docx——重現真實 Rockbox C07-PRD Word 架構（封面＋改版紀錄表＋12 章＋章節內表格），範本以 .dotx + JSON 架構描述預存在 server 端供重複使用。
• 生成 KiCad 符號與經 kicad-cli 驗證的原理圖（以參考設計為依據）。
• 佈局（pcbnew 擺件＋DRC）並匯出製造輸出（gerber／鑽孔／pos／STEP）。
• 驗證四層：ERC/DRC · 對照組交叉檢核 · SPICE · EMC/熱分析；其中對照組交叉檢核由 確定性參考比對器（G7：純 Python Hungarian 配對＋Dice/屬性/連接性加權）執行，SPICE 以 datasheet 接地的 model 卡（每筆參數帶 page-anchor 證據）取代泛用預設模型。
• 追蹤就緒度，並為每個工程檔產出可讀伴隨檔（docx/pdf）與分享文件。所有「可靠度」皆以 可重現的確定性證據展示（LLM 只負責上游抽取／裁決，驗證與比對全程不參與）。

近期變更

完整紀錄見 CHANGELOG.md。近期重點：

• 未發布（2026-10-23） — A2A 多 Agent 責任分層硬體設計治理體系（C03-C04）： 參考 zhoushoujianwork/easyeda-agent 治理機制，重構為嚴格 IDEF0 規範下的多 Agent 協作制度（規格：plans/workflow_guarded-hardware-governance/）。
  1. 微狀態機與零自我審批（Zero Self-Approval）：實作 C03（S0~S5）與 C04（P0~P7）微狀態機，強制作者（EE/Layout）不可兼審查員；
  2. 密碼學憑證（Receipt）：每次推進強制顯式列出 not_checked 未測軸向，P7 送廠前強制人類授權（天條 3）；
  3. 阻礙中樞（Blocker Hub）：結構化異常派工（BLK-nnn）與重試邊界防止循環；
  4. 認證標準電路積木庫：提供 usb_c_sink、power_ldo_3v3、power_dcdc_buck（含 $C_{FF}$）、esd_protection_array，自動處理引腳與佈局約束；
  5. 確定性佈局整潔原語：吸附網格（grid_snap）、線性元件對齊（distribute_passives）、焊盤絲印避讓（silk_tidy）；
  6. 視覺化 DRC 局部裁切：自動生成 5mm×5mm 高對比度裁切（100px/mm PNG / SVG），為多模態 Review 提供物理真相；
  7. Landing Verbs 整合：新增 c03_substate_advance、c04_substate_advance、circuit_block_apply、layout_tidy、blocker_record 5 組宿主原生動詞。
• 未發布（2026-07-06） — BR_20260706 五筆 BR 閉環（schematic 交付保真閘群）：spec eda_schematic-draftsman-quality extend DD-8..DD-11 至 living——compose_schematic 新增 fidelity（net 劃分保真閘，抓 ERC 盲區的共線熔合短路）與 density_budget （頁面密度超標 fail-fast 強制分頁）；kicad_emit 防熔合 guard（確定性 jog 錯開）； qa_svg_text 渲染層文字 QA landing verb；/tmp/engpatch 部署漂移源退場 + engine_rev 回報；SKILL.md 交付契約六硬規。62 tests OK。
• 未發布（2026-07-05） — skill 語料去誤導化：稽核出 18 筆會誤導 agent 的語料 （含 R20 HV 間距跨欄拼湊安全 bug，裸外層板低壓間距偏小 4.6 倍）全數修畢； 建立 provenance 三級制（[primary:]/[fab:]/[rot]，經驗值禁入 DRC gate）與 clean-result 邊界語紀律。雙盲 eval：新版 6/6 vs 舊版 0/6。
• 未發布（2026-07-04） — 跨 spec extend：copper-clearance checker 落地：畢業 design-ir/net-role-extension（封閉 NET_ROLES enum）與 gerber-core/copper-geometry-parser （真實 edge-to-edge 銅箔幾何）兩 spec，新增 copper_clearance.py 消費之，把 control.dfm.ipc-clearance-voltage 由 T-B stub 翻為 T-A landed（landed 8→9）。 拒絕 false-green——landed 由 9 個測試（含 6 個 no-fabrication fail-fast 守衛）背書。
• 未發布（2026-07-03） — C04 誠實機制接線：修復 aiguard 踩坑的工具層根因。新增 C04 上游履約 gate（C03 未落 netlist → blocked_upstream_c03_missing，不再誤報 drafted）， 把去孤兒化的 classify_product_feasibility（tier 分診，無 signals 不臆測）與 emit_si_constraint_export（Tier-3 SI 交手）接進 C04 emit/readiness；41 tests 綠。
• 0.2.1（2026-07-03） — 第 5 道信任層 PRD↔BOM 履約 crosscheck gate（C04 缺口治理）： 驗收發現 C00 PRD 定義的晶片模組未落到板上，以「一級一級治」補 L1 履約 gate （bodesign_prd_bom_crosscheck）、L2 Vault-Absent 降級協議、L3 NPN linear sink 重設計； C04 全鏈實跑 gate=PASS + DRC clean。另落地 atopile DSL 前端（工具 43→45）。
• 0.2.0（2026-07-02） — R13 compute/landing split（52 verbs 落地）+ WebDAV working cache。

架構圖

A2A 多 Agent 硬體治理工作流架構（C03-C04 責任分層與微狀態）

完整規格與生命週期設計見 plans/workflow_guarded-hardware-governance/。

A2A 治理體系 IDEF0 功能分解（A0）

A2A 治理體系 GRAFCET 執行流程（S0S5 ➔ P0P7 & Blocker 派工修復迴圈）

系統全域產品架構（PCB AI Viewer）

完整規格見 specs/product/pcb_ai_viewer/。

IDEF0 功能分解（A0）

GRAFCET 執行流程（生成迴圈）

執行

Docker（可攜，建議） — 內含 KiCad 9（kicad-cli + pcbnew）＋ LibreOffice ＋整套工具鏈：

./mcpctl.sh start     # 建置映像＋啟動容器（UDS 於 ./.run/bodesign.sock）
./mcpctl.sh status    # 健康檢查＋socket
./mcpctl.sh log       # 追蹤日誌
./mcpctl.sh stop

主機（不用 Docker） — 需要 PATH 上有 kicad-cli、pcbnew、soffice、ngspice：

pip install -r services/mcp/requirements.txt
python services/mcp/server.py --transport http --uds .run/bodesign.sock --port 8077
# 或 --transport stdio 供 IDE/agent 直接使用

連線（MCP）

MCP Streamable HTTP：

• 正式（DockerLab CT105，預設）：http://192.168.100.141:8177/mcp/——僅限 LAN，nginx ingress 封鎖 POST /invoke（403），只開放 /healthz、/mcp、/files。部署清單與發布 SOP 見 deploy/dockerlab/。
• 本機開發：BODESIGN_DEV=1 ./mcpctl.sh start 後經 UDS unix:///…/.run/bodesign.sock:/mcp/。 兩者擇一，不要同時跑。
• 容器內部 TCP :8077 從不直接 publish（BR_20260730d：publish 會把未認證的 POST /invoke 暴露在所有介面上），對外一律經 ingress。

註冊資訊見 mcp.json。開啟服務的 / 即是即時的自我說明指南—— 安裝、檔案模型、電路設計工作流，以及 /tools、/tools/{name} 的完整 tool-call schema。

檔案模型（兩平面，0.2.0）

Landing plane（本地直跑，零 token 往返） — 52 個確定性、只碰專案目錄的 verb （C00–C06 scaffold/readiness/emitters、orchestration spine、純函數）不再是 MCP 工具， 改由 agent 在主機以自己的身分直接執行：

python3 skills/bodesign/scripts/gate.py --list        # 權威 verb 清單
python3 skills/bodesign/scripts/gate.py <verb> --repo <abs專案路徑> [--json '{…}' | --arg k=v]

誤把已落地的名字當 MCP 工具呼叫，會收到 typed error TOOL_LANDED，內附等效的 gate.py 指令。

Compute plane（容器 token 檔案模型，docxmcp 風格） — 重工具鏈（pcbnew/kicad-cli/ngspice/ 渲染/3D）留在容器內的 43 個 MCP 工具。bodesign 不內含任何工作資料：檔案只走一條路——WebDAV 工作區。Agent 呼叫 opencode runtime verb system-manager_webdav_mount(app="bodesign") 取得 mount_path + token；把輸入檔放進 mount_path，將 token 傳給任一工具（路徑參數在工作區樹內解析）， 產出檔直接在 mount_path 讀回。伺服端工作資料依 TTL 自動垃圾回收；容器看不到主機路徑。

Working cache（WebDAV，消滅整包進出儀式） — 需要多檔往返的交付物改用伺服端工作快取： bodesign_cache_provision（由 opencode runtime 呼叫，不由 agent 呼叫）回傳 token + 絕對 mount_url（…/dav/{token}/）+ 選用的專屬 Basic 憑證；重工具直接寫入快取命名空間，產出檔在掛載目錄 直接可見——不需匯出步驟。bodesign_cache_close 回收工作區。每個 cache 依擁有者隔離， 免於 idle 回收（長 safety-net TTL 把關）。

Skill 配對

bodesign（MCP）是生成的那一半；配套的 bodesign skill 是工作流大腦（C00–C07 生命週期、 誠實契約、各階段 SOP），並且承載分析／文件引擎——kicad（原理圖／PCB／Gerber 分析）與 kidoc（工程文件）現在以 engines/kicad、engines/kidoc 的形式住在那裡，所以請安裝 bodesign skill，而非獨立的 kicad／kidoc。分工是雙向的：skill 驅動本 MCP 的 bodesign_* 工具來生成， 而 MCP 的驗證工具（bodesign_simulate／analyze_emc／analyze_thermal）回頭呼叫 skill 的引擎來 分析（透過 BODESIGN_KICAD_SKILL 解析，預設 ~/.claude/skills/bodesign/engines/kicad）。

其餘成熟的模擬／採購／製造 EDA skill（spice、emc、datasheets、bom、distributors、fab）， 連同獨立的 kicad／kidoc（legacy，已併入 bodesign skill），都可從執行中的服務在 /skills/ 下載（整包＋個別 skill），安裝到你的 skill 目錄。

skill 在執行層之上再加一層設計判斷（各階段的 reference：C01 reduction-lens＋Ashby 選材、 C02 DFM/DFA/IP 密封＋幾何作圖迴圈、C03 EE advisory＋「腳位→電路」合成法、C04 stackup/HDI/SI）。 跨站不收斂（面積／散熱／高度 budget、C06 verdict fail）會以既有 BlockerReturn 回饋到負責的 階段並擋住下游完成（遞迴自我修正）。一開始就用可行性 triage 從 C00 估算分級(Tier 1 可直接 投板／2 需人類 SI 簽核／3 HDI 級交專業 EDA)，讓「給 C00，得 C01–C04」對每個產品誠實； Tier-3 由 emit_si_constraint_export 產出中性 SI 約束包（JSON＋CSV＋逐工具對應），把繞線硬牆變成 乾淨交接而非斷點。

目錄結構

bodesign/
├── services/mcp/                 MCP server —— 產品的唯一對外介面
│   ├── server.py                 工具分派、token 路徑解析、UDS+TCP 雙綁定、自我說明網頁
│   ├── token_store.py            docxmcp 式 token 檔案儲存 ＋ TTL/GC
│   ├── requirements.txt
│   └── assets/skills/            EDA skill 套件（13 個 tarball ＋整包 bundle ＋ MANIFEST.md）
├── packages/                     通用能力函式庫（無產品專屬碼）
│   ├── shared/                   共用契約 ＋ data_root()（程式↔工作資料隔離邊界）
│   ├── design-ir/                DesignIntent 等中介表示（IR）；compare/ 子模組＝確定性
│   │                             參考比對器（G7：純 Python Hungarian＋Dice/屬性/連接性加權＋FlexiblePin）
│   ├── component-kb/             可重用零件知識（datasheet 萃取）；spice_card.py＝datasheet 接地
│   │                             SPICE model 卡（vault L4 → cascade tier-1，確定性、byte-identical）
│   ├── doc-core/                 pin-table／文件產生工具
│   ├── source-core/              來源／證據契約
│   ├── reverse-core/             專案匯入、伴隨檔渲染、文件輸出、board 重建
│   ├── gerber-core/              Gerber／鑽孔解析 ＋ 預覽
│   ├── eda-bridge/               KiCad 橋接：符號／原理圖／佈局／製造／BOM／SPICE／EMC；
│   │                             simulate 標注 model_source（vault-grounded｜generic-default）
│   ├── workflow-core/            需求規劃、證據蒐集、就緒度羅盤、對照組交叉檢核、
│   │                             可行性 triage（C04 交付分級）、跨站對帳閘、SI 約束交接；
│   │                             驗證紀律 G1–G7（需求契約／設計審查閘／crosscheck＋root-cause／
│   │                             ValidationEvidence 回流／workflow plan 衍生）
│   ├── storage-core/             客戶自有專案登錄
│   └── kicad-plugin/             in-KiCad Action Plugin 契約（roadmap）

bodesign 不內含任何工作資料；客戶專案樹只在執行期經 token 儲存進入，或由外部 data_root()（BODESIGN_DATA_DIR）讀取。

可靠度邊界

交叉檢核＋SPICE/EMC 是矽前風險層——在打樣前抓出問題。它們不取代實驗室／工廠的 認證 EMC／EVT／DVT；且 bodesign 在未經確定性驗證＋明確批准前，不會輸出任何送廠檔案。