dsh-ensp 0.5.1 → 0.7.0

package/scripts/gen-curriculum.mjs

@@ -0,0 +1,181 @@
+/**
+ * Build the curriculum index from extracted vendor lab manuals.
+ *
+ * The manuals are hundreds of pages each and cannot ship: they are vendor
+ * documentation, they are far larger than this package, and most of a page is
+ * prose that a tool has no use for. What *is* useful is the skeleton of each
+ * chapter: what it claims to teach, which `display` commands it uses to prove the
+ * claim, and which built-in scenario covers the same ground. That skeleton is
+ * small, factual, and stable across manual revisions.
+ *
+ * Input is the page-by-page JSON produced from the PDFs by the extractor in
+ * `_huawei/pages.py`; output is `src/core/curriculum.json`. The extractor is not
+ * part of the package because it needs the PDFs, which are not redistributable.
+ *
+ *   node scripts/gen-curriculum.mjs <guides.json> [more.json ...]
+ *
+ * @module scripts/gen-curriculum
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+/** Manuals whose chapters duplicate another manual; keep the first of each pair. */
+const SKIP_MANUAL = /YunShan_OS|eNSP_Pro/
+
+/**
+ * Which built-in scenarios a manual chapter teaches.
+ *
+ * This mapping is the actual editorial work. It is keyed by
+ * `<level>:<chapter title>` so it survives a chapter being renumbered in a later
+ * manual revision, and so a missing chapter is a visible gap rather than a silent
+ * mis-filing.
+ */
+const CHAPTER_SCENARIOS = {
+  'HCIA:华为网络设备基本操作': ['vlan-access', 'trunk-interconnect'],
+  'HCIA:VLAN 配置实验': ['vlan-access', 'trunk-interconnect', 'vlanif-routing', 'super-vlan'],
+  'HCIA:生成树配置实验': ['stp-rstp', 'mstp-load-balance'],
+  'HCIA:以太网链路聚合实验': ['link-aggregation'],
+  'HCIA:直连路由实验': ['vlanif-routing'],
+  'HCIA:静态路由实验': ['static-route'],
+  'HCIA:IP 地址自动配置实验': ['dhcp', 'dhcp-snooping'],
+  'HCIA:OSPF 配置实验': ['ospf-single'],
+  'HCIA:IPv6 地址配置实验': ['ipv6', 'ospfv3-ipv6'],
+  'HCIA:ACL 配置实验': ['acl-filter', 'nat'],
+  'HCIA:文件管理实验': ['aaa-local', 'network-management'],
+  'HCIA:远程登录实验': ['aaa-local', 'network-management'],
+  'HCIA:NAT 配置实验': ['nat', 'acl-filter'],
+  'HCIA:WAC+FIT AP 组网实验': ['wlan-basic', 'wlan-roaming'],
+  'HCIA:网络编程自动化实验': ['network-management'],
+  'HCIA:网络故障排除实验': ['ospf-troubleshooting', 'bgp-troubleshooting'],
+  'HCIA:园区网络综合实验': ['campus-network', 'vlanif-routing', 'static-route'],
+
+  'HCIP:OSPF 基础实验': [
+    'ospf-single',
+    'ospf-multi-area',
+    'ospf-lsa-types',
+    'ospf-stub-nssa',
+    'ospf-virtual-link',
+  ],
+  'HCIP:IS-IS 基础实验': ['isis-multi-level'],
+  'HCIP:BGP 实验': ['bgp-ebgp-ibgp', 'bgp-route-reflector', 'bgp-aggregation'],
+  'HCIP:路由策略与路由控制实验': ['route-policy-pbr', 'bgp-attributes'],
+  'HCIP:RSTP 与MSTP 实验': ['stp-rstp', 'mstp-load-balance', 'vrrp-basics'],
+  'HCIP:组播实验': ['multicast-pim-sm'],
+  'HCIP:防火墙技术实验': ['firewall-zones', 'nat'],
+  'HCIP:VRRP 实验': ['vrrp-basics'],
+  'HCIP:DHCP 实验': ['dhcp', 'dhcp-snooping'],
+  'HCIP:WLAN 实验': ['wlan-basic', 'wlan-roaming'],
+
+  'HCIP:IGP 高级特性实验': ['ospf-troubleshooting', 'bfd-fast-convergence', 'isis-multi-level'],
+  'HCIP:BGP 高级特性实验': ['bgp-troubleshooting', 'bgp-attributes', 'bgp-aggregation'],
+  'HCIP:IPv6 实验': ['ipv6', 'ospfv3-ipv6'],
+  'HCIP:VLAN 高级技术实验': ['super-vlan', 'port-isolation'],
+  'HCIP:以太网交换安全实验': ['port-security', 'arp-security', 'dhcp-snooping'],
+  'HCIP:BGP/MPLS IP VPN 实验': ['mpls-basic', 'mpls-l3vpn'],
+  'HCIP:网络准入控制实验': ['port-security', 'aaa-local', 'dhcp-snooping'],
+  'HCIP:VXLAN 与EVPN 实验': ['spine-leaf-vxlan', 'mpls-basic'],
+
+  'HCIE:IPv4 路由技术': ['ospf-troubleshooting', 'isis-multi-level', 'bgp-troubleshooting', 'bfd-fast-convergence'],
+  'HCIE:MPLS VPN': ['mpls-basic', 'mpls-l3vpn', 'ipsec-gre-tunnel'],
+  'HCIE:EVPN': ['mpls-basic', 'spine-leaf-vxlan'],
+  'HCIE:IPv6 路由技术': ['ospfv3-ipv6', 'ipv6'],
+  'HCIE:VXLAN 实验': ['spine-leaf-vxlan'],
+  'HCIE:VXLAN 虚拟化园区部署': ['spine-leaf-vxlan', 'wlan-roaming'],
+  'HCIE:广域互联网络部署': ['dual-homed-isp', 'ipsec-gre-tunnel'],
+  'HCIE:SR-MPLS 实验': ['mpls-basic', 'mpls-l3vpn'],
+  'HCIE:SRv6 实验': ['ipv6', 'ospfv3-ipv6', 'mpls-l3vpn'],
+  'HCIE:网络开放可编程': ['network-management'],
+}
+
+/** Drop sentences that are exam questions or half-cut lines from the extraction. */
+const NOISE = /^(分析|思考|讨论|如果|若|假设|为什么|如何)|？$|，$|、$/
+
+const MAX_GOALS = 6
+const MAX_VERIFY = 10
+
+/** Chapter titles carry suffixes such as （可选）that vary between manual editions. */
+function titleKey(title) {
+  return tidy(title).replace(/[（(][^）)]{1,8}[）)]$/,'').trim()
+}
+
+function tidy(text) {
+  return String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .replace(/（/g, '(')
+    .replace(/）/g, ')')
+    .trim()
+}
+
+/** `display ip routing-tableprotocol ospf` comes back fused; split it. */
+function fixCommand(cmd) {
+  return tidy(cmd).replace(/(routing-table|interface|brief|peer)(protocol|interface|verbose)/gi, '$1 $2')
+}
+
+function pick(list, max, filter = () => true) {
+  const out = []
+  for (const raw of list) {
+    const value = tidy(raw)
+    if (!value || value.length < 4 || NOISE.test(value)) continue
+    if (!filter(value)) continue
+    if (out.includes(value)) continue
+    out.push(value)
+    if (out.length >= max) break
+  }
+  return out
+}
+
+export function buildCurriculum(manuals) {
+  const entries = []
+  const seen = new Set()
+  for (const chapter of manuals) {
+    if (SKIP_MANUAL.test(chapter.manual)) continue
+    const title = tidy(chapter.title)
+    const key = `${chapter.level}:${titleKey(title)}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    entries.push({
+      level: chapter.level,
+      title,
+      page: chapter.page,
+      scenarios: CHAPTER_SCENARIOS[key] || [],
+      goals: pick(chapter.goals || [], MAX_GOALS, (g) => /^(实现|描述|阐明|掌握|理解|了解|配置)/.test(g)),
+      verify: pick((chapter.verify || []).map(fixCommand), MAX_VERIFY, (c) => /^(display|ping|tracert)\s/.test(c)),
+    })
+  }
+  entries.sort((a, b) => {
+    const order = { HCIA: 0, HCIP: 1, HCIE: 2 }
+    return (order[a.level] ?? 9) - (order[b.level] ?? 9) || a.page - b.page
+  })
+  const byLevel = { HCIA: [], HCIP: [], HCIE: [] }
+  for (const entry of entries) (byLevel[entry.level] ||= []).push(entry)
+  return { version: 1, levels: byLevel }
+}
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (invokedDirectly) {
+  const sources = process.argv.slice(2).filter((a) => !a.startsWith('--'))
+  if (!sources.length) {
+    console.error('usage: node scripts/gen-curriculum.mjs <guides.json> [more.json ...]')
+    process.exit(2)
+  }
+  const chapters = []
+  for (const file of sources) {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    chapters.push(...(Array.isArray(parsed) ? parsed : parsed.chapters || []))
+  }
+  const index = buildCurriculum(chapters)
+  const target = new URL('../src/core/curriculum.json', import.meta.url)
+  writeFileSync(target, JSON.stringify(index, null, 1) + '\n')
+  const counts = Object.entries(index.levels).map(([k, v]) => `${k} ${v.length}`)
+  const mapped = Object.values(index.levels)
+    .flat()
+    .filter((e) => e.scenarios.length).length
+  const bytes = JSON.stringify(index).length
+  console.log(
+    `wrote src/core/curriculum.json (${counts.join(', ')}; ${mapped} chapters mapped to scenarios; ${bytes} bytes)`,
+  )
+}

package/scripts/gen-knowledge.mjs

@@ -2,7 +2,7 @@
  * Regenerate `src/core/knowledge.json`.
  *
  * Usage:
- *   node scripts/gen-knowledge.mjs <source.json>
+ *   node scripts/gen-knowledge.mjs <source.json> [more.json ...]
  *
  * The source is any array of `{ n, type, stem, options: [{key, text}], answer,
  * analysis, topics }`. It is not part of this package; what ships is the index
@@ -44,8 +44,9 @@ const TOPIC_SCENARIOS = {
   mpls: ['mpls-basic', 'mpls-l3vpn'],
   ipv6: ['ipv6', 'ospfv3-ipv6'],
   qos: ['qos-basics'],
+  management: ['network-management'],
   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'],
+  security: ['acl-filter', 'aaa-local', 'ipsec-vpn', 'firewall-zones', 'firewall-hrp', 'arp-security', 'dhcp-snooping', 'port-security'],
 }
 
 /** Keywords that decide which topic a question belongs to. */
@@ -58,6 +59,7 @@ const TOPIC_TERMS = {
   mpls: ['mpls', 'ldp', 'lsr', '标签', 'vpn-instance'],
   ipv6: ['ipv6', 'ospfv3', 'slaac'],
   qos: ['qos', '队列', '拥塞', '流量监管', '优先级映射'],
+  management: ['网络管理', '网管', 'snmp', 'ntp', '日志', 'info-center', 'netconf', 'telemetry'],
   reliability: ['vrrp', 'bfd', 'hrp', '双机热备', '主备'],
   security: ['acl', '安全区域', 'security-policy', 'ipsec', 'ike', 'aaa', 'radius', '防火墙', 'nat'],
 }
@@ -65,8 +67,15 @@ const TOPIC_TERMS = {
 /** 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
+/**
+ * Points kept per topic.
+ *
+ * The brief renders at most ten of them, so this cap is about how much depth a
+ * topic carries into the index, not about screen space. It has to be generous:
+ * every source that feeds the index contributes its own best rows, and a tight
+ * cap lets a later source push out an earlier one entirely.
+ */
+const MAX_POINTS = 24
 
 /** A question must score at least this many keyword hits to be filed at all. */
 const MIN_SCORE = 2
@@ -78,24 +87,39 @@ 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.
+ * When the option text is unusable the explanation carries the fact instead: it
+ * is the part a reader can actually learn from, and dropping the question because
+ * its options came back blank throws away the answer along with them. Returns ''
+ * only when neither source says anything.
  */
 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(' / ')
+  const picked = (q.options || []).filter(
+    (o) => keys?.includes(String(o.key).toUpperCase()) && clean(o.text).replace(/^[.、\s]*$/, ''),
+  )
+  if (picked.length) {
+    return picked.map((o) => `${o.key}. ${clip(clean(o.text), 70)}`).join(' / ')
+  }
+  const explained = clean(q.analysis)
+  if (explained.length >= 12) return clip(explained, 130)
+  if (q.type === '判断题') return clean(q.answer) || ''
+  return ''
 }
 
 /**
  * Build the index.
  *
- * @param {Array<object>} source
+ * Two sources feed one topic's points: the keyword pass over the raw questions,
+ * and `carry` rows that are already in the shipped shape (`{topic, n, q, a}`).
+ * The carry path exists because the index is built from more than one source
+ * over time, and rebuilding from a single source would silently drop whatever
+ * the other one contributed.
+ *
+ * @param {Array<object>} source raw questions
+ * @param {Array<{topic: string, n: number, q: string, a: string}>} [carry] points to keep as-is
  * @returns {object}
  */
-export function buildIndex(source) {
+export function buildIndex(source, carry = []) {
   const perTopic = {}
   for (const q of source) {
     const answer = answerText(q)
@@ -117,18 +141,30 @@ export function buildIndex(source) {
   }
 
   const topics = {}
-  for (const [topic, rows] of Object.entries(perTopic)) {
+  for (const topic of new Set([...Object.keys(perTopic), ...carry.map((c) => c.topic)])) {
+    const rows = perTopic[topic] || []
     // 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 = []
+    // Carried points go first. They were already reviewed when they shipped, so a
+    // later source adds to them rather than displacing them; the alternative
+    // silently traded an established fact for a new one that scored higher.
+    for (const c of carry) {
+      if (c.topic !== topic) continue
+      if (points.length >= MAX_POINTS) break
+      const key = c.q.slice(0, 40) + '|' + c.a.slice(0, 30)
+      if (seen.has(key)) continue
+      seen.add(key)
+      points.push({ n: c.n, q: c.q, a: c.a })
+    }
     for (const r of ranked) {
+      if (points.length >= MAX_POINTS) break
       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 }
   }
@@ -143,15 +179,18 @@ const invokedDirectly =
   process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
 
 if (invokedDirectly) {
-  const sourcePath = process.argv[2]
-  if (!sourcePath) {
-    console.error('usage: node scripts/gen-knowledge.mjs <source.json>')
+  const args = process.argv.slice(2)
+  const carryPath = args.find((a) => a.startsWith('--carry='))?.slice('--carry='.length)
+  const sourcePaths = args.filter((a) => !a.startsWith('--'))
+  if (!sourcePaths.length) {
+    console.error('usage: node scripts/gen-knowledge.mjs [--carry=index.json] <source.json> [more.json ...]')
     process.exit(2)
   }
-  const source = JSON.parse(readFileSync(sourcePath, 'utf8'))
-  const index = buildIndex(source)
+  const source = sourcePaths.flatMap((p) => JSON.parse(readFileSync(p, 'utf8')))
+  const carry = carryPath ? JSON.parse(readFileSync(carryPath, 'utf8')) : []
+  const index = buildIndex(source, carry)
   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)`)
+  console.log(`wrote src/core/knowledge.json (${total} points from ${source.length} questions)`)
 }

