easyeda-agent

1.4.3 版本。 原理图以器件、引脚与连接图为依据,先在本地数据中设计 Lib 电路与几何,再通过 sch compose 组合单页、sch apply 顺序执行并回读验证。 发布状态、构建步骤与尚未完成的验收见 1.4 发布与验证。

easyeda-agent 把官方 EasyEDA 扩展 API 变成一套有类型、可观测、Skill 友好的系统。EasyEDA 插件保持极薄——它连到本地 agent、只执行被批准的动作;Go CLI/daemon 掌管协议、状态、产物、校验和面向用户的工作流。

为什么做这个

上游 run-api-gateway 证明了关键入口:代码能跑在 EasyEDA 内、访问官方 eda 对象。但它把「裸 JavaScript 执行」当作主工作流——强大,但对 AI agent 太脆弱。

本项目的连接器是真实可用的:daemon 默认固定监听单端口 60832(不外溢、被占用时自动接管旧 easyeda daemon)、连接器锁定该端口、校验握手、自愈重连、把一套有类型的动作目录分发到官方 eda.* API。debug.exec_js 保留为任务范围内的临时调试入口。

• Skill 描述专家工作流和护栏;
• Go CLI/daemon 暴露稳定的 typed actions;
• EasyEDA 连接器插件 只做到官方 eda.* 的桥接;
• 产物、截图、DRC 结果、审计日志都是一等输出。

工作原理

• Skill 或人跑一条 easyeda 命令;
• Go CLI 校验输入、把 typed action 提交给本地 daemon;
• daemon 跟踪已连接的 EasyEDA 窗口、经 WebSocket 路由每个动作、记录审计日志/产物/校验结果;
• 连接器扩展跑在 EasyEDA 内、调用官方 eda.* API;
• 结构化结果回流到 CLI 和 Skill,下一步基于真实编辑器状态来规划。

动作目录已覆盖原理图、PCB、文档导航、板级绑定、产物导出、诊断。完整清单与路线图见 docs/FEATURES.md。

站在巨人的肩膀上

我们不重造轮子,而是把成熟的一层层能力叠起来,让 AI agent 直接可用:

• 官方 eda.* API —— 嘉立创 EDA 专业版自己暴露的 86 个命名空间,是真正的能力底座;
• 上游 run-api-gateway —— 证明了「代码能跑在 EasyEDA 内、访问 eda 对象」这条关键入口;
• 成熟的 AI Agent Skill 范式 —— 用 Skill 描述专家工作流 + 护栏,用 typed action 让每一步可观测、可验收、可回放,而不是把「裸 JS 执行」丢给模型硬扛。

在这三层之上,easyeda-agent 补齐了工程化的中间层:自愈连接器、有类型的动作目录、真实 bbox 校验、门控设计流程,以及下面这个核心特色——电路块库。

核心能力 & 特色

能力总览(完整清单见 docs/FEATURES.md):

特色:电路块库(一次贡献,永久收益)

固定模块的外设电路可以直接照抄。 ESP32 自动下载电路、CH340 USB 烧录、按键去抖、 USB-HUB…这些电路的内部拓扑是死的,每次重画等于重趟坑。电路块库把它们 沉淀成验证过的、可复用的电路块(当前 37 块:19 ready / 13 verified / 5 draft)—— sch block-apply 一条命令完成放件 + 连线 + 网表对账,你只需重绑对外的几根线(ports) 到主控网络,引脚用功能名引用所以零改号,器件直接指回标准器件库(BOM 就绪)。

• 社区共建 + 署名可追:每个块带 author/contributors,一次学习贡献、永久收益;
• 验证门禁:块必须跑过 place → wire → check → DRC=0 才入库,不是「看着对」的散文堆;
• 三维知识:器件(可替换选择)+ 原理图链接注意 + PCB 布局电气特性,一块讲全;
• AI 直接消费:agent 放外设前先查块库,命中即抄,省掉一整个模块的选型与接线。

库已内嵌进 CLI:easyeda blocks ls/show/search 离线可查(无需 daemon/窗口) · 贡献指南 standard-blocks-contributing.md

安装

完整上手 & 使用注意事项见 快速开始 → —— 三要素 (CLI / 连接器 .eext / Skill)的安装、版本对齐、启动 daemon、升级纪律 与常见卡点速查,一页讲清。下面是精简版。

easyeda-agent 有三个必须配套的组成部分:CLI/daemon、连接器 .eext 插件和 easyeda-agent Skill；EasyEDA Pro 是运行它们的宿主,需开启「允许外部交互」。升级时 三方(CLI + 连接器 + Skill)要一起升到同一版本,否则 easyeda daemon health 会把 落后的连接器标成 stale。

