dsh-ensp 0.3.3 → 0.5.0

package/src/core/knowledge.mjs

@@ -0,0 +1,104 @@
+/**
+ * Curriculum knowledge attached to scenarios.
+ *
+ * The scenario presets say what to build and in what order. They deliberately do
+ * not carry commands, because the whole point of the tool is to catch a copied
+ * command that does not fit. What they were missing is the vocabulary the lab is
+ * teaching: which LSA belongs to which area, which attribute wins a BGP decision,
+ * which port role only MSTP has. That is exactly the material a certification
+ * question bank covers.
+ *
+ * This module reads a small generated index instead of the question bank itself:
+ * one topic, the scenarios that teach it, and a list of short question/answer
+ * pairs. Keeping the bank out of the package matters for two reasons. Most of its
+ * questions are three-sentence reading exercises that say nothing, and shipping
+ * a copyrighted question bank inside a GPL package is not a reasonable default.
+ *
+ * @module dsh-ensp/knowledge
+ */
+
+import { readFileSync } from 'node:fs'
+
+let cache = null
+
+/**
+ * Load the generated index, once.
+ *
+ * Read through `new URL` so the path resolves from this module rather than from
+ * whatever directory the caller happens to run in.
+ *
+ * @returns {object}
+ */
+function catalogue() {
+  if (cache) return cache
+  const text = readFileSync(new URL('./knowledge.json', import.meta.url), 'utf8')
+  cache = JSON.parse(text)
+  return cache
+}
+
+/** @returns {string[]} the topics the index covers. */
+export function knowledgeTopics() {
+  return Object.keys(catalogue().topics).sort()
+}
+
+/**
+ * Knowledge points for one scenario.
+ *
+ * A topic can feed several scenarios: `ospf` covers six of them, and each gets the
+ * same points. That repetition is intentional. A learner running the multi-area
+ * lab should not have to know that the material also sits under another scene.
+ *
+ * @param {string} scenarioId
+ * @returns {Array<{topic: string, n: number, q: string, a: string}>}
+ */
+export function knowledgeFor(scenarioId) {
+  const out = []
+  for (const [topic, entry] of Object.entries(catalogue().topics)) {
+    if (!entry.scenarios?.includes(scenarioId)) continue
+    for (const point of entry.points || []) out.push({ topic, ...point })
+  }
+  return out
+}
+
+/**
+ * Search the index by question or answer text.
+ *
+ * Case-insensitive substring match, same contract as {@link searchScenarios} so the
+ * two can be chained in a CLI command without surprising the user.
+ *
+ * @param {string} query
+ * @returns {Array<{topic: string, n: number, q: string, a: string}>}
+ */
+export function searchKnowledge(query) {
+  const needle = String(query ?? '').trim().toLowerCase()
+  if (!needle) return []
+  const out = []
+  for (const [topic, entry] of Object.entries(catalogue().topics)) {
+    for (const point of entry.points || []) {
+      if (`${point.q} ${point.a}`.toLowerCase().includes(needle)) out.push({ topic, ...point })
+    }
+  }
+  return out
+}
+
+/**
+ * Render the knowledge section for a scenario brief.
+ *
+ * Returns an empty string when the scenario has none, so callers can append it
+ * unconditionally.
+ *
+ * @param {string} scenarioId
+ * @param {object} [options]
+ * @param {number} [options.limit=10]
+ * @returns {string}
+ */
+export function renderKnowledge(scenarioId, { limit = 10 } = {}) {
+  const points = knowledgeFor(scenarioId).slice(0, limit)
+  if (!points.length) return ''
+  const lines = ['', '## 知识点（来自认证题库，按主题归类）']
+  for (const p of points) {
+    lines.push(`- ${p.q}`)
+    lines.push(`  答: ${p.a}`)
+  }
+  return lines.join('\n')
+}

package/src/core/launcher.mjs

@@ -35,6 +35,7 @@ import path from 'node:path'
 
 import { calibrateAnchors, DEFAULT_ANCHORS } from './calibrate.mjs'
 import { checkTopologySupport, describeBlocked, rootFromExe } from './compat.mjs'