package/scripts/gen-scenarios-doc.mjs

@@ -19,6 +19,7 @@ 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'
 import { hasChecks, EXPECTATIONS } from '../src/core/acceptance.mjs'
+import { curriculumFor } from '../src/core/curriculum.mjs'
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const root = path.resolve(here, '..')
@@ -137,6 +138,16 @@ function render(catalogue = SCENARIOS) {
           : `- 验收：\`ensp verify ${id} --topology ${id}.topo\`（无专门断言，逐条跑本场景的验证命令）`
         out.push(verifyLine)
       }
+
+      // Which vendor manual chapter teaches this scenario, when one does.
+      const chapters = curriculumFor(id)
+      if (chapters.length) {
+        out.push('', '**教材章节**')
+        for (const chapter of chapters) {
+          const where = `${chapter.level} · ${chapter.title}（手册第 ${chapter.page} 页）`
+          out.push(`- ${where}`)
+        }
+      }
       out.push('')
     }
   }

package/src/cli/ensp.mjs

@@ -36,6 +36,7 @@ import { runAcceptance, formatAcceptance, hasChecks, planFor } from '../core/acc
 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 { curriculumFor, renderCurriculum, searchCurriculum } from '../core/curriculum.mjs'
 import {
   LAB_IDS,
   buildScenarioTopology,
@@ -65,7 +66,7 @@ ${C.bold('USAGE')}
   ensp verify  <scenario-id> --topology <topology.topo> [--json] [--wait MS]
   ensp probe   [--json]
   ensp stop    [--topology <topology.topo>]
-  ensp preset  [<id>] [--search <keyword>] [--topo <out.topo>] [--json]
+  ensp preset  [<id>] [--search <keyword>] [--syllabus <keyword>] [--topo <out.topo>] [--json]
   ensp mcp     (start the MCP server on stdio)
 
 ${C.bold('OPTIONS')}
@@ -75,6 +76,8 @@ ${C.bold('OPTIONS')}
   --device NAME     apply only to one device
   --timeout MS      per-device readiness timeout (default 240000)
   --wait MS         verify: how long a failing assertion may keep being retried (default 60000)
+  --syllabus KW     search the vendor manual chapter index (goals and verification commands)
+  --knowledge KW    search the term index (short answers filed by topic)
   --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)
