ensp-lab-authoring

name	ensp-lab-authoring
description	Full workflow to author an eNSP lab from scratch when only a .topo file exists and no tutorial is provided. Produces deployment guide → real-device dry run → tutorial docx + summary md + diagrams. Trigger when the user hands you only a .topo (optionally with saved vrpcfg.zip) and asks to "design, run, and document" a Huawei WLAN/routing experiment.

eNSP Lab Authoring Skill

Purpose

User provides a .topo (and possibly partial vrpcfg.zip) with no tutorial. Deliver:

1. A deployment guide (paper-level inference before touching devices)
2. Real device configuration via telnet
3. Tutorial docx + summary md + architecture diagrams matching user's existing lab series style

When to trigger

• User says "design + run + document this lab", or similar
• Input contains .topo but no .docx tutorial
• Experiment involves Huawei WLAN (AC6005, AD9430, R250D, AP2050) or routing (AR2220, S3700/S5700)

Do not trigger when: tutorial already exists and user only wants config deployment (use ensp-skills instead).

Five-phase workflow

Phase 1          Phase 2         Phase 3          Phase 4           Phase 5
Paper recon  →   Env precheck →  Deploy config →  Verify + debug →  Produce docs
(topo XML)       (firewall,      (telnet to       (AP online,       (docx + md +
 (vrpcfg.zip)     VBox zombies)   device save)     DHCP, ping)       matplotlib png)
     ↓                ↓                ↓                ↓                  ↓
  guide.md       devices boot    all saved      300% ping passes     3 artifacts

Phase 6 (optional): Archive to personal KB (creates skill card + updates index + log).

---

Phase 1 — Paper reconnaissance

Goal: Without booting devices, infer a full deployment guide from .topo + any saved vrpcfg.cfg. Mark all items needing user confirmation.

Steps

1. Parse .topo XML (UTF-16 encoded)
   • <devices><dev> → name, model, com_port (telnet port), system_mac
   • <lines><interfacePair srcIndex tarIndex> → physical links (see interface index table below)
   • <txttips> → author notes (often stale / contradictory, treat as hints only)
2. Unzip vrpcfg.zip from each device UUID subfolder. Existing configs are the hard constraints (especially static routes on AR).
3. Infer IP plan — priority order:
   1. Match AR's existing static routes (highest priority, hard to change)
   2. Respect .topo <txttips> IP annotations
   3. Fall back to series convention (mgmt VLAN 100/10, service VLAN 101, etc.)
4. Output <lab-dir>/<labN>部署指导文档.md with 11 sections including explicit "Items pending confirmation".

Script: scripts/parse_topo.py Detail: references/01_topology_parsing.md

---

Phase 2 — Environment precheck

Goal: Make sure devices can actually boot.

Common blockers