+import { resolveEnspExe } from './paths.mjs'
 import { readTopology } from './topology.mjs'
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
@@ -301,7 +302,7 @@ export function enspPids() {
  * @returns {Promise<{pid: number, hwnd: string}>}
  */
 export async function launchEnsp({ topology, exspPath, readyTimeoutMs = 120000 } = {}) {
-  const exe = exspPath ?? process.env.DSH_ENSP_EXE ?? 'E:\\Huawei\\eNSP\\eNSP_Client.exe'
+  const exe = resolveEnspExe(exspPath).path
   const target = topology ? path.resolve(topology) : null
 
   // Reject topologies whose devices have no installed image *before* starting the
@@ -469,7 +470,7 @@ $p = Start-Process -FilePath '${exe.replace(/'/g, "''")}'${topology ? ` -Argumen
  * @param {string} topology
  */
 function reopenTopology(topology) {
-  const exe = process.env.DSH_ENSP_EXE ?? 'E:\\Huawei\\eNSP\\eNSP_Client.exe'
+  const exe = resolveEnspExe().path
   startDetached(exe, topology)
 }
 
@@ -591,15 +592,87 @@ Start-Sleep -Milliseconds 250
   return r.ok && r.stdout.split(/\s+/).pop() === 'True'
 }
 
+/**
+ * The window handle that currently holds the foreground, or null.
+ *
+ * Captured before eNSP is raised so it can be handed back afterwards.
+ *
+ * @returns {string|null}
+ */
+export function foregroundWindow() {
+  const r = runPowerShell(
+    `$h = [EnspWin]::GetForegroundWindow()
+([int64]$h).ToString()`,
+    { timeoutMs: 15000 },
+  )
+  const raw = (r.stdout || '').trim().split(/\s+/).pop()
+  if (!raw || raw === '0') return null
+  return raw
+}
+
+/**
+ * Put the foreground back on a previously active window.
+ *
+ * Used after a click that had to raise eNSP: leaving eNSP in front is a
+ * side effect the caller did not ask for. The window state is not touched, so a
+ * visible topology stays visible.
+ *
+ * @param {string|null} hwnd
+ * @returns {boolean} whether the foreground moved back
+ */
+export function restoreForeground(hwnd) {
+  if (!hwnd) return false
+  const r = runPowerShell(
+    `$prev = [IntPtr]::new([int64]${hwnd})
+$ok = [EnspWin]::SetForegroundWindow($prev)
+Start-Sleep -Milliseconds 120
+($ok -and ([EnspWin]::GetForegroundWindow() -eq $prev)).ToString()`,
+    { timeoutMs: 15000 },
+  )
+  return r.ok && (r.stdout || '').trim().split(/\s+/).pop() === 'True'
+}
+
 /**
  * Minimise the eNSP window, handing the desktop back to the user.
+ *
+ * `ShowWindow(SW_MINIMIZE)` minimises without moving the activation: the window
+ * is iconic but still holds the foreground, and Windows then treats the first
+ * taskbar click as an activation correction, so the window appears not to come
+ * back. Restoring the previous foreground window after minimising keeps the
+ * taskbar behaviour standard.
+ *
  * @param {string} hwnd
+ * @param {{previousForeground?: string|null}} [options]
+ * @returns {{iconic: boolean, handedBack: boolean, foreground: string|null}}
  */