@@ -92,6 +95,7 @@ ${C.bold('EXAMPLES')}
   ensp up lab.topo --exe "C:/Program Files/Huawei/eNSP/eNSP_Client.exe"
   ensp probe
   ensp preset --search ospf
+  ensp preset --syllabus "MPLS"
   ensp preset ospf-single
   ensp preset campus-network --topo campus.topo
   ensp mcp
@@ -321,6 +325,24 @@ async function cmdStatus({ flags }) {
 async function cmdPreset({ positional, flags }) {
   const id = positional[0]
 
+  if (flags.syllabus) {
+    const hits = searchCurriculum(String(flags.syllabus))
+    if (flags.json) {
+      console.log(JSON.stringify(hits, null, 2))
+      return hits.length ? 0 : 1
+    }
+    if (!hits.length) {
+      console.log(C.yellow('no manual chapter matched') + ` "${flags.syllabus}"`)
+      return 1
+    }
+    for (const h of hits) {
+      console.log(`${C.bold(h.level)} ${h.title} ${C.dim('p' + h.page)}`)
+      if (h.scenarios?.length) console.log(C.dim(`  场景: ${h.scenarios.join(', ')}`))
+      if (h.verify?.length) console.log(C.dim(`  验证: ${h.verify.slice(0, 3).join(' / ')}`))
+    }
+    return 0
+  }
+
   if (flags.knowledge) {
     const hits = searchKnowledge(String(flags.knowledge))
     if (flags.json) {
@@ -411,7 +433,19 @@ async function cmdPreset({ positional, flags }) {
 
     const text = renderScenario(id)
     const points = knowledgeFor(id)
-    console.log(flags.json ? JSON.stringify({ ...SCENARIOS[id], knowledge: points }, null, 2) : text)
+    const chapters = curriculumFor(id).map((c) => ({
+      level: c.level,
+      title: c.title,
+      page: c.page,
+      verify: c.verify,
+    }))
+    console.log(
+      flags.json
+        ? JSON.stringify({ ...SCENARIOS[id], knowledge: points, curriculum: chapters }, null, 2)
+        : text,
+    )
+    const taught = renderCurriculum(id)
+    if (taught) console.log(taught)
     const knowledge = renderKnowledge(id)
     if (knowledge) console.log(knowledge)
     if (hasLab(id)) {