easyeda-agent

259Star39Fork12Issue1Watching

把嘉立创 EDA 专业版封装成可被 DSH Agent 调用的 MCP 工具集与 Skill，让模型在 Harness 内驱动原理图与 PCB 自动化。

分类🔌 集成与服务
zhoushoujianworkzhoushoujianwork
·zhoushoujianwork/easyeda-agent.git·jlc-ext.com/item/zhoushoujian/easyeda-agent-connector
语言
Go
License
NOASSERTION
分支
main
agent-skillai-agentclaude-codedsh-plugineasyedaedaelectronicsgolang

安装

$ dsh plugin --profile web add github:zhoushoujianwork/easyeda-agent

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

把嘉立创 EDA 专业版封装成 DSH Agent 可调用的 MCP 工具集和工作流 Skill，让模型在 Harness 内驱动原理图/PCB 自动化（放件、连线、布线、铺铜、DRC、导出 BOM）。注意：本插件只负责把仓库自带的 stdio MCP server 桥接到 DSH、把 Skill 注册进 global layer；真正干活的 Go CLI/daemon 二进制和 EasyEDA 端 .eext 连接器需要先用官方一键脚本另外装上。

核心能力

  • 在 DSH profile 里激活一个 easyeda 命名空间的 MCP 桥接，模型侧可看到 easyeda_health / easyeda_actions / easyeda_schematic / easyeda_pcb / easyeda_board / easyeda_document / easyeda_project / easyeda_artifact / easyeda_system / easyeda_blocks / easyeda_workflow 等工具
  • 注册 skills/easyeda-agent/ 下的 Agent Skill（含 S0–S6 原理图流程、P0–P10 PCB 流程、门禁规范、参考数据、Python/JS 校验脚本），并通过 providerName: easyeda 的隔离实例避免和官方 bundle 的 skill-filesystem 冲突
  • 把 Go CLI 的全部 typed action（含 schematic 元件放置/布线/分区、pcb 自动布局/铺铜/4 层电源平面、board 绑定、artifact 导出、system notify toast）以 easyeda_<domain> MCP 工具形式转发给模型，每条 action 自带 Mutates 标记以提示 read-only/destructive 语义
  • 提供 easyeda_actions 自描述工具：模型可按 domain/关键字/是否 mutate 三维度筛选动作目录，取代逐个查 README
  • 通过 easyeda_workflow 暴露持久化的项目设计流程状态机（init/status/advance/confirm/reset），让 S0–S6 + P0–P10 的门禁确认可被 Agent 落盘而非只在对话里
  • 通过 easyeda_blocks 暴露内嵌的电路块库（CH340 USB 串口、ESP32 自动下载、按键去抖等成熟外围子电路），Agent 放外围前先查块、命中即复用拓扑

技术实现

  • 语言: TypeScript（MCP server）+ Go（CLI/daemon，不在本包内）+ Shell（cordis.patch.yml 声明式注入）
  • 关键依赖: @deepseek-ai/dsh-mcp-client（宿主自带的 MCP 桥接插件，本包只声明要激活它）、@deepseek-ai/dsh-skill-filesystem（宿主自带的 skill-filesystem，本包声明一个隔离实例）、@modelcontextprotocol/sdk 1.30.0（stdio server 实现）、本地 easyeda Go 二进制（MCP server 通过 child_process 调起，路径由 EASYEDA_BIN 环境变量决定）
  • 架构模式: 纯声明式 cordis bundle patch——cordis.patch.yml 里两条 insert 规则分别在 apply 阶段拉起 MCP 桥接和独立 skill-filesystem；运行时无任何自定义 JS/TS 代码，桥接委托给宿主 in-box 插件，沙箱执行委托给 Go daemon。MCP server 端采用 stdio transport，与 EasyEDA 端的 WebSocket 通信全在 daemon 里完成
  • 入口文件: cordis.patch.yml（DSH 集成入口）、mcp/src/server.mjs（stdio MCP server 实现）、mcp/src/core.mjs（CLI 调用 + 工具定义）；Go CLI 入口在 cmd/easyeda/、EasyEDA 端 .eext 在 extension/，均不属于本 DSH 插件加载范围

适用场景

