dsh-plugin-dev-kb 1.6.0 → 1.8.0

package/kb/site/reference/tool-execution-pipeline.md

@@ -8,7 +8,7 @@ rawMarkdownPath: "reference/tool-execution-pipeline.md"
 
 # 工具执行流水线
 
-此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `projectContent` 在执行后策略之前安装已准备内容；`finalizeContent` 和 `tools/result` 在此之后运行。
+内置执行器负责原始批次解析、调度、取消和 Session 调用／结果日志。此图展示其共享调用流水线如何执行策略、钩子、沙箱、文件系统守卫、结果改写、最终结果观测和 UI 呈现，而无需改动循环。`tools/pre-execute` 瀑布先执行，然后是单调守卫，再是 `tools/execute` 和 `tools/post-execute` 瀑布；三个瀑布可以转换调用。定义拥有的 `projectContent` 在后置策略之前安装准备好的内容，`finalizeContent` 和 `tools/result` 在之后执行。
 
 ```mermaid
 flowchart TD
@@ -25,14 +25,15 @@ flowchart TD
   owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
   project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
   post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
-  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  normalized["Invocation pipeline normalization<br/>pipeline/result snapshot throws become isError"]
   finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
   final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
   context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
   toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
   allResults["Tool batch settled<br/>recorded tool/result events complete"]
   presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
+  executor["Selected ToolExecutor.execute<br/>raw batch, Agent, optional logging step"]
+  model --> executor --> toolCall
   toolCall --> presentCall
   toolCall --> pre
   pre -->|allow| guards

package/lib/index.js

@@ -19,10 +19,11 @@
  * 形状（标准 JSON Schema，参照 dsh-plugin-windows-guard 的先例）。
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { buildIndex, search as kbSearch } from './kb-search.js'
+import { detectHostVersion, versionBanner } from './kb-version.js'
 
 export const name = 'dsh-plugin-dev-kb'
 export const inject = ['skills', 'tools']
@@ -34,6 +35,8 @@ const KB_DIR = join(PKG_DIR, '..', 'kb')
 const DEFAULT_CONFIG = {
   /** 注册 dsh_kb_search 知识库检索工具（false = 只保留技能，不注册工具）。 */
   searchTool: true,
+  /** 注册 dsh_kb_read 知识库局部阅读工具（1.8.0 起，false = 只用 search）。 */
+  readTool: true,
 }
 
 // ---------------------------------------------------------------------------
@@ -69,7 +72,7 @@ function renderResult(value) {
 }
 
 /** dsh_kb_search 工具定义。 */
-function kbSearchTool(getIndex) {
+function kbSearchTool(getIndex, hostVersion) {
   return {
     name: 'dsh_kb_search',
     description:
@@ -124,11 +127,111 @@ function kbSearchTool(getIndex) {
         scope: args.scope === 'api' ? 'api' : 'all',
         maxResults: args.maxResults,
       })
-      return { kind: result.kind, text: renderResult(result) }
+      const banner = versionBanner(index.kbDir, hostVersion)
+      return { kind: result.kind, text: banner ? `${banner}\n\n${renderResult(result)}` : renderResult(result) }
     }
   }
 }
 
+/** dsh_kb_read 工具定义（1.8.0）：知识库局部阅读，带行号窗口 + 中英对照提示。 */
+function kbReadTool(getIndex, hostVersion) {
+  return {
+    name: 'dsh_kb_read',
+    description:
+      'dsh 插件开发知识库局部阅读：按知识库相对路径 + 行号窗口读原文，输出带行号，' +
+      '自动防大文件整读（单次窗口有上限）、自动处理编码，并提示中英对照版本的对应路径。' +
+      '通常与 dsh_kb_search 配套：先 search 拿到 path + 命中行号，再用本工具按行号窗口读上下文。' +
+      '仅限知识库目录内的 .md 文件（路径越界会被拒绝）。' +
+      '仅限 dsh（DeepSeek Harness）插件开发知识库。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          description: '知识库相对路径（正斜杠，如 "site/develop/basic/tool.md"、"extra/upgrade-guide/v0.2.0-rc.2/guide.zh.md"）'
+        },
+        offset: {
+          type: 'integer',
+          description: '起始行（1 基，默认 1）'
+        },
+        limit: {
+          type: 'integer',
+          description: '读取行数（默认 120，最大 400）'
+        }
+      }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['kind', 'text'],
+        properties: {
+          kind: { type: 'string', enum: ['text', 'error'] },
+          text: { type: 'string' }
+        }
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }]
+    },
+    async execute(args) {
+      const { index, error } = getIndex('zh')
+      if (error) throw new Error(error)
+      const rel = String(args.path ?? '').replaceAll('\\', '/').replace(/^\/+/, '')
+      if (!rel || !rel.endsWith('.md')) {
+        return { kind: 'error', text: `【拒绝】path 必须是知识库内的 .md 相对路径，收到：${rel || '(空)'}` }
+      }
+      const abs = resolve(index.kbDir, ...rel.split('/'))
+      const kbRootResolved = resolve(index.kbDir)
+      if (abs !== kbRootResolved && !abs.startsWith(kbRootResolved + sep)) {
+        return { kind: 'error', text: `【拒绝】路径越界：${rel}（只允许知识库目录内的文件）` }
+      }
+      let lines
+      try {
+        const st = statSync(abs)
+        if (st.size > 8_000_000) {
+          return { kind: 'error', text: `【拒绝】文件过大（${st.size} 字节）：${rel}` }
+        }
+        lines = readFileSync(abs, 'utf8').split(/\r?\n/)
+      } catch (err) {
+        return { kind: 'error', text: `【读取失败】${rel}（${err?.message ?? err}）。提示：先用 dsh_kb_search 确认路径是否在索引内。` }
+      }
+      const total = lines.length
+      const offset = Math.min(Math.max(Number(args.offset) > 0 ? Number(args.offset) : 1, 1), Math.max(total, 1))
+      const limit = Math.min(Math.max(Number(args.limit) > 0 ? Number(args.limit) : 120, 1), 400)
+      const end = Math.min(offset - 1 + limit, total)
+      const width = String(end).length
+      const body = lines.slice(offset - 1, end)
+        .map((l, i) => `${String(offset + i).padStart(width)}| ${l}`)
+        .join('\n')
+      const footer = []
+      if (end < total) footer.push(`（未完：共 ${total} 行，已读 L${offset}-${end}；续读传 offset=${end + 1}）`)
+      const alt = altLangPath(rel)
+      if (alt) footer.push(`中英对照：${alt.exists ? alt.rel : alt.rel + '（未收录）'}`)
+      const banner = versionBanner(index.kbDir, hostVersion)
+      const text = [
+        banner ?? '',
+        `【知识库阅读】${rel}（共 ${total} 行，窗口 L${offset}-${end}）`,
+        body,
+        ...footer,
+      ].filter(Boolean).join('\n')
+      return { kind: 'text', text }
+    }
+  }
+}
+
+/** 中英对照路径推导：site/ ↔ site/en/，extra/*.zh.md ↔ extra/*.md。存在性现场检查。 */
+function altLangPath(rel) {
+  let counter
+  if (rel.startsWith('site/en/')) counter = rel.replace('site/en/', 'site/')
+  else if (rel.startsWith('site/')) counter = rel.replace('site/', 'site/en/')
+  else if (rel.startsWith('extra/') && rel.endsWith('.zh.md')) counter = rel.slice(0, -'.zh.md'.length) + '.md'
+  else if (rel.startsWith('extra/') && rel.endsWith('.md') && !rel.endsWith('.zh.md')) counter = rel.slice(0, -'.md'.length) + '.zh.md'
+  else return null
+  const abs = join(KB_DIR, ...counter.split('/'))
+  return { rel: counter, exists: existsSync(abs) }
+}
+
 /** logger 拿不到时降级 console。 */
 function makeLogger(ctx, tag) {
   return {
@@ -207,9 +310,17 @@ export function apply(ctx, config) {
     log.info(`技能已注册：${skill.name}`)
   }
 
-  // B. 检索工具（1.6.0 起）：索引惰性构建（首次调用时建，宿主启动零开销），
-  //    zh/en 各缓存一份；kb 目录缺失 → 工具执行时报错并提示退回文件工具检索。
-  if (cfg.searchTool) {
+  // B. 检索工具（1.6.0 起）+ 局部阅读工具（1.8.0 起）：
+  //    索引惰性构建（首次调用时建，宿主启动零开销），zh/en 各缓存一份；
+  //    宿主版本探测一次性完成（拿不到 → 工具输出不带版本横幅）；
+  //    kb 目录缺失 → 工具执行时报错并提示退回文件工具检索。
+  const hostVersion = detectHostVersion(PKG_DIR)
+  if (hostVersion) {
+    log.info(`宿主 dsh 版本探测：${hostVersion.version}（${hostVersion.source}）`)
+  } else {
+    log.warn('宿主 dsh 版本探测失败（工具输出将不带版本横幅）')
+  }
+  if (cfg.searchTool || cfg.readTool) {
     if (typeof ctx.tools?.register === 'function') {
       const indexCache = new Map()
       const getIndex = (lang) => {
@@ -233,8 +344,12 @@ export function apply(ctx, config) {
           }
         }
       }
-      ctx.effect(() => ctx.tools.register(kbSearchTool(getIndex), 'dsh-plugin-dev-kb: register dsh_kb_search'), 'dsh-plugin-dev-kb: register dsh_kb_search')
+      ctx.effect(() => ctx.tools.register(kbSearchTool(getIndex, hostVersion), 'dsh-plugin-dev-kb: register dsh_kb_search'), 'dsh-plugin-dev-kb: register dsh_kb_search')
       log.info('工具已注册：dsh_kb_search')
+      if (cfg.readTool) {
+        ctx.effect(() => ctx.tools.register(kbReadTool(getIndex, hostVersion), 'dsh-plugin-dev-kb: register dsh_kb_read'), 'dsh-plugin-dev-kb: register dsh_kb_read')
+        log.info('工具已注册：dsh_kb_read')
+      }
     } else {
       log.warn('ctx.tools.register 不可用，dsh_kb_search 未注册（工具子系统的注入可能失败）')
     }

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,7 +1,7 @@
 {
   "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",
+  "version": "1.8.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -22,7 +22,9 @@
   ],
   "scripts": {
     "selfcheck": "node scripts/selfcheck.mjs",
-    "rebuild-index": "node scripts/rebuild-index.mjs"
+    "rebuild-index": "node scripts/rebuild-index.mjs",
+    "refresh-kb": "node scripts/refresh-kb.mjs",
+    "smoke": "node scripts/smoke.mjs"
   },
   "keywords": [
     "dsh",

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 冒烟全绿')

package/skills/dsh-plugin-dev-kb.md

@@ -16,19 +16,19 @@ whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cord
 
 ```
 kb/
