CircuitAgent README

CircuitAgent · Community Edition

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

🇨🇳 中文说明 · 🇬🇧 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"]["connections"][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。

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

运行方式

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 表格（含位号聚合、基础库免换料费分类）。
13. calculate_parametric_circuit: 闭环参数化硬件设计方程（E96 标准分压电阻对求解、LDO 散热结温校核、I2C 上拉阻值及 RC 滤波）。
14. render_circuit_topology: 生成结构化 ASCII 系统架构拓扑图（电源轨、总线、传感器与保护子系统）。
15. run_erc: 网表级电气规则门禁（ERC）——悬空网络、缺 GND、未知位号、缺电源域、缺去耦电容、差分总线缺 120Ω 终端电阻，每条带 severity 与出处，blocking/error 阻断 BOM/CPL 交付。
16. analyze_power_tree: 系统级电源树与热功耗分析器，追踪电源域负载电流、LDO 压差裕量、热耗散与结温估算 ($T_j$)。
17. calculate_ipc2221_clearance: 基于 IPC-2221B Table 6-1 标准根据工作电压与导体类别 (B1内层/B2外层裸露/B4涂覆/A6引脚) 精确计算最小电气间隙。
18. export_specctra_dsn: 生成通用 Specctra DSN (v15.0) 自动布线交互文件与启发式器件自动布局，支持直接送入 Freerouting / KiCad 执行 100% 自动化走线。
19. export_kicad_schematic: 导出原生现代 KiCad 8/9 S-Expression 原理图文件 (.kicad_sch)，支持在 Eeschema 中直接以可视化原理图打开编辑（含器件符号排布、属性及图框）。
20. audit_supply_chain: 供应链多源弹性审计器（ISO 9001 采购供应链审计），自动排查单源卡脖子器件并映射引脚完全兼容的第二货源替代料 (Drop-in Second-Source) 与立创商城编号。
21. calculate_differential_skew: 高速差分对等长与时延差约束求解器（USB 2.0 HS ≤10ps、以太网 ≤25ps、CAN-FD ≤50ps），反求目标等长差与蛇形绕线 (Serpentine tuning) 齿数与几何尺寸。
22. export_ipc_d356: 导出通用工业标准 IPC-D-356A 裸板电性能飞针测试网表文件，直接喂入板厂飞针测试机 (AEMG/ATG/MicroCraft) 执行开短路连通性检验。
23. export_gerber_bundle: 原生直出符合 Ucamco RS-274X 扩展标准的制造级 Gerber 打包文件（板框 .gm1、顶层铜皮 .gtl、阻焊开窗 .gts、顶层丝印 .gto），摆脱对图形化 EDA 鼠标导出的依赖。
24. calculate_pcb_stackup_impedance: 标准工业四层板 (JLC04161H) 与六层板 (JLC06161H) 叠层矩阵查询与 IPC-2141A 特征阻抗自动反求（50Ω RF微带线、90Ω USB、100Ω 以太网、120Ω 工业差分对）。
25. export_excellon_drill: 生成生产级 IPC-NC-349 Excellon CNC 数控钻孔文件 (.drl)，补齐 PCB 制造 5 层生产包。

暴露的资源 (Resources)

支持通过 circuit:// URI 直接将规范加载到大模型上下文，无需执行额外工具：

• circuit://specs/netlist-schema: 完整的网表 Draft-07 JSON Schema。
• circuit://specs/cpl-standard: 嘉立创 SMT 坐标规范与封装偏角补偿表。
• circuit://specs/ipc-dfx-rules: IPC-2152 导线载流/温升与 IPC-2221 电气间隙/爬电距离硬规则。
• circuit://blocks/catalog: 24 大电路积木的元器件、引脚与网络全量清单。
• circuit://rules/jlc-smt: 嘉立创四层板叠层 (JLC04161H) 与生产物理规则。
• circuit://examples/esp32c3-minimal: ESP32-C3 极简温湿度节点参考网表。
• circuit://examples/stm32f103-controller: STM32F103 工业控制板参考网表。
• circuit://examples/rp2040-dualcore: RP2040 双核传感器扩展板参考网表。

