快速开始 & 使用注意事项

September 9, 2026 · View on GitHub

easyeda-agent 有三个必须配套并保持同版的组成部分；EasyEDA Pro 是运行宿主：

部件是什么装在哪
CLI / daemon (easyeda)掌管 typed action 协议、状态、审计、产物、校验本机 PATH(默认 /usr/local/bin)
连接器插件 (.eext)极薄桥接层,跑在 EasyEDA 内,把动作转成官方 eda.* 调用EasyEDA Pro「扩展管理」
Skill (easyeda-agent)AI 客户端里的工作流、参考、脚本、规范~/.claude/skills、~/.codex/skills 和/或 Codex Desktop 使用的 ~/.agents/skills
EasyEDA Pro（宿主）官方编辑器,需开启「允许外部交互」桌面应用

一句话记牢:升级不是只升 CLI —— CLI、连接器 .eext、Skill 三者要一起升到同一版本, 否则 daemon health 会把落后的连接器标成 stale(connectorVersionOk:false),动作会打不通。

首次安装(5 步)

1. 装 CLI + Skill(一条命令)

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

一键脚本会：

  • 安装/更新 easyeda CLI/daemon 到 PATH;
  • 自动检测已装的 AI 客户端,把 easyeda-agent skill 装到对应目录 —— Codex(~/.codex/skills/easyeda-agent)、Codex Desktop 共享目录(~/.agents/skills/easyeda-agent)、Claude Code(~/.claude/skills/easyeda-agent);
  • 打印连接器 .eext 的下载地址。

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

curl -fsSL https://raw.githubusercontent.com/zhoushoujianwork/easyeda-agent/main/install.sh -o install.sh
EASYEDA_INSTALL_SKILLS=codex,agents,claude bash install.sh  # 指定目标
EASYEDA_INSTALL_SKILLS=none bash install.sh         # 只装 CLI
EASYEDA_SKILL_PRESERVE=1 bash install.sh            # 保留本地内容及旧版本标记
EASYEDA_VERSION='<vX.Y.Z>' bash install.sh          # 锁定发布版，跳过 API 查询

装不上、报 403?脚本要调一次 api.github.com 查 latest release,匿名额度是每 IP 每小时 60 次,公司出口 / NAT / CI 很容易撞满。要么 export GITHUB_TOKEN=<token> (或 GH_TOKEN;已 gh auth login 的话脚本会自动取 gh auth token),要么用 EASYEDA_VERSION=<tag> 直接锁版本绕开 API。

2. 启动 daemon

easyeda daemon start        # 前台阻塞运行,Ctrl-C 退出;建议单开一个终端常驻

daemon 默认固定监听 60832，连接器重试同一端口；不要额外启动多个 daemon。

3. 导入连接器 .eext

从 GitHub Release 下载 easyeda-agent-connector.eext(与 CLI 严格同版),或从立创官方插件市场一键安装(平台可原地自动更新,但版本可能滞后 CLI —— 需严格三要素同版时以 GitHub Release 的 .eext 为准),然后:

EasyEDA Pro → 扩展管理 → 导入扩展 → 选中 .eext 文件

4. 开启「允许外部交互」

EasyEDA Pro → 设置 → 允许外部交互 (Allow external interaction)

不开这一项,连接器的 WebSocket 永远连不到本地 daemon。

5. 在 AI 客户端里用 Skill

/easyeda-agent          # 原理图 + PCB 全流程

支持 MCP 的客户端还可以选择注册仓库内的 stdio 适配层。MCP 是可选调用入口, 不是替代 CLI/daemon 或 Skill 的第五套状态;它仍经过同一套 typed action、审计和 workflow gate。

git clone https://github.com/zhoushoujianwork/easyeda-agent.git
cd easyeda-agent
npm --prefix mcp ci --ignore-scripts
codex mcp add easyeda-agent \
  --env EASYEDA_BIN="$(command -v easyeda)" \
  -- node "$(pwd)/mcp/src/server.mjs"

注册后重启 AI 客户端。可用工具包括连接健康、action 发现、7 个安全 action domain、 电路块和 guarded workflow;MCP 不暴露任意 JavaScript 的 debug.exec_js。

验证三要素是否对齐

easyeda daemon health

关注返回里的 connectorVersionOk:

  • true —— 连接器与 daemon 同版,一切就绪;
  • false —— 连接器落后(常见于升级只升了 CLI 没重导 .eext,或旧窗口没重启);
  • 字段缺失/null —— dev 构建,无法硬比对(正常)。