当用户让 DSH 模型做"基于 EasyEDA Pro 的电路板设计自动化"时使用——典型场景是用一句话需求生成原理图、把已布线原理图同步到 PCB、走 DRC 检查并导出 BOM/网表，或者在 EasyEDA 已打开时让模型直接在里面放件/布线/铺铜。本插件主要面向硬件事主理人、EDA 工程师、自动化集成方；不适合"零 EasyEDA 经验只是想跑个 hello world"的纯 DSH 用户，因为前置依赖（CLI 二进制 + .eext + EasyEDA 端开关）较多。

前置依赖与兼容性

依赖最低版本说明
DSH 宿主未在本包声明本包在 cordis.patch.yml 引用 @deepseek-ai/dsh-mcp-client 与 @deepseek-ai/dsh-skill-filesystem，依赖宿主 DSH 把这两个 in-box 插件打进安装目录；版本由宿主编译期决定，本包未写 peerDependencies
Node.js>= 20.17.0package.json#engines 与 mcp/package.json#engines 均为 >=20.17.0，低于此版本 MCP server 启动时 Node 自身会拒绝
easyeda Go CLI/daemon与本插件同主次版本（如本包 0.25.x 配 CLI 0.25.x）由官方一键脚本（curl -fsSL https://raw.githubusercontent.com/zhoushoujianwork/easyeda-agent/main/install.sh | sh）安装；MCP 工具链依赖它实际执行 typed action，没有它所有工具只能看到 NO_CONNECTOR
EasyEDA Agent Connector .eext与 CLI 严格同版本需在 EasyEDA Pro 的扩展中心导入 .eext（脚本会打印下载 URL 或在立创插件市场搜「EDA Agent Connector」一键装）；侧载版无原地自动升级，需手动卸载旧版再装新版；版本不一致时 daemon health 会标 stale
EasyEDA Proeda ~3.2.0（extension.json#engines）必须在打开的工程里开启「允许外部交互」，否则连接器的 WebSocket 永远连不上本地 daemon
平台—Makefile 交叉编译 darwin/amd64+arm64、linux/amd64+arm64、windows/amd64 五档；本 DSH 插件本身是平台无关的纯 JS/JSON/YAML，无原生模块依赖

安装方式

dsh plugin --profile web add github:zhoushoujianwork/easyeda-agent

配置项

配置类型说明默认值
EASYEDA_BIN（环境变量）字符串覆盖 MCP server 调起的 easyeda 二进制路径；留空则在 PATH 上找easyeda（PATH 查找）
easyeda-mcp 的 serverName字符串（声明式）MCP 工具命名空间前缀；模型看到的工具名形如 mcp__easyeda__easyeda_schematiceasyeda
easyeda-skill-fs 的 providerName字符串（声明式）隔离实例的命名空间标识，避免和官方 bundle 的 skill-filesystem 冲突easyeda
easyeda-skill-fs 的 customSkillDirs字符串数组（声明式）仅扫描本包内 skills/easyeda-agent/，不混入宿主默认 skill 目录node_modules/easyeda-agent-dsh/skills/easyeda-agent（相对 profile 目录）
includeDefaultRoots布尔（声明式）是否同时扫描宿主默认 skill 目录；本包设为 false 以避免和官方预设冲突false

本包没有可由用户在 profile 配置文件里直接改的运行时 schema——所有调整都通过上述声明式字段或 EASYEDA_BIN 环境变量完成。如需打开更多开关（如自定义 MCP 工具白名单），需要自己 fork mcp/src/server.mjs 或在 host 里改 in-box 的 @deepseek-ai/dsh-mcp-client 行为。

常见问题

Q: 安装命令运行成功了，但 mcp__easyeda__easyeda_* 工具列表是空的？

A: 检查三件事——easyeda daemon 是否在跑（easyeda health 应返回 status: found）、EasyEDA 是否打开了带「允许外部交互」的工程、连接器 .eext 是否真的加载进 EasyEDA（菜单栏出现「EDA Agent」分组即视为已加载）。MCP 这边依赖本地 daemon 与 EasyEDA 窗口的双向连通，缺一就会让所有 typed action 收到 NO_CONNECTOR。