快捷工程 Prompt (Slash-Commands)

• /design_hardware_project: 全流程硬件设计指令（积木匹配 → 阻抗计算 → BOM核算 → 网表校验）。
• /audit_schematic_netlist: Senior EE 硬件体检审查指令（去耦电容亲和性、差分对等长、Type-C 下拉阻抗）。
• /optimize_bom_cost: PCBA 降本优化指令（分析扩展库物料并推荐免换料费的基础库替代料）。
• /audit_industrial_compliance: 工业与量产级 DFX 审查指令（核查 IPC-2152 载流温升、IPC-2221 电气间隙、DFT 测试点覆盖率与 TVS 端口抗浪涌防护）。

数据契约 (Contracts)

• specs/netlist_schema.json — 网表 JSON Schema
• specs/cpl_standard.md — 嘉立创 SMT 坐标规范与封装偏角补偿表
• examples/ — STM32F103 / ESP32-C3 / RP2040 参考网表，CI 强制校验其符合 Schema

测试与 CI

pytest tests/ -q      # 240 passed

CI 在 ubuntu-latest + windows-latest × Python 3.10/3.11/3.12 上跑全量测试， 并额外做两件事：校验 examples/ 全部符合 Schema、离线跑通 README 里的快速上手命令。

范围与路线图 (Scope & Roadmap)

本仓库包含：硬件 DSL 与积木库、立创实时选型客户端、网表/CPL 数据契约、标准 MCP Server、REST 交互接口。

暂不包含：多层板物理布局与布线求解、参数化 3D 壳体布尔几何、Senior EE 物理规则门禁。 这些是上游编译器的高级能力，仍在开发中；本仓库通过稳定的数据契约与客户端接口与其对接， 契约本身是公开且版本化的。

路线图：

• 积木库 + 确定性映射 + 单元测试
• 立创实时选型客户端（重试/缓存/降级）
• JSON Schema + 三份参考样例 + CI
• 工业级实用积木（RS485 / CAN / TP4056 锂电）
• 标准 MCP Server 实现（纯标准库）
• 中英双语文档与官方门面 (Banner + Demo GIF)
• 更多传感器积木（AHT20 温湿度 / MPU6050 六轴）
• 支持自定义第三方芯片引脚分配映射规则
• 工业 DFX 审查引擎（DFM/DFA/DFT/DFC）+ IPC-2152 / IPC-2221 规则库
• EDA 与制造导出（KiCad 网表、嘉立创 BOM/CPL）
• 参数化设计方程求解（E96 分压、LDO 热设计、I2C 上拉、RC 滤波）
• 多层板布局与布线求解器
• 参数化 3D 壳体生成

参与贡献 (Contributing)

最欢迎的贡献是新增经过核验的电路积木：带上数据手册依据的引脚定义与立创料号， 并补上对应单测即可提 PR。Issue 里也欢迎贴出你希望支持的芯片型号。

名称说明 (Naming)

"CircuitAgent" 是一个较通用的名字，社区中已有若干同名或近名的项目（例如 singularguy/CircuitManus 内部的 CircuitAgent 类、Circuit-LLM/circuit-sdk 的 CircuitAgent 基类、以及高能物理领域的 PhEDEx CircuitAgent）。 本项目与它们没有任何关系，也不主张该名称的独占权。如果你的项目或商标与此冲突， 欢迎开 Issue 告知，我们可以协商改名。

⭐ 关注与支持 (Star History)

如果 CircuitAgent 对你的硬件开发或制造流程有所帮助，欢迎点个 Star 支持项目持续演进！

许可证与隐私 (License & Privacy)

• 许可协议：MIT License © 2026 sora
• 隐私政策：PRIVACY.md（零遥测、100% 本地运算、数据归用户所有）