@windypro-rourou/dsh-eda 0.1.5 → 0.1.7

package/lib/backend.js

@@ -197,12 +197,61 @@ export class EdaBackend {
         const val = r.json?.result !== undefined ? r.json.result : r.text
         return { ok: true, result: typeof val === 'string' ? val : JSON.stringify(val) }
       }
+      // Async-task patch (community #16): a timed-out /execute returns HTTP 504
+      // WITH a taskId — the execution was NOT cancelled and late results are
+      // retained under /tasks/<id>.
+      const taskId = r.json?.taskId
+      if (taskId) {
+        return {
+          ok: false,
+          taskId,
+          error: `执行超过 ${Math.round(timeoutMs / 1000)}s（HTTP ${r.status}），任务未取消：可用 eda_task 查询 taskId=${taskId} 取迟到结果。`,
+        }
+      }
       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) }
     }
   }
 
+  /** Submit code as a background task (bridge async-task patch, HTTP 202). */
+  async submitTask(code) {
+    if (this.port === null) return { ok: false, error: '官方桥未连接' }
+    try {
+      const r = await httpJson('POST', `http://127.0.0.1:${this.port}/tasks`, { code }, 20000)
+      if (r.ok && r.json?.taskId) {
+        return { ok: true, taskId: r.json.taskId, statusUrl: r.json.statusUrl ?? `/tasks/${r.json.taskId}` }
+      }
+      return { ok: false, error: r.json?.error ?? `tasks 提交失败（HTTP ${r.status}）：${r.text.slice(0, 200)}` }
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  /** Query one background task (status/phase/elapsedMs/result/errorDetails/events). */
+  async getTask(taskId) {
+    if (this.port === null) return { ok: false, error: '官方桥未连接' }
+    try {
+      const r = await httpJson('GET', `http://127.0.0.1:${this.port}/tasks/${encodeURIComponent(taskId)}`, undefined, 15000)
+      if (r.ok && r.json) return { ok: true, task: r.json }
+      return { ok: false, error: r.json?.error ?? `查询失败（HTTP ${r.status}）` }
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  /** List retained tasks (bounded, in-memory). */
+  async listTasks() {
+    if (this.port === null) return { ok: false, error: '官方桥未连接' }
+    try {
+      const r = await httpJson('GET', `http://127.0.0.1:${this.port}/tasks`, undefined, 15000)
+      if (r.ok && Array.isArray(r.json?.tasks)) return { ok: true, tasks: r.json.tasks }
+      return { ok: false, error: r.json?.error ?? `列表失败（HTTP ${r.status}）` }
+    } 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).

package/lib/capabilities.js

@@ -99,6 +99,9 @@ export const CAPABILITIES = [
     note: '官方 API 缺陷清单（实测）',
     methods: [
       { name: 'PCB 板框 / 非铜层', desc: '板框（layer 11）用 pcb_PrimitivePolyline + pcb_MathPolygon.createPolygon（官方 1.1.56 Remarks 明确；line 接口仅铜层）；pcb_PrimitiveLine 非铜层（丝印/阻焊/机械）实测失败，BOTTOM(2) 可用；丝印文本 API 实测挂起' },
+      { name: '桥异步任务 /tasks', desc: '长操作（自动布线/大导出/批量写回）用 eda_task 提交；/execute 超时返回 HTTP 504 + taskId 且任务不取消（迟到结果保留）——桥已打社区补丁 #16' },
+      { name: 'PCB 写回顺序', desc: '必须先建过孔、后建走线（反序产生大量 Connection Error）；改铜皮后跑 DRC 前先 rebuildCopperRegion()+save（Issues #23）' },
+      { name: 'DRC 条目', desc: 'obj1.suffix 不是图元 ID（真 ID 在 objs 数组）；DRC 不幂等——一轮验证只跑一次（Issues #23/#6）' },
       { name: 'sch_Netlist.getNetlist()', desc: '挂起 30s——用 sch_ManufactureData.getNetlistFile()' },
       { name: 'getAll()', desc: '间歇性报错——重试 3 次（间隔 700ms）' },
       { name: 'PCB 电气级连网', desc: '直放元件焊盘无网络；网表同步链路不可靠——画布级可用，DRC 可能报 SMD Pad to Track' },

package/lib/index.js

@@ -124,7 +124,8 @@ export const EDA_GUIDANCE =
   '**官方 Skill 全库已接入**：官方易达 skill 知识随插件 vendored（SKILL.md 总纲 / references/classes/*.md 逐类 API / guide、user-guide、format 教程与格式；线上镜像 https://prodocs.easyeda.com/cn/api/reference/pro-api.html 可交叉核对）。规划任何画板动作前先用 eda_skill_read 查阅（顺序：INDEX.md → 对应类文档 → eda_exec 落地）；不确定 API 存在性也可先 eda_capabilities。' +
   '**放置定位（硬规则，禁止乱放）**：原理图坐标单位 10mil、图纸 A4≈1170×825，放置前必须先 `eda_exec` 读页面尺寸（dmt_Project.getCurrentProjectInfo()→titleBlockData.Width/Height）与已有图元位置（sch_PrimitiveComponent.getAll()+getState_X/Y 在代码内映射），只放**图框内边距≥80、网格 100 步进、与已有图元间距≥150**的空位（或直接调 eda_pick_spot）；导线用 getAllPinsByPrimitiveId 取真实引脚坐标后画水平/垂直线段（只连引脚）。PCB 坐标单位 1mil，同样读已有焊盘（getAllPins）后居中布件、焊盘级走线。' +
   '**已知缺陷与技巧（实测，勿踩坑）**：`pcb_Document.importChanges` 与 `pcb_Net.setNetlist` 实测不可靠（勿用于网表同步；1.1.56 文档提到 `force=true` 防弹窗但签名无此参数）；`sch_Netlist.getNetlist` 与 `pcb_Net.getNetlist("EasyEDA")` 会挂起（网表一律用 `sch_ManufactureData.getNetlistFile` 并 `await f.text()`）；`getBomFile` 返回二进制 xlsx（arrayBuffer→base64 处理）；DRC 用 `check(true,false,true)` 拿详情；`sch_PrimitiveComponent.getAll` 间歇失败需重试；**PCB 板框（layer 11）用 `pcb_PrimitivePolyline` + `pcb_MathPolygon.createPolygon([…, "L", …])`**（官方 1.1.56 明确；`pcb_PrimitiveLine` 仅铜层）；自动布线单次硬上限 900s 且超时中间结果不提交。' +
-  '**超时防线（防自动退出）**：所有聚合/查询工具内部单查询 5s 封顶、并行、单项降级（返回值带 degraded 说明），单次调用总耗时有界——不会触发超时中断；`eda_exec` 可传 `timeoutMs`（默认 25000，定位挂起用 8000~15000，长导出用 45000）。' +
+  '**超时防线（防自动退出）**：所有聚合/查询工具内部单查询 5s 封顶、并行、单项降级（返回值带 degraded 说明），单次调用总耗时有界——不会触发超时中断；`eda_exec` 可传 `timeoutMs`（默认 25000，定位挂起用 8000~15000，长导出用 45000）。**后台任务（桥已打异步补丁）**：`/execute` 超时（HTTP 504）时任务不会取消并返回 taskId（迟到结果保留）；用 `eda_task`（action=submit 提交官方 eda.* 代码 / get 查询状态与结果 / list 列表）执行自动布线、大导出、批量写回等长操作。' +
+  '**社区实测要点（官方 Issues）**：PCB 写回**必须先建过孔、后建走线**（反序会导致大量 Connection Error）；改铜皮后**跑 DRC 前先 `rebuildCopperRegion()` + save**（否则虚假 Copper Region 错误）；DRC 条目的 `obj1.suffix` **不是图元 ID**（真 ID 在 `objs` 数组）；DRC 不幂等（一轮验证只跑一次）；netport/net label 不能直接放引脚上（要从引脚画短 stub 线再放标签）；enum 全局可能未注入（`EPCB_LayerId` 等取不到时回退字面值）；`get(id)` 返回对象字段多为 null，须用 `getState_*()`。' +
   '**主动协作（能力入口）**：你能主动为用户完成——读工程/文档、放任意大类元件（搜库→定位→放置）、引脚级连线、网络标志/端口、DRC、网表/BOM 导出、PCB 元件/过孔/走线、现场截图、紧急保存。规划任务时若不确定某个 API 是否存在或怎么调，先调 `eda_capabilities`（结构化能力清单+注意事项+实测片段），再用 `eda_exec` 落地；用户提到画板相关需求时主动提议并执行，不要等用户一字一句教。' +
   '限制：v0 离线生成器仅支持 电阻/LED；云端实时生成能力由官方 eda.* API 决定（以 ~/.dsh/eda/bridge 内官方文档为准）。' +
   '用户提到「嘉立创 / 立创EDA / 原理图 / PCB草图 / 生成电路图」时即指本插件，请据此主动协作。'
@@ -1752,6 +1753,119 @@ function edaNetflagTool(backend) {
   })
 }
 
+/**
+ * eda_task：后台任务（桥异步任务补丁，#16）。
+ * 长耗时操作（自动布线/大导出/批量写回）用 submit 提交，避免 /execute 的等待
+ * 上限；超时的 /execute 也会返回 taskId（任务未取消、迟到结果保留）。
+ */
+function edaTaskTool(backend) {
+  return defineTool({
+    name: 'eda_task',
+    description: 'Background EDA task over the official bridge (async-task patch): submit official eda.* code as a task, ' +
+      'query one task (status/phase/elapsedMs/result/errorDetails/events), or list retained tasks. ' +
+      'Use for long-running work (autorouting, large exports, bulk write-back) and to retrieve late results of a timed-out eda_exec. ' +
+      'Triggers: 后台执行, 长任务, 任务状态, async task, /tasks, 自动布线进度.',
+    parameters: {
+      action: { type: 'string', description: "'submit' | 'get' | 'list'（默认 list）" },
+      code: { type: 'string', description: 'action=submit 时：要执行的官方 eda.* 代码（如 return await eda.pcb_Document.autoRouting(...)）' },
+      taskId: { type: 'string', description: 'action=get 时：任务 id（submit 或超时的 eda_exec 返回）' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          taskId: { type: 'string' },
+          statusUrl: { type: 'string' },
+          status: { type: 'string' },
+          phase: { type: 'string' },
+          elapsedMs: { type: 'integer' },
+          outcome: { type: 'string' },
+          result: { type: 'string' },
+          errorText: { type: 'string' },
+          events: { type: 'array', items: { type: 'string' } },
+          tasks: { type: 'array', items: { type: 'object', additionalProperties: true, properties: {} } },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (value?.ok !== true) return [{ type: 'text', text: `后台任务失败: ${value?.error ?? '?'}` }]
+        if (Array.isArray(value.tasks)) {
+          const lines = value.tasks.slice(0, 30).map((t) =>
+            `${t.id ?? '?'} · ${t.status ?? '?'}${t.elapsedMs ? ' · ' + t.elapsedMs + 'ms' : ''}${t.outcome ? ' · ' + t.outcome : ''}`)
+          return [{ type: 'text', text: (lines.length ? lines.join('\n') : '（无保留任务）') }]
+        }
+        if (value.taskId && value.status === undefined) {
+          return [{ type: 'text', text: `已提交任务 ${value.taskId}（${value.statusUrl ?? ''}）——用 eda_task action=get 查询` }]
+        }
+        const parts = [`任务 ${value.taskId ?? '?'}`, `状态 ${value.status ?? '?'}${value.phase ? ' / ' + value.phase : ''}`]
+        if (value.elapsedMs) parts.push(`${value.elapsedMs}ms`)
+        if (value.outcome) parts.push(`结果 ${value.outcome}`)
+        const head = parts.join(' · ')
+        if (value.errorText) return [{ type: 'text', text: `${head}\n错误: ${value.errorText}` }]
+        return [{ type: 'text', text: `${head}${value.result ? '\n' + value.result.slice(0, 1500) : ''}` }]
+      },
+    },
+    async execute(args, exec) {
+      const sid = sessionIdOf(exec)
+      await backend.refresh()
+      if (!backend.status().connected) return { ok: false, error: '官方桥未连接：请先 eda_backend_connect（并确认 Run API Gateway 已开启「外部交互」）。' }
+      const action = typeof args?.action === 'string' ? args.action : 'list'
+      const t0 = Date.now()
+
+      if (action === 'submit') {
+        const code = typeof args?.code === 'string' ? args.code.trim() : ''
+        if (code === '') return { ok: false, error: 'action=submit 需要 code（官方 eda.* 代码）' }
+        const actId = pushPendingActivity({ sid, tool: 'eda_task', action: '提交后台任务', code: code.slice(0, 120) })
+        const r = await backend.submitTask(code)
+        updateActivity(actId, {
+          status: r.ok ? 'done' : 'error', ok: r.ok,
+          action: '提交后台任务', result: r.ok ? `taskId=${r.taskId}` : '', error: r.ok ? '' : r.error,
+          durationMs: Date.now() - t0,
+        })
+        return r.ok
+          ? { ok: true, taskId: r.taskId, statusUrl: r.statusUrl ?? `/tasks/${r.taskId}` }
+          : { ok: false, error: r.error }
+      }
+
+      if (action === 'get') {
+        const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : ''
+        if (taskId === '') return { ok: false, error: 'action=get 需要 taskId' }
+        const r = await backend.getTask(taskId)
+        if (!r.ok) return { ok: false, error: r.error }
+        const t = r.task ?? {}
+        const events = Array.isArray(t.events)
+          ? t.events.slice(-20).map((e) => (typeof e === 'string' ? e : JSON.stringify(e)))
+          : []
+        // DSH 的 value 快照要求 lossless JSON：绝不能带 undefined 属性（逐一条件赋值）。
+        const out = {
+          ok: true,
+          taskId: String(t.id ?? taskId),
+          status: typeof t.status === 'string' ? t.status : '',
+          phase: typeof t.phase === 'string' ? t.phase : '',
+          events,
+        }
+        if (Number.isFinite(t.elapsedMs)) out.elapsedMs = Math.round(t.elapsedMs)
+        if (typeof t.result?.outcome === 'string') out.outcome = t.result.outcome
+        if (t.result !== undefined) { try { out.result = JSON.stringify(t.result).slice(0, 4000) } catch (e) {} }
+        if (t.errorDetails) { try { out.errorText = JSON.stringify(t.errorDetails).slice(0, 2000) } catch (e) {} }
+        return out
+      }
+
+      const r = await backend.listTasks()
+      if (!r.ok) return { ok: false, error: r.error }
+      return { ok: true, tasks: r.tasks.map((t) => {
+        const row = { id: String(t.id ?? ''), status: typeof t.status === 'string' ? t.status : '' }
+        if (typeof t.phase === 'string') row.phase = t.phase
+        if (Number.isFinite(t.elapsedMs)) row.elapsedMs = Math.round(t.elapsedMs)
+        if (typeof t.outcome === 'string') row.outcome = t.outcome
+        return row
+      }) }
+    },
+  })
+}
+
 /** eda_save：保存当前文档（sch/pcb 自动判断）。 */
 function edaSaveTool(backend) {
   return defineTool({
@@ -1876,6 +1990,7 @@ export function apply(ctx, config) {
         edaBridgeInstallTool(backend),
         edaBackendConnectTool(edaHandle, backend),
         edaExecTool(backend),
+        edaTaskTool(backend),
         edaPickSpotTool(backend),
         edaCapabilitiesTool(),
         edaSkillReadTool(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windypro-rourou/dsh-eda",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "dsh-lichuang-eda (JCL-EDA): 嘉立创 EDA 助手 DSH 插件 —— 官方 eda.* API 云端实时生成（原理图/PCB）+ 离线标准版 JSON 兜底 + 面板记录式时间线（撤回/清空/紧急保存）。开箱即用：npm i 后 cordis.patch.yml insert 一行即挂载。",
   "packageManager": "pnpm@11.22.0",