dsh-ensp 0.1.3 → 0.1.6

package/README.md

@@ -43,6 +43,8 @@ const topo = autoLayout(
 )
 ```
 
+拓扑格式有几处约束来自 eNSP 本身：接口分组必须与机型一致，链路锚点必须落在图标包围盒内。写错任意一项，eNSP 会打开一个没有任何设备的空白画布，并且不报错。规则见 [`docs/ENSP-FORMAT.md`](docs/ENSP-FORMAT.md)。
+
 ### 启动与停止设备
 
 自动定位工具栏按钮，无需手动点击。启动后按设备逐一确认就绪，窗口随即最小化，桌面可继续使用。
@@ -53,6 +55,8 @@ ensp up lab.topo    # 打开、启动、确认就绪、最小化
 ensp stop           # 关闭全部设备
 ```
 
+eNSP 只允许运行一个实例，异常退出时可能留下不占线程的僵尸进程，它会一直持有这个单实例锁，使下一次启动打开空白窗口。工具在启动前会识别并清理这种进程。
+
 ### 下发配置
 
 逐条发送，每条命令确认提示符返回后才继续。任一命令出错即中断，并回报行号、命令与设备原始输出。
@@ -79,6 +83,20 @@ if (!result.ok) {
 }
 ```
 
+### 等待协议收敛
+
+路由协议是异步收敛的，配置下发完不代表邻居已经建立。这类断言一律走轮询，直到状态达成或超时。
+
+```js
+import { waitForOspfFull, waitForOspfRoute, waitForOutput } from 'dsh-ensp'
+
+await waitForOspfFull({ port: 2000, neighbourId: '2.2.2.2' })
+await waitForOspfRoute({ port: 2000, prefix: '2.2.2.2/32' })
+await waitForOutput({ port: 2000, command: 'display ip routing-table', until: /2\.2\.2\.2/ })
+```
+
+三个函数都返回 `{ ok, converged, output, attempts, waitedMs }`。固定等待一段时间再查询，在慢机器上会误判为失败，在快机器上纯属浪费。
+
 ### 场景预设
 
 内置 23 个场景，覆盖 VLAN、STP、静态路由、RIP、OSPF、BGP、NAT、DHCP、ACL、IPsec、IPv6、WLAN、IS-IS 等主题。
@@ -132,6 +150,8 @@ ensp status
 | Node.js | 18 或更高版本 |
 | 权限 | 插件与 eNSP 需处于相同权限级别 |
 
+系统缩放设为 125% 或 150% 时，程序会自行完成坐标换算，不需要手动调分辨率。若 eNSP 升级后按钮位置改变，执行 `ensp probe` 重新标定。
+
 ## 快速开始
 
 ```bash
