dsh-ensp 0.6.0 → 0.8.0

package/README.en.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lizi600jin/dsh-ensp/HEAD/assets/icon.webp" alt="dsh-ensp" width="180" height="180">
+</p>
+
 <p align="center">
   English | <a href="README.md">中文</a>
 </p>
@@ -54,9 +58,12 @@ Locates the toolbar buttons automatically, so nothing has to be clicked by hand.
 ```bash
 ensp probe          # re-calibrate the button positions
 ensp up lab.topo    # open, start, confirm each device, minimise
+ensp show           # bring the window back whenever you want it
 ensp stop           # shut every device down
 ```
 
+The window stays minimised while devices boot and while configuration is pushed, so nothing steals the foreground. When you want to look at the devices or change something by hand, `ensp show` restores the window and brings it to the front; minimise it again afterwards and the run continues unaffected. The command only touches the window, not the topology or the devices.
+
 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
@@ -114,31 +121,30 @@ 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.
+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.
 
 ```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.
+The addressing plan can also become commands. `--config` prints the interface and address blocks for each device in the preset. The scope is the addressing plan only: routing protocols, ACLs and VRRP are the exercise itself, so the preset does not write them for you.
 
 ```bash
-npm run docs          # regenerate docs/SCENARIOS.md
-npm run docs:check    # check whether it is stale
+ensp preset ospf-single --config                 # one block per device
+ensp preset ospf-single --config ./configs       # one .cfg per device, ready for ensp apply
+ensp preset ospf-single --config --json          # the printed form, for scripts
 ```
 
-### Knowledge points
+45 of the 50 blueprints carry addresses. The five layer 2 presets (`vlan-access`, `trunk-interconnect`, `link-aggregation`, `port-security`, `port-isolation`) have VLANs and ports but nothing to address, and `--config` says so rather than emitting an empty script.
 
-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.
+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
-ensp preset ospf-lsa-types          # the detail ends with a knowledge section
-ensp preset --knowledge LSA         # search the index by keyword
+npm run docs          # regenerate docs/SCENARIOS.md
+npm run docs:check    # check whether it is stale
 ```
 
-The points are grouped by topic by hand: each one is a checkable statement rather than a copied entry. The index keeps only the stem and the correct option text; the source material is not shipped.
-
 ### Manual chapter index
 
 `src/core/curriculum.json` records the chapter structure of the vendor lab manuals: the learning goals of each chapter, the `display` commands the manual uses to prove the result, and the built-in scenario that covers the same ground. A scenario detail lists the matching chapters, so you can compare your configuration against the official steps.
@@ -170,6 +176,26 @@ 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.
 
+Where an image belongs is decided by each model's VirtualBox template, not by a fixed path. `ensp images` reads the disk path out of the template and checks whether the file is there:
+
+```console
+$ ensp images
+USG6000V: missing E:\Huawei\eNSP\plugin\ngfw\DataBase\vfw_usg.vdi
+NE40E: missing E:\Huawei\eNSP\plugin\ne\Database\NE40E.img
+...
+```
+
+Once you have the image file, one command puts it where this particular machine looks for it and points the plugin's `system.ini` at it:
+
+```console
+$ ensp images USG6000V --install D:/downloads/vfw_usg.vdi
+installed USG6000V → E:\Huawei\eNSP\plugin\ngfw\DataBase\vfw_usg.vdi (1429741568 bytes)
+ImgFile updated in the plugin system.ini
+restart eNSP if it is already running
+```
+
+The destination comes from the template, so it is correct on a machine that installed eNSP somewhere else. Images are never shipped with this package and never downloaded: the source is a file you already have. A check-only run exits 1 when something is missing, which makes it usable at the top of a startup script.
+
 ### 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.
