dsh-ensp 0.3.3 → 0.5.0

package/README.en.md

@@ -0,0 +1,339 @@
+<p align="center">
+  English | <a href="README.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-ensp"><img alt="npm" src="https://img.shields.io/npm/v/dsh-ensp?style=flat-square&color=6c5ce7"></a>
+  <a href="https://www.npmjs.com/package/dsh-ensp"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-ensp?style=flat-square&color=4b6fff"></a>
+  <a href="https://github.com/lizi600jin/dsh-ensp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/lizi600jin/dsh-ensp?style=flat-square&color=eab308"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-GPL--3.0--or--later-blue?style=flat-square"></a>
+</p>
+
+# dsh-ensp
+
+Automation for Huawei eNSP. Generates topologies, starts devices, pushes configuration in order, and checks the result of every command.
+
+Three calling modes share one core:
+
+- CLI: scripted batch operation
+- MCP server: for Claude Desktop, Cursor and similar clients
+- DeepSeek Harness plugin: model tools inside a session
+
+## Features
+
+### Generate topologies
+
+Writes `.topo` files that eNSP opens and renders correctly. Works with the built-in scenarios or with devices and links you define yourself.
+
+Model and interface layouts live in `src/core/models.mjs` and cover 16 models. When parsing a topology, port names come from the device's own `<interface>` block first; the same model can have a different port layout after an expansion card is added, and that declaration is the only reliable source.
+
+```js
+import { twoPcLab, writeTopology } from 'dsh-ensp'
+
+await writeTopology('lab.topo', twoPcLab({ vlan: 10 }))
+```
+
+```js
+import { buildTopology, autoLayout } from 'dsh-ensp'
+
+const topo = autoLayout(
+  buildTopology()
+    .add('R1', 'AR2220', { x: 180, y: 120 })
+    .add('R2', 'AR2220', { x: 460, y: 260 })
+    .link('R1', 'GigabitEthernet0/0/0', 'R2', 'GigabitEthernet0/0/0')
+    .finish()
+)
+```
+
+A few topology rules come from eNSP itself: interface groups must match the model, and link anchors must fall inside the icon bounding box. If any of them is wrong, eNSP opens a blank canvas and reports nothing. See [`docs/ENSP-FORMAT.md`](docs/ENSP-FORMAT.md).
+
+### Start and stop devices
+
+Locates the toolbar buttons automatically, so nothing has to be clicked by hand. After starting, it confirms each device one by one, then minimises the window so the desktop stays usable.
+
+```bash
+ensp probe          # re-calibrate the button positions
+ensp up lab.topo    # open, start, confirm each device, minimise
+ensp stop           # shut every device down
+```
+
+eNSP allows only one instance. An abnormal exit can leave a zombie process with no threads, which keeps holding the single-instance lock and makes the next start open a blank window. The tool identifies and clears such processes before starting.
+
+### Push configuration
+
+Sends one command at a time and waits for the prompt after each. A prompt only counts once the echo of that command has arrived, so output still draining from the previous command cannot decide the current view. The first error aborts the batch and reports the line, the command and the device's raw output.
+
+A line the device answers with "already exists" (`address already exists`, `VLAN already exists`, `route already exists` and similar) is recorded as skipped rather than failed. Editing one line and re-running is the common loop, and stopping on those lines means the script never reaches the line that actually changed. Every other error still aborts, because a genuine rejection usually means the following lines land on the wrong object.
+
+```js
+import { pushConfig } from 'dsh-ensp'
+
+const result = await pushConfig({
+  device: 'SW1',
+  port: 2000,
+  script: `
+    system-view
+    vlan 10
+     quit
+    interface GigabitEthernet0/0/1
+     port link-type access
+     port default vlan 10
+     quit
+  `,
+})
+
+if (!result.ok) {
+  console.log(result.failedAt.line, result.failedAt.command, result.failedAt.error)
+}
+```
+
+### Wait for convergence
+
+Routing protocols converge asynchronously, so a finished push does not mean neighbours are up. Such checks poll until the state is reached or the timeout expires.
+
+```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/ })
+```
+
+All three return `{ ok, converged, output, attempts, waitedMs }`. A fixed sleep misjudges on a slow machine and wastes time on a fast one.
+
+### Scenario presets
+
+50 presets cover VLAN, STP, stacking, link aggregation, static routing, RIP, OSPF, BGP, IS-IS, MPLS, multicast, NAT, DHCP, ACL, QoS, port security, IPsec, IPv6, WLAN, firewalls and high availability.
+
+```bash
+ensp preset                          # list by difficulty
+ensp preset ospf-single              # read one preset
+ensp preset --search bgp             # search by keyword
+ensp preset campus-network --topo campus.topo   # write that topology
+```
+
+Each preset provides three things: the objects to create, the configuration order, and the commands that confirm the result. The actual commands are filled in per device.
+
+Presets ship with a topology blueprint: devices, links and addressing are ready, and `--topo` writes a `.topo` that eNSP opens, with no drawing or address planning needed. Blueprints contain no configuration commands, so a preset remains a skeleton.
+
+```bash
+ensp preset ospf-single --topo ospf-single.topo
+ensp up ospf-single.topo
+```
+
+The preset catalogue and the blueprints are both generated and checked. `docs/SCENARIOS.md` is rendered from `src/core/presets.mjs` and `src/core/labs.mjs`; `npm run docs:check` returns non-zero when the two disagree, and CI runs the same check.
+
+```bash
+npm run docs          # regenerate docs/SCENARIOS.md
+npm run docs:check    # check whether it is stale
+```
+
+### Knowledge points
+
+A scenario gives direction, not commands, so the vocabulary of the lab has to come from somewhere. `src/core/knowledge.json` holds knowledge points filed by topic: each scenario ends with a few question-and-answer pairs on the same subject, covering things like which LSA belongs to which area, which attribute decides a BGP path, and which port role only MSTP has.
+
+```bash
+ensp preset ospf-lsa-types          # the detail ends with a knowledge section
+ensp preset --knowledge LSA         # search the index by keyword
+```
+
+The points come from a certification question bank, re-filed by topic. The bank's own tags are unreliable, so a question about OSPF LSA types can also carry a security tag; each question is scored against topic keywords and kept only under the best match. Questions phrased as "which of the following is wrong" are dropped, because once the distractors are stripped what remains is a false statement. The bank itself is not shipped: `knowledge.json` keeps only the stem and the correct option text.
+
+### Device image check
+
+Some models have a catalogue entry without a shipped image, most notably `USG6000V` (its component has to be selected during eNSP installation). Such models can be placed on the canvas and saved to a `.topo`, but eNSP renders the topology and then quits, which shows up as consoles that never answer.
+
+`ensp up` reads `res/items.xml` and the plugin image files before starting the client, and reports models that cannot start together with the missing piece:
+
+```console
+$ ensp up firewall-hrp.topo
+error: topology uses devices this eNSP installation cannot start:
+  USG6000V (FW1, FW2): NGFW 镜像未安装（eNSP 安装时需勾选 USG6000V 组件）
+
+This is not a bug in the topology: eNSP opens it, renders it, then quits. ...
+```
+
+`ensp preset ... --topo` prints the same warning, and `ensp_build_topology` returns `unsupportedDevices`. The check only reads local files and does not start eNSP. Per-scenario device lists appear in [docs/SCENARIOS.md](docs/SCENARIOS.md) under the device image line.
+
+### Window occlusion check
+
+Starting devices requires clicking eNSP toolbar buttons, and a synthetic click goes to the window that owns that pixel. When another program covers eNSP, the mouse events go there and eNSP receives no input.
+
+Before clicking, the tool checks the owner of the target point with `WindowFromPoint` and skips the click when the owner is not eNSP:
+
+```console
+$ ensp up lab.topo
+error: eNSP is covered by another window at 1307,426: vmware (unknown).
+The mouse events would go to that window, so nothing was clicked.
+Bring eNSP to the front (restore it from the taskbar) and try again.
+```
+
+Calibration samples the window on a 5 by 4 grid and stops once any sample point belongs to another window. Calibration reads screen pixels, so an occluded window yields another program's pixels. After the click the owner is checked once more.
+
+The tool cannot raise the eNSP window. Windows lets only the process holding foreground rights switch the foreground window, and a cross-process `SetForegroundWindow` is refused. Keep eNSP on top before running.
+
+### Run permissions
+
+This tool must run as administrator.
+
+The eNSP client requires administrator rights and always runs at high integrity. Windows user interface privilege isolation (UIPI) drops input messages sent by lower-integrity processes, and synthetic clicks are among them. At normal privileges `SendInput` reports success but the input queue does not change, so eNSP receives nothing and clicks appear to do nothing. Started as administrator, input injection works.
+
+Administrator rights solve input injection, not window stacking. eNSP still has to stay visible and on top.
+
+Services, scheduled tasks and SSH sessions have no input-injection capability, and elevation does not change that. The `input-injection` check of `ensp doctor` reports whether the current session can be used.
+
+### Doctor
+
+When a start fails, locating the faulty item usually costs more than fixing it. `ensp doctor` splits the environment into seven checks, decides each one, and gives an actionable fix when one fails:
+
+```console
+$ ensp doctor --topology lab.topo
+[ok  ] ensp-installed: E:\\Huawei\\eNSP\\eNSP_Client.exe
+[ok  ] virtualbox: E:\\VirtualBox\\VBoxManage.exe
+[ok  ] console-ports: 2000-2100 free
+[warn] memory: 949 MB free (each router needs ~256 MB)
+       fix: Close some applications; devices may boot very slowly or fail to start.
+[ok  ] device-images: AR2220 available
+[FAIL] input-injection: SendInput accepted 2 event(s) but the session last-input tick did not change (session 1, console session 1)
+       fix: Run the tool elevated (as administrator) from an interactive desktop session.
+[ok  ] anchors: start (987,226) stop (1049,228)
+```
+
+The command does not start eNSP; it reads local files and runs one synthetic input probe, so it can run after any failure or before any operation. `--shallow` skips the slower input probe and `--json` prints the full structure. The matching tool is `ensp_doctor`.
+
+The check order is fixed: client executable, VirtualBox, topology images, console ports, input injection, memory, anchors. Fix only the item that fails.
+
+### Verification
+
+A successful push does not mean the lab works. `ensp_verify` reads console ports from the `.topo`, runs the verification commands of that scenario, and judges by output content rather than by whether the command reported an error:
+
+```console
+$ ensp verify ospf-single --topology lab.topo
+ospf-single · 单区域 OSPF
+[curated checks]
+[pass] neighbour-full on R1: display ospf peer brief
+[pass] ospf-route on R1: display ip routing-table protocol ospf
+
+accepted: 2/2 checks passed
+```
+
+About 30 scenarios have targeted assertions (OSPF needs `Full`, BGP needs `Established`, VRRP needs `Master`/`Backup`, MPLS VPN needs `Established` and a VPN routing table); the rest fall back to running the verification commands listed in the scenario. The decision logic lives in `EXPECTATIONS` in `src/core/acceptance.mjs`, and assertions support `contains`, `notContains`, `matches` and `minLines`. The matching tool is `ensp_verify`, and `ensp_scenario` reports whether a scenario has targeted assertions.
+
+Device names in assertions map by role to the topology you actually have: blueprints use `R1`/`R2` while course assignments may use `RA`/`RB`/`RC`. Verification takes the first device with a console (`R2` takes the second), so a different name does not change the result.
+
+Failed assertions are retried automatically. Routing protocols converge after the command returns, and right after `ensp apply` an OSPF neighbour is usually still in `ExStart` or `2-Way`, so a single sample would report a working lab as broken. The default wait is 60 seconds, `--wait` changes it, and a pass records how long it actually waited:
+
+```console
+$ ensp verify ospf-single --topology lab.topo
+  checking neighbour-full on R1
+  waiting 3s for neighbour-full on R1 (not contains "Full")
+  ...
+[pass] neighbour-full on R1: display ospf peer brief (converged after 27s)
+```
+
+Two kinds of failure skip the retry loop because retrying changes nothing: an unreachable console (device not started) and a command VRP rejects (wrong command). The former reports `console unreachable: ... ECONNREFUSED`, the latter reports `VRP rejected the command`; neither is disguised as an assertion mismatch.
+
+The recommended order is `doctor`, `up`, `verify`: doctor decides the environment, up decides the devices, verify decides the configuration effect.
+
+## Installation
+
+### As a DSH plugin
+
+Search `dsh-ensp` in the plugin market and install it, or:
+
+```console
+dsh plugin --profile desktop add dsh-ensp
+```
+
+### As a CLI or library
+
+```console
+npm install -g dsh-ensp
+ensp status
+```
+
+### As an MCP server
+
+```json
+{
+  "mcpServers": {
+    "ensp": {
+      "command": "npx",
+      "args": ["-y", "dsh-ensp", "mcp"]
+    }
+  }
+}
+```
+
+15 tools are provided: `ensp_status`, `ensp_build_topology`, `ensp_open`, `ensp_start`, `ensp_stop`, `ensp_apply`, `ensp_apply_dir`, `ensp_query`, `ensp_probe`, `ensp_doctor`, `ensp_verify`, `ensp_scenarios`, `ensp_scenario`, `ensp_knowledge` and `ensp_preset_config`.
+
+## Requirements
+
+| Item | Requirement |
+|---|---|
+| OS | Windows. eNSP has no other build |
+| eNSP | Installed and working |
+| Node.js | 18 or newer |
+| Privileges | Run both this tool and eNSP as administrator, at the same integrity level |
+
+The eNSP and VirtualBox install locations are detected automatically: `--exe` / `--vbox` first, then the `DSH_ENSP_EXE` / `DSH_VBOX` environment variables, then the `HKLM\SOFTWARE\Huawei\eNSP` registry key, then the usual install roots and `PATH`. Nothing needs configuring when either is installed on another drive, and a failed lookup lists every location it tried together with where that location came from.
+
+At 125% or 150% display scaling the tool converts coordinates itself, so no resolution change is needed. If an eNSP upgrade moves the buttons, run `ensp probe` to re-calibrate.
+
+## Quick start
+
+Run as administrator (see "Run permissions" above):
+
+```bash
+ensp doctor                      # confirm this machine can run a lab
+ensp preset ospf-single --topo lab.topo   # write a topology
+ensp up lab.topo                 # start the devices
+ensp apply ./configs --topology lab.topo --save
+ensp verify ospf-single --topology lab.topo   # verify against the scenario
+ensp stop
+```
+
+Timing for one two-area OSPF lab (measured on Windows 11, i5, 150% scaling):
+
+| Stage | Time |
+|---|---|
+| Write the `.topo` | 2s |
+| Open and render the topology | 14s |
+| Two AR2220 to a loginable prompt | 64s |
+| Push 9 commands to each side | 8s |
+| OSPF neighbours to Full | 40s |
+
+## Thanks and licence
+
+### Licence
+
+[GPL-3.0-or-later](LICENSE).
+
+Redistributing a modified version requires:
+
+1. Keeping the copyright notice in `LICENSE`;
+2. Naming the original project `dsh-ensp` and its repository <https://github.com/lizi600jin/dsh-ensp> in the source and the accompanying documentation;
+3. Licensing the distributed work under GPL-3.0-or-later as well.
+
+None of this applies when you use the project yourself without redistributing it.
+
+MIT and Apache-2.0 were not chosen because both allow a modified version to be distributed closed source, which conflicts with the requirement that modifications also be published.
+
+### Thanks
+
+- Huawei eNSP: the simulator itself.
+- The users who reported problems in issues.
+
+## Disclaimer
+
+This project is an automation shell. It contains neither eNSP nor any Huawei software or image. Install eNSP yourself and follow Huawei's licence terms.
+
+Automating a graphical interface carries inherent risk, for example an occluded window, an eNSP upgrade or a change in display scaling. Validate in a non-critical environment first.
+
+## Documentation
+
+| Document | Content |
+|---|---|
+| [`docs/ENSP-FORMAT.md`](docs/ENSP-FORMAT.md) | `.topo` format rules |
+| [`docs/UI-ANCHORS.md`](docs/UI-ANCHORS.md) | Interface coordinates and startup flow |
+| [`docs/SCENARIOS.md`](docs/SCENARIOS.md) | Scenario presets |

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <strong>中文</strong>
+  <strong>中文</strong> | <a href="README.en.md">English</a>
 </p>
 
 <p align="center">
