@windypro-rourou/dsh-eda 0.1.0 → 0.1.2

package/lib/index.js

@@ -27,8 +27,10 @@ import { EdaBackend, OFFICIAL_CODES, BRIDGE_PORTS } from './backend.js'
 import { installOfficialBridge, isBridgeInstalled, bridgeDir, bridgeScriptPath, OFFICIAL_EXT_URL } from './installer.js'
 import { createSnapshot } from './snapshot.js'
 import { pickSpots } from './layout.js'
+import { buildOverview, pickSpotsPcb, saveTrace } from './board.js'
 import { ActivityLog } from './activity.js'
 import { CAPABILITIES } from './capabilities.js'
+import { readSkillDoc, listSkillDocs } from './skill.js'
 import { generateSchematic, wrapAsProject } from '../src/json-gen.js'
 import { validateSchematic, checkConnectivity, deriveNetlist } from '../src/validate.js'
 import { translateRequest, TEMPLATE_CATALOG, describeDesign } from '../src/nl-to-design.js'
@@ -61,6 +63,7 @@ export const EDA_GUIDANCE =
   '工具：eda_status（状态）、eda_bridge_install（一键装官方桥）、eda_backend_connect（启动/连接官方桥）、eda_exec（执行任意官方 eda.* 代码——云端实时生成的双手）、eda_pick_spot（**框内定位**：读页面尺寸+已有图元→返回互不冲突的框内网格空位；放元件前先调用）、eda_snapshot（**紧急保存**：画板现场 .epro2 + 预览 SVG + 网表/BOM + agent 动作日志 → ~/.dsh/eda/snapshots/，断连也能留档）、' +
   'eda_sch_drc / eda_get_netlist / eda_get_bom（校验/导出，需连接）、eda_generate_schematic_json（**离线兜底**：本地生成可导入的标准版 JSON，写入 ~/.dsh/eda/output/；仅在无法连接画板时使用，连接时一律走官方 API 云端实时）、' +
   'eda_template_list / eda_translate_request（模板与需求翻译，供离线/兜底使用）。' +
+  '**官方 Skill 全库已接入**：官方易达 skill 知识随插件 vendored（SKILL.md 总纲 / references/classes/*.md 逐类 API / guide、user-guide、format 教程与格式）。规划任何画板动作前先用 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` 实测不可靠（勿用于网表同步）；`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）官方无绘制 API（人工/导入）。' +
   '**主动协作（能力入口）**：你能主动为用户完成——读工程/文档、放任意大类元件（搜库→定位→放置）、引脚级连线、网络标志/端口、DRC、网表/BOM 导出、PCB 元件/过孔/走线、现场截图、紧急保存。规划任务时若不确定某个 API 是否存在或怎么调，先调 `eda_capabilities`（结构化能力清单+注意事项+实测片段），再用 `eda_exec` 落地；用户提到画板相关需求时主动提议并执行，不要等用户一字一句教。' +
@@ -169,7 +172,7 @@ function describeEdaAction(code) {
   return map[`${mod}.${fn}`] ?? `调用 ${mod}.${fn}()`
 }
 
