dsh-easyeda-bridge
English: 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:<port>/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 侧）
- 打开嘉立创EDA 专业版（无需先开工程）
- 安装 Run API Gateway 扩展（下载/安装见 https://jlc-ext.com/item/oshwhub/run-api-gateway）
- 扩展管理器中勾选 允许外部交互 与 显示在顶部菜单
- 若扩展已加载而桥晚于它启动：点击顶部菜单 API Gateway → 重新连接 触发连接
安装到 DSH
运行时注入（免重启，适合开发）
# 在本插件目录内构建（lib/ 必须是最新）
DSH_CHECKOUT=<dsh checkout> bash scripts/build.sh
# 在 DSH 环境内注入本插件目录
dev_inject_plugin <path/to/dsh-easyeda-bridge>
永久安装（重启后仍挂载）
# DSH 环境内：写入 profile 的 bundles + link 依赖，并热装载
dev_install_package <path/to/dsh-easyeda-bridge>
插件 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=<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。
