@windypro-rourou/dsh-eda 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# dsh-lichuang-eda（嘉立创 EDA 助手）
+
+面向 0 基础开发者，在 DSH Web GUI 里自动生成**嘉立创 EDA（专业版/标准版）原理图 / PCB 草图**的插件。
+
+> **定位 = 平台层**：本插件提供官方桥的 **一键安装 / 启动 / 连接 / 状态**、执行**官方 `eda.*` API** 的双手（`eda_exec` + 校验工具）、以及**离线兜底**（`eda_generate_schematic_json`）。
+> **生成电路图 = 在对话里进行（skill 式直觉）**：用户说"嘉立创EDA，启动！帮我画一个…"→ agent 用 `eda_exec` 逐步执行官方 `eda.*` API 在用户的**云端画板**实时画。官方文档/样例已随桥 vendored 到 `~/.dsh/eda/bridge/`（`docs/`、`user-guide/`、`guide/`、`format/` 目录），agent 先 `read` 再调用。
+> 仅使用**官方栈**：官方桥 `easyeda/easyeda-api-skill` + 官方扩展 **Run API Gateway** + 官方 API（prodocs.easyeda.com）。**无任何第三方后端**。
+
+## 目录结构
+
+```
+plugin/
+├── package.json          # 包清单：dsh.bundle.patch / dsh.client / exports（. 和 ./client）
+├── cordis.patch.yml      # bundle patch：向 web profile 名册插入插件行（id: eda）
+├── lib/
+│   ├── index.js          # 宿主端：apply() 注册 10 个 agent 工具 + 5 条路由 + 系统提示
+│   ├── backend.js        # 官方桥适配层：spawn bridge-server.mjs + 端口发现(49620-49629) + /execute
+│   └── client.js         # 浏览器端（React，无构建步骤）：侧边栏入口 + 工作台面板
+├── installer.js          # 一键安装官方桥：下载官方源码包 → 解压 → 离线 vendoring ws（npm 兜底）→ 验证
+├── selfcheck.mjs         # 自检脚本：stub ctx 挂载插件，断言 DSH 四表面（见「测试 / 自检」）
+├── fixtures/
+│   └── mock-bridge.mjs   # mock 官方桥（HTTP/WS），供 backend 单测
+├── test/
+│   ├── status.test.mjs   # 状态工具/路由
+│   ├── generate.test.mjs # 离线生成端到端 + 桥接门控
+│   └── backend.test.mjs  # EdaBackend 官方桥客户端 + installer
+└── README.md
+```
+
+> 依赖仓库根的 `src/`（生成器/校验/翻译层）与 `docs/`（调研/引导文档）。**独立打包发布时需把 `src/` 一并纳入包**（见「不确定/未验证」#6）。
+
+## 已注册的 agent 工具（13 个）
+
+| 工具 | 用途 | 可用性 |
+|---|---|---|
+| `eda_status` | 插件/官方桥状态（装没装 / 端口 / 是否就绪） | ✅ |
+| `eda_template_list` | 模板卡目录（含 supported 标记，如实标注） | ✅ |
+| `eda_translate_request` | 中文需求 → 结构化设计草稿（只翻译不生成） | ✅ |
+| `eda_generate_schematic_json` | **离线兜底**：需求/模板 → 可导入嘉立创 EDA 标准版的原理图 JSON + 结构/连通性校验，产物写入 `~/.dsh/eda/output/` | ✅ |
+| `eda_bridge_install` | **一键安装官方桥**（下载官方 easyeda-api-skill → 解压 → 离线 vendoring ws（npm 兜底）→ 验证 bridge-server.mjs） | ✅ 纯函数已测；网络安装真机待验 |
+| `eda_backend_connect` | 启动/连接官方桥（bridge-server.mjs，端口 49620-49629 + health 探测） | 🧪 mock 已测，真机待验 |
+| `eda_exec` | **云端实时生成的双手**：执行任意官方 `eda.*` 代码（需已连接）；自动记录每步新建的图元（可撤回） | 🧪 桥接门控，真机待验 |
+| `eda_pick_spot` | **框内定位**：读页面尺寸(A4≈1170×825,10mil)+已有图元 → 返回互不冲突的框内网格空位（边距80/网格100/间距150）；放元件前必调 | ✅ 算法 5 例单测；桥读 mock/真机待验 |
+| `eda_capabilities` | **能力清单**：官方 eda.* API 结构化能力目录（域/方法/用法/坑/实测片段）——agent 规划时主动查询后调用 | ✅ 内置数据，注册已测 |
+| `eda_snapshot` | **紧急保存**：画板现场（`.epro2` 专业版完整恢复 + 预览 SVG + 网表/BOM）+ agent 动作日志 → `~/.dsh/eda/snapshots/`；每步独立降级，断连也能留档步骤 | 🧪 mock 已测（11 例）+ 真机 0 降级 |
+| `eda_sch_drc` | 对当前画板跑原理图 DRC（官方 `eda.sch_Drc.check(true,false,true)`——**verbose 重载**） | 🧪 需已连接 |
+| `eda_get_netlist` | 导出当前网表（**File.text() 修正**：直接返回 File 会序列化 `{}`） | 🧪 需已连接 |
+| `eda_get_bom` | 导出 BOM（**二进制 xlsx 走 base64**，返回 名称/大小 摘要） | 🧪 需已连接 |
+
+**生命周期**：插件加载时若检测到官方桥已安装，**自动启动并自动连接**（无需人工）；面板实时显示 装没装 / 端口 / 是否就绪。
+
+**面板 = 平台仪表盘/监看器**（生成发生在对话里，agent 通过 `eda_exec` 驱动官方 `eda.*` API）：
+- 顶部紧凑连接卡 + 可折叠连接教程（默认收起）；已连接时显示「💬 去对话里说：嘉立创EDA，启动！」CTA（点击复制）。
+- 主体 **「Agent 正在使用官方 API」记录式时间线**（参考 DSH 会话轨迹，3s 轮询 `GET /activity`）：
+  - **持久化**：每一步（序号/时间/动作/耗时/结果/会话）落盘 `~/.dsh/eda/activity.jsonl`——重启不空、历史可回溯；
+  - **撤回**：每个 `eda_exec` 步骤自动记录新建/删除的图元 id（前后快照 diff），面板「撤回」按钮可一键删除该步新建图元（删除的不可恢复，如实提示）；
+  - **清空记录**：卡片头部一键清空（内存+磁盘）；
+  - 点击条目展开完整代码/结果/撤回数据；pending 态「执行中…」；长任务/短任务均实时滚入；
+  - 空态展示"你可以让 agent 做…"能力速览（不空白）。
+- **按会话隔离**：每条活动记录携带调用方会话 id（工具执行上下文 `exec.agent.id`）；面板默认跟随最新会话，多会话时可下拉切换；无会话的（面板按钮点击）归为「平台操作」。
+- 底部 **「紧急保存」**：一键把画板现场抓到本地（`.epro2` 专业版完整恢复 + 预览 SVG 通用可看 + 网表/BOM 数据 + agent 动作日志 → `~/.dsh/eda/snapshots/`）——云端没同步上也能找回最后工程；画板未连接时仍保存动作日志留档。v0 离线生成（标准版 JSON，仅电阻/LED）保留为对话内工具 `eda_generate_schematic_json`，不再占用面板。
+
+**兼容性边界（如实）**：官方 API 仅能导出 epro/epro2（专业版原生）与 PDF/PNG/SVG，**没有「标准版 v6 JSON」导出通道**；因此紧急保存 = 专业版完整恢复 + 通用预览 + 数据文件，标准版可编辑需走离线重建（简单电路）。
+
+**实战经验（真机固化，详见 `docs/eda-conversation-skill.md` 附四~附六）**：框内定位规则（10mil/A4≈1170×825/边距80/网格100/间距150，先 `eda_pick_spot` 再放件）；网表/BOM/DRC 的正确用法（`File.text()` / base64 / `check(true,false,true)`）；已知官方缺陷（`importChanges`、`setNetlist`、`getNetlist('EasyEDA')`、板框无 API、`getAll` 间歇失败）。
+
+**会话说明**：`/activity` 返回 `{ activities, currentSid, sessions }`；`?sid=` 固定到某会话，缺省跟随最新。
+
+## 路由
+
+- `GET /api/dsh-eda/status` — 状态（loopback-only）
+- `GET /api/dsh-eda/activity` — 记录式时间线（`?sid=` 可固定会话；loopback-only）
+- `POST /api/dsh-eda/activity/clear` — 清空时间线（内存+磁盘）
+- `POST /api/dsh-eda/activity/revoke?id=N` — 撤回步骤 N（删除该步新建图元）
+- `GET /api/dsh-eda/templates` — 模板目录
+- `POST /api/dsh-eda/bridge` — 启动/复用官方桥
+- `POST /api/dsh-eda/install` — 一键安装官方桥
+- `POST /api/dsh-eda/generate` — 离线生成（`{ description?, template? }` → 结果 JSON）
+- `POST /api/dsh-eda/snapshot` — 紧急保存（画板现场 + 动作日志 → `~/.dsh/eda/snapshots/`）
+
+## 测试 / 自检
+
+```bash
+# 前置：@deepseek-ai/dsh-tools 可解析（工作区已有 junction，缺失时重建：
+#   mklink /J F:\dsh-lichuang\node_modules\@deepseek-ai C:\Users\35081\.dsh\profiles\node_modules\@deepseek-ai ）
+# 本机 npm.ps1 被 PowerShell ExecutionPolicy 禁用时，用 npm.cmd：
+#   C:\Program Files\nodejs\npm.cmd run test:all
+
+# 自检脚本（stub ctx，断言四表面）
+node plugin/selfcheck.mjs
+
+# 插件单元测试（沙箱受限用 --experimental-test-isolation=none；普通终端可直接跑）
+node --experimental-test-isolation=none --test "plugin/test/*.test.mjs"
+
+# 生成器单元测试（14 例）
+node --test --experimental-test-isolation=none src/json-gen.test.js
+
+# v6 样本校验（62 项结构 + 13 项工程包装/连通）
+node src/validate.mjs
+node src/validate2.mjs
+
+# 一键全部门禁（根目录）
+npm run test:all
+```
+
+**当前实测通过**：插件 **27/27**、生成器 **14/14**、自检 **OK**、v6 样本 **62/62 + 13/13**，全部 0 失败。
+
+覆盖：`eda_status` 严格 schema/render、路由 200/405、`provide`/section；官方桥客户端（端口发现/health/`/execute`/`sch.drc` 等动作）；离线生成端到端（中文需求 → JSON 结构+连通性通过、不识别的需求报错、桥接门控报错）；installer（官方仓库/市场地址、`~/.dsh/eda/bridge` 路径、幂等安装标志）；生成器 14 例（结构 lint、sheet 级网表自检、design 级连通性、故意做坏的 3 种电路必须报错、main 产物可复现）。
+
+## 如何在 DSH 里加载
+
+参考 dsh-logcat（`~/.dsh/profiles/web` 即本机 web profile），三选一、**不要同时用**：
+
+```bash
+# 方式一：本地路径（bundle 层）
+dsh plugin --profile web add link:F:\dsh-lichuang\plugin
+# 方式二：源码本地链接（profile node_modules）+ 在 profile 的 cordis.patch.yml 追加：
+#   - insert:
+#       - id: eda
+#         name: '@dsh-lichuang/dsh-eda'
+# 方式三：发布 npm 后
+dsh plugin --profile web add @dsh-lichuang/dsh-eda
+```
+
+装完后**重启 GUI** 生效。
+
+## 验证清单（当前实测状态）
+
+- [x] `node plugin/selfcheck.mjs`（OK）
+- [x] `node --test ... plugin/test/*.test.mjs`（27 pass，0 fail）
+- [x] `node --test ... src/json-gen.test.js`（14 pass）
+- [x] `node src/validate.mjs`（62/62）· `node src/validate2.mjs`（13/13）
+- [x] `node --check plugin/lib/{index,client,backend}.js`（语法通过）
+- [x] v6 真实导出样本逐字段校验通过（`docs/ref/SCH_ESP32-PICO-D4_smart_watch_2023-09-02.json`）
+- [ ] `dsh plugin --profile web add link:...` 实测 + GUI 重启后侧边栏出现「嘉立创 EDA」入口
+- [ ] 生成的标准版 JSON 在**真实嘉立创 EDA 标准版**里导入（无报错）
+- [ ] **真机（云端实时端到端）**：登录浏览器打开专业版画板 → 装官方扩展 Run API Gateway → `eda_backend_connect` 启动/连接官方桥 → **扩展连桥后 `eda_status.connected` 为 `true`** → `eda_exec` 放元件/连线/网络标签 → `eda_sch_drc`/`eda_get_netlist`/`eda_get_bom`
+
+## 不确定 / 未验证（诚实标注）
+
+1. **云端实时端到端（最重要）**：官方桥（bridge-server.mjs）与官方扩展 Run API Gateway 的**真机联通**未验证。诚实做法：扩展在编辑器连上桥后，`eda_status` 返回 `connected:true` 即为联通信号（本插件据此对外宣称"就绪"）。在此之前，`eda_exec`/`eda_sch_drc`/`eda_get_netlist`/`eda_get_bom` 会在未连接时返回明确门控错误，不会伪造结果。
+2. **「能被嘉立创 EDA 标准版无报错导入」**：生成物与真实 v6 导出样本逐键同构、结构/连通性全自动断言通过，但**未在真实编辑器实测导入**（无账号/编辑器）。官方「EasyEDA 源文件对话框粘贴 Apply」是最低成本自检路径。
+3. **官方桥的网络安装**：`eda_bridge_install` 的下载/解压/装依赖逻辑已测（`isBridgeInstalled`/路径/幂等/离线 vendoring ws），但**真实下载官方源码包**需联网，本机待真机/网络可用时验证。
+4. **`dsh plugin --profile web add link:` 语法 / client bundle 装载 / `inject=["slots"]`**：照抄 logcat，未在本机实测。
+5. **v0 离线生成器符号**：仅支持 **电阻 / LED**；模板卡里标 ⏳ 的是暂不支持，不会编造。
+6. **打包边界**：`lib/index.js` 以相对路径 `../../src/...` 引入生成器/校验/翻译层（monorepo 布局）。独立发布需将 `src/` 纳入包或改为打包构建。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-lichuang-eda bundle patch: inserts the eda plugin row into the web
+# profile roster. Applied as a profile bundle layer over dsh-base; the row is
+# a bare plugin by package name — the node half (exports ".") runs in the
+# host process (/api/dsh-eda routes, agent tools, system-prompt section), and
+# the `dsh.client` declaration in package.json makes the browser half
+# (exports "./client", served at /plugins/eda/client.js) load in the web GUI.
+- insert:
+    - id: eda
+      name: '@dsh-lichuang/dsh-eda'

