dsh-ensp 0.1.6 → 0.1.7

package/docs/UI-ANCHORS.md

@@ -63,6 +63,58 @@
 | 窗口在后台也能点 | **不可**；遮挡/最小化状态下驱动会让进程退出。必须先置前、操作完再最小化 |
 | `FindWindowW('eNSP_Client')` 可定位 | **不可靠**；标题随拓扑变化，改拓扑后取不到 |
 
+## 遮挡是硬失败，不是可重试的小问题
+
+合成点击落在**拥有那个像素的窗口**上，不是落在我们以为的窗口上。当别的程序盖住 eNSP 时，
+鼠标事件全被那个程序接走，eNSP 一条都没收到；而每一步都会报成功，调用方于是去等一批从未启动的设备。
+这不是理论问题：一次实测里，全屏 VMware 窗口正压在 eNSP 上，`(992,84)` 这个点的属主是
+`vmware-vmx`（PID 9948），点击返回 `ok:true` 而 `VBoxManage list runningvms` 全程为空。
+
+所以插件在**点击前**先用 `WindowFromPoint` + `GetAncestor(GA_ROOT)` 查落点属主：
+
+- 属主 PID ≠ eNSP PID → 不点击，抛错并点名挡路进程（`eNSP is covered by vmware (unknown) at 1307,426 ...`）
+- `startAllDevices` 在标定之前还会用一张 5×4 的采样网格扫整个窗口；只要有任何一点被外人占住就拒绝开始，
+  因为标定是**拍照**，被遮挡时量出来的是别人的像素，锚点全错
+- 点击之后会再查一次属主（`STOLEN` 情形），防止点击瞬间被抢走
+
+### 为什么不能自动置顶
+
+这里有两层独立的拦截，缺一层都解释不通实测结果。
+
+**第一层：UIPI。** eNSP 的 exe 内嵌 manifest 写死 `<requestedExecutionLevel level="requireAdministrator">`，
+所以它总以 **High 完整性**运行；普通 shell 是 **Medium**。Windows 的 UIPI 禁止低完整性进程向高完整性
+窗口投递输入类消息，因此从 Medium 上下文：
+
+| 调用 | 结果 |
+|---|---|
+| `SendMessage(hwnd, WM_MOUSEMOVE=0x200)` | `ret=0 err=5`（ERROR_ACCESS_DENIED） |
+| `SendMessage(hwnd, WM_LBUTTONDOWN=0x201)` | `ret=0 err=5` |
+| `PostMessage(hwnd, WM_MOUSEMOVE)` | `ok=False err=5` |
+| `SendMessage(hwnd, WM_GETTEXT=0xD)` / `WM_NULL` | `err=0`（只读消息能过，输入消息被拦） |
+| `ShowWindow` / `BringWindowToTop` / `SetWindowPos` | `err=5` |
+| `GetCursorPos` / `SetCursorPos` | `err=203` |
+
+**第二层：前台锁。** 用 `Start-Process -Verb RunAs` 提到 High 之后（本机 UAC 是
+`ConsentPromptBehaviorAdmin=0`，提升不弹窗），UIPI 那层就放行了——`SendMessage` 的 errno 从 5 变成 183，
+`BringWindowToTop` 甚至返回 `True`。但前台窗口仍是别的进程，`SetForegroundWindow` 依然 `False`、
+`SetCursorPos` 依然 `False`。原因是 Windows 的前台锁：只有“当前拥有前台权限”的进程才能改前台，
+一个刚从后台起来的进程没有这个权限，`AttachThreadInput` 也拿不到（`attach=False err=5`）。
+
+已排除“不同窗口站/桌面”：`GetProcessWindowStation()` = `WinSta0`、`GetThreadDesktop()` = `Default`、
+`OpenInputDesktop(0,false,0x0001)` 返回的桌面名也是 `Default`；所有进程 `SessionId` 均为 1，
+`WTSGetActiveConsoleSessionId()` 也是 1。也排除了 Job 限制：
+`QueryInformationJobObject(JobObjectBasicUIRestrictions)` 返回 `flags=0x0`。
+
+另一条路也堵着：`PrintWindow` 从 Medium 上下文返回全白（`ok=False`），从 High 上下文**能**拍到真画布
+（这是唯一一处提权有实质收益的地方），但拍到画面不等于能把点击送进去。
+
+结论：**eNSP 窗口必须由用户自己保持在最上层，并且用户得在那个桌面上**。插件能做的是尽早、明确、
+可操作地报错，而不是点空了继续等。这也是 `ensp up` 要求“启动时短暂占用前台”的真实原因。
+
+顺带一条实测结论，用来排除“是不是该提权”：**提权解决不了这件事**。提到 High 只换来
+`PrintWindow` 能拍到画布，点击仍进不去（前台锁），而代价是每次运行都要过一次 UAC
+（本机静默，别人机器不一定）。所以插件不提权，也不建议用户“用管理员身份运行”。
+
 ## 设备控制台
 
 | 项 | 值 |

package/docs/plugin-detail.en.md

