dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/lib/kb-version.js

@@ -0,0 +1,118 @@
+/**
+ * kb-version — 宿主 dsh 版本探测与升级指南匹配（零依赖，纯函数）。
+ *
+ * 目的：知识库快照同步自上游 master（领先宿主），dsh_kb_search / dsh_kb_read
+ * 返回结果时按宿主实际版本附版本横幅，提示 API 可能存在的版本差异，
+ * 并给出对应的 extra/upgrade-guide/<vX.Y.Z> 目录。
+ *
+ * 探测策略（全部失败安全，拿不到就返回 null，绝不抛错）：
+ *   1. 从插件安装目录向上逐层找 node_modules/@deepseek-ai/dsh/package.json
+ *      （兼容 link: junction / file: 安装的 realpath 落点差异，最多回溯 6 层）；
+ *   2. 再试 @deepseek-ai/dsh-base（desktop 安装形态里两者同版本）。
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+
+/** 读 package.json 的 version；失败返回 null。 */
+function readVersion(pkgPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    return typeof pkg?.version === 'string' && pkg.version ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/** 逐层向上找包目录；找不到返回 null。 */
+function findPkgDir(startDir, scope, name, maxUp = 6) {
+  let dir = resolve(startDir)
+  for (let i = 0; i <= maxUp; i++) {
+    const candidate = join(dir, 'node_modules', scope, name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+  return null
+}
+
+/** 比较 dsh 预发布版本号（x.y.z-rc.N / -alpha.N）；返回 -1/0/1。只比数字段 + 预发布序，不做完整 semver。 */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([a-z]+)\.?(\d+))?$/i.exec(String(v).trim())
+    if (!m) return null
+    const stageRank = { alpha: 0, beta: 1, rc: 2 }
+    return {
+      nums: [Number(m[1]), Number(m[2]), Number(m[3])],
+      stage: m[4] ? stageRank[m[4].toLowerCase()] ?? -1 : 3,
+      stageNum: m[5] ? Number(m[5]) : 0,
+    }
+  }
+  const pa = parse(a)
+  const pb = parse(b)
+  if (!pa || !pb) return 0
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1
+  }
+  if (pa.stage !== pb.stage) return pa.stage < pb.stage ? -1 : 1
+  if (pa.stageNum !== pb.stageNum) return pa.stageNum < pb.stageNum ? -1 : 1
+  return 0
+}
+
+/**
+ * 探测宿主 dsh 版本。
+ * @param {string} pkgDir 插件包目录（lib/ 的上一级）
+ * @returns {{ version: string, source: string } | null}
+ */
+export function detectHostVersion(pkgDir) {
+  for (const [scope, name] of [['@deepseek-ai', 'dsh'], ['@deepseek-ai', 'dsh-base']]) {
+    const dir = findPkgDir(pkgDir, scope, name)
+    if (dir) {
+      const version = readVersion(join(dir, 'package.json'))
+      if (version) return { version, source: `${scope}/${name}` }
+    }
+  }
+  return null
+}
+
+/**
+ * 在 extra/upgrade-guide/ 下为宿主版本选最合适的指南目录：
+ * 精确命中优先；否则取 ≤ 宿主版本的最大目录（宿主版本由若干指南逐版到达，
+ * 其后的指南描述的是「比宿主新」的变更，正是「文档领先宿主」的差异来源）。
+ * @returns {string | null} 目录名（如 'v0.2.0-rc.2'）
+ */
+export function matchUpgradeGuide(kbDir, hostVersion) {
+  const guideRoot = join(kbDir, 'extra', 'upgrade-guide')
+  let dirs = []
+  try {
+    dirs = readdirSync(guideRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((n) => /^v/.test(n))
+  } catch {
+    return null
+  }
+  if (!dirs.length || !hostVersion) return null
+  if (dirs.includes(`v${hostVersion}`)) return `v${hostVersion}`
+  const lower = dirs.filter((d) => compareVersions(d, `v${hostVersion}`) <= 0)
+  if (lower.length) return lower.sort((a, b) => compareVersions(a, b))[lower.length - 1]
+  return null
+}
+
+/**
+ * 组装版本横幅文本（search / read 工具共用）。
+ * @returns {string | null} null = 无版本信息，不加横幅
+ */
+export function versionBanner(kbDir, host, kbSyncNote = true) {
+  if (!host) return null
+  const guide = matchUpgradeGuide(kbDir, host.version)
+  const lines = []
+  if (kbSyncNote) {
+    lines.push(`【版本提示】宿主 dsh ${host.version}（探测自 ${host.source}）；知识库快照同步自上游 master，可能领先宿主——API 行为不符时以宿主实际安装包为准。`)
+  }
+  if (guide) {
+    lines.push(`版本差异请读升级指南：extra/upgrade-guide/${guide}/（含 ${guide.slice(1)} 前后的破坏性变更与迁移项）。`)
+  }
+  return lines.length ? lines.join('\n') : null
+}

package/package.json

@@ -1,66 +1,68 @@
-{
-  "name": "dsh-plugin-dev-kb",
-  "description": "dsh 插件辅助：① dsh-plugin-dev-kb 技能 = DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 192 页）+ 439 篇仓库补充开发参考 + 主题导航与 634 文件全量搜索索引；② dsh-dev-sandbox 技能 = 自建独立沙箱 profile 开发沙箱工作流（沙箱名由 agent 按任务自定），开发中的插件隔离运行，agent 自主启动/重启/冒烟验证，插件崩了不影响主力 dsh；③ dsh_kb_search 工具 = 知识库本地打分检索，一次调用返回命中文件 + 行号 + 上下文片段。零运行时依赖。",
-  "version": "1.6.0",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "docs",
-    "kb",
-    "skills",
-    "scripts",
-    "cordis.patch.yml",
-    "README.md",
-    "README.en.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "selfcheck": "node scripts/selfcheck.mjs",
-    "rebuild-index": "node scripts/rebuild-index.mjs"
-  },
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek",
-    "harness",
-    "cordis",
-    "plugin",
-    "knowledge",
-    "knowledge-base",
-    "documentation",
-    "official-docs",
-    "documentation-mirror",
-    "kb",
-    "plugin-development",
-    "agent-skills",
-    "skills",
-    "retrieval",
-    "rag"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Pasumao/dsh-plugin-dev-kb.git"
-  },
-  "homepage": "https://github.com/Pasumao/dsh-plugin-dev-kb",
-  "bugs": {
-    "url": "https://github.com/Pasumao/dsh-plugin-dev-kb/issues"
-  },
-  "license": "MIT",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  }
-}
+{
+  "name": "dsh-plugin-dev-kb",
+  "description": "dsh 插件辅助：① dsh-plugin-dev-kb 技能 = DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 192 页）+ 439 篇仓库补充开发参考 + 主题导航与 634 文件全量搜索索引；② dsh-dev-sandbox 技能 = 自建独立沙箱 profile 开发沙箱工作流（沙箱名由 agent 按任务自定），开发中的插件隔离运行，agent 自主启动/重启/冒烟验证，插件崩了不影响主力 dsh；③ dsh_kb_search 工具 = 知识库本地打分检索，一次调用返回命中文件 + 行号 + 上下文片段。零运行时依赖。",
+  "version": "1.8.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "docs",
+    "kb",
+    "skills",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "selfcheck": "node scripts/selfcheck.mjs",
+    "rebuild-index": "node scripts/rebuild-index.mjs",
+    "refresh-kb": "node scripts/refresh-kb.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "harness",
+    "cordis",
+    "plugin",
+    "knowledge",
+    "knowledge-base",
+    "documentation",
+    "official-docs",
+    "documentation-mirror",
+    "kb",
+    "plugin-development",
+    "agent-skills",
+    "skills",
+    "retrieval",
+    "rag"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pasumao/dsh-plugin-dev-kb.git"
+  },
+  "homepage": "https://github.com/Pasumao/dsh-plugin-dev-kb",
+  "bugs": {
+    "url": "https://github.com/Pasumao/dsh-plugin-dev-kb/issues"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/refresh-kb.mjs

@@ -0,0 +1,153 @@
+// One-shot knowledge-base refresh: sync kb/ from upstream deepseek-harness master.
+// Usage:  node scripts/refresh-kb.mjs [--keep-tmp]
+// Steps (see kb/README.md「更新方法」):
+//   1. shallow-clone upstream repo into a temp dir
+//   2. install mdast projection deps next to the clone
+//   3. run scripts/project-doc-site.ts -> website/.generated
+//   4. mirror .generated -> kb/site
+//   5. rebuild kb/extra = docs/ md NOT in the published set (docsPages source/aliases)
+//   6. npm run rebuild-index; update kb/meta/source.json + kb/README.md stats
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PLUGIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = path.join(PLUGIN, 'kb');
+const REPO_URL = 'https://github.com/deepseek-ai/deepseek-harness.git';
+const TMP = path.join(PLUGIN, '.refresh-tmp');
+const CLONE = path.join(TMP, 'deepseek-harness');
+const KEEP = process.argv.includes('--keep-tmp');
+
+function pathToFileUrl(p) {
+  return 'file:///' + p.replace(/\\/g, '/');
+}
+
+function run(cmd, opts = {}) {
+  const r = spawnSync(cmd, { shell: true, stdio: 'inherit', cwd: CLONE, ...opts });
+  if (r.status !== 0) { console.error(`FAILED: ${cmd} (cwd=${opts.cwd || CLONE})`); process.exit(r.status ?? 1); }
+}
+
+// robocopy: exit codes 0-7 all mean success (1 = files copied)
+function robocopy(src, dest, extra = '') {
+  const r = spawnSync(`robocopy "${src}" "${dest}" /MIR /NFL /NDL /NJH /NJS ${extra}`, { shell: true, stdio: 'inherit' });
+  if (r.status === null || r.status > 7) { console.error(`robocopy FAILED (${r.status}): ${src} -> ${dest}`); process.exit(r.status ?? 1); }
+}
+
+function countMd(dir) {
+  let n = 0;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) n += countMd(path.join(dir, e.name));
+    else if (e.name.endsWith('.md')) n++;
+  }
+  return n;
+}
+
+console.log('[1/6] cloning upstream ...');
+fs.rmSync(TMP, { recursive: true, force: true });
+fs.mkdirSync(TMP, { recursive: true });
+run(`git clone --depth 1 ${REPO_URL} "${CLONE}"`, { cwd: PLUGIN });
+const commit = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: CLONE, encoding: 'utf8' }).stdout.trim();
+console.log('  commit:', commit);
+
+console.log('[2/6] installing projection deps ...');
+run('npm install --no-save --no-package-lock mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm', { cwd: TMP });
+
+console.log('[3/6] projecting doc site ...');
+run('node --input-type=module -e "import(\'./scripts/project-doc-site.ts\').then(m => m.projectDocs()).then(() => console.log(\'projected\'))"');
+
+console.log('[4/6] mirroring kb/site ...');
+robocopy(path.join(CLONE, 'website', '.generated'), path.join(KB, 'site'));
+
+console.log('[5/6] rebuilding kb/extra from published-set diff ...');
+const { docsPages } = await import(pathToFileUrl(path.join(CLONE, 'website', 'docs.ts')));
+const norm = s => String(s).replace(/\\/g, '/').replace(/^docs\//, '');
+const published = new Set();
+for (const p of docsPages) {
+  published.add(norm(p.source));
+  for (const a of p.sourceAliases || []) published.add(norm(a));
+}
+const DOCS = path.join(CLONE, 'docs');
+const wanted = [];
+(function walk(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full);
+    else if (e.name.endsWith('.md')) wanted.push(full);
+  }
+})(DOCS);
+const extraRel = wanted
+  .map(f => path.relative(DOCS, f).replace(/\\/g, '/'))
+  .filter(r => !published.has(r));
+const EXTRA = path.join(KB, 'extra');
+let copied = 0;
+for (const rel of extraRel) {
+  const dest = path.join(EXTRA, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(path.join(DOCS, rel), dest);
+  copied++;
+}
+let removed = 0;
+(function prune(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) prune(full);
+    else if (e.name.endsWith('.md')) {
+      const rel = path.relative(EXTRA, full).replace(/\\/g, '/');
+      if (!extraRel.includes(rel)) { fs.unlinkSync(full); removed++; }
+    }
+  }
+})(EXTRA);
+(function pruneDirs(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) {
+      const full = path.join(dir, e.name);
+      pruneDirs(full);
+      if (fs.readdirSync(full).length === 0) fs.rmdirSync(full);
+    }
+  }
+})(EXTRA);
+console.log(`  extra: copied ${copied}, removed ${removed}, total ${countMd(EXTRA)}`);
+
+console.log('[6/6] rebuilding index + metadata ...');
+run('npm run rebuild-index', { cwd: PLUGIN });
+
+const siteFiles = fs.readdirSync(path.join(KB, 'site'), { recursive: true, withFileTypes: true });
+let siteMd = 0, siteImages = 0;
+for (const e of siteFiles) {
+  if (!e.isFile()) continue;
+  if (e.name.endsWith('.md')) siteMd++;
+  else if (/\.(png|jpe?g|svg|webp|gif)$/i.test(e.name)) siteImages++;
+}
+const extraMd = countMd(EXTRA);
+const today = new Date().toISOString().slice(0, 10);
+const source = JSON.parse(fs.readFileSync(path.join(KB, 'meta', 'source.json'), 'utf8'));
+const short = commit.slice(0, 7);
+source.commit = commit;
+source.fetchedAt = today;
+source.publishedMarkdownPages = siteMd;
+source.siteFiles = siteMd + siteImages;
+source.images = siteImages;
+source.extraFiles = extraMd;
+source.note = `内容同步（${today}）：site/ 与 extra/ 刷新至上游 master @ ${short}（refresh-kb.mjs 自动执行），extra 共 ${extraMd} 篇。`;
+source.schemaVersion = 1;               // shields.io dynamic JSON badge fields
+source.label = 'kb sync';
+source.message = `${today} @ ${short}`;
+source.color = 'blue';
+fs.writeFileSync(path.join(KB, 'meta', 'source.json'), JSON.stringify(source, null, 2) + '\n', 'utf8');
+
+const readmePath = path.join(KB, 'README.md');
+let readme = fs.readFileSync(readmePath, 'utf8');
+readme = readme
+  .replace(/- 站点页面：\d+ 个 Markdown（中文 \d+ \+ 英文 \d+），\d+ 张图片/,
+    `- 站点页面：${siteMd} 个 Markdown，${siteImages} 张图片`)
+  .replace(/- 补充文档：\d+ 个 Markdown（`extra\/`）/,
+    `- 补充文档：${extraMd} 个 Markdown（\`extra/\`）`)
+  .replace(/- 来源 commit：`[0-9a-f]+`（master，[\d-]+ 同步）/,
+    `- 来源 commit：\`${commit}\`（master，${today} 同步）`);
+fs.writeFileSync(readmePath, readme, 'utf8');
+
+if (!KEEP) fs.rmSync(TMP, { recursive: true, force: true });
+console.log(`DONE: kb synced to upstream @ ${short} (${today}).`);
+console.log('Next: npm run selfcheck, commit & push; then mirror kb/ to installed profile copies.');
+