@@ -203,8 +229,8 @@ When a start fails, locating the faulty item usually costs more than fixing it.
 
 ```console
 $ ensp doctor --topology lab.topo
-[ok  ] ensp-installed: E:\\Huawei\\eNSP\\eNSP_Client.exe
-[ok  ] virtualbox: E:\\VirtualBox\\VBoxManage.exe
+[ok  ] ensp-installed: C:\Program Files\Huawei\eNSP\eNSP_Client.exe
+[ok  ] virtualbox: C:\Program Files\Oracle\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.
@@ -232,9 +258,26 @@ ospf-single · 单区域 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.
+48 scenarios have targeted assertions (OSPF needs `Full`, BGP needs `Established`, VRRP needs `Master`/`Backup`, MPLS VPN needs `Established` and a VPN routing table). Those reports say `[curated checks]` and every check is judged on its output. 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.
+
+The other 2 scenarios have no assertions and only run the verification commands listed in the scenario. The report marks those checks `[skip]`, ends with `unverified`, and exits with code 3 rather than counting them as passes:
+
+```console
+$ ensp verify firewall-hrp --topology lab.topo
+firewall-hrp · 防火墙双机热备（HRP）
+[smoke checks]
+[skip] smoke-1 on FW1: display hrp state
+         no assertion: this command only had to run
+[skip] smoke-2 on FW1: display vrrp
+         no assertion: this command only had to run
+[skip] smoke-3 on FW1: display session table
+         no assertion: this command only had to run
+
+unverified: 3/3 checks had no assertion, 0 passed. Nothing contradicted the expected state, but no output was checked either.
+```
+
+Device names in assertions match by device family to the topology you actually have: blueprints use `R1`/`R2` while course assignments may use `RA`/`RB`/`RC`. Verification takes the Nth device in the same prefix family (`R2` takes the second `R*`). When the family has no such name the report says `no console port for device "..."` instead of silently substituting a different device.
 
-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:
 
@@ -250,6 +293,36 @@ Two kinds of failure skip the retry loop because retrying changes nothing: an un
 
 The recommended order is `doctor`, `up`, `verify`: doctor decides the environment, up decides the devices, verify decides the configuration effect.
 
+### Lab report
+
+When a finished lab needs a document you can hand in, `ensp report` writes this run out as a Word file:
+
+```console
+$ ensp report ospf-single --topology lab.topo --out ospf-single.docx
+collecting evidence for ospf-single from lab.topo
+  checking neighbour-full on R1
+  checking ospf-route on R1
+wrote ospf-single.docx (7169 bytes)
+verdict: passed (2 passed, 0 failed, 0 unverified of 2)
+```
+
+The document has six fixed chapters: goal, topology and addressing, configuration and command list, verification results, problems and conclusion, appendix.
+
+Everything comes from this run rather than from a filled-in template:
+
+| Chapter | Source |
+|---|---|
+| Topology and addressing | Devices, links and console ports read from the `.topo`; the address table comes from the scenario blueprint |
+| Configuration and commands | `display current-configuration` on every device, so the document carries the configuration that actually took effect |
+| Verification results | The scenario assertions are re-run and each command's full output is quoted verbatim |
+| Problems and conclusion | The scenario's pitfalls plus this run's verdict |
+
+The configuration is quoted from the device, not from the `.cfg` files that were pushed: the file says what was meant, the device says what took effect, and a report is worth more when it records the latter.
+
+The conclusion chapter keeps the same three states as verification. A passing run says "verification passed"; a failing assertion says "verification failed"; a scenario without assertions says the run was not verified and that the chapter cannot serve as proof. `ensp report` exits non-zero only on a definite failure, leaving unverified at 0 so it stays distinct from the exit code 3 of `ensp verify`.
+
+Reports are produced on request. The tool never writes a file by itself after a lab finishes; you name the scenario you want a document for. The matching tool is `ensp_report`.
+
 ## Installation
 
 ### As a DSH plugin
@@ -280,7 +353,7 @@ ensp status
 }
 ```
 
-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`.
+17 tools are provided: `ensp_status`, `ensp_build_topology`, `ensp_open`, `ensp_start`, `ensp_stop`, `ensp_apply`, `ensp_apply_dir`, `ensp_query`, `ensp_probe`, `ensp_show`, `ensp_images`, `ensp_doctor`, `ensp_verify`, `ensp_report`, `ensp_scenarios`, `ensp_scenario` and `ensp_preset_config`.
 
 ## Requirements
 
@@ -292,7 +365,7 @@ ensp status
 | DSH | 0.2.0 up to but not including 0.3.0 (`engines.dsh` decides compatibility) |
 | 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.
+The eNSP and VirtualBox install locations are detected automatically: `--exe` / `--vbox` first, then the `DSH_ENSP_EXE` / `DSH_VBOX` environment variables, then the registry, then the usual install roots and `PATH`. The registry entries read are the ones the installers actually write: eNSP under `HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\eNSP` as `InstallPath`, VirtualBox under `HKLM\SOFTWARE\Oracle\VirtualBox` as `InstallDir`. 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.
 
@@ -306,6 +379,7 @@ 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 report ospf-single --topology lab.topo --out ospf-single.docx   # write the lab report
 ensp stop
 ```
 

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lizi600jin/dsh-ensp/HEAD/assets/icon.webp" alt="dsh-ensp" width="180" height="180">
+</p>
+
 <p align="center">
   <strong>中文</strong> | <a href="README.en.md">English</a>
 </p>
