Zaptrace

警告

Pre-1.0。 ZapTrace 是一个验证优先的 EDA 内核，并不保证产品一定可制造。所有生成的输出在制造或使用前都必须经过工程人员审核。请参阅安全免责声明。

说明

证明包是证据层，并不代表绝对正确。 证明包会记录已配置的检查、工件、假设以及通过／失败证据。证明包检查通过，并不意味着电路板已获制造商批准、可用于生产，或无需审核即可安全制造。

---

ZapTrace 是什么

• 一个 Python SDK，用于以编程方式进行电子设计——解析、验证、布局、布线和导出。
• 一个 CLI（zaptrace），用于在终端中快速迭代设计。
• 一个 MCP 服务（zaptrace-mcp），默认的 expert 接口提供 93 个设计工具和 3 个会话管理工具，并提供面向任务的精简接口 inspect、design、verify、repair 和 release，用于范围明确的工作流。
• 一个 REST API，用于基于 Web 的设计工作流。
• 一个验证引擎，内置电气规则检查（ERC）和设计规则检查（DRC）。
• 一条制造导出流水线，支持 Gerber RS-274X、Excellon 钻孔文件、BOM、贴装文件和 KiCad。
• 一个证明包生成器，为每项设计生成可审计、可复现的工件包。

ZapTrace 不是什么

• ❌ 不是 KiCad、Altium 或 Eagle 的替代品——ZapTrace 是一个后端引擎，而不是完整的 PCB 编辑器 GUI。
• ❌ 不是通用 SPICE 仿真器或可用于签核的求解工具——ZapTrace 可以导出 SPICE 并运行基于 ngspice 的有限证据门控，但这些功能无法替代完整的模拟验证或合格的工程审查。
• ❌ 不能替代人工工程判断——所有输出都必须在制造前经过审查。
• ❌ 未经制造验证——ZapTrace 尚未达到 1.0 版本。制造输出仍处于实验阶段。
• ❌ 不适合制造或生产——不作任何适用于制造的声明。
• ❌ Proof Pack 不保证正确性——它是一个证据层，用于记录检查过的内容以及通过或失败的项目。没有错误并不意味着设计正确或可制造。
• ❌ KiCad Oracle（ERC/DRC）是外部验证，不代表绝对正确——它只能检测规则集所涵盖的违规情况。通过 KiCad Oracle 检查并不能保证电路可正常工作。
• ❌ Fab 配置文件不代表制造商批准——内置配置文件符合常见制造商的能力，但你必须根据特定制造商的最新规格进行核实。务必在制造前获得批准。
• ❌ GitHub 硬件 CI 无法捕获所有硬件错误——CI 在模拟或受限硬件上运行；物理验证（探测、上电、功能测试）不可替代。

---

状态

区域	状态
设计解析	✅ 已实现
原理图综合	⚠️ 模板选择（通过关键词匹配预构建模板；不是从零开始综合）
ERC（电气规则检查）	✅ 已实现
元器件布局	✅ 已实现
基于网格的布线	✅ 已实现
网络感知智能布线	✅ 已实现
DRC（设计规则检查）	✅ 已实现
网络分类（电子工程知识）	✅ 已实现
铜箔覆铜生成	✅ 已实现
Gerber RS-274X 导出	✅ 已实现
Excellon 钻孔文件导出	✅ 已实现
BOM（CSV + JSON）导出	✅ 已实现
贴片文件导出	✅ 已实现
KiCad 原理图导出	✅ 已实现
KiCad 层级项目导入	✅ 已实现
EasyEDA Standard 导入/导出（往返转换 ≥0.75）	✅ 已实现（单个扁平 JSON；仅支持导入，不含 PCB 编辑器）
EasyEDA Pro 写入器（通过 KiCad 仅支持导入）	✅ 已实现（ZIP+JSONL；与 Standard 不同）
Altium ASCII 原理图导入	✅ 已实现（仅支持 ASCII 导出；不支持 OLE 二进制）
SVG 原理图渲染	✅ 已实现
制造 ZIP 包	✅ 已实现
MCP 服务（96 个已公开工具：93 个设计工具 + 3 个会话管理工具）	✅ 已实现
电源树架构规划器 + 网表生成	✅ 已实现
REST API 服务	✅ 已实现
设计差异对比	✅ 已实现
完整流水线（自动驾驶模式）	✅ 已实现
Proof Pack 系统	✅ 已实现——证据/签核基础；不保证正确性
插件系统	🚧 实验性——已记录签名运行时策略；仍需生产级沙箱
Review Studio	✅ 已实现——人工审查面板、Proof Pack 证据、基准测试就绪状态
SPICE 网表导出	✅ 基础功能已实现——DC 门控会考虑证据/跳过状态，并非完整模拟签核
DFM（面向制造的设计）	✅ 基础功能已实现——制造商配置文件、制造证据、电流/热/SI 风险报告
多板设计	🔮 计划中——0.3.0 之后
射频/微波支持	🔮 计划中

