zaptrace

<p align="center"> <a href="https://www.buymeacoffee.com/oaslananka"> <img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=oaslananka&button_colour=FFDD00&font_colour=000000&font_family=Arial&outline_colour=000000&coffee_colour=ffffff" alt="Buy me a coffee" /> </a> </p> # 工具列表 **ZapTrace** 是一款基于 AI 的、优先进行验证的、开源的电子设计自动化（EDA）内核，适用于代理和工程师。 > **1.0 版本之前** 所有输出都需要人类工程审查后才能制造或使用。 > 请参阅 [安全免责声明](#安全免责声明)。 > 从意向 → 标准化设计 → 原理图 → 电气规则检查（ERC）→ 布局 → 布线 → 设计规则检查（DRC）→ 物料清单（BOM）→ 生产制造包 → 可审计证明包。 ``` Prompt-to-Fab，具有证明。 基于 AI 的 EDA 内核，适用于代理。 优先进行验证的电子设计。 确定性核心，AI 辅助工作流程。 无需 EDA 依赖，具备优秀的 EDA 互操作性。 ``` > **证明包 = 证据层，非保证** 请参阅 [验证模型](#验证模型)。 --- ## ZapTrace 是什么 - **Python SDK** 用于程序化电子设计 — 解析、验证、布局、布线、导出。 - **CLI** (`zaptrace`) 用于终端的快速设计迭代。 - **MCP 服务器** (`zaptrace-mcp`) 暴露 81 种面向 AI 代理的工具。 - **REST API** 用于基于 Web 的设计工作流程。 - **验证引擎** — 内置电气规则检查（ERC）+ 设计规则检查（DRC）。 - **制造导出管道** — Gerber RS-274X、Excellon 钻孔、BOM、拾取和放置、KiCad。 - **证明包生成器** — 可审计的、 reproducible 的 artifact bundles 适用于每个设计。 ## ZapTrace 不是什么 - ❌ **不是 KiCad、Altium 或 Eagle 的替代品** — ZapTrace 是一个 *后端引擎*，而非完整的 PCB 编辑器 GUI。 - ❌ **不是 SPICE 模拟器** — 没有模拟功能（待实现）。 - ❌ **不是人类工程判断的替代品** — 所有输出在制造前都需要审查。 - ❌ **未经过制造验证** — ZapTrace 处于 1.0 版本之前，制造输出为实验性。 - ❌ **不是制造就绪或生产就绪** — 不能保证制造适合度。 - ❌ **证明包不是正确性保证** — 它是证据层，记录了检查的内容和通过/失败的结果。错误 absence 不代表设计正确或可制造。 - ❌ **KiCad Oracle（ERC/DRC）是外部验证，非绝对正确** — 它检查规则漏洞，规则所知范围有限。KiCad Oracle 检查通过不保证电路功能。 - ❌ **制造配置文件不是制造商批准** — 内置配置文件匹配常见制造商能力，但您必须验证特定制造商的当前规格。始终获取制造前批准。 - ❌ **GitHub 硬件 CI 不能捕获所有硬件错误** — CI 运行在模拟或有限硬件上；物理验证（探针、上电、功能测试）不可替代。 --- ## 状态 | 领域 | 状态 | |------|--------| | 设计解析 | ✅ 已实现 | | 原理图合成 | ⚠️ 模板选择（关键字匹配预建模板；非从零合成） | | ERC（电气规则检查） | ✅ 已实现 | | 元件布局 | ✅ 已实现 | | 网格基布线 | ✅ 已实现 | | 网感知智能布线 | ✅ 已实现 | | DRC（设计规则检查） | ✅ 已实现 | | 网分类（EE 知识） | ✅ 已实现 | | 铜浇注生成 | ✅ 已实现 | | Gerber RS-274X 导出 | ✅ 已实现 | | Excellon 钻孔导出 | ✅ 已实现 | | BOM（CSV + JSON）导出 | ✅ 已实现 | | 拾取和放置导出 | ✅ 已实现 | | KiCad 原理图导出 | ✅ 已实现 | | SVG 原理图渲染 | ✅ 已实现 | | 制造 ZIP 包 | ✅ 已实现 | | MCP 服务器（81 种工具） | ✅ 已实现 | | 电源树架构规划器 + 网表导出 | ✅ 已实现 | | REST API 服务器 | ✅ 已实现 | | 设计差异 | ✅ 已实现 | | 全管道（自动驾驶） | ✅ 已实现 | | 证明包系统 | 🚧 实验性 — M0 中 v1 证据强化 | | 插件系统 | 🚧 实验性 — M2 中计划签名运行时 | | 基于 Web 的查看器 | 🔮 计划中 | | SPICE 网表导出 | 🔮 计划中 — M3+ | | DFM（设计制造） | 🧪 已实现基础 — M1 中制造配置文件证据强化 | | 多板设计 | 🔮 计划中 — M3 后 | | RF/微波意识 | 🔮 计划中 | --- ## 快速入门 ```bash # 安装 uv pip install zaptrace ``` PyPI 分发版为 `zaptrace`；Python 导入包和 CLI 命令仍为 `zaptrace`。 ```bash # 或从源代码安装 git clone https://github.com/oaslananka/zaptrace.git cd zaptrace uv sync --all-extras # 运行诊断 zaptrace doctor # 解析和验证设计 zaptrace parse examples/esp32_i2c_sensor_node/design.yaml zaptrace erc my_design # 生成制造输出 zaptrace export manufacturing my_design --output build/board ``` --- ## CLI 用法 ```bash # 解析设计 YAML zaptrace parse design.yaml # 检查解析的设计 zaptrace inspect my_design # 运行 ERC 验证 zaptrace erc my_design # 列出 ERC 规则 zaptrace erc-rules # 布局元件 zaptrace place my_design # 布线 zaptrace route my_design # 生成 BOM zaptrace bom my_design zaptrace bom my_design --format json # 生成设计报告 zaptrace report my_design --output report.md # 渲染原理图 SVG zaptrace svg my_design --output schematic.svg # 导出到 KiCad zaptrace kicad my_design output/kicad/ # 比较两个设计 zaptrace diff design_a design_b # 搜索库 zaptrace library search resistor zaptrace library get 0402_10k # 运行完整管道 zaptrace pipeline --source design.yaml --output build/ zaptrace pipeline --intent "ESP32 I2C sensor node" ``` --- ## Python SDK 用法 ```python from zaptrace.core.parser import parse_file from zaptrace.erc.runner import ERCRunner from zaptrace.algo.placer import place_components from zaptrace.algo.router import route_design_smart from zaptrace.export.manufacturing import generate_manufacturing_bundle from zaptrace.ee.classifier import classify_design # 解析 design = parse_file("design.yaml") # 验证 runner = ERCRunner() erc_result = runner.run(design) # 分类网络 classify_design(design) # 布局和布线 positions = place_components(design) routing, route_result = route_design_smart(design, positions) # 导出 bundle = generate_manufacturing_bundle(design, "build/") print(f"Gerber layers: {list(bundle['gerber_layers'].keys())}") ``` --- ## MCP 用法 ZapTrace 暴露了一个用于 AI 代理集成的 MCP 服务器。 ```bash # 启动 MCP 服务器（stdio 模式） zaptrace-mcp # 启动 MCP 服务器（HTTP 模式） zaptrace-mcp --http --port 8090 ``` 在 AI 客户端的 MCP 设置中配置： ```json { "mcpServers": { "zaptrace": { "command": "zaptrace-mcp" } } } ``` 请参阅 [docs/mcp/quickstart.md](docs/mcp/quickstart.md) 获取完整的工具目录和提示模板。 --- ## REST API 用法 ```bash # 启动 API 服务器 zaptrace-api # 解析设计 curl -X POST -H "Content-Type: multipart/form-data" \ -F "file=@design.yaml" http://localhost:8000/parse # 运行 ERC curl http://localhost:8000/erc/my_design ``` 请参阅 [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) 获取 REST API 设置和用法。 --- ## 制造导出 ZapTrace 生成所有 PCB 制造所需的文件： | 工件 | 格式 | 状态 | |----------|--------|--------| | 铜层 | Gerber RS-274X | ✅ | | 钻孔文件 | Excellon | ✅ | | 物料清单 | CSV / JSON | ✅ | | 拾取和放置 | CSV | ✅ | | 制造包 | ZIP | ✅ | | KiCad 项目 | .kicad_pcb, .kicad_sch | ✅ | | 原理图 | SVG | ✅ | | 设计报告 | Markdown | ✅ | ```bash # 生成所有内容 zaptrace export manufacturing my_design --output build/board ``` --- ## 证明包 证明包是一个可审计的、 reproducible 的 artifact bundle，解释了 ZapTrace 生成的内容和原因。 ```bash zaptrace proof-pack design.yaml --output build/proof-pack ``` 每个证明包包含： - 设计输入和标准化模型 - ERC 结果（检查内容和通过/失败结果） - DRC 结果 - BOM 和供应链概述 - 所有制造工件 - 决策日志 - 再现性元数据 - 警告和审查清单 请参阅 [docs/strategy/proof-pack-spec.md](docs/strategy/proof-pack-spec.md) 获取详细信息。 --- ## 验证模型 ZapTrace 使用分层验证模型。每一层都生成证据；没有一个是正确性保证。 ### 证据层 | 层 | 功能 | 不具备功能 | |-------|-------------|---------------------| | **解析器** | 验证设计 YAML 结构和约束 | 不验证电路功能 | | **ERC（29 条规则）** | 检查电气规则（网络连接、引脚兼容性、电源、电源树、DNP 感知） | 不模拟电路或验证时序 | | **DRC（16 条规则）** | 检查物理设计规则（间隙、宽度、钻孔） | 不保证可制造性 | | **KiCad Oracle** | 导出到 KiCad 并运行 KiCad 的 ERC/DRC 作为外部验证 | KiCad 可能有不同的规则；通过不意味着设计正确 | | **证明包** | 记录所有验证结果、工件哈希、环境元数据和决策 | 验证内容证据，非正确性保证 | | **制造配置文件** | 记录制造商能力（最小轨迹、最小钻孔、层） | 不是制造商批准；始终与您的制造商核实 | | **GitHub 硬件 CI** | 在可用运行器上运行硬件级集成检查 | 无法重现所有现实世界的硬件条件；物理测试不可替代 | ### “验证优先” 的含义 - 验证 **内置于管道**，而非在导出后附加。 - 每个设计工件都有可审计的链条：谁检查了什么，使用哪个工具，结果是什么。 - 设计管道在硬错误（ERC/DRC 失败）时停止，需要显式覆盖。 - **人类工程审查是必须的**，在制造前。没有任何自动化工具可以取代领域专业知识。 ### 不主张 ZapTrace 不主张： - **制造就绪** — 没有自动化验证管道可以保证 PCB 制造正确。 - **生产就绪** — 1.0 版本之前；API 和输出可能会更改。 - **制造商批准** — 制造配置文件是参考配置，不是批准。 - **保证正确性** — 所有验证工具都有盲点。 - **完全自动制造** — 每个制造输出都需要人工审查和制造商批准。 --- ## 架构 ```mermaid graph TD A[YAML 设计文件] --> B[解析器] A1[自然语言意图] --> B1[合成引擎] B1 --> B B --> C[设计模型<br/>Pydantic] C --> D[EE 知识<br/>分类器] D --> E[ERC 引擎] E --> F{RC 通过？} F -->|是| G[布局器] F -->|否| H[建议补丁] H --> C G --> I[路由器] I --> J[DRC 引擎] J --> K{DRC 通过？} K -->|是| L[导出管道] K -->|否| I L --> M[Gerber] L --> N[Excellon] L --> O[BOM] L --> P[拾取和放置] L --> Q[KiCad] L --> R[SVG 原理图] L --> S[证明包生成器] S --> T[manifest.json + 工件] C --> U[MCP 服务器] C --> V[REST API] C --> W[CLI] ``` --- ## 示例画廊 | 示例 | 描述 | |---------|-------------| | [ESP32 I2C 传感器节点](examples/esp32_i2c_sensor_node/) | ESP32-C3 读取温度/湿度，基于 I2C | | [RP2040 USB HID](examples/rp2040_usb_hid/) | 基于 RP2040 的 USB 键盘控制器 | | [USB-C LiPo 充电器](examples/usb_c_lipo_charger/) | USB-C 供电 LiPo 充电器，带保护 | | [STM32 RS485 节点](examples/stm32_rs485_node/) | 工业 STM32 RS485 Modbus 节点 | | [nRF52840 BLE 传感器](examples/nrf52840_ble_sensor/) | BLE 环境传感器，基于 nRF52840 | 请参阅 [examples/](examples/) 获取设计 YAML 文件和演练。 --- ## 安全免责声明 > **⚠️ 电子设计本质上是有风险的。** > > ZapTrace 是 1.0 版本之前软件。所有输出 — 原理图、布局、制造文件 — **必须由合格的电气工程师审查后才能制造或使用**。 > > 不正确的 PCB 设计可能导致： > - 火灾或热损伤 > - 设备损坏 > - 电击 > - 无线电干扰（法律责任） > - 完整的系统故障 > > ZapTrace 按原样提供，不提供任何形式的保证。维护者不承担因使用该软件或其输出而产生的损害的责任。 > > **验证工具是证据层，不是正确性保证。** > - 通过 ERC/DRC/KiCad Oracle 检查并不意味着设计正确或可制造。 > - 有效的证明包证明了检查了什么，而不是设计是安全的。 > - GitHub 硬件 CI 无法替代物理测试。 > - 制造配置文件是参考配置，不是制造商批准。 > > **如果您不是电气工程师，请在制造任何 ZapTrace 生成的设计之前咨询电气工程师。** > > 请参阅 [docs/SAFETY.md](docs/SAFETY.md) 获取完整的安全政策。 --- ## 路线图 | 阶段 | 焦点 | |---------|-------| | **现在（v0.2）** | 证明包系统、插件架构、制造验证 | | **下一个（v0.3）** | SPICE 网表导出、DFM 检查、多板支持 | | **即将推出（v0.4）** | 基于 Web 的查看器、交互式布线 GUI、云 CI 集成 | | **未来（v0.5+）** | RF/微波意识、热模拟、ML 辅助布局 | 请参阅 [docs/ROADMAP.md](docs/ROADMAP.md) 获取完整的路线图。 --- ## 贡献 我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。 - **问题跟踪器**： [GitHub Issues](https://github.com/oaslananka/zaptrace/issues) - **讨论**： [GitHub Discussions](https://github.com/oaslananka/zaptrace/discussions) - **行为准则**： [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) --- ## 许可证 MIT 许可证 - 请参阅 [LICENSE](LICENSE)。 ZapTrace 免费用于商业和个人使用。 --- ## 当前限制 - **1.0 版本之前**：API 不稳定，可能会在不通知的情况下更改。 - **无 GUI**：所有交互基于 CLI/SDK/MCP。 - **无 SPICE**：无模拟或混合信号模拟。 - **无交互式布线编辑器**：布线是算法的（基于网格）。 - **原理图合成基于模板**：不使用 LLM 生成的设计。 - **有限的封装库**：~50 个常用封装支持。 - **无热分析**：无热模拟或 PDN 分析。 - **无信号完整性分析**：无 SI/PI/EMI 分析。 - **不适用于制造**：不声明制造就绪。 - **不适用于生产**：1.0 版本之前；API、格式和输出可能会更改。 - **证明包是证据，不是保证**：通过证明包不意味着设计正确、安全或可制造。 - **KiCad Oracle 是外部验证**：KiCad 自己的 ERC/DRC 有局限性。通过检查不保证电路功能。 - **制造配置文件不是制造商批准**：始终与您的特定制造商核实。 - **GitHub 硬件 CI ≠ 物理测试**：CI 无法重现所有现实世界的条件。 - **KiCad 导出是单向的**：不支持 KiCad 文件导入。 - **插件系统是实验性的**：尚未稳定。运行时安全设计正在进行中。 - **证明包系统是实验性的**：格式可能会更改。