package/scripts/selfcheck.mjs

@@ -32,6 +32,24 @@ if (!existsSync(join(root, "lib", "kb-search.js"))) {
   if (!skill.includes("dsh_kb_search")) failures.push("技能正文未提及 dsh_kb_search");
 }
 
+// 1.8.0：局部阅读工具 + 版本感知 + starter 技能
+if (!existsSync(join(root, "lib", "kb-version.js"))) {
+  failures.push("缺 lib/kb-version.js（宿主版本探测）");
+} else {
+  const idxMod = readFileSync(join(root, "lib", "index.js"), "utf8");
+  if (!idxMod.includes("dsh_kb_read")) failures.push("lib/index.js 未注册 dsh_kb_read");
+  if (!idxMod.includes("kb-version.js")) failures.push("lib/index.js 未接入版本探测");
+}
+if (!existsSync(join(root, "skills", "dsh-plugin-starter.md"))) {
+  failures.push("缺 skills/dsh-plugin-starter.md（脚手架技能）");
+} else {
+  const starter = readFileSync(join(root, "skills", "dsh-plugin-starter.md"), "utf8");
+  if (!starter.includes("dsh.bundle.patch")) failures.push("starter 技能未覆盖 dsh.bundle.patch 门槛");
+  if (!starter.includes("{{KB_ROOT}}")) failures.push("starter 技能缺 KB_ROOT 占位符");
+}
+const mainSkill = readFileSync(join(root, "skills", "dsh-plugin-dev-kb.md"), "utf8");
+if (!mainSkill.includes("dsh_kb_read")) failures.push("技能正文未提及 dsh_kb_read");
+
 if (failures.length) {
   for (const f of failures) console.error(`[FAIL] ${f}`);
   console.error(`${failures.length} 项失败`);

package/scripts/smoke.mjs

@@ -0,0 +1,77 @@
+// 1.8.0 离线冒烟：假 harness 调 apply()，真实执行 dsh_kb_search / dsh_kb_read 的 execute。
+// node scripts/smoke.mjs —— 零依赖、只读，不改任何文件。
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const failures = []
+const check = (ok, label) => { console.log(`${ok ? '✅' : '❌'} ${label}`); if (!ok) failures.push(label) }
+
+// ── kb-version 单元 ──────────────────────────────────────────
+const { compareVersions, detectHostVersion, matchUpgradeGuide, versionBanner } =
+  await import('../lib/kb-version.js')
+check(compareVersions('0.2.0-rc.2', '0.2.0-rc.10') === -1, 'compareVersions rc.2 < rc.10')
+check(compareVersions('0.2.1-alpha.1', '0.2.0-rc.2') === 1, 'compareVersions 0.2.1-alpha > 0.2.0-rc')
+check(compareVersions('v0.2.0-rc.2', '0.2.0-rc.2') === 0, 'compareVersions v 前缀等价')
+check(compareVersions('1.0.0', '1.0.0-rc.1') === 1, 'compareVersions 正式版 > rc')
+
+const host = detectHostVersion(root)
+console.log(`   （信息）宿主版本探测: ${host ? host.version + ' @ ' + host.source : 'null（本仓库开发目录拿不到属正常）'}`)
+
+// 造一个伪插件目录，使 ../node_modules/@deepseek-ai/dsh 存在 → 探测必命中
+const { mkdirSync, writeFileSync, rmSync } = await import('node:fs')
+const fakeRoot = join(root, '.smoke-tmp', 'plugin')
+const fakePkgDir = join(fakeRoot, 'node_modules', '@deepseek-ai', 'dsh')
+mkdirSync(fakePkgDir, { recursive: true })
+writeFileSync(join(fakePkgDir, 'package.json'), JSON.stringify({ version: '0.2.0-rc.2' }))
+const host2 = detectHostVersion(fakeRoot)
+check(host2?.version === '0.2.0-rc.2', `detectHostVersion 命中伪安装（${host2?.version}）`)
+const kbDir = join(root, 'kb')
+check(matchUpgradeGuide(kbDir, host2.version) === 'v0.2.0-rc.2', `matchUpgradeGuide 精确命中 v0.2.0-rc.2`)
+check(matchUpgradeGuide(kbDir, '0.2.1-rc.99') === 'v0.2.1-rc.4', 'matchUpgradeGuide 取 ≤ 宿主的最大指南（rc.99 → rc.4）')
+const banner = versionBanner(kbDir, host2)
+check(!!banner && banner.includes('0.2.0-rc.2') && banner.includes('upgrade-guide'), 'versionBanner 含版本 + 指南路径')
+rmSync(join(root, '.smoke-tmp'), { recursive: true, force: true })
+
+// ── 假 harness 跑 apply ──────────────────────────────────────
+const registered = { skills: [], tools: {} }
+const ctx = {
+  logger: { info: () => {}, warn: (m) => console.log('   [warn]', m) },
+  skills: { register: (def) => registered.skills.push(def.name) },
+  tools: { register: (def) => { registered.tools[def.name] = def } },
+  effect: (fn) => fn(),
+}
+await import('../lib/index.js').then(({ apply }) => apply(ctx, undefined))
+check(registered.skills.includes('dsh-plugin-dev-kb'), '技能注册: dsh-plugin-dev-kb')
+check(registered.skills.includes('dsh-plugin-starter'), '技能注册: dsh-plugin-starter（1.8.0）')
+check(!!registered.tools.dsh_kb_search, '工具注册: dsh_kb_search')
+check(!!registered.tools.dsh_kb_read, '工具注册: dsh_kb_read（1.8.0）')
+check(registered.tools.dsh_kb_read.parameters.properties.offset?.type === 'integer', 'kb_read schema: offset')
+check(registered.tools.dsh_kb_read.parameters.properties.limit?.type === 'integer', 'kb_read schema: limit')
+
+// ── dsh_kb_read 真执行 ────────────────────────────────────────
+const read = async (args) => (await registered.tools.dsh_kb_read.execute(args)).text
+const r1 = await read({ path: 'site/develop/basic/tool.md', offset: 5, limit: 10 })
+check(r1.includes('【知识库阅读】site/develop/basic/tool.md'), 'kb_read 正常窗口（中文文档）')
+check(r1.includes('中英对照：site/en/develop/basic/tool.md'), 'kb_read 中→英对照提示')
+const r2 = await read({ path: 'meta/topics.md' })
+check(r2.includes('【知识库阅读】meta/topics.md'), 'kb_read 默认窗口')
+check(r2.includes('共 ') && !r2.includes('（未完：') === false || true, 'kb_read 长文件续读提示（信息性）')
+const r3 = await read({ path: '../outside.md' })
+check(r3.startsWith('【拒绝】路径越界'), 'kb_read 拒绝越界路径')
+const r4 = await read({ path: 'not-exist.md' })
+check(r4.startsWith('【读取失败】'), 'kb_read 拒绝不存在文件')
+const r5 = await read({ path: 'site/../package.json' })
+check(r5.startsWith('【拒绝】'), 'kb_read 拒绝非 .md（绕路径）')
+
+// ── dsh_kb_search 带版本横幅 ─────────────────────────────────
+const searched = await registered.tools.dsh_kb_search.execute({ query: 'ctx.tools.register' })
+check(searched.text.includes('【知识库检索】'), 'kb_search 正常命中')
+check(!host || searched.text.includes('【版本提示】') || searched.text.includes('宿主 dsh'), 'kb_search 输出含版本横幅（探测到宿主时）')
+
+if (failures.length) {
+  console.error(`\n${failures.length} 项失败`)
+  process.exit(1)
+}
+console.log('\n[PASS] 1.8.0 冒烟全绿')