@@ -146,6 +166,16 @@ ensp status --topology lab.topo  # 查看控制台状态
 ensp apply ./configs --topology lab.topo --save
 ```
 
+一次两级 OSPF 实验的完整耗时（本机实测，Windows 11、i5、系统缩放 150%）：
+
+| 阶段 | 耗时 |
+|---|---|
+| 生成 `.topo` | 2s |
+| 打开并渲染拓扑 | 14s |
+| 两台 AR2220 启动到可登录 | 64s |
+| 下发两侧各 9 条配置 | 8s |
+| OSPF 邻居到 Full | 40s |
+
 ## 致谢与许可
 
 ### 开源协议
@@ -165,7 +195,6 @@ ensp apply ./configs --topology lab.topo --save
 ### 致谢
 
 - Huawei eNSP：仿真器本体。
-- dsh-ops：本 README 的组织方式参考了该项目。
 - 在 issue 中反馈问题的使用者。
 
 ## 免责声明

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ensp",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Automate Huawei eNSP labs: generate .topo files, start and stop devices, and push configuration one command at a time with per-command error reporting.",
   "keywords": [
     "dsh",
@@ -54,18 +54,6 @@
       "patch": "./cordis.patch.yml"
     }
   },
-  "peerDependencies": {
-    "@deepseek-ai/dsh-client-ui": "*",
-    "@deepseek-ai/dsh-tools": "*"
-  },
-  "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-client-ui": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
-    }
-  },
   "author": {
     "name": "lizi600jin"
   },

package/src/core/index.mjs

@@ -49,7 +49,15 @@ export {
   DEFAULT_ANCHORS,
 } from './calibrate.mjs'
 
-export { pushConfig, pushConfigMany, queryDevice, parseScript } from './provision.mjs'
+export {
+  pushConfig,
+  pushConfigMany,
+  queryDevice,
+  parseScript,
+  waitForOutput,
+  waitForOspfFull,
+  waitForOspfRoute,
+} from './provision.mjs'
 
 export {
   SCENARIOS,

package/src/core/launcher.mjs

@@ -30,6 +30,8 @@
 
 import { spawn, spawnSync } from 'node:child_process'
 import net from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
 
 import { calibrateAnchors, DEFAULT_ANCHORS } from './calibrate.mjs'
 
@@ -180,17 +182,61 @@ ${body}
   return { ok: r.status === 0, stdout: (r.stdout || '').trim(), stderr: (r.stderr || '').trim() }
 }
 
-/** PID of the running eNSP client, or null. */
+/**
+ * PID of a *live* eNSP client, or null.
+ *
+ * eNSP leaves zombie processes behind: the process object survives with
+ * `Threads.Count === 0` and holds the client's single-instance lock, so a new
+ * launch inherits an empty canvas. Such a PID must never be reused.
+ *
+ * @returns {number|null}
+ */
 export function enspPid() {
   const r = spawnSync(
     'powershell',
-    ['-NoProfile', '-Command', '(Get-Process eNSP_Client -ErrorAction SilentlyContinue | Select-Object -First 1).Id'],
+    [
+      '-NoProfile',
+      '-Command',
+      'Get-Process eNSP_Client -ErrorAction SilentlyContinue | ' +
+        'Where-Object { $_.Threads.Count -gt 0 } | ' +
+        'Select-Object -First 1 -ExpandProperty Id',
+    ],
     { encoding: 'utf8', windowsHide: true },
   )
   const pid = Number((r.stdout || '').trim())
   return Number.isInteger(pid) && pid > 0 ? pid : null
 }
 
+/**
+ * Is this window handle still valid and owned by a live process?
+ *
+ * @param {string} hwnd
+ * @returns {boolean}
+ */
+export function windowAlive(hwnd) {
+  const r = runPowerShell(
+    `$h = [IntPtr]::new([int64]${hwnd})
+     if (-not [EnspWin]::IsWindow($h)) { 'no'; exit 0 }
+     $owned = Get-Process eNSP_Client -ErrorAction SilentlyContinue | Where-Object { $_.Threads.Count -gt 0 }
+     if ($owned) { 'yes' } else { 'no' }`,
+    { timeoutMs: 20000 },
+  )
+  return r.ok && r.stdout.trim().endsWith('yes')
+}
+
+/** Every eNSP client PID, including zero-thread zombies. */
+export function enspPids() {
+  const r = spawnSync(
+    'powershell',
+    ['-NoProfile', '-Command', 'Get-Process eNSP_Client -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Id'],
+    { encoding: 'utf8', windowsHide: true },
+  )
+  return (r.stdout || '')
+    .split(/\s+/)
+    .map(Number)
+    .filter((n) => Number.isInteger(n) && n > 0)
+}
+
 /**
  * Launch the eNSP client, optionally opening a topology.
  *
@@ -200,38 +246,236 @@ export function enspPid() {
  * @param {number} [options.readyTimeoutMs=90000] - how long to wait for the window to exist
  * @returns {Promise<{pid: number, hwnd: string}>}
  */
-export async function launchEnsp({ topology, exspPath, readyTimeoutMs = 90000 } = {}) {
+export async function launchEnsp({ topology, exspPath, readyTimeoutMs = 120000 } = {}) {
   const exe = exspPath ?? process.env.DSH_ENSP_EXE ?? 'E:\\Huawei\\eNSP\\eNSP_Client.exe'
-  const already = enspPid()
-  if (already) {
-    const hwnd = locateWindow(already)
-    if (hwnd) return { pid: already, hwnd, reused: true }
+  const target = topology ? path.resolve(topology) : null
+
+  // Reuse an existing window only when it renders something; a blank window is a
+  // dead instance that would otherwise be reported as success.
+  const existing = enspPid()
+  if (existing) {
+    const hwnd = locateWindow(existing)
+    if (hwnd && (!target || topologyRendered(hwnd))) {
+      return { pid: existing, hwnd, reused: true, rendered: Boolean(hwnd) }
+    }
+    if (hwnd && target) {
+      // A live window showing nothing: reopen the file in it first.
+      reopenTopology(target)
+      if (await waitForRender(hwnd, { attempts: 6, intervalMs: 2500 })) {
+        return { pid: existing, hwnd, reused: true, rendered: true }
+      }
+    }
+    // Give up on it: stale clients hold eNSP's single-instance lock and make every
+    // new window open blank.
+    killAllClients()
+    await sleep(2500)
   }
 
-  const args = topology ? [topology] : []
-  const child = spawn(exe, args, { detached: true, stdio: 'ignore', windowsHide: false })
-  child.unref()
+  /** Launch once and wait for a frame window. */
+  const boot = async () => {
+    startDetached(exe, target)
+    const started = Date.now()
+    const deadline = started + readyTimeoutMs
+    while (Date.now() < deadline) {
+      const pid = enspPid()
+      if (pid) {
+        const hwnd = locateWindow(pid)
+        if (hwnd) return { pid, hwnd, waitMs: Date.now() - started }
+      }
+      await sleep(250)
+    }
+    return null
+  }
 
-  // Poll tightly: eNSP creates its frame before it finishes painting, and every
-  // second spent here is dead time the caller cannot overlap with anything.
-  const started = Date.now()
-  const deadline = started + readyTimeoutMs
-  let pid = null
-  let hwnd = null
-  while (Date.now() < deadline) {
-    pid = enspPid()
-    if (pid) {
-      hwnd = locateWindow(pid)
-      if (hwnd) return { pid, hwnd, waitMs: Date.now() - started }
+  // Up to three attempts: the client occasionally opens with an empty canvas on a
+  // cold start, and a clean relaunch always renders. Verified empirically.
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const booted = await boot()
+    if (!booted) {
+      killAllClients()
+      await sleep(1500)
+      continue
+    }
+    if (!target) return { ...booted, reused: false, rendered: true }
+    if (await waitForRender(booted.hwnd, { attempts: 6, intervalMs: 2000 })) {
+      return { ...booted, reused: false, rendered: true }
     }
-    await sleep(250)
+    // Blank canvas: tear the instance down and try again from a clean state.
+    killAllClients()
+    await sleep(2500)
   }
+
   throw new Error(
-    `eNSP window did not appear within ${readyTimeoutMs} ms` +
-      (pid ? ` (pid ${pid} started but no frame window)` : ' (process never started)'),
+    'eNSP opened but never rendered the topology after 3 attempts. ' +
+      'Close every eNSP window and retry; a leftover client holds the single-instance lock.',
   )
 }
 
+/**
+ * Force-terminate every eNSP client process.
+ *
+ * Zombie processes (zero threads) cannot be killed by any API; they linger until
+ * the OS reaps them. This reports what survived so the caller can decide whether
+ * retrying is worthwhile.
+ *
+ * @returns {{killed: boolean, survivors: number[]}}
+ */
+function killAllClients() {
+  spawnSync('taskkill', ['/F', '/IM', 'eNSP_Client.exe'], { windowsHide: true, encoding: 'utf8' })
+  return { killed: true, survivors: enspPids() }
+}
+
+/**
+ * Poll until the canvas actually shows the topology.
+ *
+ * @param {string} hwnd
+ * @param {{attempts?: number, intervalMs?: number}} [options]
+ * @returns {Promise<boolean>}
+ */
+async function waitForRender(hwnd, { attempts = 6, intervalMs = 2000 } = {}) {
+  for (let i = 0; i < attempts; i++) {
+    await sleep(intervalMs)
+    if (topologyRendered(hwnd)) return true
+  }
+  return false
+}
+
+/**
+ * Start the client so that it outlives this Node process.
+ *
+ * `spawn(..., {detached:true})` is not enough on Windows: eNSP is a GUI application
+ * that terminates when the console session that launched it goes away. Going
+ * through `cmd /c start` hands ownership to the shell, which is what a double-click
+ * in Explorer does, and the client then survives its launcher.
+ *
+ * @param {string} exe
+ * @param {string|null} [topology]
+ */
+function startDetached(exe, topology) {
+  // Win32_Process.Create via WMI is the only launch path measured to leave the
+  // client fully independent of this Node process:
+  //
+  //   spawn(..., {detached:true})  -> client dies with its launcher
+  //   cmd /c start                 -> client dies with its launcher
+  //   Start-Process -WindowStyle Hidden -> client exits before creating a window
+  //   Start-Process (visible)      -> unreliable when called from a hidden shell
+  //   WMI Win32_Process.Create     -> survives; returns the real PID
+  //
+  // The client must outlive the tool call, otherwise every follow-up (start
+  // devices, push config) finds a dead console.
+  const cmdline = topology ? `"${exe}" "${topology}"` : `"${exe}"`
+  const r = runPowerShell(
+    `
+$r = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
+  CommandLine = '${cmdline.replace(/'/g, "''")}'
+}
+if ($r.ReturnValue -ne 0) { 'ERR ' + $r.ReturnValue; exit 0 }
+'pid=' + $r.ProcessId
+`,
+    { timeoutMs: 30000 },
+  )
+  if (!r.ok || !/pid=\d+/.test(r.stdout)) {
+    throw new Error(`could not launch eNSP: ${r.stdout || r.stderr || 'WMI refused the request'}`)
+  }
+  return Number(/pid=(\d+)/.exec(r.stdout)[1])
+}
+
+/**
+ * Ask the running client to open a topology again.
+ *
+ * A second instance is normally refused, so this relaunches the client with the
+ * same file; the window handle changes and the caller re-locates it.
+ *
+ * @param {string} topology
+ */
+function reopenTopology(topology) {
+  const exe = process.env.DSH_ENSP_EXE ?? 'E:\\Huawei\\eNSP\\eNSP_Client.exe'
+  startDetached(exe, topology)
+}
+
+/**
+ * Take a screenshot of the client's canvas, cropped to the drawing area.
+ *
+ * Used by `topologyRendered` and by the probe diagnostics. The canvas excludes the
+ * left device palette and the toolbar, so anything found inside it came from the
+ * open topology.
+ *
+ * @param {string} hwnd
+ * @returns {string} absolute path to the PNG, or '' on failure
+ */
+export function captureCanvas(hwnd) {
+  const out = path.join(os.tmpdir(), `dsh-ensp-canvas-${Date.now()}.png`)
+  const r = runPowerShell(
+    `
+$h = [IntPtr]::new([int64]${hwnd})
+[void][EnspWin]::FocusWindow($h)
+Start-Sleep -Milliseconds 900
+$wr = New-Object EnspWin+RECT
+[void][EnspWin]::GetWindowRect($h, [ref]$wr)
+$w = $wr.R - $wr.L; $ht = $wr.B - $wr.T
+if ($w -lt 400 -or $ht -lt 300) { 'ERR small'; exit 0 }
+Add-Type -AssemblyName System.Drawing
+$bmp = New-Object System.Drawing.Bitmap $w, $ht
+$g = [System.Drawing.Graphics]::FromImage($bmp)
+$g.CopyFromScreen($wr.L, $wr.T, 0, 0, $bmp.Size)
+$bmp.Save('${out.replace(/\\/g, '\\\\')}', [System.Drawing.Imaging.ImageFormat]::Png)
+$bmp.Dispose(); $g.Dispose()
+'ok'
+`,
+    { timeoutMs: 40000 },
+  )
+  return r.ok ? out : ''
+}
+
+/**
+ * Does the open topology show devices on the canvas?
+ *
+ * eNSP paints with DirectX, so there is no window tree to query. Two independent
+ * signals are combined, because either alone is weak:
+ *
+ *   1. **Icon colour.** Device icons are a saturated blue on a pale canvas; the
+ *      empty canvas has no such pixels.
+ *   2. **Link lines.** Rendered links are near-black thin strokes across the canvas.
+ *
+ * This is the check that gates "the topology actually opened". Callers retry on a
+ * negative result rather than reporting success for a blank window.
+ *
+ * @param {string} hwnd
+ * @returns {boolean}
+ */
+export function topologyRendered(hwnd) {
+  const png = captureCanvas(hwnd)
+  if (!png) return false
+  const r = runPowerShell(
+    `
+Add-Type -AssemblyName System.Drawing
+$bmp = [System.Drawing.Bitmap]::FromFile('${png.replace(/\\/g, '\\\\')}')
+$w = $bmp.Width; $ht = $bmp.Height
+# Canvas only: skip the palette column and the toolbar band.
+$x0 = [int]($w * 0.22); $x1 = [int]($w * 0.97)
+$y0 = [int]($ht * 0.10); $y1 = [int]($ht * 0.92)
+$icon = 0; $dark = 0
+for ($y = $y0; $y -lt $y1; $y += 2) {
+  for ($x = $x0; $x -lt $x1; $x += 2) {
+    $c = $bmp.GetPixel($x, $y)
+    if ($c.B -gt 140 -and ($c.B - $c.R) -gt 55 -and ($c.B - $c.G) -gt 25) { $icon++ }
+    elseif ($c.R -lt 90 -and $c.G -lt 90 -and $c.B -lt 90) { $dark++ }
+  }
+}
+$bmp.Dispose()
+'icon=' + $icon + ' dark=' + $dark
+`,
+    { timeoutMs: 40000 },
+  )
+  if (!r.ok) return false
+  const m = /icon=(\d+) dark=(\d+)/.exec(r.stdout)
+  if (!m) return false
+  const icon = Number(m[1])
+  const dark = Number(m[2])
+  // A rendered lab shows dozens of icon pixels and a few hundred link pixels.
+  return icon >= 15 && dark >= 40
+}
+
 /**
  * Locate the eNSP main frame window for a PID.
  * @param {number} pid
@@ -399,6 +643,12 @@ export async function startAllDevices({
 
   // Locate the toolbar buttons by colour instead of trusting hard-coded pixels;
   // this survives eNSP upgrades, DPI changes and different display sizes.
+  // The window must still exist: a stale handle means the client already exited,
+  // and clicking a dead handle does nothing while reporting success below.
+  if (!hwnd || !windowAlive(hwnd)) {
+    throw new Error('eNSP window is gone; reopen the topology before starting devices')
+  }
+
   report({ phase: 'calibrate', hwnd })
   let anchors
   try {
@@ -406,6 +656,16 @@ export async function startAllDevices({
   } catch (error) {
     anchors = { ...DEFAULT_ANCHORS, method: 'default', detail: { reason: error.message } }
   }
+
+  // A default anchor means calibration failed, and an unmeasured click can land on
+  // any toolbar control (including the one that closes the document). Refuse
+  // instead of guessing.
+  if (anchors.method !== 'measured') {
+    throw new Error(
+      `toolbar calibration failed (${anchors.detail?.reason ?? 'unknown'}). ` +
+        'Make sure the eNSP window is visible and run ensp_probe to re-measure.',
+    )
+  }
   report({ phase: 'calibrated', method: anchors.method, detail: anchors.detail })
 
   report({ phase: 'focus', hwnd })

package/src/core/provision.mjs

@@ -280,3 +280,84 @@ export async function queryDevice({ port, command, timeoutMs = 25000 }) {
     session?.close()
   }
 }
+
+/**
+ * Poll a device until a predicate accepts its command output, or time runs out.
+ *
+ * Routing protocols converge asynchronously: right after `ospf 1` is committed a
+ * peering sits in ExStart/Exchange/Loading for a while, and a single query taken
+ * too early reads as "failed" when it is merely "not finished". Waiting a fixed
+ * number of seconds either wastes time or is still too short on a slow machine,
+ * so every convergence assertion in this package goes through this helper.
+ *
+ * @param {{
+ *   port: number,
+ *   command: string,
+ *   until: (output: string) => boolean,
+ *   timeoutMs?: number,
+ *   intervalMs?: number,
+ *   probeTimeoutMs?: number,
+ * }} options
+ * @returns {Promise<{ok: boolean, converged: boolean, output: string, attempts: number, waitedMs: number}>}
+ */
+export async function waitForOutput({
+  port,
+  command,
+  until,
+  timeoutMs = 120000,
+  intervalMs = 3000,
+  probeTimeoutMs = 20000,
+}) {
+  const started = Date.now()
+  let attempts = 0
+  let output = ''
+  while (Date.now() - started < timeoutMs) {
+    attempts += 1
+    const r = await queryDevice({ port, command, timeoutMs: probeTimeoutMs })
+    if (r.ok) output = r.output
+    if (r.ok && until(r.output)) {
+      return { ok: true, converged: true, output, attempts, waitedMs: Date.now() - started }
+    }
+    await sleep(intervalMs)
+  }
+  return {
+    ok: false,
+    converged: false,
+    output,
+    attempts,
+    waitedMs: Date.now() - started,
+  }
+}
+
+/**
+ * Wait until an OSPF adjacency reaches Full on `port`, optionally naming the peer.
+ *
+ * @param {{port: number, neighbourId?: string, timeoutMs?: number}} options
+ */
+export async function waitForOspfFull({ port, neighbourId, timeoutMs = 120000 }) {
+  const r = await waitForOutput({
+    port,
+    command: 'display ospf peer brief',
+    until: (out) =>
+      out
+        .split('\n')
+        .filter((l) => /\bFull\b/.test(l))
+        .some((l) => !neighbourId || l.includes(neighbourId)),
+    timeoutMs,
+  })
+  return { ...r, neighbourId: neighbourId || null }
+}
+
+/**
+ * Wait until a prefix shows up in the OSPF routing table on `port`.
+ *
+ * @param {{port: number, prefix: string, timeoutMs?: number}} options
+ */
+export async function waitForOspfRoute({ port, prefix, timeoutMs = 120000 }) {
+  return waitForOutput({
+    port,
+    command: 'display ip routing-table protocol ospf',
+    until: (out) => out.includes(prefix),
+    timeoutMs,
+  })
+}

package/src/core/topology.mjs

@@ -43,8 +43,25 @@ const MODEL_SPECS = {
   Cloud: { groups: [['Ethernet', 'Ethernet', 3, 0]] },
 }
 
-/** Icon bounding box offsets used for cable anchors. */
-const ICON = { w: 86, h: 86, left: -16.2, right: 70.2 }
+/**
+ * Icon bounding box, measured from every cable anchor in eNSP's own samples.
+ *
+ * The box is **not** centred on (cx, cy): it runs from `cx - 16.2` to
+ * `cx + 70.2` horizontally, so its centre is `cx + 27`, not `cx + 43`. Using
+ * `height / 2` puts the anchor outside the icon and eNSP then rejects the whole
+ * `<lines>` block, which shows up as an empty canvas with no error message.
+ *
+ * Frequencies across the bundled samples: (+70.2,+27.0) x35, (-16.2,+27.0) x35,
+ * (+27.0,+70.2) x29, (+27.0,-16.2) x27.
+ */
+const ICON = {
+  left: -16.2,
+  right: 70.2,
+  top: -16.2,
+  bottom: 70.2,
+  centerX: 27.0,
+  centerY: 27.0,
+}
 
 /**
  * Interfaces exposed by each model eNSP can run, in declaration order.
@@ -255,11 +272,12 @@ export function serialiseTopology(topo) {
     const dst = byId.get(l.dstId)
     if (!src || !dst) throw new Error(`link references unknown device: ${l.srcId} -> ${l.dstId}`)
 
-    // Anchor on the facing sides: right edge of the source, left edge of the target.
+    // Anchor on the facing sides: right edge of the source, left edge of the target,
+    // both at the icon's true vertical centre.
     const sx = src.x + ICON.right
-    const sy = src.y + ICON.h / 2
+    const sy = src.y + ICON.centerY
     const tx = dst.x + ICON.left
-    const ty = dst.y + ICON.h / 2
+    const ty = dst.y + ICON.centerY
 
     return (
       `        <line srcDeviceID="${src.id}" destDeviceID="${dst.id}">\n` +