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（設計ルールチェック）	✅ 実装済み
ネット分類（EE の知識）	✅ 実装済み
銅箔ベタの生成	✅ 実装済み
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（製造性設計）	✅ 基盤を実装済み — Fab プロファイル、製造エビデンス、電流／熱／SI リスクレポート
マルチボード設計	🔮 予定 — 0.3.0 以降
RF／マイクロ波への対応	🔮 予定

---

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 は、AI エージェントとの連携用に MCP サーバーを公開しています。

# Start MCP server (stdio mode)
zaptrace-mcp

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

AI クライアントの MCP 設定で構成します。

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

ツールカタログについてはMCP クイックスタートを、製品が所有するスキル、ランタイムの境界、アクティベーションゲートについてはエージェントプラグインの公開を参照してください。

---

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 は階層化された検証モデルを採用しています。各階層は証拠を生成しますが、いずれも正しさを保証するものではありません。

エビデンスレイヤー

レイヤー	機能	機能しないこと
パーサー	設計 YAML の構造と制約を検証します	回路の機能は検証しません
ERC（29 ルール）	電気的ルール（ネットの接続、ピンの互換性、電源、電源ツリー、DNP 対応）をチェックします	回路のシミュレーションやタイミングの検証は行いません
DRC（16 ルール）	物理設計ルール（クリアランス、幅、ドリル）をチェックします	製造可能であることを保証しません
KiCad Oracle	KiCad にエクスポートし、外部検証として KiCad の ERC/DRC を実行します	KiCad のルールは異なる場合があり、チェックに合格しても設計が正しいとは限りません
Proof Pack	すべての検証結果、成果物のハッシュ、環境メタデータ、判断を記録します	チェック内容の証拠であり、正しさを保証するものではありません
Fab Profiles	メーカーの対応能力（最小配線幅、最小ドリル径、層数）を記録します	メーカーの承認ではありません。必ず製造業者に確認してください
GitHub Hardware CI	利用可能なランナー上でハードウェアレベルの統合チェックを実行します	現実世界のハードウェア環境をすべて再現することはできません。物理的なテストが必要です

「検証優先」が意味すること

• 検証はエクスポート後に追加するのではなく、パイプラインに組み込まれています。
• すべての設計成果物には、誰が、どのツールを使って何をチェックし、どのような結果だったかを追跡できる記録があります。
• 設計パイプラインは重大なエラー（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	I2C 経由で温度と湿度を読み取る ESP32-C3
RP2040 USB HID	RP2040 ベースの USB キーボードコントローラー
USB-C LiPo Charger	保護機能付きの USB-C 給電 LiPo 充電器
STM32 RS485 Node	産業用 STM32 RS485 Modbus ノード
nRF52840 BLE Sensor	nRF52840 を使用した BLE 環境センサー

設計 YAML ファイルと手順については、examples/ をご覧ください。

---

安全に関する免責事項

⚠️ 電子機器の設計には本質的にリスクが伴います。

ZapTrace は 1.0 より前のソフトウェアです。回路図、レイアウト、製造用ファイルなど、すべての出力は、製造または使用の前に、資格を持つ電気技術者によるレビューが必要です。

PCB の設計に誤りがあると、以下の事態が発生するおそれがあります。

• 火災または熱による損傷
• 機器の損傷
• 感電
• 電波干渉（法的責任が発生する可能性）
• システムの完全な故障

ZapTrace は現状有姿で提供され、いかなる種類の保証もありません。メンテナーは、本ソフトウェアまたはその出力の使用に起因する損害について、一切の責任を負いません。

検証ツールはエビデンスレイヤーであり、正しさを保証するものではありません。

• ERC/DRC/KiCad Oracle のチェックに合格しても、設計が正しい、または製造可能であるとは限りません。
• 有効な Proof Pack が証明するのはチェック内容であり、設計の安全性ではありません。
• GitHub Hardware CI は物理的なテストに取って代わるものではありません。
• Fab Profiles は参考構成であり、メーカーの承認ではありません。

電気技術者でない場合は、ZapTrace が生成した設計を製造する前に、電気技術者に相談してください。

