CircuitAgent

CircuitAgent · Community Edition

Prompt → Schematic → Layout → 3D Enclosure → Fabrication Bundle

🌐 在线 EDA 工作台 / Live Demo · 🇨🇳 中文说明 · 🇬🇧 English · 🔌 MCP Server · 🧩 19+ 积木清单 · 🏭 工业 DFX · 📐 KiCad/BOM 导出 · 💬 反馈

Status: alpha. This repository is the open community layer of CircuitAgent: the

hardware DSL, the LCSC live-selection client, and the data contracts that the

full compiler consumes. The block set is deliberately small and every block is

unit-tested — correctness over coverage.

---

为什么需要这一层 (Why this layer exists)

让大语言模型直接生成底层走线、焊盘与封装，几乎必然产出非法几何或引脚短路。 CircuitAgent 的做法是把 LLM 的输出约束在预验证的电路积木上，再用 Pydantic 契约把它变成确定性网表 —— 模型只负责"选积木"，不负责"画线"。

Natural language prompt

│ ▼ ┌────────────────────────┐ │ CircuitBlocks DSL │ keyword → audited sub-circuits (deterministic) └────────────────────────┘ │ ▼ ┌────────────────────────┐ │ Netlist contract │ Pydantic / JSON Schema (SSOT) └────────────────────────┘ │ ┌────┴─────┐ ▼ ▼ ┌────────┐ ┌──────────────────┐ │ LCSC │ │ REST / MCP APIs │ │ client │ │ (community layer)│ └────────┘ └──────────────────┘

---

快速上手 (Quick Start)

方式 A · 从 PyPI 安装（推荐）

pip install circuit-agent-client

方式 B · 从源码使用

git clone https://github.com/mo9652962-ai/circuit-agent.git

cd circuit-agent

零运行时依赖 —— 纯 Python 标准库实现，装完即用，不拉任何第三方包。 跑测试才需要 dev extra：pip install -e ".[dev]"

1 · 一句话生成硬件网表

from client.synthesizer import synthesize_from_prompt

spec = synthesize_from_prompt( "基于 ESP32-C3 的环境监测节点，带 Type-C 供电、I2C 传感器插座、指示灯和2个按键" )

print(spec["chip_id"]) # ESP32-C3 print(len(spec["modules"])) # 元器件数 print(spec"netlist"[0]) # 第一条网络连接 print(spec["unmatched"]) # 你要求了、但 DSL 还不支持的模块（可执行信号） print(spec["not_requested"]) # 你没提到的可选模块（仅参考，非能力缺口）

映射是确定性的：同一句话永远产出逐字节相同的结果（CI 中有对应断言）。

unmatched 与 not_requested 是两个刻意分开的信号，不要混用：

不会被静默丢弃：任何未识别的意图都会出现在 unmatched 里，而不是悄悄消失。

2 · 查询立创商城实时库存与单价

from client.lcsc_client import search_lcsc_parts

for part in search_lcsc_parts("CH340N", limit=3): print(f"[{part['lcsc_part']}] {part['part_number']} | {part['package']} | " f"库存 {part['stock']} | ${part['price_usd']} | {part['part_class']}")

[C506813] CH340N | SOP-8_L5.0-W4.0-P1.27-LS6.0-BL | 库存 196 | $0.5537 | Extended Part

客户端自带重试退避 + 硬超时 + 24 小时磁盘缓存 + 防御式解析：上游改结构不会 抛异常，断网时回落到缓存（缓存也没有则返回空列表，调用方永远不必处理传输层异常）。

3 · 直接用积木搭电路

from client.circuit_blocks import block_usb_c_power, block_power_ldo_3v3

blk = block_power_ldo_3v3() for comp in blk.components: print(comp.ref, comp.value, comp.package, comp.lcsc)

---

积木清单 (Block Catalogue)

每个积木的引脚号、LCSC 料号、封装名在冻结前均对照数据手册与立创商城列表核验过。 tests/test_circuit_blocks.py 会强制校验：位号唯一、每个元件都有封装与料号、 网络端点必须指向已声明的元件、每个积木都必须接 /GND。

---

