easyeda-agent架构深潜:数据驱动的设计、计算与执行,AI如何安全操作EasyEDA
easyeda-agent架构深潜:数据驱动的设计、计算与执行,AI如何安全操作EasyEDA
easyeda-agent 是 EasyEDA Pro(嘉立创 EDA 专业版)的 AI 自动化层:它给 AI 装上一双能真正画原理图、布局 PCB、跑 DRC 检查的「手」。全部能力都被封装成有明确输入输出的 typed 原理图/PCB 动作,并支持 CLI、Agent Skill、stdio MCP 三种形态接入你的 AI 客户端。
本文将从「设计、计算、执行」三个层面拆解这套架构,帮你理解它如何把"帮我画一块板"从一段危险的自由脚本,变成一个可验证、可审计、可回滚的安全闭环 🎯。
初识 easyeda-agent:三形态融合的 EasyEDA 自动化工具
对新手来说,先建立一个直观印象:你只需要用自然语言描述需求,例如"做一个 ESP32-S3 最小系统板,4 层板,GND 内电层,模组天线区域 keepout",Agent 就会自己完成选型、原理图、布局、布线、铺铜、丝印和 DRC 检查,全程操作的是你眼前真实的 EasyEDA Pro 工程。
它由三个部分协作完成:
| 部件 | 职责 | 安装位置 |
|---|---|---|
CLI / daemon(easyeda) |
掌管 typed action 协议、状态、审计日志与产物 | 本机 PATH |
连接器插件(.eext) |
极薄桥接层,把动作转成官方 eda.* API 调用 |
EasyEDA Pro「扩展管理」 |
Skill(easyeda-agent) |
AI 客户端中的工作流、参考与规范 | ~/.claude/skills、~/.codex/skills 等 |
安装入口一条命令即可完成(自动识别 Codex、Claude Code 等客户端),完整步骤见 docs/quick-start.md。
架构总览:从自然语言到 eda.* API 的四层通路
整条数据流是单向且分层的(详见 docs/architecture.md):
- Skill / Agent 层:负责需求与数据手册依据、选择入口、准备源数据、解释结构化问题。它不直接碰编辑器。
- Go CLI / 纯计算内核:以 Cobra 子命令暴露能力(
sch、pcb、lib、bom等),布局内核只消费数据、返回完整结果或明确失败,从不操作编辑器。 - daemon / Connector 层:daemon 负责长连接、端口管理、多窗口路由、输入校验、审计与防抖自动保存;Connector 在 EasyEDA 宿主内把 typed action 翻译成官方
eda.*调用(实现见 extension/src/actions.ts 与 internal/protocol/actions.go)。 - EasyEDA Pro 工程:唯一的真实落点,写完后由官方 API 回读对账。
为什么不让 AI 直接执行任意 JavaScript?因为自由脚本难审查、难确认部分失败。easyeda-agent 的答案是:固定动作面 + 写入前后双向校验。协议契约(请求、响应、错误、产物文件)完整定义在 docs/protocol.md,命令组织规则见 docs/cli-design.md。
数据驱动设计:电气事实与画面坐标彻底分离
这是整套架构最核心的思想:先数据,后几何,最后才是画布。
以一张门禁控制板的原理图为例:粉色虚线框表示独立功能区,每个区内的器件、引脚、导线由数据计算生成,而不是 AI"看着截图摆位置"。
架构上这依赖一个稳定的 Connectivity IR(连接中间表示,规范见 docs/schematic-connectivity-model.md):
component:器件的稳定实例 ID、位号、库身份;pin/net:每个引脚、每条网络;pin_net:引脚与网络的绑定关系,保存、导入 PCB、DRC 和回归测试都以它对账。
坐标、旋转、线段、框线和文字属于"布局层",可以随时重算;而 component/pin/net/pin_net 这些电气事实在重排前后必须一字不差。这样 AI 排版失误时,电气设计不受污染——数据错了改数据,几何错了重算几何,互不拖累。
数据确认后的执行链路是:固定渲染 / compose --layout-page 生成可检查的 Apply 队列 → 经 CLI 写入 EasyEDA → 逐脚回读。写前核对目标快照,写后核对器件、引脚、连接与呈现层,任何短路、孤儿桩或拓扑偏差都会停止队列,而不是继续补线。
纯计算内核:不碰编辑器的 Go 算法层
"计算"被刻意隔离在编辑器之外。PCB 侧拆成了四个可独立引用的纯 Go 包(单向依赖、不引用文件系统与编辑器对象):
| 包 | 职责 |
|---|---|
pkg/pcbmodel |
板、层叠、器件、焊盘、铜与刚体变换的模型 |
pkg/pcblayout |
完整移动组候选生成与机械合法性检查 |
pkg/pcbrouting |
单次路径搜索、多网共同选择与独立检查 |
pkg/pcbsolve |
布局布线协调、路由反馈、共享预算与整体复验 |
以嘉立创 PCB 初级考试第十八期的 AT32F415 学习板为例(69 个器件、15 个功能区、90×50 mm 圆角板框),流程是"样例关系 → 算法候选 → AI 选择 → typed 写入 → 回读":算法读取实测的 anchor、bbox、pads 和板框,有限枚举出少量完整坐标候选(每个候选包含全部成员的可执行位置、间隙对象对、缺测项),AI 根据具体事实挑选,而不是自己"估算"坐标。搜索预算耗尽只会得到 incomplete(不完整),绝不宣称全局无解——这种诚实的失败语义贯穿整个内核。
原理图侧同理:PlanSchematicLayout 接收组件 ID、实测几何、逐脚网络状态后返回局部 placements/wires/flags,评分和候选用量一并给出,sch layout-plan 可完全离线运行验证。
安全执行闭环:写前守卫、写后回读、审计兜底
AI 操作真实工程,最怕的是"半成功"和"盲重试"。easyeda-agent 在写入路径上叠了五层保险:
- 写前检查:目标工程、页面、器件身份和源数据全部核对,状态漂移直接拒绝;
- 写后回读:引脚、网络、几何、对象绑定逐项对账,官方原始快照是唯一事实来源;
- 分项门禁:原理图走
layout-lint → check → bridge-check → DRC,PCB 用真实 DRC 规则把关; - 失败即停:部分成功、超时、无法确认的结果一律停止盲目重试,保持
incomplete状态; - 保存纪律:自动保存只是安全网,关键节点必须显式
save → reload → readback,且保存成功必须有真实布尔saved:true证据。
除了机制,交互模式本身也做了设计取舍(见 docs/adr/0002-design-proposal-and-interaction-modes.md):决策交互化、执行自动化。有唯一正确答案的"坑"(保存纪律、reload、DRC 硬门)内置为硬门禁,永不打扰用户;真正的权衡(2 层 vs 4 层、地策略、天线 keepout 范围)则在 S0 阶段汇总成一份机器可消费的设计方案书(spec JSON),一次性交用户拍板。交互分全自动 / 里程碑 / 逐步三档,正常客户设计默认走"里程碑确认",既保留人在环,又不至于每步阻塞。
三形态接入:CLI、Agent Skill 与 stdio MCP
同一个 typed 动作面,三种使用姿势,能力完全等价:
- CLI:
easyeda sch place、easyeda pcb route-short、easyeda pcb drc……适合脚本化与调试,--help自描述,AI 读帮助即可调用; - Agent Skill:安装在 AI 客户端中,承载完整工作流知识(design-flow、检查覆盖边界、验收判据),是让 Agent"会做板"的知识包;
- stdio MCP:本地 stdio 适配层暴露 12 个工具(健康检查、动作发现、7 个安全动作域、电路块、工作流状态机、工程传输),刻意不暴露任意 JavaScript 调试域——变更仍全部经过 Go daemon、Connector、工作流门禁与审计日志(详见 mcp/README.md)。
三条入口最终汇入同一条 CLI → daemon → Connector → 官方 eda.* API 链路,不设旁路。
实战成效:一份需求文档到一块过 DRC 的四层板
架构的最终检验是成品。在 docs/showcase-esp32-mini.md 记录的真实案例中,输入只是一份 30 行的中文需求,输出是一块完整交付板:
关键指标全部机械可验,而非肉眼判断:sch drc 0 fatal / 0 error;PCB DRC Connection 0、Clearance 0;pcb check 0 findings;BOM 13 行全带 LCSC C 号可直接下单。DRC 归零是 5 轮数据闭环的产物(Connection 50 → 17 → 6 → 5 → 3 → 0),每轮都从 DRC 明细坐标反推根因——这正是"数据驱动"在执行层的体现。
能力边界:诚实地说不做什么
- 稠密板的迷宫式整板自动布线需要外部 Freerouting,内置路由器适合短线与清晰局部连接;
- EasyEDA 扩展 API 不提供编程式 undo,项目用源数据、写前守卫、回读与失败回滚降低风险,而不是假装能撤销;
- 受控阻抗所需的介质厚度、Er、铜厚无法从当前
eda.*API 完整读取,不能自动声称阻抗合格; - PDF 自动建库遇到封装后缀不明、缺少焊盘依据时会暂停询问,不靠猜。
这些边界写在 docs/FEATURES.md 与 docs/cli-STATUS.md 中,与功能清单一起维护。
写在最后
easyeda-agent 值得学习的不是"AI 画板"这个效果,而是它背后的工程取舍:把电气事实冻结成可重算的数据,把算法隔离成不碰编辑器的纯计算内核,把 AI 的自由度关进 typed 动作与回读对账的笼子里。三层各守其位,AI 才第一次可以"安全地动手"。
想动手试试?安装后启动 easyeda daemon start,在 EasyEDA Pro 中开启「设置 → 允许外部交互」,再用一句话描述你的电路需求,观察 Agent 如何一步步把数据、计算与执行串成一条完整闭环。核心概念词汇表见 docs/concepts.md,架构职责边界见 docs/architecture.md。








