dsh-ensp 0.5.0 → 0.6.0

package/src/core/knowledge.mjs

@@ -5,14 +5,13 @@
  * 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.
+ * which port role only MSTP has. Short, checkable statements about those terms
+ * are what a learner needs before touching a device.
  *
- * 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.
+ * This module reads a small generated index: one topic, the scenarios that teach
+ * it, and a list of short question/answer pairs. Shipping only the index keeps the
+ * package small and keeps third-party source material out of a GPL distribution,
+ * while `npm run knowledge` still makes every entry reproducible.
  *
  * @module dsh-ensp/knowledge
  */
@@ -95,7 +94,7 @@ export function searchKnowledge(query) {
 export function renderKnowledge(scenarioId, { limit = 10 } = {}) {
   const points = knowledgeFor(scenarioId).slice(0, limit)
   if (!points.length) return ''
-  const lines = ['', '## 知识点（来自认证题库，按主题归类）']
+  const lines = ['', '## 知识点（按主题归类）']
   for (const p of points) {
     lines.push(`- ${p.q}`)
     lines.push(`  答: ${p.a}`)

package/src/dsh/index.mjs

@@ -49,6 +49,7 @@ import { SCENARIOS, SCENARIO_IDS, renderScenario, searchScenarios, byLevel } fro
 import { doctor, modelsOf } from '../core/doctor.mjs'
 import { runAcceptance, hasChecks } from '../core/acceptance.mjs'
 import { knowledgeFor, searchKnowledge, knowledgeTopics, renderKnowledge } from '../core/knowledge.mjs'
+import { curriculumFor, renderCurriculum, searchCurriculum } from '../core/curriculum.mjs'
 import { VERSION } from '../core/version.mjs'
 
 /** Declared hard dependency: the tool registry. */
@@ -582,6 +583,7 @@ export function apply(ctx) {
       schema: obj({
         id: req(str()),
         brief: req(str()),
+        curriculum: req(arr()),
         error: req(str()),
       }),
       render(args, value) {
@@ -600,7 +602,14 @@ export function apply(ctx) {
           (hasChecks(id)
             ? `\n\n验收: ensp_verify { scenario: "${id}", topology: "${id}.topo" }`
             : '\n\n验收: 无专门断言，ensp_verify 会逐条跑场景里的验证命令') +
+          renderCurriculum(id) +
           renderKnowledge(id),
+        curriculum: curriculumFor(id).map((c) => ({
+          level: c.level,
+          title: c.title,
+          page: c.page,
+          verify: c.verify,
+        })),
       }
     },
   })
@@ -610,12 +619,13 @@ export function apply(ctx) {
   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.',
+      'Look up two reference indexes. Pass scenario to list what one lab teaches, query to ' +
+      'search short term/answer notes, or syllabus to search the vendor manual chapter index ' +
+      '(chapter goals plus the display commands each chapter uses to prove its result).',
     parameters: {
       query: str('Keyword, e.g. "LSA" or "MED".'),
       scenario: str('Scenario id, e.g. "ospf-lsa-types".'),
+      syllabus: str('Keyword to search the manual chapter index, e.g. "MPLS" or "BFD".'),
     },
     output: {
       schema: obj({
@@ -628,7 +638,22 @@ export function apply(ctx) {
         return text(value.points || '(no knowledge point matched)')
       },
     },
-    async execute({ query, scenario }) {
+    async execute({ query, scenario, syllabus }) {
+      if (syllabus) {
+        const chapters = searchCurriculum(syllabus)
+        return {
+          scope: `syllabus:${syllabus}`,
+          count: chapters.length,
+          points: chapters
+            .map(
+              (c) =>
+                `${c.level} · ${c.title} (p${c.page})\n` +
+                (c.scenarios.length ? `  场景: ${c.scenarios.join(', ')}\n` : '') +
+                (c.verify.length ? `  验证: ${c.verify.slice(0, 4).join(' / ')}` : ''),
+            )
+            .join('\n'),
+        }
+      }
       if (scenario) {
         if (!SCENARIOS[scenario]) throw new Error(`unknown scenario "${scenario}"`)
         const points = knowledgeFor(scenario)
@@ -638,7 +663,7 @@ export function apply(ctx) {
           points: points.map((p) => `#${p.n} [${p.topic}] ${p.q}\n  答: ${p.a}`).join('\n'),
         }
       }
-      if (!query) throw new Error('pass query or scenario')
+      if (!query) throw new Error('pass query, scenario or syllabus')
       const points = searchKnowledge(query)
       return {
         scope: String(query),

package/src/mcp/server.mjs

@@ -41,6 +41,7 @@ import { calibrateAnchors, inspectAnchors, DEFAULT_ANCHORS } from '../core/calib
 import { doctor, modelsOf } from '../core/doctor.mjs'
 import { runAcceptance, hasChecks, EXPECTATIONS } from '../core/acceptance.mjs'
 import { knowledgeFor, searchKnowledge, knowledgeTopics } from '../core/knowledge.mjs'
+import { curriculumFor, renderCurriculum, searchCurriculum } from '../core/curriculum.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'
@@ -327,12 +328,13 @@ const TOOLS = [
       if (!SCENARIOS[id]) throw new Error(`unknown scenario "${id}"`)
       return {
         id,
-        brief: renderScenario(id),
+        brief: renderScenario(id) + renderCurriculum(id),
         data: SCENARIOS[id],
         hasTopology: hasLab(id),
         hasCuratedChecks: hasChecks(id),
         ...(hasLab(id) ? { devices: labDevices(id), addressing: labAddressing(id) } : {}),
         knowledge: knowledgeFor(id),
+        curriculum: curriculumFor(id),
       }
     },
   },
@@ -378,20 +380,30 @@ const TOOLS = [
   {
     name: 'ensp_knowledge',
     description:
-      'Search the curriculum knowledge index derived from a certification question bank. ' +
+      'Search the curriculum knowledge index: short factual statements about the terms each '
+        + 'scenario exercises, grouped by topic. ' +
       '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' },
+      syllabus: { type: 'string', description: 'keyword to search the manual chapter index instead' },
     }),
-    async run({ query, scenario }) {
+    async run({ query, scenario, syllabus }) {
+      if (syllabus) {
+        return { syllabus, chapters: searchCurriculum(syllabus) }
+      }
       if (scenario) {
         if (!SCENARIOS[scenario]) throw new Error(`unknown scenario "${scenario}"`)
-        return { scenario, topics: knowledgeTopics(), points: knowledgeFor(scenario) }
+        return {
+          scenario,
+          topics: knowledgeTopics(),
+          points: knowledgeFor(scenario),
+          curriculum: curriculumFor(scenario),
+        }
       }
-      if (!query) throw new Error('pass query or scenario')
+      if (!query) throw new Error('pass query, scenario or syllabus')
       return { query, points: searchKnowledge(query) }
     },
   },