---

v0.3.0 发布范围

ZapTrace 0.3.0 是一个强化证据的版本。它增加了有界自主签署用语、需求覆盖率、假设证据、KiCad 预言机证据、制造/DFM 证据、组件/数据表/封装溯源、布局/电源/SI/PI 风险报告、已知故障基准测试变异覆盖率，以及 Review Studio 基准测试就绪情况面板。

此版本仍不声称设计已具备制造条件。通过表示配置的证据门槛未阻止流程；这并不意味着设计已获制造商批准、已可投入生产，或无需人工工程审查即可安全制造。

---

快速入门

ZapTrace 尚未达到 1.0 版本。注册表分发标识为 zaptrace-eda，而 Python 导入包和 CLI 仍为 zaptrace。PyPI 上已提供 v0.3.5；其不可变标记工作流在创建 GitHub Release 前未通过容器安全门槛，因此保留该标记作为部分发布证据，而不对其进行重写。目前的开发版本已推进至 0.3.6.dev0。如需从 PyPI 安装最新发布包，请执行：

uv venv --python 3.13
uv pip install "zaptrace-eda==0.3.5"
source .venv/bin/activate

# Run diagnostics
zaptrace doctor

# First run: scaffold a design locally (the published wheel does not
# contain the repository's examples/ directory).
zaptrace init sensor-demo --template esp32_i2c_sensor
zaptrace parse sensor-demo/design.yaml
zaptrace view sensor-demo/design.yaml --output sensor-demo/review

# Create KiCad/inspection outputs inside the working directory.
# Generation success does not mean ERC/DRC or fabrication readiness.
zaptrace pipeline --source sensor-demo/design.yaml --output sensor-demo/build

---

CLI 用法

# Parse a design YAML
zaptrace parse design.yaml

# Inspect a parsed design
zaptrace inspect my_design

# Run ERC validation
zaptrace erc my_design

# List ERC rules
zaptrace erc-rules

# Place components
zaptrace place my_design

# Route nets
zaptrace route my_design

# Generate BOM
zaptrace bom my_design
zaptrace bom my_design --format json

# Generate design report
zaptrace report my_design --output report.md

# Render schematic SVG
zaptrace svg my_design --output schematic.svg

# Export to KiCad
zaptrace kicad my_design output/kicad/

# Diff two designs
zaptrace diff design_a design_b

# Search library
zaptrace library search resistor
zaptrace library get 0402_10k

# Run full pipeline
zaptrace pipeline --source design.yaml --output build/
zaptrace pipeline --intent "ESP32 I2C sensor node"

---

Python SDK 用法

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

# Parse
design = parse_file("design.yaml")

# Validate
runner = ERCRunner()
erc_result = runner.run(design)

# Classify nets
classify_design(design)

# Place & route
positions = place_components(design)
routing, route_result = route_design_smart(design, positions)

# Export
bundle = generate_manufacturing_bundle(design, "build/")
print(f"Gerber layers: {list(bundle['gerber_layers'].keys())}")

---

MCP 用法

ZapTrace 提供 MCP 服务，用于集成 AI Agent。

# Start MCP server (stdio mode)
zaptrace-mcp

# Start MCP server (HTTP loopback mode)
zaptrace-mcp-http

在 AI 客户端的 MCP 设置中进行配置：

{
  "mcpServers": {
    "zaptrace": {
      "command": "zaptrace-mcp"
    }
  }
}

有关工具目录，请参阅 MCP 快速入门；有关产品自有技能、运行时边界和激活门槛，请参阅 Agent 插件发布。

---

REST API 用法

# Start the secure loopback server on 127.0.0.1:8080.
zaptrace-api

# Health does not require a bearer token.
curl http://127.0.0.1:8080/health

对于经过身份验证的 REST 和 MCP HTTP Compose 部署，请复制 .env.example，设置两个令牌值，然后运行 docker compose up --build --wait。请参阅 REST API 生产环境强化和 MCP HTTP 部署。

---

制造导出

ZapTrace 会生成 PCB 制造所需的所有文件：

工件	格式	状态
铜层	Gerber RS-274X	✅
钻孔文件	Excellon	✅
物料清单	CSV / JSON	✅
贴片文件	CSV	✅
制造文件包	ZIP	✅
KiCad 项目	.kicad_pcb, .kicad_sch	✅
原理图	SVG	✅
设计报告	Markdown	✅

# Generate everything
zaptrace export manufacturing my_design --output build/board

---

证明包