@@ -61,7 +61,9 @@ eNSP 只允许运行一个实例。异常退出可能遗留不占线程的僵尸
 
 ### 下发配置
 
-逐条发送，每条命令确认提示符返回后才继续。任一命令出错即中断，并回报行号、命令与设备原始输出。
+逐条发送，每条命令确认提示符返回后才继续。提示符必须在本条命令的回显之后出现，否则视为上一条命令的输出尚未结束，不会据此判断视图。任一命令出错即中断，并回报行号、命令与设备原始输出。
+
+设备回答“已存在”的行（`address already exists`、`VLAN already exists`、`route already exists` 等）视为已达目标状态，记为跳过而不是失败。改一行再重跑是最常见的用法，如果这些行一出现就中断，脚本永远跑不到真正改动的那一行。其他错误仍然中断，因为真正的拒绝通常意味着后面的行也会落到错误的对象上。
 
 ```js
 import { pushConfig } from 'dsh-ensp'
@@ -121,6 +123,17 @@ ensp up ospf-single.topo
 
 场景清单与蓝图均可生成、可校验。`docs/SCENARIOS.md` 由 `src/core/presets.mjs` 与 `src/core/labs.mjs` 渲染，`npm run docs:check` 在两者不一致时返回非零，CI 亦执行该检查。
 
+### 知识点
+
+场景说明只给方向，命令由使用者补全，因此需要知道该场景涉及的术语。`src/core/knowledge.json` 收录按主题归类的知识点：每个场景在末尾附上同主题的若干「问题 + 答案」，涵盖 LSA 类型归属、BGP 选路属性、MSTP 端口角色等。
+
+```bash
+ensp preset ospf-lsa-types          # 详情末尾带知识点小节
+ensp preset --knowledge LSA         # 按关键词检索知识点
+```
+
+知识点来自认证题库，按主题重新归类：题目的原始标签并不可靠，同一道 OSPF 题可能同时被标为安全，因此按正文关键词评分后只归入最匹配的主题，并剔除「以下错误的是」这类去掉干扰项后只剩错误陈述的题目。题库原文不随包分发，`knowledge.json` 只保留题干与正确选项文本。
+
 ```bash
 npm run docs          # 重新生成 docs/SCENARIOS.md
 npm run docs:check    # 只检查是否过期