Symptom	Cause	Fix
"Add eNSP to firewall" popup; "Allow" button greyed with "managed by organization"	Windows public-profile firewall on + local sec policy restriction	netsh advfirewall set allprofiles state off
Devices don't start; VBox shows <inaccessible> VMs	Prior crashed eNSP session left orphans	VBoxManage unregistervm "{uuid}" --delete; VBoxManage closemedium disk "{uuid}"
AR telnet prompt is <Huawei> not <AR1> (config not loaded)	vrpcfg.zip not remounted after VBox clone rebuild	Just redeploy in Phase 3 (don't dig into mount mechanism)
AP takes 60-120s to respond; telnet returns # (busybox)	Normal boot time for AD9430/R250D	Wait for <Huawei> prompt

Script: scripts/vbox_cleanup.py — dry-run audit + apply cleanup Detail: references/02_env_precheck.md

---

Phase 3 — Config deployment (telnet)

Goal: Push commands via socket-based telnet client, handle [Y/N] confirms, parse echo for errors.

4 iron rules (from project CLAUDE.md)

1. Every command starts in system-view; finishes with return → save → Y
2. Any [Y/N] prompt → must send Y (undo/reset/save family)
3. Every command must read the echo — never send commands back-to-back without reading
4. Echo containing Error / Unrecognized / Incomplete / % = failure (record + report)

Ordering traps

• dhcp enable (global) must precede interface Vlanif X → dhcp select interface. Otherwise: Error: Please enable DHCP in the global view first.
• capwap source interface Vlanif X — X must be the VLAN whose Vlanif IP lives in the AP/RU DHCP subnet
• Under ap auth-mode no-auth, APs auto-join default group (not ap-group1). Either bind VAP to default, or use mac-auth + whitelist.

Script: scripts/telnet_configure.py — provides run_pipeline({device_name: (port, commands)}) Detail: references/03_config_deployment.md

---

Phase 4 — Verify + debug

Standard verification checklist (on AC)

Check	Expected	Command
AP online	All nor	display ap all
VAP broadcasting	Status ON, BSSID non-zero	display vap ssid <name>
STA association	MAC in list, correct VLAN	display station ssid <name>
DHCP pool	service pool Used > 0	display ip pool
AC → AP reachable	ping success	ping -c 3 <AP-IP>
AC → Internet (via NAT)	ping success	ping -c 3 8.8.8.8

STA DHCP failure — 5 diagnostic buckets

1. Discover not reaching AC — check LSW / AC trunk VLAN allow-list (in eNSP even tunnel-forward needs service-VLAN on trunk)
2. DHCP not enabled globally — dhcp enable missing → interface-level dhcp select interface is no-op
3. AP in wrong group — VAP bound to ap-group1 but APs joined default
4. CAPWAP source VLAN mismatch — AP can't find AC
5. eNSP R250D+STA WPA 4-way handshake simulator bug — VAP "associates" but unicast encryption channel never opens; AC's Offer dropped at air interface. Not a config bug. Workaround: static IP on STA for data-plane verification.

Detail: references/04_ap_ru_verification.md

---

Phase 5 — Produce documents

Goal: Match user's existing lab series style (ref: 实验03...docx for tutorial, 实验06总结.md for summary).

Tutorial docx structure (7 chapters)

1. Purpose & significance (+ 4 application scenarios)
2. Topology diagram (eNSP screenshot + matplotlib architecture diagram)
3. Network planning (device/VLAN/WLAN tables)
4. Config steps (per-device, command blocks with inline comments)
5. Verification (including success screenshot)
6. Notes / caveats (6-8 items)
7. Comparison with other labs in series

Summary md structure (10 chapters)

Purpose → Topology → Architecture analysis → Per-device config line-by-line → Debug journey with pitfalls → Verification results → Application scenarios (4+ real) → Series comparison → File locations → Conclusion.

Architecture diagram

Do not use cairosvg/svglib on Windows (requires libcairo-2.dll). Use matplotlib directly to PNG.

Script: scripts/make_docx.py — Doc helper class (H/P/CMD/TBL/PIC/CAP methods) Detail: references/05_doc_generation.md

---

Phase 6 — Archive to personal KB (optional)

Goal: Make this work discoverable by future agents via 个人知识库/index.md + tag search.

Three updates:

1. Create skill card at 个人知识库/skills/<name>.md (copy template, fill frontmatter)
2. Append one line to 个人知识库/index.md under correct category
3. Append dated entry to 个人知识库/log.md

Script: scripts/archive_to_kb.py — one-shot for all three.

Detail: references/06_kb_archive.md

---

Dependencies

• Python 3.x at C:/ProgramData/miniconda3/python.exe
• python-docx, matplotlib, Pillow
• eNSP + VirtualBox (Windows)

First validation

Lab 309 (WLAN agile-distributed L2 tunnel-forward), 2026-04-22. Zero-tutorial input → deployment guide + docx tutorial (2.2 MB, 3 embedded images) + 10-chapter summary md. See examples/lab309_walkthrough.md.

Related

• [[ensp-skills]] — base telnet automation (this skill layers on top)
• [[courseware-template]] — docx style contract