-export function minimiseEnsp(hwnd) {
-  runPowerShell(
-    `[EnspWin]::ShowWindow([IntPtr]::new([int64]${hwnd}), 6) | Out-Null; 'ok'`,
-    { timeoutMs: 15000 },
+export function minimiseEnsp(hwnd, options = {}) {
+  const previous = options.previousForeground ?? null
+  const r = runPowerShell(
+    `
+$h = [IntPtr]::new([int64]${hwnd})
+[EnspWin]::ShowWindow($h, 6) | Out-Null
+Start-Sleep -Milliseconds 150
+$fg = [EnspWin]::GetForegroundWindow()
+$iconic = [EnspWin]::IsIconic($h)
+$back = $false
+if ($iconic -and $fg -eq $h) {
+  $prev = $null
+  ${previous ? `$prev = [IntPtr]::new([int64]${previous})` : ''}
+  if ($prev -ne $null -and $prev -ne [IntPtr]::Zero) {
+    $back = [EnspWin]::SetForegroundWindow($prev)
+  }
+  $fg = [EnspWin]::GetForegroundWindow()
+  if ($fg -eq $h) { $back = $false }
+}
+"ICONIC=$iconic FOREGROUND=" + ([int64]$fg).ToString() + " BACK=$back"
+`,
+    { timeoutMs: 20000 },
   )
+  const text = r.stdout || ''
+  const iconic = /ICONIC=True/i.test(text)
+  const handedBack = /BACK=True/i.test(text)
+  const m = /FOREGROUND=(-?\d+)/.exec(text)
+  return { iconic, handedBack, foreground: m ? m[1] : null }
 }
 
 /**
@@ -820,6 +893,8 @@ export async function startAllDevices({
   // Doing it the other way round reports the window that was on top a moment ago
   // (usually the terminal that launched us) as if it were a permanent blocker.
   report({ phase: 'focus', hwnd })
+  // Remember who had the foreground so the minimised eNSP does not keep it.
+  const previousForeground = minimise ? foregroundWindow() : null
   let focused = focusEnsp(hwnd)
   if (focused) await new Promise((resolve) => setTimeout(resolve, 300))
 
@@ -867,8 +942,8 @@ export async function startAllDevices({
 
   // Hand the desktop back immediately; boot continues without the window.
   if (minimise) {
-    minimiseEnsp(hwnd)
-    report({ phase: 'minimised' })
+    const handback = minimiseEnsp(hwnd, { previousForeground })
+    report({ phase: 'minimised', ...handback })
   }
 
   report({ phase: 'wait', devices: targets.length })
@@ -909,7 +984,12 @@ export function stopAllDevices(hwnd, options = {}) {
       anchors = { ...DEFAULT_ANCHORS, method: 'default', detail: {} }
     }
   }
+  const previousForeground = foregroundWindow()
   const focused = focusEnsp(hwnd)
   const result = clickToolbar(hwnd, { button: 'stop', anchors })
-  return { focused, anchors, ...result }
+  // The click needs eNSP in front, but leaving it there surprises the user who
+  // asked for a stop: hand the foreground back without touching the window
+  // state, so the topology stays visible while the devices power down.
+  const handback = restoreForeground(previousForeground)
+  return { focused, anchors, handback, ...result }
 }

package/src/core/paths.mjs

@@ -0,0 +1,190 @@
+/**
+ * Locate the eNSP client and VBoxManage.
+ *
+ * Both used to be hardcoded to `E:\`, which made every machine with a normal
+ * install fail at launch. The lookup order is:
+ *
+ *   1. an explicit override (CLI flag, plugin config, or function argument)
+ *   2. `DSH_ENSP_EXE` / `ENSP_EXE` / `DSH_VBOX`
+ *   3. the Windows install registry
+ *   4. the usual install roots
+ *   5. `where` on PATH (VBoxManage only)
+ *
+ * Every candidate that was tried is reported on failure, so a wrong override
+ * produces a message that says what was looked at instead of a bare ENOENT.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+/** Registry keys an installer may have written the install root to. */
+const ENSP_REGISTRY = [
+  ['HKLM\\SOFTWARE\\Huawei\\eNSP', 'InstallPath'],
+  ['HKLM\\SOFTWARE\\WOW6432Node\\Huawei\\eNSP', 'InstallPath'],
+  ['HKLM\\SOFTWARE\\Huawei\\eNSP', 'InstallDir'],
+]
+
+/** Install roots seen on real machines, most common first. */
+const ENSP_ROOTS = [
+  'C:\\Program Files\\Huawei\\eNSP',
+  'C:\\Program Files (x86)\\Huawei\\eNSP',
+  'D:\\Huawei\\eNSP',
+  'E:\\Huawei\\eNSP',
+]
+
+/** Where VirtualBox installs itself, most common first. */
+const VBOX_PATHS = [
+  'C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe',
+  'C:\\Program Files (x86)\\Oracle\\VirtualBox\\VBoxManage.exe',
+  'D:\\VirtualBox\\VBoxManage.exe',
+  'E:\\VirtualBox\\VBoxManage.exe',
+]
+
+const isWindows = process.platform === 'win32'
+
+/** True when the path exists and is a file. Never throws. */
+function isFile(candidate) {
+  if (!candidate) return false
+  try {
+    return fs.statSync(candidate).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** Read one string value out of the registry, or null. */
+function registryValue(key, name) {
+  if (!isWindows) return null
+  const r = spawnSync('reg', ['query', key, '/v', name], { encoding: 'utf8', windowsHide: true })
+  if (r.status !== 0 || !r.stdout) return null
+  const m = new RegExp(`${name}\\s+REG_\\w+\\s+(.+)`).exec(r.stdout)
+  return m ? m[1].trim() : null
+}
+
+/** Expand `%VAR%` and strip surrounding quotes from a registry value. */
+function cleanRoot(value) {
+  if (!value) return null
+  const unquoted = value.trim().replace(/^"|"$/g, '')
+  const expanded = unexpanded(unquoted)
+  return expanded || null
+}
+
+/** Expand Windows environment variables without depending on the shell. */
+function unexpanded(value) {
+  return value.replace(/%([^%]+)%/g, (whole, name) => process.env[name] ?? whole)
+}
+
+/** Every candidate eNSP client path, in lookup order, with its source. */
+export function enspCandidates(override) {
+  const out = []
+  if (override) out.push({ path: override, source: 'override' })
+  for (const name of ['DSH_ENSP_EXE', 'ENSP_EXE']) {
+    const v = process.env[name]
+    if (v) out.push({ path: v, source: name })
+  }
+  for (const [key, name] of ENSP_REGISTRY) {
+    const root = cleanRoot(registryValue(key, name))
+    if (root) out.push({ path: path.join(root, 'eNSP_Client.exe'), source: `${key}\\${name}` })
+  }
+  for (const root of ENSP_ROOTS) out.push({ path: path.join(root, 'eNSP_Client.exe'), source: 'install root' })
+  return out
+}
+
+/** Every candidate VBoxManage path, in lookup order, with its source. */
+export function vboxCandidates(override) {
+  const out = []
+  if (override) out.push({ path: override, source: 'override' })
+  if (process.env.DSH_VBOX) out.push({ path: process.env.DSH_VBOX, source: 'DSH_VBOX' })
+  if (isWindows) {
+    const r = spawnSync('where', ['VBoxManage.exe'], { encoding: 'utf8', windowsHide: true })
+    const first = (r.stdout || '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0]
+    if (first) out.push({ path: first, source: 'PATH' })
+  }
+  for (const p of VBOX_PATHS) out.push({ path: p, source: 'install root' })
+  return out
+}
+
+/** First existing candidate, or null. */
+function firstExisting(candidates) {
+  for (const c of candidates) if (isFile(c.path)) return c
+  return null
+}
+
+/**
+ * Resolve the eNSP client executable.
+ *
+ * @param {string} [override] - explicit path from a flag or plugin config
+ * @returns {{path: string, source: string, tried: string[]}}
+ * @throws when nothing exists
+ */
+export function resolveEnspExe(override) {
+  // An explicit path is a statement of intent, not a hint. Falling back to some
+  // other installation would run a different eNSP than the one that was asked
+  // for, and the user would see a working launch on the machine they pointed at
+  // and a mystery on the machine they meant.
+  if (override && !isFile(override)) {
+    throw new Error(
+      `the eNSP client path given does not exist: ${override}\n`
+        + 'Check the path, or drop --exe to let the tool search for an installation.',
+    )
+  }
+  const candidates = enspCandidates(override)
+  const hit = firstExisting(candidates)
+  if (hit) return { path: hit.path, source: hit.source, tried: candidates.map((c) => c.path) }
+  const tried = candidates.map((c) => `  ${c.path}  (${c.source})`).join('\n')
+  throw new Error(
+    `eNSP client not found. Looked at:\n${tried}\n\n`
+      + 'Pass --exe, set DSH_ENSP_EXE, or configure the plugin, with the full path to eNSP_Client.exe. '
+      + 'Installing eNSP to its default location also works.',
+  )
+}
+
+/**
+ * Resolve VBoxManage.
+ *
+ * @param {string} [override]
+ * @returns {{path: string, source: string, tried: string[]}}
+ * @throws when nothing exists
+ */
+export function resolveVBoxManage(override) {
+  if (override && !isFile(override)) {
+    throw new Error(
+      `the VBoxManage path given does not exist: ${override}\n`
+        + 'Check the path, or drop --vbox to let the tool search for an installation.',
+    )
+  }
+  const candidates = vboxCandidates(override)
+  const hit = firstExisting(candidates)
+  if (hit) return { path: hit.path, source: hit.source, tried: candidates.map((c) => c.path) }
+  const tried = candidates.map((c) => `  ${c.path}  (${c.source})`).join('\n')
+  throw new Error(
+    `VBoxManage.exe not found. Looked at:\n${tried}\n\n`
+      + 'Pass --vbox, set DSH_VBOX, or add the VirtualBox install directory to PATH.',
+  )
+}
+
+/**
+ * Resolve the eNSP install root, which holds `res/items.xml` and the plugins.
+ *
+ * Derived from the client path when it can be found, so a machine that launches
+ * successfully also has a correct catalogue path.
+ *
+ * @param {{exe?: string, root?: string}} [options]
+ * @returns {string|null}
+ */
+export function resolveEnspRoot(options = {}) {
+  if (options.root && fs.existsSync(options.root)) return options.root
+  if (options.exe) return path.dirname(options.exe)
+  const hit = firstExisting(enspCandidates())
+  return hit ? path.dirname(hit.path) : null
+}
+
+/** Non-throwing probe used by `doctor`, which reports instead of raising. */
+export function probePaths({ exe, vbox } = {}) {
+  const ensp = firstExisting(enspCandidates(exe))
+  const box = firstExisting(vboxCandidates(vbox))
+  return {
+    ensp: ensp ? { ok: true, path: ensp.path, source: ensp.source } : { ok: false, path: null },
+    vbox: box ? { ok: true, path: box.path, source: box.source } : { ok: false, path: null },
+  }
+}

package/src/core/provision.mjs

@@ -22,10 +22,37 @@
  * @module dsh-ensp/provision
  */
 
-import { openConsole, viewOf } from './console.mjs'
+import { openConsole } from './console.mjs'
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/**
+ * Errors that mean "the device is already in the state you asked for".
+ *
+ * Re-running the same configuration is the normal way to work: change one line,
+ * apply again, look at the effect. VRP answers the unchanged lines with an error,
+ * and aborting the batch there makes the tool unusable for that loop. These
+ * specific replies are recorded as no-ops instead. Everything else still stops
+ * the batch, because a genuine rejection means the rest of the script is
+ * probably landing on the wrong object.
+ */
+const IDEMPOTENT_RE =
+  /already exists|The VLAN already exists|address already exists|The object already exists|has already been created|is already configured|The route already exists|The ACL rule already exists/i
+
+/**
+ * Whether a VRP error means "this line is already in effect".
+ *
+ * Exported so the behaviour can be tested without a device: the distinction
+ * between "already there" and "rejected" is the whole point of a re-runnable
+ * apply, and it is easy to widen the pattern until real failures are swallowed.
+ *
+ * @param {string} message
+ * @returns {boolean}
+ */
+export function isIdempotentError(message) {
+  return IDEMPOTENT_RE.test(String(message ?? ''))
+}
+
 /**
  * Split a configuration script into executable lines.
  *
@@ -111,21 +138,21 @@ export async function pushConfig({
       // not. Because we already entered system view above, a leading `system-view`
       // would be rejected ("Unrecognized command") and abort the batch. Treat it as
       // idempotent: skip it when we are already in the right place.
-      if (/^system-view$/i.test(command) && viewOf(session.prompt) === 'system') {
+      if (/^system-view$/i.test(command) && session.view === 'system') {
         applied += 1
         transcript.push({ line, command, ok: true, skipped: 'already in system view', output: '' })
         report?.({ phase: 'command', device, line, command, ok: true, skipped: true })
         continue
       }
       // Likewise `return` from system view is a no-op noise source.
-      if (/^return$/i.test(command) && viewOf(session.prompt) === 'system') {
+      if (/^return$/i.test(command) && session.view === 'system') {
         applied += 1
         transcript.push({ line, command, ok: true, skipped: 'already at top of system view', output: '' })
         report?.({ phase: 'command', device, line, command, ok: true, skipped: true })
         continue
       }
       // Guard against view drift: a previous `quit` may have dropped us out.
-      if (viewOf(session.prompt) === 'user') {
+      if (session.view === 'user') {
         const back = await session.ensureSystemView()
         if (!back.ok) {
           return {
@@ -159,6 +186,15 @@ export async function pushConfig({
       })
       report({ phase: 'command', device, line, command, ok: result.ok, view: result.view })
 
+      if (!result.ok && isIdempotentError(result.error)) {
+        // Already in the requested state. Count it so the totals stay meaningful,
+        // and keep the transcript honest about what the device actually said.
+        applied += 1
+        transcript[transcript.length - 1].skipped = 'already in the requested state'
+        report({ phase: 'command', device, line, command, ok: true, skipped: true, view: result.view })
+        continue
+      }
+
       if (!result.ok) {
         if (stopOnError) {
           return {

package/src/dsh/index.mjs

@@ -48,6 +48,7 @@ import { pushConfig, pushConfigMany, queryDevice } from '../core/provision.mjs'
 import { SCENARIOS, SCENARIO_IDS, renderScenario, searchScenarios, byLevel } from '../core/presets.mjs'
 import { doctor, modelsOf } from '../core/doctor.mjs'
 import { runAcceptance, hasChecks } from '../core/acceptance.mjs'
+import { knowledgeFor, searchKnowledge, knowledgeTopics, renderKnowledge } from '../core/knowledge.mjs'
 import { VERSION } from '../core/version.mjs'
 
 /** Declared hard dependency: the tool registry. */
@@ -104,6 +105,45 @@ function stripRequired(node) {
 /** Declare a closed output object. */
 const obj = (properties) => compileObject(properties)
 
+/**
+ * Fill in required properties that a return branch omitted.
+ *
+ * A tool has several branches, and some of them legitimately have nothing to
+ * report: when eNSP is not running there is no pid, no hwnd and no anchor. The
+ * consumer still benefits from a stable shape, so the branch does not have to
+ * repeat empty fields and the schema does not have to relax.
+ *
+ * Missing required keys get the empty value for their type. Keys the branch did
+ * return are never touched, so a wrong value still reaches the validator.
+ */
+/**
+ * Fill in the branches a tool did not return.
+ *
+ * Exported so the contract can be tested without calling a device: every tool
+ * declares its full output shape, and a run that legitimately has nothing to say
+ * about one field must still satisfy that shape.
+ */
+export function conform(schema, value) {
+  if (!schema || schema.type !== 'object') return value
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value
+  const out = { ...value }
+  for (const key of schema.required ?? []) {
+    if (out[key] !== undefined) continue
+    out[key] = emptyFor(schema.properties?.[key])
+  }
+  return out
+}
+
+/** The empty value for a schema node's type. */
+function emptyFor(node) {
+  const type = node?.type
+  if (type === 'number' || type === 'integer') return 0
+  if (type === 'boolean') return false
+  if (type === 'array') return []
+  if (type === 'object') return {}
+  return ''
+}
+
 /** One plain text content block. */
 const text = (value) => [{ type: 'text', text: String(value) }]
 
@@ -121,7 +161,8 @@ function add(tools, definition) {
   return tools.register({
     ...rest,
     async execute(args) {
-      return execute(args ?? {})
+      const value = await execute(args ?? {})
+      return conform(definition.output?.schema, value)
     },
   })
 }
@@ -558,13 +599,55 @@ export function apply(ctx) {
           brief +
           (hasChecks(id)
             ? `\n\n验收: ensp_verify { scenario: "${id}", topology: "${id}.topo" }`
-            : '\n\n验收: 无专门断言，ensp_verify 会逐条跑场景里的验证命令'),
+            : '\n\n验收: 无专门断言，ensp_verify 会逐条跑场景里的验证命令') +
+          renderKnowledge(id),
       }
     },
   })
 
   /* ---------------------------------------------------------- preset config */
 
+  add(tools, {
+    name: 'ensp_knowledge',
+    description:
+      'Look up curriculum knowledge derived from a certification question bank: short ' +
+      'question/answer pairs filed by topic, and the scenarios that teach each topic. ' +
+      'Pass scenario to list what one lab teaches, or query to search the index.',
+    parameters: {
+      query: str('Keyword, e.g. "LSA" or "MED".'),
+      scenario: str('Scenario id, e.g. "ospf-lsa-types".'),
+    },
+    output: {
+      schema: obj({
+        scope: req(str()),
+        count: req(num()),
+        points: req(str()),
+        error: req(str()),
+      }),
+      render(args, value) {
+        return text(value.points || '(no knowledge point matched)')
+      },
+    },
+    async execute({ query, scenario }) {
+      if (scenario) {
+        if (!SCENARIOS[scenario]) throw new Error(`unknown scenario "${scenario}"`)
+        const points = knowledgeFor(scenario)
+        return {
+          scope: scenario,
+          count: points.length,
+          points: points.map((p) => `#${p.n} [${p.topic}] ${p.q}\n  答: ${p.a}`).join('\n'),
+        }
+      }
+      if (!query) throw new Error('pass query or scenario')
+      const points = searchKnowledge(query)
+      return {
+        scope: String(query),
+        count: points.length,
+        points: points.map((p) => `#${p.n} [${p.topic}] ${p.q}\n  答: ${p.a}`).join('\n'),
+      }
+    },
+  })
+
   add(tools, {
     name: 'ensp_preset_config',
     description: 'Return the configuration text for the built-in two-PC lab.',

package/src/mcp/server.mjs

@@ -40,6 +40,7 @@ import {
 import { calibrateAnchors, inspectAnchors, DEFAULT_ANCHORS } from '../core/calibrate.mjs'
 import { doctor, modelsOf } from '../core/doctor.mjs'
 import { runAcceptance, hasChecks, EXPECTATIONS } from '../core/acceptance.mjs'
+import { knowledgeFor, searchKnowledge, knowledgeTopics } from '../core/knowledge.mjs'
 import { pushConfig, pushConfigMany, queryDevice } from '../core/provision.mjs'
 import { SCENARIOS, SCENARIO_IDS, byLevel, renderScenario, searchScenarios } from '../core/presets.mjs'
 import { PACKAGE_NAME, VERSION } from '../core/version.mjs'
@@ -331,6 +332,7 @@ const TOOLS = [
         hasTopology: hasLab(id),
         hasCuratedChecks: hasChecks(id),
         ...(hasLab(id) ? { devices: labDevices(id), addressing: labAddressing(id) } : {}),
+        knowledge: knowledgeFor(id),
       }
     },
   },
@@ -373,6 +375,27 @@ const TOOLS = [
       return runAcceptance({ id: scenario, topology, timeoutMs: timeout, waitMs: wait })
     },
   },
+  {
+    name: 'ensp_knowledge',
+    description:
+      'Search the curriculum knowledge index derived from a certification question bank. ' +
+      'Use it to look up the vocabulary a scenario teaches (which LSA belongs to which area, ' +
+      'which BGP attribute wins, which port role is MSTP only) without leaving the lab. ' +
+      'Returns short question/answer pairs plus the scenarios that teach each topic.',
+    inputSchema: obj({
+      query: { type: 'string', description: 'keyword, e.g. "LSA" or "MED"' },
+      scenario: { type: 'string', description: 'scenario id, to list what that lab teaches' },
+    }),
+    async run({ query, scenario }) {
+      if (scenario) {
+        if (!SCENARIOS[scenario]) throw new Error(`unknown scenario "${scenario}"`)
+        return { scenario, topics: knowledgeTopics(), points: knowledgeFor(scenario) }
+      }
+      if (!query) throw new Error('pass query or scenario')
+      return { query, points: searchKnowledge(query) }
+    },
+  },
+
   {
     name: 'ensp_preset_config',
     description: 'Return the configuration that makes the built-in two-PC lab pass traffic.',