@@ -252,7 +265,7 @@ ensp status
 }
 ```
 
-提供 14 个工具：`ensp_status`、`ensp_build_topology`、`ensp_open`、`ensp_start`、`ensp_stop`、`ensp_apply`、`ensp_apply_dir`、`ensp_query`、`ensp_probe`、`ensp_doctor`、`ensp_verify`、`ensp_scenarios`、`ensp_scenario`、`ensp_preset_config`。
+提供 15 个工具：`ensp_status`、`ensp_build_topology`、`ensp_open`、`ensp_start`、`ensp_stop`、`ensp_apply`、`ensp_apply_dir`、`ensp_query`、`ensp_probe`、`ensp_doctor`、`ensp_verify`、`ensp_scenarios`、`ensp_scenario`、`ensp_knowledge`、`ensp_preset_config`。
 
 ## 环境要求
 
@@ -263,6 +276,8 @@ ensp status
 | Node.js | 18 或更高版本 |
 | 权限 | 以管理员身份运行本工具与 eNSP，两者需为同一权限级别 |
 
+eNSP 与 VirtualBox 的安装位置自动探测：先看 `--exe` / `--vbox`，再看 `DSH_ENSP_EXE` / `DSH_VBOX` 环境变量，再看注册表 `HKLM\SOFTWARE\Huawei\eNSP`，最后看常见安装根目录与 `PATH`。装在非默认盘符时不必手工配置，探测失败会列出每一个尝试过的位置及其来源。
+
 系统缩放设为 125% 或 150% 时，程序会自行完成坐标换算，不需要手动调分辨率。若 eNSP 升级后按钮位置改变，执行 `ensp probe` 重新标定。
 
 ## 快速开始

package/docs/UI-ANCHORS.md

@@ -48,9 +48,15 @@
 4. 点击「开启设备」＝ window-relative (660, 59)
 5. 判定启动成功：Get-NetTCPConnection 出现 2000..2100 的监听端口
    （AR1220 约 60~120s；这不是“进程在不在”，是唯一可靠判据）
-6. SW_MINIMIZE 最小化，把桌面还给用户
+6. SW_MINIMIZE 最小化，并把激活交还给最小化之前的那个窗口
 ```
 