证明包是一组可审计、可复现的工件，用于说明 ZapTrace 生成了什么以及为何生成。

zaptrace proof-pack design.yaml --output build/proof-pack

每个证明包包含：

• 设计输入和规范化模型
• ERC 结果（检查了什么，以及哪些项目通过/失败）
• DRC 结果
• BOM 和供应链概览
• 所有制造工件
• 决策日志
• 可复现性元数据
• 警告和审查清单

详情请参阅 docs/strategy/proof-pack-spec.md。

---

验证模型

ZapTrace 使用分层验证模型。每一层都会生成证据；但没有任何一层能保证正确性。

证据层

层	功能	不执行的操作
Parser	验证设计 YAML 结构和约束	不验证电路功能
ERC（29 条规则）	检查电气规则（网络连接、引脚兼容性、电源、电源树、考虑 DNP 的规则）	不模拟电路或验证时序
DRC（16 条规则）	检查物理设计规则（间距、线宽、钻孔）	不保证可制造性
KiCad Oracle	导出到 KiCad 并运行 KiCad 的 ERC/DRC，作为外部验证	KiCad 可能采用不同的规则；通过检查不代表设计正确
Proof Pack	记录所有验证结果、工件哈希、环境元数据和决策	证明检查了什么，但不保证正确性
Fab Profiles	记录制造商的能力（最小线宽、最小钻孔、层数）	不代表制造商批准；务必向你的制造商确认
GitHub Hardware CI	在可用的运行器上运行硬件级集成检查	无法复现所有真实硬件条件；仍需进行物理测试

“Verification-First”的含义

• 验证内置于流水线，而不是导出后再追加。
• 每个设计工件都有可审计的链路：谁用什么工具检查了什么，以及结果如何。
• 设计流水线遇到硬性错误（ERC/DRC 失败）时会停止，并要求明确覆盖。
• 制造前必须进行人工工程审核。 自动化工具无法替代领域专业知识。

不作出的承诺

ZapTrace 不承诺：

• 可直接制造——任何自动化验证流水线都无法保证电路板能正确制造。
• 可用于生产——目前版本低于 1.0；API 和输出可能会发生变化。
• 制造商已批准——Fab Profiles 是参考配置，不代表获得批准。
• 保证正确——所有验证工具都有盲区。
• 全自动制造——每份制造输出都需要人工审核并获得制造商批准。

---

架构

graph TD
    A[YAML Design File] --> B[Parser]
    A1[Natural Language Intent] --> B1[Synthesis Engine]
    B1 --> B

    B --> C[Design Model<br/>Pydantic]
    C --> D[EE Knowledge<br/>Classifier]

    D --> E[ERC Engine]
    E --> F{RC Passed?}

    F -->|Yes| G[Placer]
    F -->|No| H[Suggest Patches]
    H --> C

    G --> I[Router]
    I --> J[DRC Engine]

    J --> K{DRC Passed?}
    K -->|Yes| L[Export Pipeline]
    K -->|No| I

    L --> M[Gerber]
    L --> N[Excellon]
    L --> O[BOM]
    L --> P[Pick-and-Place]
    L --> Q[KiCad]
    L --> R[SVG Schematic]

    L --> S[Proof Pack Generator]
    S --> T[manifest.json + artifacts]

    C --> U[MCP Server]
    C --> V[REST API]
    C --> W[CLI]

---

示例集

示例	描述
ESP32 I2C Sensor Node	基于 ESP32-C3，通过 I2C 读取温度和湿度
RP2040 USB HID	基于 RP2040 的 USB 键盘控制器
USB-C LiPo Charger	由 USB-C 供电并带有保护功能的 LiPo 充电器
STM32 RS485 Node	工业级 STM32 RS485 Modbus 节点
nRF52840 BLE Sensor	基于 nRF52840 的 BLE 环境传感器

请参阅 examples/ 中的设计 YAML 文件和操作指南。

---

安全免责声明

⚠️ 电子设计本身具有风险。

ZapTrace 是低于 1.0 版本的软件。所有输出——原理图、布局、制造文件——在制造或使用前都必须由具备资质的电气工程师审核。

PCB 设计错误可能导致：

• 火灾或热损坏
• 设备损坏
• 触电
• 无线电干扰（可能承担法律责任）
• 系统彻底失效

ZapTrace 按“原样”提供，不附带任何形式的保证。维护者对因使用本软件或其输出而造成的损失不承担任何责任。

验证工具提供的是证据层，而非正确性保证。

• ERC/DRC/KiCad Oracle 检查通过，不代表设计正确或可制造。
• 有效的 Proof Pack 证明检查了什么，并不证明设计安全。
• GitHub 硬件 CI 无法替代物理测试。
• Fab Profiles 是参考配置，不代表制造商批准。