@@ -3,10 +3,11 @@
 
 Automation for Huawei eNSP: generate topologies, boot devices, push configuration line by line and verify every command's result.
 
-- Generates `.topo` files eNSP opens directly, from built-in scenarios or custom devices and links
+- Generates `.topo` files eNSP opens directly, from a scenario blueprint (devices, links and addressing included) or from custom devices and links
 - Locates the toolbar buttons to start and stop devices, confirms each one individually, then minimises the window
 - Pushes configuration one command at a time; the first error aborts the batch and reports the line, the command and the device's raw output
-- Ships 23 scenario presets covering VLAN, STP, routing, BGP, NAT, ACL, IPsec, IPv6, WLAN and IS-IS
+- Ships 50 scenario presets covering VLAN, STP, stacking, link aggregation, routing, BGP, MPLS, multicast, NAT, ACL, QoS, IPsec, IPv6, WLAN, firewalls and high availability
+- Checks that every device image is installed before launching, and names the missing component instead of letting eNSP open the topology and quit silently
 - Usable as a CLI, an MCP server, or a DeepSeek Harness plugin
 
 Scroll down and open "dsh-ensp>" under the included components to reach its settings.

package/docs/plugin-detail.zh.md

@@ -3,10 +3,11 @@
 
 面向华为 eNSP 的自动化工具：生成拓扑、启动设备、逐条下发配置并核对每条命令的结果。
 
-- 生成 eNSP 可直接打开的 `.topo` 文件，支持内置场景与自定义设备、链路
+- 直接生成 eNSP 可打开的 `.topo` 文件，可用场景蓝图（含设备、链路、地址规划）或自定义设备与连线
 - 自动定位工具栏按钮完成设备启停，启动后按设备逐一确认就绪，窗口随即最小化
 - 逐条下发配置，任一命令出错即中断并回报行号、命令与设备原始输出
-- 内置 23 个场景预设，覆盖 VLAN、STP、路由、BGP、NAT、ACL、IPsec、IPv6、WLAN、IS-IS 等主题
+- 内置 50 个场景预设，覆盖 VLAN、STP、堆叠、链路聚合、路由、BGP、MPLS、组播、NAT、ACL、QoS、IPsec、IPv6、WLAN、防火墙与高可用等主题
+- 启动前检查机型镜像是否齐全，缺镜像时直接说明缺哪个组件，而不是让 eNSP 打开后静默退出
 - 提供 CLI、MCP Server 与 DeepSeek Harness 插件三种调用方式
 
 向下翻页后点击“包含的组件”内的“dsh-ensp>”进入设置界面。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ensp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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",
