dsh-plugin-dev-kb 1.5.2 → 1.8.0

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。零运行时依赖。",
-  "version": "1.5.2",
+  "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.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

@@ -22,6 +22,34 @@ for (const f of ["README.md", "LICENSE"]) {
   if (!existsSync(join(root, f))) failures.push(`缺 ${f}`);
 }
 
+// 1.6.0：检索工具完整性
+if (!existsSync(join(root, "lib", "kb-search.js"))) {
+  failures.push("缺 lib/kb-search.js（dsh_kb_search 工具实现）");
+} else {
+  const idxMod = readFileSync(join(root, "lib", "index.js"), "utf8");
+  if (!idxMod.includes("dsh_kb_search")) failures.push("lib/index.js 未注册 dsh_kb_search");
+  const skill = readFileSync(join(root, "skills", "dsh-plugin-dev-kb.md"), "utf8");
+  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,30 +16,31 @@ 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 ↔ 本地文件 对照
 └── README.md        知识库总览与更新方法
 ```
 
-## 2. 使用流程（三选一，从快到慢）
+## 2. 使用流程（从快到慢，优先用工具）
 
-1. **按任务找文档**：读 `kb/meta/topics.md`，找到对应主题（如"开发一个 Tool"），按核心/扩展顺序读列出的文件。
-2. **按关键词检索**：对 `kb/meta/search-index.json` 用 grep 过滤（如 `grep -i "tool" search-index.json`），或直接 grep `kb/site/` 内容定位。
-3. **按 URL 反查**：已知线上页面 URL 时，在 `kb/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. 阅读原则
 

package/skills/dsh-plugin-starter.md

@@ -0,0 +1,65 @@
+---
+name: dsh-plugin-starter
+description: dsh 插件脚手架助手：从零新建一个合规的 dsh 插件骨架（package.json 含 dsh.bundle.patch 与 peer 显式预发布范围、cordis.patch.yml、双语 README、selfcheck、CHANGELOG、GitHub topics），逐项满足 dsh 官方发布要求与 dsh-market / awesome-dsh-plugin 收录门槛。用户说「新建 dsh 插件 / 做一个插件 / 插件脚手架 / starter」时加载本技能。注意：写 NoneBot 插件时请用 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 用户要从零开始新建一个 dsh 插件，或问「插件骨架怎么搭 / 发布要准备什么文件」时
+---
+# dsh 插件脚手架（dsh-plugin-starter）
+
+帮用户从零搭一个**能通过官方校验、能进 market / awesome 收录**的 dsh 插件骨架。
+原则：每生成一个文件都对照下方清单自检；知识库文档只读不猜，拿不准就先检索确认。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`
+- 先读两篇再动手：`{{KB_ROOT}}/site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，
+  `ctx.effect()` 自动清理）与 `{{KB_ROOT}}/site/develop/basic/publish.md`（打包发布）。
+- 配置 / 工具 / 事件写法按需检索：`dsh_kb_search`，如 query=`ctx.tools.register 工具定义`。
+
+## 1. 骨架清单（缺一 = 发布/收录会卡）
+
+在用户指定的目录 `<plugin-name>/` 下生成（命名规范：`dsh-plugin-<topic>` 或 `dsh-<topic>`）：
+
+| 文件 | 要点 |
+|---|---|
+| `package.json` | `"main": "./lib/index.js"`；`files` 数组**必须含 main 入口所在目录**；`license: "MIT"`；`homepage` 指 GitHub 仓库 `#readme`；`repository.url`；`keywords ≥3`（含 `dsh` / `dsh-plugin` / `deepseek-harness`）；**`dsh: { bundle: { patch: "./cordis.patch.yml" } }`**（只声明 `dsh.client` 会被 awesome CI 拒）；`engines.node >=18`；`peerDependencies` 若引 `@deepseek-ai/*`，**范围必须显式覆盖预发布分支**（如 `"^4.0.1"` 对 cordis 可行，对 dsh 主包要写 `">=0.2.0-rc.1 <0.3.0-0"` 形态，否则预发布构建被静默排除）；`scripts.selfcheck` 指向最小自检 |
+| `cordis.patch.yml` | 插件自注册声明（`dsh.profile.bundles` 挂载用）；含 Config 时在此声明配置 schema |
+| `lib/index.js` | `export function apply(ctx, config)`；零 `@deepseek-ai/*` 运行时 import（插件以 link:/file: 装入 profile，外部依赖按 realpath 解析不到——用原始 definition 形状注册工具，参照 dsh-plugin-windows-guard 先例）；每个注册动作包 `ctx.effect(() => ..., '说明')` |
+| `README.md` | ① 顶部标题 + 一句话描述；② `## 安装` 段**必须含标准安装命令**（`git clone` / `npm install` 等——market ease 项）；③ `## 功能` + `## 配置`/`## 示例` 双标题；④ ≥2 个代码块；⑤ `## 相关插件` 互相引用段（列同系列全部**已发布**插件：npm 链 + GitHub 链 + 一句话）；⑥ 长度 >2000 字更佳；⑦ 需要 `AI 生成声明` 段 |
+| `README.en.md` | 结构与中文一致（i18n 规范见 `{{KB_ROOT}}/extra/i18n/`） |
+| `CHANGELOG.md` | `## x.y.z - 日期` 逐版条目：修了什么/为什么/怎么验证 |
+| `LICENSE` | MIT |
+| `scripts/selfcheck.mjs` | 最小结构自检（文件存在性 + package.json 关键字段），发布前必跑 |
+| `.github/workflows/`（可选） | CI / 自动化（如每周内容同步） |
+
+## 2. 命名与元数据红线
+
+- 目录名 = npm 包名（例外如 `dsh-notify` 是历史遗留，新插件不要再造）
+- **README 里写「无需配置」时必须带否定词**（"无需 / 不需要 / zero-config"）——market 的
+  needsConfig 反向检测按裸关键词（`API_KEY` 等）扫描，否定语境会被先摘除；确需配置的插件
+  写配置项时避免裸写这些 KEY 名
+- 描述不得夸大：awesome 评审会对着源码逐条核对数字 / 命令 / API 名
+
+## 3. GitHub 侧（骨架生成后提醒用户补）
+
+```powershell
+gh api -X PATCH repos/<owner>/<repo> -f description="…（一句话中文简介，勿夸大）" -f homepage="https://github.com/<owner>/<repo>#readme"
+# topics 至少含 dsh / dsh-plugin / deepseek-harness + 主题词——缺 topics 是 market 收录失败最常见原因
+gh api -X PUT repos/<owner>/<repo>/topics --input topics.json
+```
+
+## 4. 验证闭环
+
+1. `node scripts/selfcheck.mjs` → 全部通过
+2. 用 dsh-dev-sandbox 技能建独立沙箱 profile 挂载冒烟（不污染主力 dsh）：
+   启动日志**不得**出现 `skipping profile bundle "<你的插件>"`（出现 = peer 闸门没过 = 静默失效）
+3. `npm pack --dry-run` 核对发布内容（files 不夹带内部文档）
+4. 发布流程与版本纪律见 `{{KB_ROOT}}/site/develop/basic/publish.md`
+
+## 5. 红线
+
+- **不要双挂载**：插件经 `dsh.profile.bundles` 进场后，profile 层不得再 insert 同 id
+  （`duplicate loader entry id` 启动即崩）
+- **不要在插件运行时 import `@deepseek-ai/*`**（见 lib/index.js 要点）
+- **不要把凭据写进入库文件**；用户凭据走 credentials ref / 环境变量
+- 知识库快照可能领先宿主 dsh 版本：API 行为不符时以宿主实际安装包为准，
+  版本差异读 `{{KB_ROOT}}/extra/upgrade-guide/`

package/skills/dsh-upgrade-assistant.md

@@ -0,0 +1,62 @@
+---
+name: dsh-upgrade-assistant
+description: DeepSeek Harness (dsh) 升级助手：用户升级 dsh 版本时，用知识库里的官方升级指南（upgrade-guide/）与持久化变更记录（persistence-changes/）生成迁移检查清单、预判破坏性变更、给出回滚方案。用户提到「升级 dsh / 更新 Harness / 换版本 / upgrade」或升级 dsh 后报错时加载本技能。注意：写 NoneBot 时请用 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 用户要升级 dsh / DeepSeek Harness 版本，或升级后插件不工作、会话打不开等需要排查迁移问题时
+---
+# dsh 升级助手（dsh-upgrade-assistant）
+
+帮用户安全升级 DeepSeek Harness：先搞清「从哪版 → 到哪版」，再用知识库把两版之间的全部变更读出来，
+生成检查清单，升级后逐条验证。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`（插件挂载时自动替换为实际绝对路径，可直接 read/glob/grep）
+- 升级相关内容在：`{{KB_ROOT}}/extra/upgrade-guide/`（逐版本升级指南）与
+  `{{KB_ROOT}}/extra/persistence-changes/`（持久化格式变更，按日期命名）
+
+## 1. 标准流程
+
+### 第一步：确定版本区间
+
+1. **当前版本**：读用户 profile 的安装信息（如 `%LOCALAPPDATA%` / profile 目录下的
+   `package.json` 中 `@deepseek-ai/dsh` 的版本，或让用户看 Desktop 关于页）。
+2. **目标版本**：`npm view @deepseek-ai/dsh version`（latest）或用户指定版本。
+3. 列出区间内的版本号，形如 `v0.2.0-rc.2 → v0.2.1-rc.4`。
+
+### 第二步：读变更（知识库检索）
+
+1. 对区间内**每个版本**读一份指南：
+   `{{KB_ROOT}}/extra/upgrade-guide/<版本>/`（目录按 `v0.1.7-rc.2` … `v0.2.2-alpha.3` 组织，
+   每个子目录是一篇 guide.md / guide.zh.md，读中文版）。
+2. 持久化/会话格式变更：列出 `{{KB_ROOT}}/extra/persistence-changes/` 中日期晚于当前版本
+   发布日的条目（文件名即日期），只读标题相关条目判断「历史会话会不会丢/迁移」。
+3. 快速定位也可用 `dsh_kb_search` 工具，如 query=`升级 upgrade-guide v0.2.1`。
+4. 优先关注三类破坏点：**删除/改名的 API**（插件会静默失效）、**会话格式升级**
+   （旧会话打不开或需要迁移）、**配置字段变更**（profile 的 cordis.patch.yml / package.json）。
+
+### 第三步：给出升级检查清单（输出给用户）
+
+清单必须包含：
+
+- **备份**：升级前备份 profile 的 `package.json` 与 `pnpm-lock.yaml`
+- **变更摘要**：区间内每个版本的破坏性变更，逐条说明「影响你吗」
+- **插件兼容**：dsh 有插件兼容闸门——`peerDependencies` 不覆盖目标版本的插件会被
+  **整体拒绝安装**或**启动时跳过（静默失效）**；把用户已装插件与目标版本对照，
+  预先列出需要升级/移除/豁免（allow-version）的插件
+- **回滚方案**：保留旧版本安装包/备份路径，回滚 = 恢复备份 + 重装旧版
+
+### 第四步：升级后验证
+
+- 启动时逐条看 stderr 的 `dsh: skipping profile bundle "X"` 警告——被跳过 = 该插件静默失效
+- 用一个旧会话验证历史消息正常加载（会话格式变更最常坏这里）
+- 逐个核心功能冒烟：新建会话、工具调用、技能加载、设置页
+- 若用户安装了 `dsh-plugin-dev-kb`，知识库可能比目标版本新（快照领先），
+  文档与实际行为不符时以实际安装包为准
+
+## 2. 红线
+
+- **不要在未备份的情况下动 profile**；备份是第一步，不是可选项
+- **不要用 allow-version 豁免兼容闸门来「绕过」不兼容插件**——除非用户明确要求并理解风险
+  （静默失效比拒绝安装更难排查）
+- 知识库是快照，若 upgrade-guide 目录里没有目标版本的目录（比如目标版本比知识库同步点新），
+  明确告知用户「该版本的官方指南未收录」，让用户看官方 release notes，不要编造变更内容