package/lib/activity.js

@@ -0,0 +1,144 @@
+/**
+ * dsh-lichuang-eda — 活动日志（记录式时间线）。
+ *
+ * 参考 DSH 会话轨迹：每一步 = 一条记录（序号/时间/动作/耗时/结果/会话），
+ * 持久化到 ~/.dsh/eda/activity.jsonl（重启面板不空、历史可回溯）；
+ * 每步可携带 revoke 数据（该步创建的图元 id），实现"撤回上一步"。
+ *
+ * 性能：内存 ring buffer（cap）+ 串行落盘（写全量 JSONL，200 条为上限）。
+ */
+import { promises as fsp, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const ACTIVITY_CAP = 200
+export function defaultActivityFile() {
+  return join(homedir(), '.dsh', 'eda', 'activity.jsonl')
+}
+
+export class ActivityLog {
+  constructor({ file = defaultActivityFile(), cap = ACTIVITY_CAP } = {}) {
+    this.file = file
+    this.cap = cap
+    this.entries = []
+    this.seq = 0
+    this._writeChain = Promise.resolve()
+  }
+
+  /** Synchronous load (apply-time — the log is readable instantly). */
+  loadSync() {
+    try {
+      const text = readFileSync(this.file, 'utf8')
+      const lines = text.split('\n').filter((l) => l.trim() !== '')
+      const parsed = []
+      for (const line of lines) {
+        try {
+          const e = JSON.parse(line)
+          if (e && typeof e.id === 'number') parsed.push(e)
+        } catch { /* skip corrupt line */ }
+      }
+      this.entries = parsed.slice(-this.cap)
+      this.seq = this.entries.reduce((m, e) => Math.max(m, e.id), 0)
+    } catch { /* first run / missing file */ }
+    return this
+  }
+
+  /** Asynchronous load (still available for tests/tools). */
+  async load() {
+    try {
+      const text = await fsp.readFile(this.file, 'utf8')
+      const lines = text.split('\n').filter((l) => l.trim() !== '')
+      const parsed = []
+      for (const line of lines) {
+        try {
+          const e = JSON.parse(line)
+          if (e && typeof e.id === 'number') parsed.push(e)
+        } catch { /* skip corrupt line */ }
+      }
+      this.entries = parsed.slice(-this.cap)
+      this.seq = this.entries.reduce((m, e) => Math.max(m, e.id), 0)
+    } catch { /* first run / missing file */ }
+    return this
+  }
+
+  /** Append one entry; fire-and-forget persist (serialized). */
+  push(entry) {
+    const id = ++this.seq
+    const e = {
+      id,
+      ts: new Date().toISOString(),
+      status: entry.status ?? 'done',
+      sid: entry.sid ?? '',
+      ...entry,
+      error: String(entry.error ?? '').slice(0, 4000),
+      code: String(entry.code ?? '').slice(0, 4000),
+      result: String(entry.result ?? '').slice(0, 4000),
+      durationMs: entry.durationMs ?? 0,
+    }
+    this.entries.push(e)
+    this._trim()
+    void this._persist()
+    return id
+  }
+
+  /** Patch an entry in place (pending → done/error). */
+  update(id, patch) {
+    const e = this.entries.find((x) => x.id === id)
+    if (!e) return
+    if (patch.status !== undefined) e.status = patch.status
+    if (patch.ok !== undefined) e.ok = patch.ok
+    if (patch.action !== undefined) e.action = patch.action
+    if (patch.result !== undefined) e.result = String(patch.result ?? '').slice(0, 4000)
+    if (patch.error !== undefined) e.error = String(patch.error ?? '').slice(0, 4000)
+    if (patch.durationMs !== undefined) e.durationMs = patch.durationMs
+    void this._persist()
+  }
+
+  get(id) {
+    return this.entries.find((x) => x.id === id)
+  }
+
+  /** Clear everything (memory + disk). */
+  async clear() {
+    this.entries = []
+    await this._writeChain.catch(() => {}) // let queued writes settle first
+    try { await fsp.writeFile(this.file, '', 'utf8') } catch { /* best-effort */ }
+  }
+
+  /**
+   * Feed for the panel: newest-first entries (optionally pinned to one
+   * session via `sid`), plus a session summary.
+   */
+  feed({ sid = '', limit = 50 } = {}) {
+    const list = this.entries.slice().reverse().slice(0, limit)
+    const sessions = []
+    const seen = new Set()
+    for (const a of list) {
+      const key = a.sid || '(platform)'
+      const existing = sessions.find((s) => (s.sid || '(platform)') === key)
+      if (existing !== undefined) existing.count += 1
+      else sessions.push({ sid: a.sid || '', label: a.sid ? a.sid.slice(0, 8) + '…' : '平台操作', count: 1, lastTs: a.ts })
+    }
+    const wantSid = sid !== '' ? sid : (list[0]?.sid ?? '')
+    return {
+      currentSid: wantSid,
+      sessions,
+      activities: wantSid === '' ? list : list.filter((a) => a.sid === wantSid),
+    }
+  }
+
+  _trim() {
+    if (this.entries.length > this.cap) this.entries.splice(0, this.entries.length - this.cap)
+  }
+
+  _persist() {
+    const snapshot = this.entries.map((e) => JSON.stringify(e)).join('\n') + '\n'
+    this._writeChain = this._writeChain.then(async () => {
+      try {
+        await fsp.mkdir(dirname(this.file), { recursive: true })
+        await fsp.writeFile(this.file, snapshot, 'utf8')
+      } catch { /* disk write is best-effort */ }
+    }).catch(() => {})
+    return this._writeChain
+  }
+}

package/lib/backend.js

@@ -0,0 +1,240 @@
+/**
+ * dsh-lichuang-eda — EDA backend adapter (OFFICIAL STACK ONLY).
+ *
+ * Based entirely on the official 嘉立创EDA(专业版) extension ecosystem:
+ *
+ *   [EasyEDA Pro 窗口（官方扩展 Run API Gateway，已开「允许外部交互」）]
+ *        │  WS 客户端连出（自动扫描端口 49620-49629 + 握手 easyeda-bridge）
+ *        ▼
+ *   [官方 Bridge Server（easyeda/easyeda-api-skill 的 scripts/bridge-server.mjs）]
+ *        │  HTTP: GET /health · POST /execute {"code": "return await eda.xxx()"}
+ *        ▼
+ *   [DSH 插件 dsh-lichuang-eda]（本文件：spawn/health/execute）
+ *
+ * Sources (all official, verified in-repo 2026-08):
+ *   - easyeda/easyeda-api-skill      (Skill `easyeda-api` v1.1.28, MIT, author JLCEDA)
+ *   - easyeda/eext-run-api-gateway   (扩展 Run API Gateway, jlc-ext.com/item/oshwhub/run-api-gateway)
+ *   - prodocs.easyeda.com/cn/api/    (官方 API 参考: SCH_Drc/SCH_Netlist/SCH_ManufactureData/…)
+ *
+ * No third-party backend (easyeda-agent / jlcmcp / easyeda-mcp-pro) is used here.
+ */
+
+import { spawn } from 'node:child_process'
+
+export const BRIDGE_PORTS = Array.from({ length: 10 }, (_, i) => 49620 + i)
+export const BRIDGE_SERVICE = 'easyeda-bridge'
+
+export const STATE = {
+  idle: 'idle',
+  starting: 'starting',
+  ready: 'ready',
+  connected: 'connected',
+  error: 'error',
+}
+
+/** Official API snippets per action id (prodocs.easyeda.com/cn/api/).
+ *  Notes: DRC must use the verbose overload to GET the error list (the bare
+ *  `check()` returns only boolean); netlist is a File whose bridge JSON
+ *  serialization is `{}`, so read `f.text()`; BOM is a BINARY xlsx File, so
+ *  it is returned as base64 (`{name,size,b64}`). */
+export const OFFICIAL_CODES = {
+  'sch.drc': 'return await eda.sch_Drc.check(true, false, true);',
+  'sch.netlist': `return await (async () => { const f = await eda.sch_ManufactureData.getNetlistFile(); return f ? await f.text() : null; })();`,
+  'sch.bom': `return await (async () => { const f = await eda.sch_ManufactureData.getBomFile(); if (!f) return null; const bytes = new Uint8Array(await f.arrayBuffer()); let bin = ''; for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000)); return { name: f.name, size: f.size, b64: btoa(bin) }; })();`,
+  'pcb.drc': 'return await eda.pcb_Drc.check(true, false, true);',
+  'project.info': 'return await eda.dmt_Project.getCurrentProjectInfo();',
+}
+
+async function httpJson(method, url, body, timeoutMs = 15000) {
+  const res = await fetch(url, {
+    method,
+    headers: { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  const text = await res.text()
+  let parsed = null
+  try { parsed = JSON.parse(text) } catch { parsed = null }
+  return { ok: res.ok, status: res.status, text, json: parsed }
+}
+
+/** Scan the official port range (or an injected set) for a live bridge. */
+export async function findBridgePort(timeoutMs = 6000, ports = BRIDGE_PORTS) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    for (const port of ports) {
+      try {
+        const r = await httpJson('GET', `http://127.0.0.1:${port}/health`, undefined, 1000)
+        if (r.ok && /easyeda-bridge/.test(r.text)) return port
+      } catch { /* port closed — keep scanning */ }
+    }
+    await new Promise((res) => setTimeout(res, 500))
+  }
+  return null
+}
+
+/**
+ * The official bridge: spawns the official Bridge Server (if not already
+ * running), discovers its port, and executes `eda.*` code through it.
+ * @param {object} cfg {
+ *   bridgeDir='~/.dsh/eda/bridge'  — vendored easyeda-api-skill (npm install 后含 scripts/bridge-server.mjs)
+ *   nodeBin='node', discoveryPorts=BRIDGE_PORTS, spawnBridge=true, timeouts
+ * }
+ */
+export class EdaBackend {
+  constructor(cfg = {}) {
+    this.cfg = cfg
+    this.bridgeDir = cfg.bridgeDir ?? ''
+    this.nodeBin = cfg.nodeBin ?? process.execPath
+    this.discoveryPorts = cfg.discoveryPorts ?? BRIDGE_PORTS
+    this.spawnBridge = cfg.spawnBridge ?? true
+    this.timeouts = cfg.timeouts ?? { startMs: 25000, callMs: 60000 }
+    this.state = STATE.idle
+    this.error = null
+    this.child = null
+    this.port = null
+    this.lastHealth = null
+  }
+
+  isRunning() {
+    return this.port !== null ||
+      (this.spawnBridge && this.child !== null && this.child.exitCode === null)
+  }
+
+  /** Probe the discovery port range (real or injected). */
+  async discover() {
+    for (const port of this.discoveryPorts) {
+      try {
+        const r = await httpJson('GET', `http://127.0.0.1:${port}/health`, undefined, 1500)
+        if (r.ok && /easyeda-bridge/.test(r.text)) {
+          this.port = port
+          this.lastHealth = { ok: true, port, raw: r.text.slice(0, 300) }
+          return port
+        }
+      } catch { /* keep scanning */ }
+    }
+    return null
+  }
+
+  /** One live probe of the current (or first reachable) bridge port. */
+  async probeCurrent() {
+    for (const port of this.port !== null ? [this.port] : this.discoveryPorts) {
+      try {
+        const r = await httpJson('GET', `http://127.0.0.1:${port}/health`, undefined, 1500)
+        if (r.ok && /easyeda-bridge/.test(r.text)) {
+          this.port = port
+          this.lastHealth = { ok: true, port, raw: r.text.slice(0, 300) }
+          return this.lastHealth
+        }
+      } catch { /* port closed */ }
+    }
+    return null
+  }
+
+  /**
+   * Refresh the health snapshot live (the cached one goes stale: an editor may
+   * connect/disconnect after `start()`). Called by /status, eda_status and the
+   * bridge-gated tools so they always see the CURRENT connection facts.
+   */
+  async refresh() {
+    const h = await this.probeCurrent()
+    if (h !== null && this.state !== STATE.error) this.state = STATE.connected
+    return this.status()
+  }
+
+  async start() {
+    if (this.port !== null) return this.status()
+    this.state = STATE.starting
+    this.error = null
+    // 1) spawn the official bridge server (background) if nothing is on the range.
+    if (!(await this.discover()) && this.spawnBridge) {
+      try {
+        const sep = process.platform === 'win32' ? '\\' : '/'
+        const script = this.bridgeDir.replace(/[\\/]+$/, '') + sep + 'scripts' + sep + 'bridge-server.mjs'
+        const child = spawn(this.nodeBin, [script], {
+          stdio: ['ignore', 'ignore', 'pipe'],
+          windowsHide: true,
+          cwd: this.bridgeDir || undefined,
+        })
+        this.child = child
+        child.stderr?.on('data', (d) => { this.error = String(d).slice(-400) })
+        child.on('exit', () => { if (this.state !== STATE.idle) this.state = STATE.error })
+      } catch (error) {
+        this.state = STATE.error
+        this.error = error instanceof Error ? error.message : String(error)
+        return this.status()
+      }
+    }
+    // 2) wait for health on the official port range.
+    const deadline = Date.now() + this.timeouts.startMs
+    let port = null
+    while (Date.now() < deadline && port === null) {
+      port = await this.discover()
+      if (port !== null) break
+      await new Promise((res) => setTimeout(res, 700))
+    }
+    if (port !== null) {
+      this.state = STATE.connected
+      this.error = ''
+    } else {
+      this.state = STATE.error
+      if (!this.error) {
+        this.error = '官方桥未就绪（49620-49629 无 easyeda-bridge 服务）。请确认：① 已一键安装/启动官方桥；② EasyEDA Pro 已安装 Run API Gateway 扩展并勾选「允许外部交互」。'
+      }
+    }
+    return this.status()
+  }
+
+  /** Execute official `eda.*` code through the bridge. */
+  async execute(code, timeoutMs = this.timeouts.callMs) {
+    if (this.port === null) {
+      return { ok: false, error: '官方桥未连接（请先启动桥并确认扩展已勾选「允许外部交互」）' }
+    }
+    try {
+      const r = await httpJson('POST', `http://127.0.0.1:${this.port}/execute`, { code }, timeoutMs)
+      if (r.ok) {
+        // Normalize: prefer the JSON `result` field; fall back to raw text.
+        const val = r.json?.result !== undefined ? r.json.result : r.text
+        return { ok: true, result: typeof val === 'string' ? val : JSON.stringify(val) }
+      }
+      return { ok: false, error: `execute 失败（HTTP ${r.status}）：${r.text.slice(0, 300)}` }
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  /**
+   * Call one action: uses the official snippet for known ids, or runs a raw
+   * code snippet passed in params.code (official execute accepts any code).
+   */
+  async callTool(name, params = {}) {
+    const code = (typeof params?.code === 'string' && params.code.trim() !== '')
+      ? params.code
+      : OFFICIAL_CODES[name]
+    if (code === undefined) {
+      return { ok: false, error: `未知动作 ${name}（可用官方 eda.* 代码直接传 code 执行；已知映射：${Object.keys(OFFICIAL_CODES).join(', ')}）` }
+    }
+    return this.execute(code)
+  }
+
+  status() {
+    return {
+      backend: 'official-easyeda-bridge',
+      state: this.state,
+      running: this.port !== null || (this.child !== null && this.child.exitCode === null),
+      connected: this.port !== null && this.state === STATE.connected,
+      port: this.port,
+      health: this.lastHealth?.raw ?? '',
+      error: this.error ?? '',
+      ports: this.discoveryPorts,
+    }
+  }
+
+  dispose() {
+    try { this.child?.kill() } catch { /* gone */ }
+    this.child = null
+    this.port = null
+    this.lastHealth = null
+    if (this.state !== STATE.error) this.state = STATE.idle
+  }
+}

package/lib/capabilities.js

@@ -0,0 +1,106 @@
+/**
+ * dsh-lichuang-eda — 官方 API 能力清单（eda_capabilities 工具数据源）。
+ *
+ * 从官方文档（~/.dsh/eda/bridge/references/classes/*）与真机实测（esp32_multitool
+ * 全流程/14 大类/完整 demo）整理：告诉 agent「官方 eda.* API 能做什么、怎么调用、
+ * 有什么坑」。agent 不确定能力时调用 eda_capabilities 即可获得结构化清单。
+ *
+ * 仅收录实测/官方文档确认可用的核心能力；标注 ⚠ 的为已知不可靠项。
+ */
+export const CAPABILITIES = [
+  {
+    domain: 'dmt_Project',
+    note: '工程级（当前焦点工程）',
+    methods: [
+      { name: 'getCurrentProjectInfo()', desc: '读当前工程（名称/图页/PCB 树 + titleBlockData.Width/Height 页面尺寸）' },
+      { name: 'openProject(uuid)', desc: '打开指定工程（会丢未保存改动）' },
+    ],
+  },
+  {
+    domain: 'dmt_SelectControl / dmt_EditorControl',
+    note: '文档状态与视口',
+    methods: [
+      { name: 'getCurrentDocumentInfo()', desc: '当前文档 documentType（1=原理图/3=PCB）/uuid/tabId——**任何操作前先确认**' },
+      { name: 'openDocument(uuid)', desc: '打开图页/PCB，返回 tabId（切换后等 1~1.5s）' },
+      { name: 'activateDocument(tabId)', desc: '激活已开标签' },
+      { name: 'zoomToAllPrimitives()', desc: '缩放到全部图元（截图前必调）' },
+      { name: 'getCurrentRenderedAreaImage(tabId)', desc: '截图返回 Blob（→arrayBuffer→base64→PNG）' },
+    ],
+  },
+  {
+    domain: 'lib_Device',
+    note: '系统库搜索（结果可直接喂 create）',
+    methods: [
+      { name: 'search(keyword)', desc: '英文关键词（R0402/LED/10K/S8050/ESP32/BUZZER/PTC…）→ 器件数组' },
+      { name: 'searchByProperties({supplierId})', desc: '按立创 C 编号精确搜索' },
+    ],
+  },
+  {
+    domain: 'sch_PrimitiveComponent',
+    note: '原理图元件（单位 10mil，A4≈1170×825）',
+    methods: [
+      { name: 'create(dev, x, y, …)', desc: '放元件（dev=search 结果或 {libraryUuid,uuid}）；**先 eda_pick_spot 定位再放**' },
+      { name: 'createNetFlag(type, net, x, y)', desc: "网络标志：'Power'/'Ground'/'AnalogGround'/'ProtectGround'" },
+      { name: 'createNetPort(type, net, x, y)', desc: "网络端口：'IN'/'OUT'/'BI'" },
+      { name: 'getAllPinsByPrimitiveId(id)', desc: '取真实引脚坐标（连线前必调，只连引脚）' },
+      { name: 'delete(ids)', desc: '删除（与导线分开调用，勿混传）' },
+      { name: 'modify(id, prop)', desc: '改属性（改后重新 get 读最新）' },
+    ],
+  },
+  {
+    domain: 'sch_PrimitiveWire',
+    note: '原理图导线',
+    methods: [
+      { name: 'create(line, net?, color?, width?, type?)', desc: '画线：line 为水平/垂直段数组；net 指定网络名；端点落引脚才连通' },
+      { name: 'delete(ids)', desc: '删除导线' },
+    ],
+  },
+  {
+    domain: 'sch_Document / sch_Drc / sch_ManufactureData',
+    note: '保存/校验/导出',
+    methods: [
+      { name: 'sch_Document.save()', desc: '保存当前原理图（每步后必调，失败返回 false）' },
+      { name: 'sch_Drc.check(true, false, true)', desc: 'DRC **必须 verbose 重载**；返回聚合 [{type,count}]（明细在 UI 面板）' },
+      { name: 'getNetlistFile()', desc: '导出网表：返回 **File 对象，须 await f.text()**（直接返回会变 {}）' },
+      { name: 'getBomFile()', desc: '导出 BOM：**二进制 xlsx**，arrayBuffer→base64 处理' },
+    ],
+  },
+  {
+    domain: 'pcb_PrimitiveComponent / pcb_PrimitiveVia / pcb_PrimitiveLine',
+    note: 'PCB 图元（单位 1mil，居中布件）',
+    methods: [
+      { name: 'pcb_PrimitiveComponent.create(dev, 1, x, y)', desc: '放元件（layer 1=TOP）；get(id)→getAllPins() 取焊盘坐标' },
+      { name: 'pcb_PrimitiveVia.create(net, x, y, hole, dia)', desc: '过孔（网络名直给）' },
+      { name: 'pcb_PrimitiveLine.create(net, 1, x1,y1,x2,y2, width)', desc: '走线（TOP 层）；焊盘间连线的正解' },
+      { name: 'pcb_Document.save()', desc: '保存 PCB（每步后必调）' },
+    ],
+  },
+  {
+    domain: 'pcb_Drc / pcb_Net',
+    note: 'PCB 校验与网表（⚠ 部分受限）',
+    methods: [
+      { name: 'pcb_Drc.check(true, false, true)', desc: 'DRC 详细数组（规则/对象/层/间距数值）——真实可用' },
+      { name: "pcb_Net.getNetlist('JLCEDA')", desc: '读 PCB 网表（组件数/网络）——JLCEDA 格式可用；"EasyEDA" 格式会挂起，禁用' },
+      { name: 'pcb_Document.importChanges()', desc: '⚠ 实测返回 true 但元件不进画布/网表不变并留 Netlist Error——勿用于画 PCB' },
+      { name: 'pcb_Net.setNetlist(type, text)', desc: '⚠ 实测返回 true 但不生效——勿依赖' },
+    ],
+  },
+  {
+    domain: 'sys_FileManager / 快照链路',
+    note: '文档导出与本地留档',
+    methods: [
+      { name: 'sys_FileManager.getDocumentFile(name)', desc: '导出当前文档 .epro2（专业版原生，zip, File→text）——紧急保存核心' },
+      { name: 'sch_ManufactureData.getExportDocumentFile(name,\'SVG\',…)', desc: '导出当前图页 SVG 通用预览' },
+    ],
+  },
+  {
+    domain: '已知边界',
+    note: '官方 API 缺陷清单（实测）',
+    methods: [
+      { name: 'PCB 板框', desc: 'pcb_PrimitiveLine layer=11 四组参数全失败；无绘制 API——板框人工/导入' },
+      { name: 'sch_Netlist.getNetlist()', desc: '挂起 30s——用 sch_ManufactureData.getNetlistFile()' },
+      { name: 'getAll()', desc: '间歇性报错——重试 3 次（间隔 700ms）' },
+      { name: 'PCB 电气级连网', desc: '直放元件焊盘无网络；网表同步链路不可靠——画布级可用，DRC 可能报 SMD Pad to Track' },
+    ],
+  },
+]