MCP Server (AI Agent 工具服务)

CircuitAgent 内置标准 JSON-RPC 2.0 stdio MCP Server，基于纯 Python 标准库构建（无需任何第三方 pip 库），可无缝接入 Claude Desktop、Cursor 或 Windsurf。

当前暴露 84 个工具、8 个资源（circuit:// URI）与 4 个工程提示词（slash-command）。

协议版本：MCP 2026-07-28

服务器实现 2026-07-28 无状态协议核心，同时向后兼容到 2024-11-05 的握手客户端：

双通道输出

MCP 2026-07-28 规定 tools/call 有两个输出通道，且同时存在时语义必须等价：

• content — 面向模型。语言模型只读得到这一段，token 成本与可读性优先。
• structuredContent — 面向程序。给代码生成、类型化编排与 outputSchema 严格校验用。

本服务器的做法是从同一份文档派生：工具已经返回 JSON，结构化通道由解析该文档得到， 因此两个通道不可能不一致（有测试对全部工具断言这一点）。返回文件内容的导出工具 （KiCad 网表、Gerber、IPC-2581、BOM CSV）与返回 ASCII 图的工具不声明 outputSchema —— 它们产出的是文档不是数据对象，给它写 schema 只会描述一个字符串容器。错误结果同样不带 结构化负载：失败的调用没有符合 schema 的文档，编造一个错误对象形状是没人要求的契约。

server/discover 的 instructions 字段直接写给 LLM 看：先 synthesize_circuit 出网表，再 run_erc 门禁， 然后 audit_industrial_dfx 与 validate_manufacturing_package，最后才导出。calculate_* / analyze_* 全是纯函数（无网络、无状态），可放心试探；只有 search_lcsc_parts 联网且免 Key。

运行方式

python -m client.mcp_server

Claude Desktop 配置 (claude_desktop_config.json)

{

"mcpServers": { "circuit-agent": { "command": "python", "args": ["-m", "client.mcp_server"], "cwd": "/path/to/circuit-agent" } } }

暴露的工具 (Tools)

1. synthesize_circuit: 输入自然语言，输出确定性硬件网表与积木清单。
2. search_lcsc_parts: 免 Key 实时查询立创商城的元器件库存、封装、阶梯单价与基础库/扩展库属性。
3. list_circuit_blocks: 列出 DSL 中全部可用的 24 大已审计电路积木规格。
4. validate_netlist: 根据正式 JSON Schema 校验网表数据结构合法性。
5. calculate_trace_impedance: 基于 IPC-2141 解析公式计算微带线与差分对走线阻抗（50Ω RF / 90Ω USB / 120Ω CAN/485）。
6. calculate_bom_cost: PCBA 成本核算器，自动精算元器件裸成本与嘉立创扩展库换料费（¥20/种）。
7. list_supported_chips: 查询当前支持的微控制器型号及其引脚分配硬规则。
8. register_custom_chip: 动态注册第三方 MCU 物理引脚约束与外设映射表。
9. calculate_ipc2152_trace_current: 依据 IPC-2152 标准精确计算印制导线载流能力或反算线宽（温升 ΔT、铜厚 1oz/2oz、内层降额）。
10. audit_industrial_dfx: 工业级 DFX (DFM/DFA/DFT/DFC) 与生产合规自动化静态审查器，输出打分评级、问题分类与 Markdown 体检报告。
11. export_kicad_netlist: 导出标准 KiCad S-Expression 网表 (.net)，支持 KiCad 6/7/8/9/10 直接导入 Pcbnew 快速布线。
12. export_manufacturing_bom: 生成量产级嘉立创 SMT BOM CSV 表格（含位号聚合、基础库免换料费分类）。

12b. export_manufacturing_cpl: 生成嘉立创 SMT 贴片坐标文件（CPL/pos，位号 + 中心坐标 + 层 + 旋转角）。BOM 与 CPL 必须成对交付——只在 BOM 里而不在 CPL 里的器件会被采购但不会贴装，故障留到功能测试才暴露。

