hffs6/dsh-easyeda-bridge

dsh-easyeda-bridge

英文： README.en.md

嘉立创EDA（EasyEDA 专业版）桥接插件 — 在 DeepSeek Harness (DSH) 内内置
easyeda-bridge WebSocket 网关，让 DSH 直接驱动用户本机正在运行的嘉立创EDA 专业版窗口。

配套 EDA 侧扩展：run-api-gateway
（即 run-api-gateway_v1.0.5.eext，嘉立创EDA 专业版扩展）。

┌──────────┐  WS(/eda)   ┌──────────────────────────┐  HTTP/WS   ┌──────────────┐
│  DSH      │ ◄────────► │ 本插件（内置 Bridge）     │ ◄────────► │  EasyEDA     │
│  (Agent)  │  4 个工具   │  127.0.0.1:49620-49629   │  自动      │  (Pro Client)│
└──────────┘             └──────────────────────────┘            └──────────────┘

功能

- 协议完全兼容官方 easyeda-api-skill 的 scripts/bridge-server.mjs：EDA 扩展连入
ws://127.0.0.1:/eda → 服务端发 handshake(service=easyeda-bridge) → 扩展
register(windowId) → 服务端下发 execute(id, code) → 扩展执行并回 result/error。
- 双模式自动切换：
- own — 端口区间（默认 49620-49629）内没有桥 → 本进程内自建 HTTP+WS 服务
- adopt — 已有其它桥（如 OpenCode 拉起官方 bridge-server）→ 直接复用其 HTTP API，
避免 EDA 扩展到另一个桥而工具落空；own 模式空置且有外部桥时自动切换（自愈）
- 四个模型工具：
| 工具 | 用途 |
|------|------|
| easyeda_status | 桥/EDA 连接状态、窗口列表、当前文档/图页、页框范围、未连接排查提示 |
| easyeda_windows | 列出已连接窗口；selectWindowId 切换活动窗口 |
| easyeda_device | 查器件：query 关键词搜索（带 limit）/ cNumber 立创 C 编号精确查找，返回名称/库UUID/器件UUID/封装 |
| easyeda_execute | 在目标窗口执行 async (eda) => { … } 代码并回传结果 |
| easyeda_docs | 检索内置官方 API 参考（query 搜索签名 / doc 读全文） |
- 内置官方 API 文档（docs/，vendored from easyeda/easyeda-api-skill，MIT）：
120+ 类、62 枚举、70 接口 + 工程/原理图/PCB 源文件格式 + 扩展开发向导，离线可查。
- 官方 HTTP API 兼容面：GET /health、GET /eda-windows、POST /eda-windows/select、
POST /execute，其它 AI 工具（OpenCode 等）可同时使用同一座桥。

前置条件（EDA 侧）

1. 打开嘉立创EDA 专业版（无需先开工程）
2. 安装 Run API Gateway 扩展（下载/安装见 https://jlc-ext.com/item/oshwhub/run-api-gateway）
3. 扩展管理器中勾选 允许外部交互 与 显示在顶部菜单
4. 若扩展已加载而桥晚于它启动：点击顶部菜单 API Gateway → 重新连接 触发连接

安装到 DSH

运行时注入（免重启，适合开发）

在本插件目录内构建（lib/ 必须是最新）
DSH_CHECKOUT= bash scripts/build.sh
在 DSH 环境内注入本插件目录
dev_inject_plugin

永久安装（重启后仍挂载）

DSH 环境内：写入 profile 的 bundles + link 依赖，并热装载
dev_install_package

插件 cordis.patch.yml 会在装配时插入 easyeda-bridge 行（无配置即可用）。

使用（对 DSH 说）

嘉立创EDA，启动！

DSH 会依次：easyeda_status 确认桥与窗口 → （多窗口时）easyeda_windows 选定 →
easyeda_execute 验证 return await eda.dmt_Project.getCurrentProjectInfo();。

执行代码规则（完整版见插件 systemPrompt 引导）：

- 代码形态 async (eda) => { … }，必须 return（console.log 不回传）；Promise 必须 await
- 运行环境为 EDA 内部浏览器上下文：无 Node API；用 eda.sys_* 替代浏览器 API
- 枚举必须用枚举成员（EPCB_LayerId.TOP），先用 easyeda_docs 查 references/enums/
- 单位：PCB 1 单位 = 1mil（1mm≈39.37）；原理图 1 单位 = 0.01inch（1mm≈3.937）
- 操作前验证文档状态：eda.dmt_Project.getCurrentProjectInfo() +
eda.dmt_SelectControl.getCurrentDocumentInfo()（PCB API 只对活动 PCB 文档有效）
- 改图元用异步模式：const p = await eda.pcb_PrimitiveVia.get([id]); const a = p.toAsync(); a.setState_X(..); a.done()

开发与测试

npm install                 # 安装 ws 等依赖
DSH_CHECKOUT= bash scripts/build.sh
node scripts/mock-eda.mjs   # 端到端协议冒烟（模拟 EDA 扩展：handshake/register/execute/ping + HTTP API + /agent 通道）
node scripts/test-adopt.mjs # adopt 模式测试（模拟“外部已有桥”场景）

文档同步：见 docs/README.md（从 easyeda/easyeda-api-skill 拉取更新）。

许可

插件代码 MIT。内置文档（docs/）来自 easyeda/easyeda-api-skill
（作者 JLCEDA，MIT），归属与署名见 docs/README.md。