升级注意事项(务必三要素一起升)

  1. easyeda update —— 升级 CLI 二进制 + Skill 目录(装过一次之后的常规路径): 
    easyeda update            # 下载本平台二进制 → sha256 校验(有 checksums.txt 时) → 原子替换 + 同步 skill
easyeda update --check    # 只看不改:cli / skill / connector 三方版本一次列清
sudo easyeda update       # 二进制装在 /usr/local/bin 等 root 目录时
    升完 daemon 仍在跑旧二进制,要重启 daemon;命令会提示。 开发机上的 dev 构建(git-describe 版本号)默认不覆盖 —— 这是有意的,--force 才强升。 一键脚本仍是首次安装(和重装连接器)的路径: 
    curl -fsSL https://raw.githubusercontent.com/zhoushoujianwork/easyeda-agent/main/install.sh | bash
  2. 重导连接器 .eext —— EasyEDA 按 uuid 去重,光 bump 版本号不够: 先在「已安装」里卸载旧连接器,再导入新 .eext(uuid 不变,原地更新)。 (这步只针对侧载的 GitHub Release .eext;若连接器是从立创插件市场装的,平台会原地自动更新 —— 但市场版本可能滞后 CLI,严格同版仍以 Release .eext 为准。)
  3. 完全退出并重启 EasyEDA —— 重导不会重载已开着的窗口;旧窗口会继续跑旧代码、 和新连接器抢 daemon socket。必须彻底退出 EasyEDA 再打开。
  4. easyeda daemon health 复核 —— connectorVersionOk:true 才算升级到位。

大多数改动其实不需要重导 .eext(daemon 侧的 typed action / CLI 更新无需碰连接器); 只有连接器 manifest / handler 变了才需要重新导入。是否需要,看 Release 说明。

自动帮你做的部分(省去手动)

  • Skill 目录自动同步:daemon start 默认带 --auto-update-skill,启动时会后台 把已存在的 Skill 目录拉齐到运行中的 CLI 发布版本，开发构建不自动写入，并把每一步打进 daemon 日志。客户端目录遵循 CODEX_HOME / CLAUDE_CONFIG_DIR，默认仍为 ~/.codex / ~/.claude。尊重 EASYEDA_SKILL_PRESERVE=1(保留本地改动);关掉用 daemon start --auto-update-skill=false。 手动触发/查看: 
    easyeda skill status      # 各 skill 目录版本 vs 最新 release
easyeda skill sync        # 立即同步到最新(--version 锁版本,--preserve 保留本地改动)
easyeda update --check    # 想连 CLI 二进制和连接器一起看时用这个
  • 连接器落后自动提示:连接器一注册,daemon 就比对版本;落后时打一条可操作日志 (「stale connector: vX < daemon vY — 重导 .eext + 彻底重启 EasyEDA」)。 侧载(GitHub Release)的连接器 .eext 无法被 daemon 静默替换(sideload 无原地自动更新), 所以这里只检测+提示,重导那步仍需你手动做(见上)。若连接器是从 立创插件市场装的, 平台可原地自动更新 —— 但市场版本可能滞后 CLI,严格三要素同版仍以 GitHub Release 的 .eext 为准。

常见卡点速查

症状原因处理
动作全部超时、连不上没开「允许外部交互」设置里打开
不确定谁落后了CLI / skill / 连接器版本不一致easyeda update --check 一次列清三方
connectorVersionOk:false.eext 落后 / 旧窗口没重启重导 .eext + 彻底重启 EasyEDA
重导 .eext 后没生效EasyEDA 按 uuid 去重,旧的没卸载「已安装」里先卸载旧的再导入
easyeda: command not foundPATH 没含安装目录把 /usr/local/bin 加进 ~/.zshrc
registry 安装的 Skill 版本不同registry 审核或同步有延迟用一键脚本,或从同一 Release 下 skills.tar.gz 解压到 skills 目录

给 AI Agent 的推荐引导 Prompt

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

把 easyeda update --check --exit-code 作为当前会话第一条命令。只有 easyeda CLI、
easyeda-agent Skill、运行中 daemon、所有已连接 EDA Agent Connector 都可验证且精确等于
GitHub latest 时继续。否则运行 easyeda update，重启 daemon；Connector 不同版时安装
命令所示同一 GitHub Release 的 easyeda-agent-connector.eext，保存文档并完全退出、重开
EasyEDA。任何组件升级后立即结束当前 Agent 会话并新开会话，从版本检查重新开始。确认
已开启“允许外部交互”，再运行 easyeda health 核对目标工程、页面和版本。

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

延伸阅读:功能清单与路线图 · 架构 · 开发环境与调试手册