-├── site/            线上站点完整镜像（中英双语 188 页，优先读这里）
+├── site/            线上站点完整镜像（中英双语 192 页，优先读这里）
 │   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy / public-deployments
 │   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
 │   │                practice(能力分层/LLM适配器/动态装配)、cordis-tutorial(7章)
 │   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
 │   │                config-catalog、tool-catalog、api-gateway、cordis-api/(6)、cookbook/(5)、subsystems/(46)
 │   └── en/          英文站镜像（结构与中文站一致）
-├── extra/           仓库内未发布到站点的补充文档（182 篇）：glossary、defensive-patterns、
+├── extra/           仓库内未发布到站点的补充文档（468 篇）：glossary、defensive-patterns、
 │                    module-graph、testing、postmortem/、i18n/、cookbook 与 subsystems 扩展、
 │                    upgrade-guide/(各版本升级指南)、persistence-changes/(持久化格式变更)
 ├── meta/
 │   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
-│   ├── search-index.json  全量检索索引（373 文件：path/url/title/字符数）
+│   ├── search-index.json  全量检索索引（663 文件：path/url/title/字符数）
 │   ├── source.json  来源信息（commit/时间/统计）
 │   └── site-pages.txt     线上站点页面清单
 ├── INDEX.md         全部 站点 URL ↔ 本地文件 对照