+最小化只改窗口状态，不转移激活。`ShowWindow(h, SW_MINIMIZE)` 之后窗口已经 iconic，
+但 `GetForegroundWindow()` 仍然是 eNSP；此时从任务栏点它，第一击会被 Windows 当成
+“修正激活一致性”吞掉，表现为点了没反应、要再点一次。因此最小化后必须显式
+`SetForegroundWindow(previousForeground)`，并在 120ms 后回读确认。
+停止设备同理：点击需要 eNSP 在前台，但用户要的是停止，操作结束后不该把 eNSP 留在前台。
+
 ### 关键纠正（都来自实测，推翻了早期假设）
 
 | 早期假设 | 实测结论 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ensp",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "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",
@@ -40,13 +40,15 @@
     "cordis.patch.yml",
     "screenshots.json",
     "README.md",
+    "README.en.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test tests/core.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"
+    "docs:check": "node scripts/gen-scenarios-doc.mjs --check",
+    "knowledge": "node scripts/gen-knowledge.mjs"
   },
   "engines": {
     "node": ">=18"

package/scripts/gen-knowledge.mjs

@@ -0,0 +1,161 @@
+/**
+ * Regenerate `src/core/knowledge.json` from a certification question bank.
+ *
+ * The bank is not part of this package: it is copyrighted material, and most of
+ * its questions are three-sentence reading exercises rather than facts. What the
+ * package does ship is the index this script produces, so the transformation has
+ * to be reproducible and reviewable by anyone who has the bank.
+ *
+ * Usage:
+ *   node scripts/gen-knowledge.mjs <bank.json>
+ *
+ * The bank is expected as an array of
+ * `{ n, type, stem, options: [{key, text}], answer, analysis, topics }`.
+ *
+ * Two rules shape the output, and both exist because the obvious version of this
+ * script produced a worse index:
+ *
+ * 1. **One topic per question.** The bank's own tags are unreliable: a question
+ *    about OSPF LSA types carries `ospf` and `security` both, and honouring every
+ *    tag files the same fact under two headings. Score the text against topic
+ *    keywords and keep the best match.
+ * 2. **Drop "which is wrong" questions.** Once the distractors are removed, the
+ *    surviving string is a false statement, which is worse than no material.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+/** Topic tag -> the scenarios that teach it. */
+const TOPIC_SCENARIOS = {
+  ospf: ['ospf-single', 'ospf-multi-area', 'ospf-stub-nssa', 'ospf-lsa-types', 'ospf-virtual-link', 'ospf-troubleshooting'],
+  bgp: ['bgp-ebgp-ibgp', 'bgp-route-reflector', 'bgp-attributes', 'bgp-aggregation', 'bgp-troubleshooting'],
+  isis: ['isis-multi-level'],
+  switching: [
+    'vlan-access',
+    'trunk-interconnect',
+    'stp-rstp',
+    'mstp-load-balance',
+    'link-aggregation',
+    'super-vlan',
+    'port-security',
+    'port-isolation',
+    'stack-istack',
+  ],
+  multicast: ['multicast-pim-sm'],
+  mpls: ['mpls-basic', 'mpls-l3vpn'],
+  ipv6: ['ipv6', 'ospfv3-ipv6'],
+  qos: ['qos-basics'],
+  reliability: ['vrrp-basics', 'bfd-fast-convergence', 'firewall-hrp', 'dual-homed-isp'],
+  security: ['acl-filter', 'aaa-local', 'ipsec-vpn', 'firewall-zones', 'firewall-hrp', 'arp-security', 'dhcp-snooping'],
+}
+
+/** Keywords that decide which topic a question belongs to. */
+const TOPIC_TERMS = {
+  ospf: ['ospf', 'lsa', 'abr', 'asbr', 'nssa', 'stub', 'router-id'],
+  bgp: ['bgp', 'as-path', 'ibgp', 'ebgp', 'community', 'aggregator', 'med', 'local-preference'],
+  isis: ['is-is', 'isis', 'level-1', 'level-2', 'dis', 'lsp', 'att'],
+  switching: ['vlan', 'mstp', 'rstp', 'stp', 'eth-trunk', '端口隔离', '端口安全', '堆叠', '根桥', 'bpdu'],
+  multicast: ['pim', 'igmp', '组播', 'rpf', 'spt'],
+  mpls: ['mpls', 'ldp', 'lsr', '标签', 'vpn-instance'],
+  ipv6: ['ipv6', 'ospfv3', 'slaac'],
+  qos: ['qos', '队列', '拥塞', '流量监管', '优先级映射'],
+  reliability: ['vrrp', 'bfd', 'hrp', '双机热备', '主备'],
+  security: ['acl', '安全区域', 'security-policy', 'ipsec', 'ike', 'aaa', 'radius', '防火墙', 'nat'],
+}
+
+/** A question phrased this way keeps only a false statement once stripped. */
+const NEGATIVE = /错误的是|不正确的是|不属于|不支持|不能|无需/
+
+/** Points kept per topic. Enough to cover the vocabulary, short enough to read. */
+const MAX_POINTS = 8
+
+/** A question must score at least this many keyword hits to be filed at all. */
+const MIN_SCORE = 2
+
+const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
+const clip = (s, n) => (s.length <= n ? s : s.slice(0, n - 1).replace(/[，,、；;：: .]*$/, '') + '…')
+
+/**
+ * The answer as readable text.
+ *
+ * A bare key list (`A,C`) teaches nothing, so every chosen option is spelled out.
+ * Returns '' when the answer is not machine-readable, which is the case for the
+ * drag-and-drop and fill-in-the-blank questions.
+ */
+function answerText(q) {
+  const keys = clean(q.answer).toUpperCase().match(/[A-Z]/g)
+  if (!keys || !q.options?.length) return q.type === '判断题' ? clean(q.answer) : ''
+  const picked = q.options.filter((o) => keys.includes(String(o.key).toUpperCase()))
+  if (!picked.length) return ''
+  return picked.map((o) => `${o.key}. ${clip(clean(o.text), 70)}`).join(' / ')
+}
+
+/**
+ * Build the index.
+ *
+ * @param {Array<object>} bank
+ * @returns {object}
+ */
+export function buildIndex(bank) {
+  const perTopic = {}
+  for (const q of bank) {
+    const answer = answerText(q)
+    if (!answer) continue
+    const stem = clean(q.stem)
+    if (NEGATIVE.test(stem)) continue
+    const hay = (stem + ' ' + clean(q.analysis)).toLowerCase()
+    let best = null
+    let bestScore = 0
+    for (const [topic, terms] of Object.entries(TOPIC_TERMS)) {
+      const score = terms.reduce((sum, t) => sum + (hay.split(t).length - 1), 0)
+      if (score > bestScore) {
+        bestScore = score
+        best = topic
+      }
+    }
+    if (!best || bestScore < MIN_SCORE) continue
+    ;(perTopic[best] ||= []).push({ n: q.n, q: clip(stem, 90), a: answer, score: bestScore })
+  }
+
+  const topics = {}
+  for (const [topic, rows] of Object.entries(perTopic)) {
+    // Highest keyword score first, then the shortest stem: a one-line question
+    // states a fact, while a long one describes a scene.
+    const ranked = rows.slice().sort((a, b) => b.score - a.score || a.q.length - b.q.length)
+    const seen = new Set()
+    const points = []
+    for (const r of ranked) {
+      const key = r.q.slice(0, 40) + '|' + r.a.slice(0, 30)
+      if (seen.has(key)) continue
+      seen.add(key)
+      points.push({ n: r.n, q: r.q, a: r.a })
+      if (points.length >= MAX_POINTS) break
+    }
+    topics[topic] = { scenarios: TOPIC_SCENARIOS[topic], points }
+  }
+
+  return {
+    generatedFrom: 'HCIP H12-821 单选/多选/判断题',
+    sourceQuestions: bank.length,
+    topics,
+  }
+}
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (invokedDirectly) {
+  const bankPath = process.argv[2]
+  if (!bankPath) {
+    console.error('usage: node scripts/gen-knowledge.mjs <bank.json>')
+    process.exit(2)
+  }
+  const bank = JSON.parse(readFileSync(bankPath, 'utf8'))
+  const index = buildIndex(bank)
+  const target = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'core', 'knowledge.json')
+  writeFileSync(target, JSON.stringify(index, null, 1) + '\n', 'utf8')
+  const total = Object.values(index.topics).reduce((sum, t) => sum + t.points.length, 0)
+  console.log(`wrote src/core/knowledge.json (${total} points from ${bank.length} questions)`)
+}