1. calculate_parametric_circuit: 闭环参数化硬件设计方程（E96 标准分压电阻对求解、LDO 散热结温校核、I2C 上拉阻值及 RC 滤波）。
2. render_circuit_topology: 生成结构化 ASCII 系统架构拓扑图（电源轨、总线、传感器与保护子系统）。
3. run_erc: 网表级电气规则门禁（ERC）——悬空网络、缺 GND、未知位号、缺电源域、缺去耦电容、差分总线缺 120Ω 终端电阻、电容真实有效容值不足等 45+ 条规则，每条带 severity 与出处，blocking/error 阻断 BOM/CPL 交付。其中 MLCC_EFFECTIVE_CAPACITANCE_DEFICIT 会用真实降额模型复算每颗电容在额定偏置下的实际容值，跌破标称 60% 即告警；器件未带偏置数据时保持沉默而不编造。DECOUPLING_PER_IC_DEFICIT 按器件数量而非网络判断去耦是否充足——三颗 IC 共用一颗 100nF 会被拦下，因为共用意味着远端器件的瞬态电流要穿过走线电感。COMPONENT_RATING_INSUFFICIENT 从电源轨名解析电压（/+3.3V、/VMOT_24V、/VBUS），与器件声明的额定值比对，6.3V 电容接在 24V 轨上直接判 error；未声明额定值的器件跳过而不猜测。
4. analyze_power_tree: 系统级电源树与热功耗分析器，追踪电源域负载电流、LDO 压差裕量、热耗散与结温估算 ($T_j$)。
5. calculate_ipc2221_clearance: 基于 IPC-2221B Table 6-1 标准根据工作电压与导体类别 (B1内层/B2外层裸露/B4涂覆/A6引脚) 精确计算最小电气间隙。
6. export_specctra_dsn: 生成通用 Specctra DSN (v15.0) 自动布线交互文件与启发式器件自动布局，支持直接送入 Freerouting / KiCad 执行 100% 自动化走线。

18b. autoroute_pcb: 运行原生 Python 零 JVM 依赖多层自动布线引擎，执行启发式布局、Specctra DSN 转换与走线求解，输出 Specctra SES 走线文件与物理布线指标（网络连通率、走线总长、过孔数）。布线结果自动过物理 DRC 门禁，引擎不合格时按 exact → room → grid 自动回退，engines_tried 记录实际采用的引擎。 18c. run_pcb_drc: 对布线结果执行物理 DRC 审计——真铜箔间距、蚀刻酸角、电源线宽、板边与禁布区、差分对偏斜，违规按网络聚合输出（错误/警告分级 + 定位坐标 + 修复建议）。 18d. analyze_ionic_contamination: 组件后清洗离子污染 (ROSE) 与离子色谱合规审计器——依据 IPC-CH-65 与 IPC-TM-650 2.3.25/2.3.28，对标 Class 1.56 / Class 3 1.20 μg/cm² NaCl 当量限值与氯 0.70 / 溴 0.54 μg/cm² 物种限值，按偏压与导体间距评分枝晶/CAF 生长风险。 18e. analyze_enig_plating: ENIG/ENEPIG 镀层厚度与黑盘 (镍晶界腐蚀) 风险审计器——依据 IPC-4552A/4556 校核金 0.05~0.20μm、镍 3.0~6.0μm、磷 7~10wt% 与钯 0.10~0.30μm 工艺窗口，综合返修次数与工艺类型评估电偶过腐蚀脆断风险，并预警金厚 >0.25μm 的 AuSn₄ 焊点脆化。 18f. estimate_solder_joint_thermal_fatigue: IPC-9701A / IPC-D-279 Engelmaier 热循环疲劳寿命估算器——按 CTE 失配剪切应变范围 (Δα·ΔT·DNP/2h)、蠕变感知循环指数 (热驻留时间与平均结温) 计算 TC1~TC4 车规/航空温度谱下焊点 63.2% 失效特征寿命 (NTC)，对照服役循环数判定陶瓷大 DNP 封装是否需欠填充。 18g. plan_conformal_coating: IPC-CC-830C / IPC-A-610G §10 三防漆选型与掩膜禁涂区规划器——校核 AR/ER/UR (30~130μm)、