Q: 报「STALE_READ」/`动作在 PCB mutation 后读不到最新数据」之类的错误？

A: 这是 daemon 的硬性约束：任何 pcb.* mutation 之后必须先跑 easyeda doc reload 再读/判/DRC；不 reload 就直接读，daemon 直接拒并告诉你下一步该跑什么。同网 Connection Error 暴增通常要先 pour-rebuild，而不是真断线。

Q: easyeda update --check 报告 connector 落后但 update 不升级它？

A: 侧载的 .eext 不在自动升级范围内。easyeda update 会打印落后的连接器版本和重导地址，需要人在 EasyEDA 扩展中心手动卸载旧版再导入新版；如果装的是立创插件市场版，市场会自动原地升级但版本可能滞后 CLI 几个 minor。

Q: DSH web profile 下提示 skill 冲突/加载失败？

A: cordis.patch.yml 故意声明了一个 includeDefaultRoots: false 的隔离 skill-filesystem 实例来避免冲突；如果仍然冲突，多半是有人手动在同一个 profile 的 cordis.patch.yml 里加了第二个 easyeda-skill-fs row 或改了 providerName 撞名。dump 配置后删掉多余 row 即可。

Q: 离线/无外网环境下能跑哪些工具？

A: easyeda_blocks（查询内置电路块库）、easyeda_actions（读取 action 目录的离线 JSON）、easyeda_health（查本地 daemon 状态）这三个不依赖 EasyEDA 在线或外网；其余 easyeda_schematic / easyeda_pcb 等需要 EasyEDA 窗口打开，部分动作还会按需查 LCSC 立创库。

上手难度

进阶 — 用户需要理解 DSH profile/cordis 分层（安装本插件只是第一步），还要自己装 Go CLI 二进制、导入 .eext 连接器、打开 EasyEDA「允许外部交互」开关；任一环节缺失都会让 MCP 工具列表"装着但调不通"。优势是只要四件套齐了，模型就可以用一整套类型化动作驱动 EasyEDA，并配合持久化 workflow 状态机跑门禁流程。

已知问题与限制

  • internal/daemon/connect.go:19-21 标注了一处待办：daemon 接受 WebSocket 时临时跳过了 origin 校验（InsecureSkipVerify: true），等嘉立创官方公开扩展 origin 后再补精确白名单；当前 daemon 仅绑定 127.0.0.1，风险面有限
  • cordis.patch.yml 里 MCP 桥接走 dsh-mcp-client、skill 注册走 dsh-skill-filesystem，都是 DSH 宿主的 in-box 插件——若宿主版本过老/裁剪过这两项，本包激活会失败
  • 本包不写任何用户文件、不创建任何持久状态；卸载本包不会清掉 Go CLI、.eext、EasyEDA 端开关
  • MCP server 刻意不把 debug.exec_js 域暴露给模型，限制了"任意 JavaScript 执行"的逃生口；这同时意味着部分尚未类型化的实验性动作（裸 JS 调用）只能由人在终端里手动跑 easyeda call debug.exec_js
  • EASYEDA_BIN 环境变量被多个进程共享时（如同一 profile 起多个 agent）会出现竞争；通常让所有 agent 共用同一份 daemon 即可规避
  • 三方版本（CLI / Skill / 连接器）必须同版本对齐，否则 easyeda daemon health 会把连接器标 stale；侧载版 .eext 无原地自动升级，需要人手动维护
  • easyeda update --check --exit-code 在 CI 里退出码为 10 可被 gate，但仅能反映 CLI/skill/连接器的版本对齐状态，不验证 EasyEDA 端是否真正启用、daemon 是否在跑
  • 本包当前 package.json#version 是 0.25.1，而仓库内 extension/extension.json#version 是 1.1.0——CLAUDE.md 注明 make release 流程会把两者统一，但当前提交状态尚未同步；遇到"easyeda health 标 stale"时可优先以 CLI 侧版本为准
  • 受嘉立创官方 eda.* API 限制：迷宫档自动布线、交互式布线 UX、受控阻抗 Z0、teardrop、无编程 undo、增量 import_changes 等能力无法用 typed action 表达，只能走外部 Freerouting（DSN 往返）或手动 UI 兜底
返回插件目录