@@ -54,9 +58,12 @@ const topo = autoLayout(
 ```bash
 ensp probe          # 重新标定按钮位置
 ensp up lab.topo    # 打开、启动、确认就绪、最小化
+ensp show           # 随时把窗口唤回前台
 ensp stop           # 关闭全部设备
 ```
 
+启动和下发配置期间窗口保持最小化，不抢前台。想看设备状态或手工改动时用 `ensp show` 唤回，改完再把它最小化即可，配置流程不受影响。这个命令只还原窗口并尝试置前，不触碰拓扑与设备状态。
+
 eNSP 只允许运行一个实例。异常退出可能遗留不占线程的僵尸进程，该进程持续持有单实例锁，导致下一次启动只打开空白窗口。工具在启动前会识别并清理此类进程。
 
 ### 下发配置
@@ -114,25 +121,24 @@ ensp preset campus-network --topo campus.topo   # 生成该场景的拓扑
 
 每个场景提供三项信息：需要创建的对象、配置顺序、用于确认结果的检查命令。具体命令由使用者按设备补全。
 
-场景自带拓扑蓝图：设备、链路、地址规划均为现成内容，加 `--topo` 即生成 eNSP 可打开的 `.topo`，无需先绘图再规划地址。蓝图不含配置命令，场景仍为骨架。
+场景自带拓扑蓝图：设备、链路、地址规划均为现成内容，加 `--topo` 即生成 eNSP 可打开的 `.topo`，无需先绘图再规划地址。
 
 ```bash
 ensp preset ospf-single --topo ospf-single.topo
 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 端口角色等。
+地址规划也能直接变成命令。加 `--config` 输出该场景每台设备的接口与地址配置，范围仅限地址规划：路由协议、ACL、VRRP 这些仍是练习本身，场景不会代你写好。
 
 ```bash
-ensp preset ospf-lsa-types          # 详情末尾带知识点小节
-ensp preset --knowledge LSA         # 按关键词检索知识点
+ensp preset ospf-single --config                 # 按设备分段打印
+ensp preset ospf-single --config ./configs       # 写成每台设备一个 .cfg，可直接交给 ensp apply
+ensp preset ospf-single --config --json          # 打印模式下的同一份内容，便于脚本处理
 ```
 
-知识点按主题人工归类：每条是一句可核对的事实，而不是照搬原始条目。索引只保留题干与正确选项文本，原始资料不随包分发。
+50 个蓝图里 45 个带地址规划，五个二层场景（`vlan-access`、`trunk-interconnect`、`link-aggregation`、`port-security`、`port-isolation`）只有 VLAN 与端口，没有地址可配，`--config` 对它们报错而不是输出空脚本。
+
+场景清单与蓝图均可生成、可校验。`docs/SCENARIOS.md` 由 `src/core/presets.mjs` 与 `src/core/labs.mjs` 渲染，`npm run docs:check` 在两者不一致时返回非零，CI 亦执行该检查。
 
 ### 教材章节索引
 
@@ -170,6 +176,26 @@ This is not a bug in the topology: eNSP opens it, renders it, then quits. ...
 
 `ensp preset ... --topo` 生成文件时给出同样的提示，`ensp_build_topology` 的返回值包含 `unsupportedDevices`。该检查只读取本机文件，不启动 eNSP。各场景的设备清单见 [docs/SCENARIOS.md](docs/SCENARIOS.md) 中的“设备镜像”一行。
 
+镜像放在哪，由各机型的 VirtualBox 模板决定，不是一个固定位置。`ensp images` 逐个机型读出模板里的磁盘路径，再检查文件在不在：
+
+```console
+$ ensp images
+USG6000V: missing E:\Huawei\eNSP\plugin\ngfw\DataBase\vfw_usg.vdi
+NE40E: missing E:\Huawei\eNSP\plugin\ne\Database\NE40E.img
+...
+```
+
+拿到镜像文件后，用一条命令放到这台机器该放的位置，同时把插件的 `system.ini` 指向它：
+
+```console
+$ ensp images USG6000V --install D:/downloads/vfw_usg.vdi
+installed USG6000V → E:\Huawei\eNSP\plugin\ngfw\DataBase\vfw_usg.vdi (1429741568 bytes)
+ImgFile updated in the plugin system.ini
+restart eNSP if it is already running
+```
+
+目标路径从模板解析，换一台机器装在不同目录也照样正确。镜像不随包分发、也不会自动下载，来源是你手上已有的文件。只做检查不动文件时退出码为 1，方便写在启动脚本前面。
+
 ### 窗口遮挡检查
 
 启动设备需要点击 eNSP 工具栏按钮，而合成点击由持有该像素的窗口接收。其他程序覆盖 eNSP 时，鼠标事件被该程序接收，eNSP 收不到任何输入。
@@ -203,8 +229,8 @@ eNSP 客户端要求管理员权限，始终以高完整性级别运行。Window
 
 ```console
 $ ensp doctor --topology lab.topo
-[ok  ] ensp-installed: E:\Huawei\eNSP\eNSP_Client.exe
-[ok  ] virtualbox: E:\VirtualBox\VBoxManage.exe
+[ok  ] ensp-installed: C:\Program Files\Huawei\eNSP\eNSP_Client.exe
+[ok  ] virtualbox: C:\Program Files\Oracle\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.
@@ -232,9 +258,26 @@ ospf-single · 单区域 OSPF
 accepted: 2/2 checks passed
 ```
 
-约 30 个场景配置了针对性断言（OSPF 需 `Full`、BGP 需 `Established`、VRRP 需 `Master`/`Backup`、MPLS VPN 需 `Established` 与 VPN 路由表），其余场景回退为执行场景内列出的验证命令。判定逻辑位于 `src/core/acceptance.mjs` 的 `EXPECTATIONS`，断言支持 `contains`、`notContains`、`matches`、`minLines`。对应工具为 `ensp_verify`，`ensp_scenario` 会标明某场景是否具有针对性断言。
+约 48 个场景配置了针对性断言（OSPF 需 `Full`、BGP 需 `Established`、VRRP 需 `Master`/`Backup`、MPLS VPN 需 `Established` 与 VPN 路由表）。这些场景的报告标 `[curated checks]`，每条检查都按输出内容判定。判定逻辑位于 `src/core/acceptance.mjs` 的 `EXPECTATIONS`，断言支持 `contains`、`notContains`、`matches`、`minLines`。对应工具为 `ensp_verify`，`ensp_scenario` 会标明某场景是否具有针对性断言。
+
+其余 2 个场景没有断言，只执行场景内列出的验证命令。报告把这类检查标为 `[skip]`，结尾写 `unverified`，退出码为 3，不会计为通过：
+
+```console
+$ ensp verify firewall-hrp --topology lab.topo
+firewall-hrp · 防火墙双机热备（HRP）
+[smoke checks]
+[skip] smoke-1 on FW1: display hrp state
+         no assertion: this command only had to run
+[skip] smoke-2 on FW1: display vrrp
+         no assertion: this command only had to run
+[skip] smoke-3 on FW1: display session table
+         no assertion: this command only had to run
+
+unverified: 3/3 checks had no assertion, 0 passed. Nothing contradicted the expected state, but no output was checked either.
+```
+
+断言中的设备名按设备族匹配到实际拓扑：蓝图使用 `R1`/`R2`，课程作业可能使用 `RA`/`RB`/`RC`，校验时取同一前缀族里的第 N 台（`R2` 取第二个 `R*`）。族里没有这个名字时报 `no console port for device "..."`，不会静默换成另一台设备。
 
-断言中的设备名按角色映射到实际拓扑：蓝图使用 `R1`/`R2`，课程作业可能使用 `RA`/`RB`/`RC`，校验时取第一台具备控制台的设备（`R2` 取第二台），名称不同不影响判定。
 
 断言不通过时会自动重试。路由协议在命令返回之后才收敛，`ensp apply` 结束后立即验收时，OSPF 邻居通常仍处于 `ExStart` 或 `2-Way`，单次采样会误判为失败。默认等待 60 秒，可通过 `--wait` 调整，通过时注明确切等待时长：
 
@@ -250,6 +293,36 @@ $ ensp verify ospf-single --topology lab.topo
 
 推荐顺序为 `doctor`、`up`、`verify`：doctor 判定环境，up 判定设备，verify 判定配置效果。
 
+### 实验报告
+
+实验做完需要一个能交的文档时，`ensp report` 把这次运行的事实写成一份 Word 文档：
+
+```console
+$ ensp report ospf-single --topology lab.topo --out ospf-single.docx
+collecting evidence for ospf-single from lab.topo
+  checking neighbour-full on R1
+  checking ospf-route on R1
+wrote ospf-single.docx (7169 bytes)
+verdict: passed (2 passed, 0 failed, 0 unverified of 2)
+```
+
+文档固定六章：实验目的、拓扑与地址规划、配置思路与命令、验证结果、问题与结论、附录。
+
+内容全部来自这次运行，不是模板填空：
+
+| 章节 | 来源 |
+|---|---|
+| 拓扑与地址规划 | 读 `.topo` 的设备、链路与控制台端口，地址表取自场景蓝图 |
+| 配置思路与命令 | 每台设备执行 `display current-configuration`，收录设备上实际生效的配置 |
+| 验证结果 | 重跑该场景的验收断言，把每条命令的完整输出原文抄进文档 |
+| 问题与结论 | 场景的易错点，加上本次的验证结论 |
+
+配置原文取自设备而不取下发过的 `.cfg` 文件：文件说的是打算配什么，设备说的是配成了什么，两者不一致时报告应当记录后者。
+
+结论一章沿用验收的三态。验证通过写「验证通过」；有断言失败写「验证未通过」；场景没有断言时写「本次运行未验证」，并说明该章不能作为达标证明。`ensp report` 只在明确失败时以非零退出码结束，未验证按 0 返回，与 `ensp verify` 的退出码 3 区分开。
+
+文档按需生成，工具不会在实验结束后自行产出文件。要写哪个实验的文档由你指定，对应工具为 `ensp_report`。
+
 ## 安装
 
 ### 作为 DSH 插件
@@ -280,7 +353,7 @@ ensp status
 }
 ```
 
-提供 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`。
+提供 17 个工具：`ensp_status`、`ensp_build_topology`、`ensp_open`、`ensp_start`、`ensp_stop`、`ensp_apply`、`ensp_apply_dir`、`ensp_query`、`ensp_probe`、`ensp_show`、`ensp_images`、`ensp_doctor`、`ensp_verify`、`ensp_report`、`ensp_scenarios`、`ensp_scenario`、`ensp_preset_config`。
 
 ## 环境要求
 
@@ -292,7 +365,7 @@ ensp status
 | DSH | 0.2.0 到 0.3.0 之前的版本（`engines.dsh` 决定兼容性） |
 | 权限 | 以管理员身份运行本工具与 eNSP，两者需为同一权限级别 |
 
-eNSP 与 VirtualBox 的安装位置自动探测：先看 `--exe` / `--vbox`，再看 `DSH_ENSP_EXE` / `DSH_VBOX` 环境变量，再看注册表 `HKLM\SOFTWARE\Huawei\eNSP`，最后看常见安装根目录与 `PATH`。装在非默认盘符时不必手工配置，探测失败会列出每一个尝试过的位置及其来源。
+eNSP 与 VirtualBox 的安装位置自动探测：先看 `--exe` / `--vbox`，再看 `DSH_ENSP_EXE` / `DSH_VBOX` 环境变量，再看注册表，再看常见安装根目录与 `PATH`。注册表读的是安装程序实际写入的位置：eNSP 在卸载项 `HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\eNSP` 的 `InstallPath`，VirtualBox 在 `HKLM\SOFTWARE\Oracle\VirtualBox` 的 `InstallDir`。装在非默认盘符时不必手工配置，探测失败会列出每一个尝试过的位置及其来源。
 
 系统缩放设为 125% 或 150% 时，程序会自行完成坐标换算，不需要手动调分辨率。若 eNSP 升级后按钮位置改变，执行 `ensp probe` 重新标定。
 
@@ -306,6 +379,7 @@ ensp preset ospf-single --topo lab.topo   # 生成拓扑
 ensp up lab.topo                 # 启动设备
 ensp apply ./configs --topology lab.topo --save
 ensp verify ospf-single --topology lab.topo   # 按场景断言验收
+ensp report ospf-single --topology lab.topo --out ospf-single.docx   # 产出实验报告
 ensp stop
 ```
 

package/docs/ENSP-FORMAT.md

@@ -1,7 +1,7 @@
-# eNSP topology format — verified reference
+# eNSP topology format: verified reference
 
 Every rule below was derived from the **40 sample topologies shipped with eNSP**
-(`E:\Huawei\eNSP\examples\**\*.topo`) and confirmed by opening generated files in
+(`<eNSP install>\examples\**\*.topo`, wherever you installed it) and confirmed by opening generated files in
 eNSP. Nothing here is guessed; where a rule could not be established it is marked
 **UNVERIFIED** rather than assumed.
 
@@ -18,7 +18,7 @@ node scripts/survey-topologies.mjs   # prints the tables this document summarise
 | Rule | Value |
 |---|---|
 | Text encoding | **UTF-8** (no BOM), despite the declaration |
-| XML declaration | `<?xml version="1.0" encoding="UNICODE" ?>` — eNSP writes `UNICODE` but saves UTF-8 |
+| XML declaration | `<?xml version="1.0" encoding="UNICODE" ?>`: eNSP writes `UNICODE` but saves UTF-8 |
 | Root element | `<topo version="1.2.00.390">` (newest samples; `1.3.00.100` also accepted) |
 | Child order | `<devices>` → `<lines>` → `<shapes />` → `<txttips />` |
 | Empty elements | self-closing (`<shapes />`), not `<shapes></shapes>` |
@@ -56,8 +56,8 @@ Attribute order: `id name poe model settings system_mac com_port bootmode cx cy
 |---|---|---|
 | `edit_left` | `cx + 27` | every sample, no exceptions |
 | `edit_top` | `cy + 54` | every sample, no exceptions |
-| `id` | UUID; eNSP writes **lowercase** in newer files, mixed case in older | — |
-| `com_port` | console TCP port; `0` for models without a console (PC, Server, Cloud) | — |
+| `id` | UUID; eNSP writes **lowercase** in newer files, mixed case in older | n/a |
+| `com_port` | console TCP port; `0` for models without a console (PC, Server, Cloud) | n/a |
 | `bootmode` | `1` in practice; does **not** auto-start devices | tested: bootmode=1 + open ⇒ no boot |
 
 > `system_mac` is absent from router/switch/PC entries in native files. Writing it
@@ -65,7 +65,7 @@ Attribute order: `id name poe model settings system_mac com_port bootmode cx cy
 
 ---
 
-## 3. `<slot>` and `<interface>` — the part that breaks silently
+## 3. `<slot>` and `<interface>`, the part that breaks silently
 
 Every device has exactly one slot:
 
@@ -114,12 +114,12 @@ The CLI name order was confirmed on a live device: `display interface brief` lis
 > **`PC` declares `interfacename="GE"`, not `"Ethernet"`.** An earlier version of
 > this project wrote `Ethernet` for PCs on the theory that a PC has one Ethernet
 > port; that produced an empty canvas. The CLI name of that single port is still
-> `Ethernet0/0/1` — the file's `interfacename` and the CLI name are different
+> `Ethernet0/0/1`: the file's `interfacename` and the CLI name are different
 > vocabularies.
 
 ### Models not present in the samples
 
-`AR2240`, `USG5500`, `USG6000V`, `Server`, `STA`, `Cellphone` — **UNVERIFIED**.
+`AR2240`, `USG5500`, `USG6000V`, `Server`, `STA`, `Cellphone`: **UNVERIFIED**.
 `AR2240` is believed to be `Ethernet/GE×4` (its predecessor AR2220 style), but no
 bundled file proves it. Generate one by hand in eNSP and diff before relying on it.