@@ -37,9 +37,10 @@ kb/
 
 ## 2. 使用流程（从快到慢，优先用工具）
 
-1. **dsh_kb_search 工具检索（首选）**：调用本插件的 `dsh_kb_search` 工具，一次拿到命中文件路径 + 行号 + 上下文片段，再用 read 工具按行号局部读原文。参数：`query`（关键词，空白分词；空或 `"topics"` 返回主题导航）、`scope`（`api` = 只搜 API 签名/目录类文档，查 `ctx.*` API 用）、`lang`（默认 zh）、`maxResults`。
-2. **文件工具兜底**（工具不可用时）：读 `{{KB_ROOT}}/meta/topics.md` 按主题找文件；或对 `{{KB_ROOT}}/meta/search-index.json` / `{{KB_ROOT}}/site/` 用 grep 定位。
-3. **按 URL 反查**：已知线上页面 URL 时，在 `{{KB_ROOT}}/INDEX.md` 查对应本地文件。
+1. **dsh_kb_search 工具检索（首选）**：调用本插件的 `dsh_kb_search` 工具，一次拿到命中文件路径 + 行号 + 上下文片段。参数：`query`（关键词，空白分词；空或 `"topics"` 返回主题导航）、`scope`（`api` = 只搜 API 签名/目录类文档，查 `ctx.*` API 用）、`lang`（默认 zh）、`maxResults`。输出自带**版本横幅**（宿主 dsh 版本 vs 知识库 master 快照 + 对应 upgrade-guide 路径），横幅提示版本差异时务必读指南。
+2. **dsh_kb_read 工具按行号窗口读原文（1.8.0 起，次选）**：拿到 path + 命中行号后用 `dsh_kb_read`（参数 `path` / `offset` / `limit`）带行号窗口读上下文，输出自动提示中英对照路径与续读位置；替代通用 read 工具，防大文件整读。
+3. **文件工具兜底**（工具不可用时）：读 `{{KB_ROOT}}/meta/topics.md` 按主题找文件；或对 `{{KB_ROOT}}/meta/search-index.json` / `{{KB_ROOT}}/site/` 用 grep 定位。
+4. **按 URL 反查**：已知线上页面 URL 时，在 `{{KB_ROOT}}/INDEX.md` 查对应本地文件。
 
 ## 3. 阅读原则