先装 easyeda CLI/daemon,再装 EasyEDA 连接器 —— 两条通道任选:安装器会打印与 CLI 严格同版的 GitHub Release .eext 下载地址,或从立创官方插件市场一键安装(平台可原地自动更新,但市场版本可能滞后 CLI,严格三方同版时以 Release .eext 为准):

ℹ️ 插件更名说明(2026-08):应市场管理规范要求,插件显示名改为 EDA Agent Connector(不再含 "easyeda" 字样)。经与市场管理员确认,内部包名 easyeda-agent-connector 与 uuid 均保持不变,同一条目重新上传即可 —— 已装用户的原地自动更新不受影响,无需任何操作。

curl -fsSL https://raw.githubusercontent.com/zhoushoujianwork/easyeda-agent/main/install.sh | bash

一键脚本会：安装/更新 easyeda CLI/daemon;自动检测已安装的客户端并把 easyeda-agent skill 安装/更新到对应目录 —— Codex(~/.codex/skills/easyeda-agent)、Claude Code(~/.claude/skills/easyeda-agent);打印连接器 .eext 导入地址。

装过之后升级不必再跑脚本 —— 用 easyeda update:

easyeda update              # CLI 二进制(sha256 校验 + 原子替换)+ skill 目录 → latest
easyeda update --check      # 只读:cli / skill / connector 三方版本对齐表
easyeda update --check --exit-code   # 有落后退出码 10(CI/agent 可 gate)
easyeda update --version <x.y.z>     # 钉版本;--skill-only / --cli-only 缩范围

连接器 .eext 不在自动升级范围内(侧载无原地更新)—— update 会报出它落后并打印重导地址。 dev 构建(git-describe 版本号)默认不覆盖,--force 才强升;二进制在 root 目录时用 sudo easyeda update。

可用环境变量控制 skill 安装:

curl -fsSL .../install.sh | EASYEDA_INSTALL_SKILLS=codex,claude bash  # 指定目标
curl -fsSL .../install.sh | EASYEDA_INSTALL_SKILLS=none bash  # 跳过 skill
curl -fsSL .../install.sh | EASYEDA_SKILL_PRESERVE=1 bash  # 保留本地改动
curl -fsSL .../install.sh | EASYEDA_VERSION='<vX.Y.Z>' bash  # 指定版本(跳过 API 查询)

遇到 403 / GitHub API 限流:脚本默认要调一次 api.github.com 解析 latest release,匿名调用每个 IP 每小时只有 60 次 —— 公司出口 / NAT / CI 很容易撞满。两条 出路(脚本报错时也会打印):

export GITHUB_TOKEN=<token>   # 或 GH_TOKEN;已登录 gh CLI 时会自动取 `gh auth token`
gh auth login                 # 等价做法,额度提升到 5000/小时

curl -fsSL .../install.sh | EASYEDA_VERSION='<vX.Y.Z>' bash   # 或者直接锁版本,完全不碰 API

可用 tag 见 Releases。

Skill slug 为 easyeda-agent(后缀有意为之,区分于官方 EasyEDA 工具)。只从 registry 装 skill:

# ClawHub(make release 时自动同步发布,版本与 repo 对齐)
clawhub install easyeda-agent

SkillHub 另有官方 CLI,与其他同名 skillhub 工具不兼容。 需要与 CLI/连接器保持同版时,使用上面的一键安装器或 GitHub Release 的 skills.tar.gz。

EasyEDA 需开启「允许外部交互」,连接器的 WebSocket 才能连到本地 daemon。

给 AI Agent 的推荐引导 Prompt

把下面内容连同具体设计需求交给 Agent。它要求 Agent 先确认工具链和数据证据，再写入 EDA，避免直接从截图猜接或在页面上反复试摆：

请使用 easyeda-agent 完成 EasyEDA Pro 任务。

开始前先确认三个组成部分处于同一发布版本：
1. easyeda CLI/daemon
2. easyeda-agent Skill
3. EDA Agent Connector 插件

运行 easyeda update --check --exit-code。CLI 或 Skill 落后时运行 easyeda update；
Connector 落后时安装同一 GitHub Release 的 easyeda-agent-connector.eext，保存文档并
完全退出、重开 EasyEDA。确认已开启“允许外部交互”，运行 easyeda health 核对目标工程、
页面和版本。

绘制原理图时先读取或建立本地 canonical connectivity JSON，以器件、完整物理引脚、
稳定网络 ID、pin→net/NC 为权威数据；先在本地计算器件 XY、朝向、连线与功能 Lib，
再生成 diff/Apply 队列。Apply 后逐脚回读，运行 layout-lint、check、bridge-check、DRC，
显式保存并导出图片检查。不要直接依赖截图猜接，不修改原位号，不把 GPIO 号当器件物理
脚号，也不要把未验证或仍有 WARN 的结果描述成通过。

