# easyeda-agent

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

## Metadata

- Author: [@zhoushoujianwork](https://github.com/zhoushoujianwork)
- Repo: <https://github.com/zhoushoujianwork/easyeda-agent.git>
- GitHub: [zhoushoujianwork/easyeda-agent](https://github.com/zhoushoujianwork/easyeda-agent)
- Stars: 259
- Language: Go
- License: [NOASSERTION](https://spdx.org/licenses/NOASSERTION.html)
- Homepage: <https://jlc-ext.com/item/zhoushoujian/easyeda-agent-connector>
- Topics: `agent-skill`, `ai-agent`, `claude-code`, `dsh-plugin`, `easyeda`, `eda`, `electronics`, `golang`, `hardware-design`, `jlceda`, `lceda`, `mcp`, `mcp-server`, `pcb`, `pcb-design`, `schematic`
- Forks: 39
- Open Issues: 12
- Last push: 2026-08-20T16:34:11.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
把嘉立创 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.0 | `package.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 Pro | eda ~3.2.0（`extension.json#engines`） | 必须在打开的工程里开启「允许外部交互」，否则连接器的 WebSocket 永远连不上本地 daemon |
| 平台 | — | `Makefile` 交叉编译 darwin/amd64+arm64、linux/amd64+arm64、windows/amd64 五档；本 DSH 插件本身是平台无关的纯 JS/JSON/YAML，无原生模块依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:zhoushoujianwork/easyeda-agent
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `EASYEDA_BIN`（环境变量） | 字符串 | 覆盖 MCP server 调起的 `easyeda` 二进制路径；留空则在 PATH 上找 | `easyeda`（PATH 查找） |
| `easyeda-mcp` 的 `serverName` | 字符串（声明式） | MCP 工具命名空间前缀；模型看到的工具名形如 `mcp__easyeda__easyeda_schematic` | `easyeda` |
| `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 兜底

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [easyeda-agent](https://deepseek-plugin.org/plugins/zhoushoujianwork/easyeda-agent)
Wiki generated by AI (model: `MiniMax-M3`)