-/** Loopback-only guard (simplified from dsh-logcat): refuses non-local callers. */
+/** Loopback-only guard: refuses non-local callers (DSH web-server convention). */
 function isLoopbackRequest(req) {
   const address = req.socket?.remoteAddress ?? ''
   if (address === '') return true // no socket info (tests / some proxies) — allow
@@ -832,12 +835,14 @@ async function readSchLayout(backend) {
 function edaPickSpotTool(backend) {
   return defineTool({
     name: 'eda_pick_spot',
-    description: 'Pick in-frame empty grid spots on the CURRENT schematic page (units 10mil; A4 ≈ 1170 x 825). ' +
-      'Reads the page size + existing primitives via the OFFICIAL API and returns collision-free points (frame margin 80, grid 100, min gap 150). ' +
-      'USE BEFORE placing any component: get spots, then sch_PrimitiveComponent.create(dev, spot.x, spot.y) — never place outside the frame. ' +
-      'Triggers: 在哪里放, where to place, 框内定位, pick a spot.',
+    description: 'Pick collision-free empty spots on the CURRENT document before placing components. ' +
+      'kind=sch (default): reads the schematic page size (units 10mil; A4 ≈ 1170 x 825) + existing primitives, returns in-frame grid spots (margin 80, grid 100, gap 150). ' +
+      'kind=pcb: reads existing PCB primitives (units 1mil) and returns spots around their bounding box (gap 600, grid 300). ' +
+      'USE BEFORE placing any component: get spots, then sch_PrimitiveComponent.create / pcb_PrimitiveComponent.create — never place blind. ' +
+      'Triggers: 在哪里放, where to place, 框内定位, pick a spot, PCB放哪里.',
     parameters: {
       count: { type: 'integer', description: '需要的空位数量（默认 1）' },
+      kind: { type: 'string', description: 'sch（默认，原理图图框内）| pcb（PCB 围绕已有图元）' },
     },
     output: {
       schema: {
@@ -876,22 +881,290 @@ function edaPickSpotTool(backend) {
     },
     async execute(args) {
       const count = Math.max(1, Math.min(50, Number(args?.count) || 1))
-      const layout = await readSchLayout(backend)
-      if (!layout.ok) return { ok: false, error: layout.error, page: '', size: '', usedCount: 0, spots: [], note: '', }
-      const spots = pickSpots({ pageWidth: layout.width, pageHeight: layout.height, used: layout.used, count })
+      const kind = args?.kind === 'pcb' ? 'pcb' : 'sch'
+      if (kind === 'sch') {
+        const layout = await readSchLayout(backend)
+        if (!layout.ok) return { ok: false, error: layout.error, page: '', size: '', usedCount: 0, spots: [], note: '', }
+        const spots = pickSpots({ pageWidth: layout.width, pageHeight: layout.height, used: layout.used, count })
+        return {
+          ok: spots.length > 0,
+          page: layout.name,
+          size: `${layout.width} x ${layout.height} (10mil)`,
+          usedCount: layout.used.length,
+          spots,
+          note: spots.length < count ? `仅找到 ${spots.length} 个空位（页面空间不足，建议换一页或改用更小间距）` : `框内空位推荐（边距 80 / 网格 100 / 与已有图元间距 ≥150）`,
+          error: '',
+        }
+      }
+      const layout = await readPcbLayout(backend)
+      if (!layout.ok) return { ok: false, error: layout.error, page: 'PCB', size: '(1mil)', usedCount: 0, spots: [], note: '', }
+      const spots = pickSpotsPcb(layout.used, count)
       return {
         ok: spots.length > 0,
-        page: layout.name,
-        size: `${layout.width} x ${layout.height} (10mil)`,
+        page: 'PCB',
+        size: '(1mil · 围绕已有图元)',
         usedCount: layout.used.length,
         spots,
-        note: spots.length < count ? `仅找到 ${spots.length} 个空位（页面空间不足，建议换一页或改用更小间距）` : `框内空位推荐（边距 80 / 网格 100 / 与已有图元间距 ≥150）`,
+        note: spots.length < count ? `仅找到 ${spots.length} 个空位` : `PCB 空位推荐（与已有图元间距 ≥600 / 网格 300）`,
         error: '',
       }
     },
   })
 }
 
+/** 读 PCB 现有图元分布（元件/过孔/线），供 pcb 定位。 */
+async function readPcbLayout(backend) {
+  const CODE = `return await (async () => {
+    const used = [];
+    const grab = async (api) => {
+      try { const all = await eda[api].getAll(); for (const x of (all || [])) { try { used.push({ x: x.getState_X(), y: x.getState_Y() }); } catch (e) {} } } catch (e) {}
+    };
+    await grab('pcb_PrimitiveComponent');
+    await grab('pcb_PrimitiveVia');
+    await grab('pcb_PrimitiveLine');
+    return { used, count: used.length };
+  })();`
+  const r = await backend.execute(CODE, 30000)
+  if (!r.ok) return { ok: false, error: r.error }
+  try { const j = JSON.parse(r.result); return { ok: true, used: j.used ?? [], count: j.count ?? 0 } } catch { return { ok: false, error: 'pcb layout read failed' } }
+}
+
+/** 画板全览：当前文档的图元/网络摘要（agent 的眼睛，避免盲画）。 */
+function edaBoardOverviewTool(backend) {
+  return defineTool({
+    name: 'eda_board_overview',
+    description: 'Overview the CURRENT document (domain / doc info / page size / components / wires / vias / lines / nets — pin coords with full=true). ' +
+      'The agent\'s eyes on the board: call BEFORE drawing to know what exists, and after changes to verify. ' +
+      'Triggers: 画板上有什么, what is on the board, 看看画板, overview, 当前画板内容.',
+    parameters: {
+      full: { type: 'boolean', description: '默认 false（前 40 个元件 + 网络 + 统计）；true 时返回全部元件清单（≤200）' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          domain: { type: 'string' },
+          doc: { type: 'string' },
+          pageSize: { type: 'string' },
+          componentCount: { type: 'integer' },
+          wireCount: { type: 'integer' },
+          viaCount: { type: 'integer' },
+          lineCount: { type: 'integer' },
+          nets: { type: 'array', items: { type: 'string' } },
+          componentsPreview: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                designator: { type: 'string', required: true },
+                name: { type: 'string' },
+                type: { type: 'string' },
+                x: { type: 'number' },
+                y: { type: 'number' },
+                net: { type: 'string' },
+              },
+            },
+          },
+          truncated: { type: 'boolean' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (value?.ok !== true) return { type: 'text', text: `画板全览失败: ${value?.error ?? '?'}` }
+        const lines = [
+          `${value.domain === 'pcb' ? 'PCB' : '原理图'}（${value.doc ?? '?'}）· ${value.pageSize ?? ''}`,
+          `元件 ${value.componentCount ?? 0} · 导线 ${value.wireCount ?? 0} · 过孔 ${value.viaCount ?? 0} · 走线 ${value.lineCount ?? 0}`,
+          `网络: ${(value.nets ?? []).join(', ') || '（无）'}`,
+        ]
+        if ((value.componentsPreview ?? []).length > 0) {
+          lines.push('元件清单:')
+          for (const c of value.componentsPreview.slice(0, 20)) lines.push(`  ${c.designator} ${c.name} @(${c.x},${c.y})${c.net ? ` [${c.net}]` : ''}`)
+          if (value.truncated) lines.push(`  …共 ${value.componentCount} 个（full=true 看全）`)
+        }
+        return { type: 'text', text: lines.join('\n') }
+      },
+    },
+    async execute(args) {
+      const full = args?.full === true
+      const r = await backend.execute(OVERVIEW_CODE, 40000)
+      if (!r.ok) return { ok: false, error: r.error, domain: 'sch', doc: '', pageSize: '', componentCount: 0, wireCount: 0, viaCount: 0, lineCount: 0, nets: [], componentsPreview: [], truncated: false }
+      let raw
+      try { raw = JSON.parse(r.result) } catch { return { ok: false, error: 'overview parse failed', domain: 'sch', doc: '', pageSize: '', componentCount: 0, wireCount: 0, viaCount: 0, lineCount: 0, nets: [], componentsPreview: [], truncated: false } }
+      const o = buildOverview(raw, { full })
+      return { ok: true, ...o, doc: raw?.doc?.name ?? raw?.doc?.uuid ?? '' }
+    },
+  })
+}
+
+const OVERVIEW_CODE = `return await (async () => {
+  const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+  let info = null;
+  for (let i = 0; i < 3 && info == null; i++) {
+    try { info = await eda.dmt_SelectControl.getCurrentDocumentInfo(); } catch (e) { info = null; }
+    if (info == null) await sleep(700);
+  }
+  const domain = info?.documentType === 3 ? 'pcb' : 'sch';
+  const out = { domain, doc: info };
+  if (domain === 'sch') {
+    try {
+      const proj = await eda.dmt_Project.getCurrentProjectInfo();
+      const page = proj?.data?.[0]?.schematic?.page?.[0];
+      out.pageSize = { w: Number(page?.titleBlockData?.Width?.value ?? 1170), h: Number(page?.titleBlockData?.Height?.value ?? 825), unit: '10mil' };
+    } catch (e) {}
+    let comps = []; let wires = [];
+    for (let i = 0; i < 3; i++) {
+      try { comps = await eda.sch_PrimitiveComponent.getAll(); break; } catch (e) { await sleep(700); }
+    }
+    try { wires = await eda.sch_PrimitiveWire.getAll(); } catch (e) { wires = []; }
+    const nets = new Set();
+    out.components = (comps || []).map(c => {
+      let d = ''; let t = ''; let n = ''; let x = 0; let y = 0;
+      try { d = (c.getState_Designator ? c.getState_Designator() : '') || ''; } catch (e) {}
+      try { t = (c.getState_ComponentType ? c.getState_ComponentType() : '') || ''; } catch (e) {}
+      try { n = (c.getState_Net ? c.getState_Net() : '') || ''; if (n) nets.add(n); } catch (e) {}
+      try { x = c.getState_X(); y = c.getState_Y(); } catch (e) {}
+      return { id: c.getState_PrimitiveId ? c.getState_PrimitiveId() : '', d, n, t, x, y };
+    });
+    out.wireCount = (wires || []).length;
+    try { for (const w of (wires || [])) { const n = w.getState_Net ? w.getState_Net() : ''; if (n) nets.add(n); } } catch (e) {}
+    out.nets = [...nets];
+  } else {
+    const grab = async (api) => {
+      try { const all = await eda[api].getAll(); return (all || []).map(x => {
+        let d = ''; let n = ''; let x = 0; let y = 0;
+        try { d = (x.getState_Designator ? x.getState_Designator() : '') || ''; } catch (e) {}
+        try { n = (x.getState_Net ? x.getState_Net() : '') || ''; } catch (e) {}
+        try { x = x.getState_X(); y = x.getState_Y(); } catch (e) {}
+        return { id: x.getState_PrimitiveId ? x.getState_PrimitiveId() : '', d, n, t: 'part', x, y };
+      }); } catch (e) { return []; }
+    };
+    const comps = await grab('pcb_PrimitiveComponent');
+    const vias = await grab('pcb_PrimitiveVia');
+    const lines = await grab('pcb_PrimitiveLine');
+    out.components = comps; out.viaCount = vias.length; out.lineCount = lines.length; out.wireCount = 0;
+    const nets = new Set();
+    for (const x of [...comps, ...vias, ...lines]) if (x.n) nets.add(x.n);
+    out.nets = [...nets];
+  }
+  return out;
+})();`
+
+/** 现场截图：缩放适配 → 截图 → 存 ~/.dsh/eda/shots/，agent 与用户可查看。 */
+function edaTraceTool(backend) {
+  return defineTool({
+    name: 'eda_trace',
+    description: 'Capture the CURRENT document as a PNG (zooms to all primitives first; saves to ~/.dsh/eda/shots/). ' +
+      'Use to show/review the board state or keep a visual record after drawing. ' +
+      'Triggers: 截图, screenshot, 看看效果, capture the board.',
+    parameters: {
+      name: { type: 'string', description: '可选：文件名前缀（默认 board）' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          path: { type: 'string' },
+          file: { type: 'string' },
+          size: { type: 'integer' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => ({ type: 'text', text: value?.ok ? `✅ 截图已保存: ${value.path}（${((value.size ?? 0) / 1024).toFixed(1)}KB）` : `截图失败: ${value?.error ?? '?'}` }),
+    },
+    async execute(args) {
+      const r = await backend.execute(TRACE_CODE, 60000)
+      if (!r.ok) return { ok: false, path: '', file: '', size: 0, error: r.error }
+      let j
+      try { j = JSON.parse(r.result) } catch { return { ok: false, path: '', file: '', size: 0, error: 'trace parse failed' } }
+      if (!j?.b64) return { ok: false, path: '', file: '', size: 0, error: j?.error ?? '未取到截图（请确认当前文档已打开）' }
+      const saved = await saveTrace(j.b64, { name: typeof args?.name === 'string' && args.name !== '' ? args.name : 'board' })
+      return saved.ok ? { ok: true, path: saved.path, file: saved.file, size: saved.size } : { ok: false, path: '', file: '', size: 0, error: saved.error }
+    },
+  })
+}
+
+const TRACE_CODE = `return await (async () => {
+  try { await eda.dmt_EditorControl.zoomToAllPrimitives(); } catch (e) {}
+  await new Promise(r => setTimeout(r, 1200));
+  const info = await eda.dmt_SelectControl.getCurrentDocumentInfo();
+  const blob = await eda.dmt_EditorControl.getCurrentRenderedAreaImage(info.tabId);
+  if (!blob) return null;
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  let bin = ''; for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+  return { type: blob.type, size: bytes.length, b64: btoa(bin) };
+})();`
+
+/** 一键验收：连接状态下的 DRC + 网表 + BOM 组合校验（agent 一步拿结论）。 */
+function edaVerifyTool(handle, backend) {
+  return defineTool({
+    name: 'eda_verify',
+    description: 'One-shot acceptance check on the connected board: schematic DRC (verbose) + netlist + BOM in one call. ' +
+      'Returns summaries so the agent can report pass/fail immediately. Use after finishing a drawing. ' +
+      'Triggers: 验收, 检查一下, verify, 看看行不行.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          drc: { type: 'string' },
+          netlist: { type: 'string' },
+          bom: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => ({
+        type: 'text',
+        text: [
+          `验收: ${value?.ok ? '完成' : '部分失败'}`,
+          value?.drc ? `DRC: ${value.drc}` : '',
+          value?.netlist ? `网表: ${value.netlist}` : '',
+          value?.bom ? `BOM: ${value.bom}` : '',
+          ...(value?.errors ?? []).map((e) => `⚠ ${e}`),
+          value?.note ?? '',
+        ].filter(Boolean).join('\n'),
+      }),
+    },
+    async execute(_args, exec) {
+      const sid = sessionIdOf(exec)
+      const id = pushPendingActivity({ sid, tool: 'eda_verify', action: '一键验收（DRC+网表+BOM）' })
+      await handle.backend.refresh()
+      const st = statusOf(handle.backend)
+      if (!st.connected) {
+        updateActivity(id, { status: 'error', ok: false, error: '官方桥未连接（门控拦截）' })
+        return { ok: false, drc: '', netlist: '', bom: '', errors: ['官方桥未连接'], note: '' }
+      }
+      const errors = []
+      const out = { ok: false, drc: '', netlist: '', bom: '', errors, note: '' }
+      const drc = await handle.backend.execute('return await eda.sch_Drc.check(true, false, true);', 40000)
+      if (drc.ok) {
+        let sum = drc.result
+        try { const arr = JSON.parse(drc.result); sum = arr.map((x) => `${x.type}:${x.count}`).join(', ') || '通过(0)' } catch { /* raw */ }
+        out.drc = sum
+      } else errors.push(`DRC: ${drc.error}`)
+      const net = await handle.backend.execute(`return await (async () => { const f = await eda.sch_ManufactureData.getNetlistFile(); if (!f) return null; const t = await f.text(); return { len: t.length, comps: (() => { try { return Object.keys(JSON.parse(t).components ?? {}).length; } catch { return -1; } })() }; })();`, 40000)
+      if (net.ok) {
+        try { const j = JSON.parse(net.result); out.netlist = `文件 ${j?.len ?? '?'} 字节 · 元件 ${j?.comps ?? '?'}` } catch { out.netlist = net.result.slice(0, 80) }
+      } else errors.push(`网表: ${net.error}`)
+      const bom = await handle.backend.execute(`return await (async () => { const f = await eda.sch_ManufactureData.getBomFile(); if (!f) return null; return { name: f.name, size: f.size }; })();`, 40000)
+      if (bom.ok) {
+        try { const j = JSON.parse(bom.result); out.bom = `${j?.name ?? 'Export_BOM.xlsx'}（${((j?.size ?? 0) / 1024).toFixed(1)}KB）` } catch { out.bom = bom.result.slice(0, 80) }
+      } else errors.push(`BOM: ${bom.error}`)
+      out.ok = errors.length === 0
+      out.note = errors.length === 0 ? '三项全部返回（DRC 明细见 UI 面板；完整内容用 eda_get_netlist / eda_get_bom）' : `${errors.length} 项未完成`
+      updateActivity(id, { status: out.ok ? 'done' : 'error', ok: out.ok, action: '一键验收（DRC+网表+BOM）', result: `${out.drc} · ${out.netlist} · ${out.bom}`, error: out.errors.join('; '), durationMs: 0 })
+      return out
+    },
+  })
+}
+
 /** 官方 API 能力清单：agent 规划时主动查 -> 用 eda_exec 落地。 */
 function edaCapabilitiesTool() {
   return defineTool({
@@ -943,6 +1216,57 @@ function edaCapabilitiesTool() {
   })
 }
 
+/** 官方 skill 全库查阅：直接在对话里读取 vendored 官方文档（SKILL.md / 类 / guide 等）。 */
+function edaSkillReadTool() {
+  return defineTool({
+    name: 'eda_skill_read',
+    description: 'Read the OFFICIAL EasyEDA skill docs (SKILL.md / references/classes/*.md / guide / user-guide / format / INDEX.md) — the full official API knowledge, vendored in the package. ' +
+      'Call before writing any eda.* code: INDEX.md first, then the specific class doc, then eda_exec. ' +
+      'Triggers: 官方文档, official skill, 查API文档, read skill class, 怎么看这个API.',
+    parameters: {
+      doc: { type: 'string', description: '文档相对路径，默认 INDEX.md；例如 references/classes/SCH_PrimitiveComponent.md、SKILL.md、guide/using-extension.md' },
+      offset: { type: 'integer', description: '分页偏移字符数（默认 0；truncated=true 时用 nextOffset 继续）' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          doc: { type: 'string' },
+          path: { type: 'string' },
+          len: { type: 'integer' },
+          start: { type: 'integer' },
+          content: { type: 'string' },
+          truncated: { type: 'boolean' },
+          nextOffset: { type: 'integer' },
+          suggestions: { type: 'array', items: { type: 'string' } },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (value?.ok === false) {
+          let text = `官方文档查阅失败: ${value?.error ?? '?'}`
+          const sug = value?.suggestions ?? []
+          if (sug.length > 0) text += `\n可尝试（前若干）：${sug.slice(0, 10).join('、')}`
+          return [{ type: 'text', text }]
+        }
+        const head = `📖 ${value?.doc ?? ''}（${value?.len ?? 0} 字符 · 从 ${value?.start ?? 0} 起）`
+        let text = `${head}\n${value?.content ?? ''}`
+        if (value?.truncated) text += `\n…已截断，继续读：再次调用 doc=…&offset=${value?.nextOffset ?? 0}`
+        return [{ type: 'text', text }]
+      },
+    },
+    async execute(args) {
+      const r = readSkillDoc(args?.doc, { offset: args?.offset })
+      if (r.ok === false && typeof r.error === 'string' && r.error.startsWith('未知文档')) {
+        r.suggestions = listSkillDocs().files.slice(0, 60)
+      }
+      return r
+    },
+  })
+}
+
 /** 紧急保存：把 agent 在画板上做的内容抓到本地（断连也能保留最后步骤）。 */function edaSnapshotTool(handle, backend) {
   return defineTool({
     name: 'eda_snapshot',
@@ -1071,6 +1395,10 @@ export function apply(ctx, config) {
         edaExecTool(backend),
         edaPickSpotTool(backend),
         edaCapabilitiesTool(),
+        edaSkillReadTool(),
+        edaBoardOverviewTool(backend),
+        edaTraceTool(backend),
+        edaVerifyTool(edaHandle, backend),
         edaSnapshotTool(edaHandle, backend),
         bridgeTool(edaHandle, backend, {
           name: 'eda_sch_drc',

package/lib/installer.js

@@ -70,10 +70,10 @@ async function copyDir(src, dst) {
 }
 
 /**
- * Locate an existing `ws` package on this machine (the DSH host ships it via
- * dsh-logcat's dependency) so we can vendor it WITHOUT npm — this machine has
- * PowerShell ExecutionPolicy blocking `npm.ps1`, and offline copy is faster
- * and never touches the registry.
+ * Locate an existing `ws` package on this machine (the DSH host ships it) so
+ * we can vendor it WITHOUT npm — this machine has PowerShell ExecutionPolicy
+ * blocking `npm.ps1`, and offline copy is faster and never touches the
+ * registry.
  */
 export async function findExistingWs() {
   const profiles = join(homedir(), '.dsh', 'profiles')

package/lib/skill.js

@@ -0,0 +1,138 @@
+/**
+ * dsh-lichuang-eda — 官方 EasyEDA skill 知识库查阅（eda_skill_read 数据源）。
+ *
+ * 官方 skill 知识文档已完整 vendored 在 <包根>/skill/ 下（SKILL.md 总纲、
+ * README.official.md、README.zh-Hans.official.md、references/classes/*.md 逐类
+ * API、references/enums|types|interfaces、guide/、user-guide/、format/）。本模块提供
+ * 三类能力，让 agent 在对话里直接用工具读取任意官方文档（不依赖文件权限）：
+ *   - resolveDoc(doc)：把用户给出的相对 doc 规范化并安全解析为 SKILL_ROOT 内的绝对路径；
+ *   - readSkillDoc(doc, opts)：读取文档全文并支持按字符偏移分页；
+ *   - listSkillDocs()：枚举全部可查阅文档（相对 SKILL_ROOT，按目录分组排序，上限 400）。
+ *
+ * 安全性：doc 会做正斜杠/去前导斜杠/normalize 规范化，拒绝含 '..' 或空字节的输入
+ * （防路径穿越），且最终绝对路径必须位于 SKILL_ROOT 内且是存在的文件。
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, dirname, normalize, relative, isAbsolute, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 官方 skill 知识根目录（<包根>/skill），基于本文件位置计算，不硬编码盘符。 */
+export const SKILL_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', 'skill')
+
+/** listSkillDocs 返回的文件数上限。 */
+const MAX_DOCS = 400
+
+/** 默认总览文档名（无 INDEX.md 时列表里以实际顶层 md 为准）。 */
+const DEFAULT_DOC = 'INDEX.md'
+
+/** 把绝对路径转成相对 SKILL_ROOT 的、用正斜杠分隔的文档路径。 */
+function toRelSlash(absPath) {
+  return relative(SKILL_ROOT, absPath).split(sep).join('/')
+}
+
+/**
+ * 规范化并安全解析一个文档相对路径 → 返回 SKILL_ROOT 内存在的文件绝对路径；否则 null。
+ *  - 正斜杠、去前导斜杠、normalize；
+ *  - 含 '..' 或空字节 → null（防路径穿越）；
+ *  - 最终路径必须位于 SKILL_ROOT 内且是存在的文件 → 否则 null。
+ */
+export function resolveDoc(doc = DEFAULT_DOC) {
+  let d = typeof doc === 'string' ? doc : String(doc ?? '')
+  d = d.replace(/\\/g, '/').replace(/^\/+/, '')
+  if (d === '') return null // 显式空串无效（只有 undefined/缺省走 DEFAULT_DOC）
+  if (d.includes('\0')) return null
+  if (d.split('/').includes('..')) return null
+  const norm = normalize(d) // 在 Windows 上产生反斜杠分隔
+  if (norm.split(sep).includes('..')) return null
+  const full = join(SKILL_ROOT, norm)
+  const rel = relative(SKILL_ROOT, full)
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null
+  try {
+    return statSync(full).isFile() ? full : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 读取一份官方 skill 文档，支持按字符偏移分页。
+ *  - doc 未命中 → { ok:false, error:'未知文档: <doc>（INDEX.md 可看总览）' }；
+ *  - 命中 → { ok:true, doc, path, len, start, content, truncated, nextOffset }。
+ */
+export function readSkillDoc(doc, { offset = 0, maxChars = 12000 } = {}) {
+  const effDoc = (typeof doc === 'string' && doc.trim() !== '') ? doc : DEFAULT_DOC
+  const resolved = resolveDoc(doc)
+  if (!resolved) {
+    return { ok: false, error: `未知文档: ${effDoc}（${DEFAULT_DOC} 可看总览）` }
+  }
+  let text
+  try {
+    text = readFileSync(resolved, 'utf8')
+  } catch (error) {
+    return { ok: false, error: `读取失败: ${error instanceof Error ? error.message : String(error)}` }
+  }
+  const len = text.length
+  const start = Number.isFinite(Number(offset)) && Number(offset) > 0 ? Math.floor(Number(offset)) : 0
+  const sliceLen = Number.isFinite(Number(maxChars)) && Number(maxChars) > 0 ? Math.floor(Number(maxChars)) : 12000
+  const end = Math.min(len, start + sliceLen)
+  const content = text.slice(start, end)
+  const truncated = end < len
+  return {
+    ok: true,
+    doc: toRelSlash(resolved),
+    path: resolved,
+    len,
+    start,
+    content,
+    truncated,
+    nextOffset: end,
+  }
+}
+
+/** 递归收集目录下的全部 .md（onlyTop=true 时仅列直接文件），返回相对 SKILL_ROOT 的数组。 */
+function collectMd(dir, onlyTop) {
+  const out = []
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name)
+    if (onlyTop) {
+      if (e.isFile() && e.name.endsWith('.md')) out.push(toRelSlash(full))
+    } else if (e.isDirectory()) {
+      out.push(...collectMd(full, false))
+    } else if (e.isFile() && e.name.endsWith('.md')) {
+      out.push(toRelSlash(full))
+    }
+  }
+  return out.sort()
+}
+
+/**
+ * 枚举全部可查阅的官方 skill 文档（相对 SKILL_ROOT）。
+ * 构成：顶层 .md（如 SKILL.md、README.official.md、README.zh-Hans.official.md）
+ *      + references/classes/*.md 全部
+ *      + references/enums、types、interfaces 下 md
+ *      + references/ 下的索引（_index.md、_quick-reference.md）
+ *      + guide、user-guide、format 下 md（含子目录）。
+ * 按目录分组排序，最多 MAX_DOCS 条。
+ */
+export function listSkillDocs() {
+  const groups = [
+    { dir: SKILL_ROOT, onlyTop: true },
+    { dir: join(SKILL_ROOT, 'references', 'classes'), onlyTop: false },
+    { dir: join(SKILL_ROOT, 'references', 'enums'), onlyTop: false },
+    { dir: join(SKILL_ROOT, 'references', 'types'), onlyTop: false },
+    { dir: join(SKILL_ROOT, 'references', 'interfaces'), onlyTop: false },
+    { dir: join(SKILL_ROOT, 'references'), onlyTop: true },
+    { dir: join(SKILL_ROOT, 'guide'), onlyTop: false },
+    { dir: join(SKILL_ROOT, 'user-guide'), onlyTop: false },
+    { dir: join(SKILL_ROOT, 'format'), onlyTop: false },
+  ]
+  const files = []
+  for (const g of groups) files.push(...collectMd(g.dir, g.onlyTop))
+  return { count: Math.min(files.length, MAX_DOCS), files: files.slice(0, MAX_DOCS) }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@windypro-rourou/dsh-eda",
-  "description": "嘉立创 EDA 助手（dsh-lichuang-eda）——面向 0 基础开发者，在 DSH Web GUI 里自动生成嘉立创 EDA（专业版/标准版）原理图/PCB 草图的插件。当前为可加载的骨架版本：DSH 插件表面（提供服务、HTTP 路由、agent 工具、系统提示通告、浏览器面板）已接通，EDA 后端尚未接入（backend: not-wired）。Hot-pluggable — mounted via profile cordis.patch.yml + profile node_modules copy, no dsh source changes.",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -35,6 +35,7 @@
   "files": [
     "lib/**/*.js",
     "src/**/*.js",
+    "skill/**/*.md",
     "cordis.patch.yml",
     "README.md"
   ],