package/src/cli/ensp.mjs

@@ -35,6 +35,7 @@ import { doctor, formatDoctor, modelsOf } from '../core/doctor.mjs'
 import { runAcceptance, formatAcceptance, hasChecks, planFor } from '../core/acceptance.mjs'
 import { pushConfig } from '../core/provision.mjs'
 import { SCENARIOS, SCENARIO_IDS, byLevel, renderScenario, searchScenarios } from '../core/presets.mjs'
+import { knowledgeFor, renderKnowledge, searchKnowledge } from '../core/knowledge.mjs'
 import {
   LAB_IDS,
   buildScenarioTopology,
@@ -76,6 +77,8 @@ ${C.bold('OPTIONS')}
   --wait MS         verify: how long a failing assertion may keep being retried (default 60000)
   --topo PATH       write the scenario's topology blueprint to a .topo file
   --topology PATH   the .topo file that is running (doctor, verify)
+  --exe PATH        full path to eNSP_Client.exe (default: auto-detect via registry and install roots)
+  --vbox PATH       full path to VBoxManage.exe (default: auto-detect via PATH and install roots)
   --shallow         doctor: skip the input-injection probe
   --json            machine-readable output
   -h, --help        show this help
@@ -86,6 +89,7 @@ ${C.bold('EXAMPLES')}
   ensp verify ospf-single --topology lab.topo
   ensp apply ./configs --topology lab.topo --save
   ensp status --topology lab.topo
+  ensp up lab.topo --exe "C:/Program Files/Huawei/eNSP/eNSP_Client.exe"
   ensp probe
   ensp preset --search ospf
   ensp preset ospf-single
@@ -317,6 +321,23 @@ async function cmdStatus({ flags }) {
 async function cmdPreset({ positional, flags }) {
   const id = positional[0]
 
+  if (flags.knowledge) {
+    const hits = searchKnowledge(String(flags.knowledge))
+    if (flags.json) {
+      console.log(JSON.stringify(hits, null, 2))
+      return hits.length ? 0 : 1
+    }
+    if (!hits.length) {
+      console.log(C.yellow('no knowledge point matched') + ` "${flags.knowledge}"`)
+      return 1
+    }
+    for (const h of hits) {
+      console.log(`${C.bold('#' + h.n)} ${C.dim('[' + h.topic + ']')} ${h.q}`)
+      console.log(`   答: ${h.a}`)
+    }
+    return 0
+  }
+
   if (flags.search) {
     const hits = searchScenarios(String(flags.search))
     if (flags.json) {
@@ -389,7 +410,10 @@ async function cmdPreset({ positional, flags }) {
     }
 
     const text = renderScenario(id)
-    console.log(flags.json ? JSON.stringify(SCENARIOS[id], null, 2) : text)
+    const points = knowledgeFor(id)
+    console.log(flags.json ? JSON.stringify({ ...SCENARIOS[id], knowledge: points }, null, 2) : text)
+    const knowledge = renderKnowledge(id)
+    if (knowledge) console.log(knowledge)
     if (hasLab(id)) {
       console.log(C.dim(`\n可生成拓扑: ensp preset ${id} --topo ${id}.topo`))
     }
@@ -518,6 +542,10 @@ async function cmdVerify({ positional, flags }) {
 // ------------------------------------------------------------------------- main
 async function main() {
   const { verb, positional, flags } = parseArgs(process.argv.slice(2))
+  // --exe and --vbox are global: every verb that launches or inspects eNSP has
+  // to see the same install, and the launcher reads these variables anyway.
+  if (flags.exe) process.env.DSH_ENSP_EXE = String(flags.exe)
+  if (flags.vbox) process.env.DSH_VBOX = String(flags.vbox)
   if (!verb || flags.help) {
     console.log(HELP)
     return flags.help && !verb ? 0 : 2