如果你不是电气工程师，请在制造任何由 ZapTrace 生成的设计前咨询电气工程师。

完整安全政策请参阅 docs/SAFETY.md。

---

持久化本地状态

受控部署可将已提交的设计、不可变的版本沿袭、快照、事务、审计事件、对象 ACL 和证据身份持久化到本地 SQLite：

export ZAPTRACE_SESSION_STORE_ROOT="$HOME/.local/share/zaptrace/state"
zaptrace-mcp

持久化为可选功能；未启用时，部署仍保持进程内行为。隔离的工作进程无法直接写入持久状态，活跃的证明／发布引用会保护制品，避免其被保留策略清理，而架构或完整性错误会导致启动失败并默认拒绝。有关备份、恢复、迁移、部署模式和不作出的声明，请参阅持久化版本化状态。

---

路线图

阶段	重点
历史基线（v0.3.3）	仅发布到 PyPI，未提供公开的 Git 来源；作为不可变的历史证据予以保留
失败的候选版本（v0.3.4）	在提交 76ecc97 中止的发布候选版本；工作流在发布前失败，并作为不可变的失败证据予以保留
部分发布（v0.3.5）	PyPI 制品已发布并通过验证；容器安全门禁在创建 GitHub Release 前失败，因此保留不可变标签作为部分发布证据
活跃开发（0.3.6.dev0）	发布后的开发线；未来发布必须通过容器安全检查，才能晋级到 TestPyPI/PyPI
下一版本（v0.4.0）	拓扑与布局深度、有限范围的评估覆盖、审查证据，以及受控的发布就绪度强化
后续	更大的组件库、实时分销商集成、更深入的布线保真度、求解器级 SI/PI/热集成、多板工作流

完整路线图请参阅 docs/ROADMAP.md。

---

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

• 问题跟踪器：GitHub Issues
• 问题与设计讨论：使用 GitHub Discussions；确认的错误和范围明确的工作请使用 Issues
• 行为准则：CODE_OF_CONDUCT.md

---

许可证

当前由项目编写的 ZapTrace 源代码依据 PolyForm Noncommercial License 1.0.0 提供。商业用途需获得版权所有者另行出具的书面许可；请参阅 COMMERCIAL-LICENSING.md 和 LICENSING.md。

先前已依据 MIT 发布的版本和修订版，仍适用发布时的 MIT 条款。第三方材料沿用其各自的许可条款。

---

当前限制

• Pre-1.0：API 不稳定，可能会在不另行通知的情况下发生变化。
• 没有交互式 PCB GUI：主要使用界面为 CLI、SDK、MCP、REST、生成的产物和 Review Studio 证据视图。
• 不提供制造审批：不声称产品已达到可制造状态；所有输出都需要具备资质的工程人员审核。
• 启发式分析：当前的热分析、SI/PI、阻抗、电流密度和功率报告是证据预检，并非求解器级别的签核。
• 算法布线：布线会考虑网格和网络，但并非专业的推挤式交互布线器。
• 有限范围的综合：综合由模块、模板和需求驱动，并非针对任意电路从零开始进行开放式创新。
• 封装／库覆盖有限：许多模块、DFN/LGA/aQFN/RJ45/RF 焊盘封装仍需根据数据手册扩展几何数据。
• KiCad Oracle 属于外部验证：KiCad 自身的 ERC/DRC 有局限性。检查通过并不保证电路功能正常。
• Fab 配置文件不代表制造商认可：请务必根据具体的代工厂和制造商当前的能力进行核实。
• 基准测试通过仅是回归证据：这不代表具备制造安全性或可投入生产。
• GitHub 硬件 CI ≠ 实物测试：CI 无法重现所有真实世界的故障模式。
• KiCad 导出主要是单向的：导入及往返转换的保真度仍有待进一步完善。
• 插件系统处于实验阶段：虽已制定签名运行时策略，但生产环境沙箱仍需进一步强化。

仓库成熟度与社区健康状况

ZapTrace 作为一个 pre-1.0 的专业源代码可用项目进行管理。仓库公开了成熟度证据、治理方式、贡献要求、发布流程和安全态势，供用户和贡献者审阅项目的运作模式。

• 仓库成熟度报告
• OpenSSF 证据
• OpenSSF 差距分析
• 治理
• 维护者及访问权限连续性
• 支持政策
• 开发标准
• 测试政策
• 发布流程
• 依赖项管理
• 发布完整性验证

当前成熟度目标：专业的源代码可用工程成熟度。较早的 OpenSSF/FLOSS 证据描述的是 MIT 许可时期，不应被解读为当前仍采用 FLOSS 许可证的声明；独自维护等治理局限也仍会明确说明。