@@ -43,8 +43,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test",
-    "probe": "node src/cli/ensp.mjs probe"
+    "test": "node --test \"tests/**/*.test.mjs\"",
+    "probe": "node src/cli/ensp.mjs probe",
+    "docs": "node scripts/gen-scenarios-doc.mjs",
+    "docs:check": "node scripts/gen-scenarios-doc.mjs --check"
   },
   "engines": {
     "node": ">=18"

package/scripts/gen-scenarios-doc.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Regenerate `docs/SCENARIOS.md` from `src/core/presets.mjs`.
+ *
+ * The doc used to be maintained by hand, which meant the count in the heading
+ * drifted away from the catalogue every time a scenario was added. It is now a
+ * build product: run this after editing presets, and the same script validates
+ * the catalogue before writing anything.
+ *
+ *   node scripts/gen-scenarios-doc.mjs          # rewrite docs/SCENARIOS.md
+ *   node scripts/gen-scenarios-doc.mjs --check  # fail if the file is stale
+ */
+
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { SCENARIOS, SCENARIO_IDS, byLevel } from '../src/core/presets.mjs'
+import { LABS, LAB_IDS, hasLab, labAddressing, labDevices, labModels } from '../src/core/labs.mjs'
+import { imageNotesFor } from '../src/core/compat.mjs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const root = path.resolve(here, '..')
+const target = path.join(root, 'docs', 'SCENARIOS.md')
+
+const LEVEL_TITLES = { basic: '基础', intermediate: '进阶', advanced: '高级' }
+const REQUIRED = ['title', 'titleEn', 'level', 'source', 'devices', 'goal']
+
+/**
+ * Validate every entry. A broken catalogue should stop the build rather than
+ * silently produce a doc missing a scenario.
+ *
+ * @returns {string[]} problems, empty when the catalogue is sound
+ */
+export function validateScenarios(catalogue = SCENARIOS) {
+  const problems = []
+  const ids = Object.keys(catalogue)
+  const seenTitles = new Map()
+
+  for (const id of ids) {
+    const s = catalogue[id]
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(id)) {
+      problems.push(`${id}: id must be kebab-case`)
+    }
+    for (const field of REQUIRED) {
+      if (!s?.[field] || typeof s[field] !== 'string') {
+        problems.push(`${id}: missing ${field}`)
+      }
+    }
+    if (!LEVEL_TITLES[s?.level]) {
+      problems.push(`${id}: level must be basic, intermediate or advanced (got ${s?.level})`)
+    }
+    if (!Array.isArray(s?.steps) || s.steps.length === 0) {
+      problems.push(`${id}: needs at least one step`)
+    } else {
+      s.steps.forEach((step, i) => {
+        if (!step?.do || typeof step.do !== 'string') problems.push(`${id}: step ${i + 1} has no "do"`)
+        if (step?.detail !== undefined && typeof step.detail !== 'string') {
+          problems.push(`${id}: step ${i + 1} detail must be a string`)
+        }
+        if (step?.verify !== undefined && typeof step.verify !== 'string') {
+          problems.push(`${id}: step ${i + 1} verify must be a string`)
+        }
+      })
+    }
+    if (!Array.isArray(s?.pitfalls) || s.pitfalls.length === 0) {
+      problems.push(`${id}: needs at least one pitfall`)
+    }
+
+    const titleKey = `${s?.title}\u0000${s?.titleEn}`
+    if (seenTitles.has(titleKey)) {
+      problems.push(`${id}: duplicate title of ${seenTitles.get(titleKey)}`)
+    } else {
+      seenTitles.set(titleKey, id)
+    }
+  }
+  for (const id of LAB_IDS) {
+    if (!catalogue[id]) problems.push(`${id}: topology blueprint with no matching scenario`)
+  }
+  return problems
+}
+
+function render(catalogue = SCENARIOS) {
+  const groups = byLevel()
+  const out = [
+    `# 场景预设（${SCENARIO_IDS.length} 个）`,
+    '',
+    '由 `scripts/gen-scenarios-doc.mjs` 从 `src/core/presets.mjs` 与 `src/core/labs.mjs` 生成，勿手改。',
+    '',
+    '每个场景只给**方向、顺序、验证命令**，不给成品命令块。',
+    '',
+    `其中 ${LAB_IDS.length} 个带拓扑蓝图，可直接生成 \`.topo\`：`,
+    '',
+    '```',
+    'ensp preset ospf-single --topo ospf-single.topo',
+    'ensp up ospf-single.topo',
+    '```',
+  ]
+
+  for (const level of ['basic', 'intermediate', 'advanced']) {
+    out.push('', `## ${LEVEL_TITLES[level]}`, '')
+    for (const id of groups[level]) {
+      const s = catalogue[id]
+      out.push(`### ${id} — ${s.title}`, '')
+      out.push(`- **英文名**：${s.titleEn}`)
+      out.push(`- **来源**：${s.source}`)
+      out.push(`- **设备**：${s.devices}`)
+      out.push(`- **目标**：${s.goal}`)
+      out.push('', '**配置顺序**', '')
+      s.steps.forEach((step, i) => {
+        const detail = step.detail ? ` — ${step.detail}` : ''
+        out.push(`${i + 1}. **${step.do}**${detail}`)
+        if (step.verify) out.push(`   - 验证：\`${step.verify}\``)
+      })
+      if (s.pitfalls?.length) {
+        out.push('', '**易错点**', '')
+        for (const p of s.pitfalls) out.push(`- ${p}`)
+      }
+      if (hasLab(id)) {
+        out.push('', '**拓扑蓝图**', '')
+        out.push(`- 设备：${labDevices(id).join('、')}`)
+        const links = LABS[id].links.length
+        out.push(`- 链路：${links} 条`)
+        const addressing = labAddressing(id)
+        if (addressing.length) {
+          out.push('', '| 设备 | 接口 | 地址 | 说明 |', '| --- | --- | --- | --- |')
+          for (const row of addressing) {
+            out.push(`| ${row.device} | ${row.port} | ${row.ip} | ${row.note || ''} |`)
+          }
+        }
+        out.push('', `生成：\`ensp preset ${id} --topo ${id}.topo\``)
+        const notes = imageNotesFor(labModels(id))
+        for (const [model, note] of notes) out.push(`- 设备镜像：${model} ${note}`)
+      }
+      out.push('')
+    }
+  }
+  return `${out.join('\n').replace(/\n+$/, '')}\n`
+}
+
+const problems = validateScenarios()
+if (problems.length) {
+  console.error(`catalogue invalid (${problems.length}):`)
+  for (const p of problems) console.error(`  - ${p}`)
+  process.exit(1)
+}
+
+// Only act when run directly. Tests import `validateScenarios` from this file, and
+// an unguarded body would rewrite docs/SCENARIOS.md as a side effect of importing.
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (invokedDirectly) {
+  const next = render()
+  const check = process.argv.includes('--check')
+
+  if (check) {
+    let current = ''
+    try {
+      current = await readFile(target, 'utf8')
+    } catch {
+      current = ''
+    }
+    if (current !== next) {
+      console.error('docs/SCENARIOS.md is stale; run `node scripts/gen-scenarios-doc.mjs`')
+      process.exit(1)
+    }
+    console.log(`docs/SCENARIOS.md is current (${SCENARIO_IDS.length} scenarios)`)
+  } else {
+    await writeFile(target, next, 'utf8')
+    console.log(`wrote docs/SCENARIOS.md (${SCENARIO_IDS.length} scenarios)`)
+  }
+}