安全ポリシーの全文については、docs/SAFETY.md をご覧ください。

---

永続的なローカル状態

管理されたデプロイでは、コミット済みの設計、変更不可のバージョン系譜、スナップショット、トランザクション、監査イベント、オブジェクト ACL、証拠の識別情報をローカル SQLite に永続化できます。

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

永続化はオプトインです。設定されていないデプロイでは、プロセス内の状態が維持されます。隔離されたワーカーは永続状態に直接書き込めません。また、有効な証明／リリース参照によって、保持期間の経過に伴うアーティファクトのクリーンアップが防止されます。スキーマまたは整合性エラーがある場合、起動はフェイルクローズします。バックアップ、復元、移行、デプロイモード、明示的に保証しない事項については、バージョン管理された永続状態を参照してください。

---

ロードマップ

期間	注力分野
レガシーベースライン（v0.3.3）	公開 Git の来歴を伴わない PyPI のみのリリース。変更不可の過去の証拠として保持
失敗した候補（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 の条件のもとで引き続き利用できます。サードパーティの素材には、それぞれ独自のライセンス条件が適用されます。

---

現在の制限事項

• 1.0 未満：API は不安定であり、予告なく変更される場合があります。
• 対話型 PCB GUI なし：主な利用手段は CLI、SDK、MCP、REST、生成された成果物、Review Studio のエビデンスビューです。
• 製造承認なし：製造可能な状態であるとの主張はしていません。すべての出力には、資格を持つエンジニアによる確認が必要です。
• ヒューリスティック分析：現在の熱、SI/PI、インピーダンス、電流密度、電力に関するレポートは、エビデンスによる事前チェックであり、ソルバー相当の承認ではありません。
• アルゴリズムによる配線：配線はグリッドとネットを考慮しますが、プロ向けの押し引き対応インタラクティブルーターではありません。
• 範囲を限定した合成：合成はブロック、テンプレート、要件に基づいており、任意の回路をゼロから自由に発明するものではありません。
• パッケージ／ライブラリの対応範囲が限定的：多くのモジュール、DFN/LGA/aQFN/RJ45/RF のランドパターンでは、データシートに基づく形状の拡充が引き続き必要です。
• KiCad Oracle は外部検証です：KiCad 自体の ERC/DRC にも制限があります。チェックに合格しても、回路が機能する保証にはなりません。
• ファブプロファイルはメーカーによる承認ではありません：必ず、利用するファブハウスおよびメーカーの最新の対応能力に照らして確認してください。
• ベンチマーク合格は回帰テストのエビデンスです：製造上の安全性や量産準備が整っていることを意味しません。
• GitHub ハードウェア CI ≠ 実機テスト：CI では、現実世界におけるすべての故障モードを再現できません。
• KiCad エクスポートは主に外部への出力です：インポートや往復変換の忠実度は、今後強化すべき領域です。
• プラグインシステムは実験的です：署名済みランタイムのポリシーはありますが、本番環境向けのサンドボックス化にはさらなる強化が必要です。

リポジトリの成熟度とコミュニティの健全性

ZapTrace は、1.0 未満のプロ向けソース公開プロジェクトとして管理されています。このリポジトリでは、成熟度のエビデンス、ガバナンス、コントリビューションに関する期待事項、リリースプロセス、セキュリティ体制を公開しているため、ユーザーやコントリビューターはプロジェクトの運営モデルを確認できます。

• リポジトリ成熟度レポート
• OpenSSF エビデンス
• OpenSSF ギャップ分析
• ガバナンス
• メンテナーとアクセスの継続性
• サポートポリシー
• 開発標準
• テストポリシー
• リリースプロセス
• 依存関係の管理
• リリースの完全性検証

現在の成熟度目標：プロ向けのソース公開エンジニアリング成熟度。過去の OpenSSF/FLOSS エビデンスは MIT ライセンスが適用されていた期間について述べたものであり、現在も FLOSS ライセンスであるという主張として解釈しないでください。また、単独メンテナンスなどのガバナンス上の制約も明示されています。