可选:MCP 接入

仓库内的 mcp/ 是一个本地 stdio MCP 适配层,方便 Codex 等支持 MCP 的 agent 直接发现并调用 easyeda_* 工具。它复用现有 easyeda CLI/daemon,不会绕过 typed action、审计、workflow gate 或官方 eda.* API;任意 JavaScript 的 debug.exec_js 域不会通过 MCP 暴露。

npm --prefix mcp ci --ignore-scripts
codex mcp add easyeda-agent \
  --env EASYEDA_BIN="$(command -v easyeda)" \
  -- node "$(pwd)/mcp/src/server.mjs"

重启 agent 客户端后即可使用。其他 MCP 客户端使用同一 stdio command/env 配置; 详细工具清单与开发验证见 mcp/README.md。

效果演示

门禁控制板示例：本地数据 → SCH Apply → 真实原理图

器件、完整物理引脚、稳定网络 ID 和 NC 保存在本地连接图中。Agent 先依据实测引脚几何 计算功能 Lib 内的器件位置、方向和连线，再组合页面，通过 sch apply 顺序写入 EasyEDA，并回读核对。原位号与器件身份保持不变。

23 个器件 · 165 个物理引脚 · 28 个网络 · 2 页原理图

电源与 RF 主控

电源、RF 主控和下载接口分别组成 Lib；外围电路按引脚方向连接，端口长短错落， 粉色虚线框与 0.2 inch 标题由数据计算。

对讲与外设接口

从左上角按 Z 字阅读顺序排列，每框随内容独立收紧并保留最小内边距；同行顶齐， 下一行按本行最大高度推进。标题利用上方或下方空档，减少额外高度。

Apply 实际执行

动图使用电源与 RF 主控页实际 Apply 捕捉的 12 张关键阶段导图，加速播放；两张静图源自 EasyEDA 官方导图，展示名称已匿名化。 录制脚本与复现步骤见 Apply 动图捕捉。 两页布局与连接检查均为 0 错误、0 警告；官方 DRC 仍有 3 WARN，严格门禁未通过，部分文字避让仍待完善。 完整验证范围见 1.4 发布与验证。

历史 PCB 案例：ESP32-S3 四层板

完整实战案例:一份需求文档 → AI 全自动画完 ESP32-S3 四层板 —— 19 器件原理图 + 四层 PCB(GND 内电层/VCC 电源层/天线禁铜/四角 M3), pcb drc Connection/Clearance 双归零、pcb check 0、layout-lint 100/100,附原生截图与全流程复盘。

下面的历史录屏来自 ESP32 回归板的真实 EasyEDA 画布，展示 PCB 布局、板框和铺铜：

下面这块板由 agent 驱动完整 PCB 流程产出——自动布局 → 板框贴合 → 规则感知布线 → 4 层电源平面 → 丝印碰撞避让——并在真实 EasyEDA 画布上验证(DRC 31 → 3、No-Connection 归零):

几个单步的真机前后对比(同一块板):

本节 PCB GIF 和截图来自 ESP32 回归板真机流程(原理图 → 导入 PCB → 4 层叠层 → 布局 → GND 内电层/VCC 信号 plane → 天线禁区+检查 → 丝印/LED 极性 → 挖槽)。这是独立于门禁控制板示例的历史回归案例，原始需求见 esp32MiniRequire.md。

能力清单(已支持)

以 typed CLI 子命令暴露(easyeda <domain> <verb>)。1.4.3 的验证范围与未完成项见 1.4 发布与验证。

原理图 — 完整功能地图(已支持 40+ 子命令按功能域 + 待支持路线)见 docs/cli/schematic.md(CLI 功能索引:docs/cli/);摘要:

• 器件与库:从立创/LCSC 库按 uuid 放真实器件、换型号(replace)、符号/封装重绑、C 号确定性解析(resolve-lcsc);modify 属性 merge 语义(只 patch 顶层字段不再清空自定义属性,#175)。
• 连线:connect/autoconnect(打分器自选方向——碰撞/穿件/图签/fanout 全几何成本,netport 竖排折叠惩罚让密集引脚列标签保持水平)/disconnect 成对删;电源/地标志自动补偿旋转存储的坑。
• 数据与布局:连接图保留稳定器件 ID、引脚、网络与 NC;合法数字位号保持原样,功能名称存 Role。sch compose 基于已设计的 Lib 几何离线组合单页,从左上向右按 Z 字排列；每框按内部内容独立收紧,同行顶齐,下一行按本行最大高度推进。sch frame apply/check 生成并检查保留最小内边距的粉色虚线框与 0.2 inch 标题。组合器不推导任意外围电路、不自动分页或删除源页。