dsh-plugin-dev-kb 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.6.0] - 2026-10-30
+
+- **新增 `dsh_kb_search` 工具**：知识库本地打分检索（零 token、毫秒级、零运行时依赖）。
+  一次调用返回命中文件路径 + 行号 + 上下文片段（每文件最多 3 处，前后各 2 行），替代
+  agent 多轮 grep/read 检索 634 文件知识库。
+  - 参数：`query`（空白分词多词；空或 `"topics"` 返回主题导航）、`scope`（`api` 只搜
+    API 签名/目录类文档：tool-catalog / config-catalog / capability-seams / cordis-api /
+    subsystems 等）、`lang`（zh 默认；en 首次调用现场建索引）、`maxResults`（默认 8）。
+  - 打分：标题 ×8、路径 ×4、正文行命中平方和（多词同现加权）、路径子词弱匹配
+    （`ctx.tools.register` → tool.md）、`site/develop|guide/` 教程优先 +2。
+  - 索引惰性构建（首次调用时，~60ms / 314 个中文文件）、内存缓存、只读不写；
+    `searchTool: false` 可关闭。
+  - 技能 `dsh-plugin-dev-kb` 检索指南同步改为「工具优先，文件工具兜底」。
+
+## [1.5.2] - 2026-10-21
+
+- `dsh-dev-sandbox` 技能去掉固定 `dev` profile 约定：**沙箱 profile 名由 agent 按任务自定**
+  （建议 `sb-<插件名>`），建前检查不与现有 profile（尤其主力）重名，端口同样自选空闲高位端口；
+  新增沙箱「用完即删、不留残留」的收尾说明。
+
 ## [1.5.1] - 2026-10-21
 
 - **知识库同步上游 master `687f282e`（2026-10-17）**：

package/README.en.md

@@ -17,6 +17,7 @@
 **The official docs at your side whenever you write dsh plugins**: the entire content of the DeepSeek Harness official documentation site
 <https://deepseek-harness.github.io/deepseek-harness/> is organized into a form natively usable by dsh —
 once this plugin is installed, the agent automatically loads the knowledge base when writing plugins and locates docs by task scenario, so you never have to dig through web pages again.
+It also ships the `dsh_kb_search` tool (since 1.6.0): local scored search over the knowledge base that returns matched files, line numbers, and context snippets in a single call.
 
 ## What is this
 
@@ -25,6 +26,9 @@ once this plugin is installed, the agent automatically loads the knowledge base
 - **Supplementary docs**: 439 development references from the repo's `docs/` that were not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, upgrade guides, persistence changes, etc.).
 - **Agent-friendly**: the `skills/dsh-plugin-dev-kb.md` skill lets dsh auto-load it during plugin development tasks, providing the knowledge base location,
   topic navigation, and search strategy; `kb/meta/topics.md` maps task scenarios to the files to read; `kb/meta/search-index.json` provides full search coverage.
+- **Local search tool**: `dsh_kb_search` performs scored search over the knowledge base (title / path / body multi-term weighting) and returns
+  matched file paths, line numbers, and context snippets in a single call; supports `scope: api` (search only API-signature/catalog docs),
+  `lang: en`, and an empty query returning topic navigation. The index is built lazily in memory (~60ms / 314 files), read-only.
 
 ## Features
 
@@ -32,9 +36,9 @@ once this plugin is installed, the agent automatically loads the knowledge base
   192 pages in both Chinese and English, links rewritten to site routes, verbatim identical to the live site;
 - **Repo supplementary docs**: 439 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, upgrade guides, persistence changes, etc.);
 - **Agent-friendly**: the `dsh-plugin-dev-kb` skill lets dsh auto-load the knowledge base during plugin development tasks;
-  `kb/meta/topics.md` maps task scenarios to the files to read, and `kb/meta/search-index.json` provides full search coverage;
+  the `dsh_kb_search` tool locates docs in a single call; `kb/meta/topics.md` maps task scenarios to the files to read, and `kb/meta/search-index.json` provides full search coverage;
 - **Human-usable**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping;
-- Pure data plugin, zero runtime dependencies, registers no tools.
+- Zero runtime dependencies; the single tool `dsh_kb_search` is a pure local Node implementation (no network, no file writes).
 
 ## Configuration
 
@@ -80,8 +84,8 @@ After restarting, open a new session and simply ask:
 
 > Help me write a minimal dsh plugin
 
-The agent will automatically load the `dsh-plugin-dev-kb` skill (visible in the skill catalog), locate the docs via `kb/meta/topics.md`,
-and only then start working — if you see it referencing `kb/site/...` paths, the verification has passed.
+The agent will automatically load the `dsh-plugin-dev-kb` skill (visible in the skill catalog), locate the docs via the `dsh_kb_search` tool
+(or `kb/meta/topics.md`), and only then start working — if you see it referencing `kb/site/...` paths, the verification has passed.
 
 ## Directory structure
 
@@ -107,7 +111,8 @@ dsh-plugin-dev-kb/
 ## Usage
 
 - **Agent side**: when writing plugins / Tools / config / services / events / packaging / LLM adapters, load
-  the `dsh-plugin-dev-kb` skill → read `kb/meta/topics.md` to locate → read/grep as needed.
+  the `dsh-plugin-dev-kb` skill → prefer the `dsh_kb_search` tool (one call returns matched files + line numbers + snippets;
+  `scope: api` for `ctx.*` API signatures) → read the source locally by line number; fall back to grepping `kb/` if the tool is unavailable.
 - **Human side**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping.
 
 ## Self-check

package/README.md

@@ -17,8 +17,9 @@
 **写 dsh 插件时的随身辅助**：① 把 DeepSeek Harness 官方文档站点
 <https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
 装了这个插件，agent 写插件时自动加载知识库，按任务场景定位文档，不用再翻网页；
-② 附带 `dsh-dev-sandbox` 技能：独立 dev profile 开发沙箱工作流，开发中的插件隔离运行，
-agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh。
+② 附带 `dsh-dev-sandbox` 技能：自建独立沙箱 profile 开发沙箱工作流（沙箱名由 agent 按任务自定），
+开发中的插件隔离运行，agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh；
+③ `dsh_kb_search` 工具（1.6.0 起）：知识库本地打分检索，一次调用返回命中文件 + 行号 + 上下文片段。
 
 ## 这是什么
 
@@ -27,9 +28,12 @@ agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh。
 - **补充文档**：仓库 `docs/` 中未发布到站点的 439 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）。
 - **agent 友好**：`skills/dsh-plugin-dev-kb.md` 技能让 dsh 在插件开发任务中自动加载，获知知识库位置、
   主题导航与检索策略；`kb/meta/topics.md` 按任务场景映射要读的文件；`kb/meta/search-index.json` 提供全量检索。
-- **开发沙箱**：`skills/dsh-dev-sandbox.md` 技能提供独立 dev profile（`~/.dsh/profiles/dev`，可自定义）
-  沙箱工作流——初始化（兼容闸门 / link: 挂载）、后台启动（独立端口）、自主重启、headless 冒烟验证，
+- **开发沙箱**：`skills/dsh-dev-sandbox.md` 技能提供自建独立沙箱 profile 工作流（沙箱名 agent 按任务
+  自定，不与主力 profile 重名）——初始化（兼容闸门 / link: 挂载）、后台启动（自选空闲端口）、自主重启、headless 冒烟验证，
   全程 agent 闭环，不要求用户重启。
+- **本地检索工具**：`dsh_kb_search` 工具在知识库上做打分检索（标题 / 路径 / 正文多词加权），
+  一次调用返回命中文件路径、行号与上下文片段；支持 `scope: api`（只搜 API 签名/目录类文档）、
+  `lang: en`、空 query 返回主题导航。索引惰性构建于内存（约 60ms / 314 文件），只读不写。
 
 ## 功能
 
@@ -37,17 +41,19 @@ agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh。
   中英双语共 188 页，链接按站点路由重写，与线上逐字一致；
 - **仓库补充文档**：未发布到站点的 182 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）；
 - **agent 友好**：`dsh-plugin-dev-kb` 技能让 dsh 在插件开发任务中自动加载知识库；
-  `kb/meta/topics.md` 按任务场景映射要读的文件，`kb/meta/search-index.json` 提供全量检索；
+  `dsh_kb_search` 工具一次调用完成检索定位；`kb/meta/topics.md` 按任务场景映射要读的文件，`kb/meta/search-index.json` 提供全量检索；
 - **人侧可用**：直接浏览 `kb/` 目录，或打开 `kb/INDEX.md` 按 URL 对照查阅；
-- 纯数据插件，零运行时依赖，不注册任何工具。
+- 零运行时依赖；唯一的工具 `dsh_kb_search` 为纯 Node 本地实现（不联网、不写文件）。
 
 ## 配置
 
-无需任何配置，安装即用：
+默认零配置，安装即用：
 
 - 不读取环境变量，不需要 API Key / token，不写配置文件；
 - 挂载后 `skills/dsh-plugin-dev-kb.md` 技能在会话启动时进入可用技能列表，自动生效；
-- 知识库更新走 `npm run rebuild-index`（见「更新知识库」），无手动配置项。
+- `dsh_kb_search` 工具随宿主启动注册，首次调用时构建索引（毫秒级）；如需关闭，
+  在 profile 的插件配置里设 `searchTool: false`（只保留技能，不注册工具）；
+- 知识库更新走 `npm run rebuild-index`（见「更新知识库」）。
 
 ## 安装 / 挂载
 
@@ -85,8 +91,8 @@ npm install
 
 > 帮我写一个最小的 dsh 插件
 
-agent 会自动加载 `dsh-plugin-dev-kb` 技能（技能清单里可见），按 `kb/meta/topics.md`
-定位文档后再动手——看到它引用 `kb/site/...` 路径即验证通过。
+agent 会自动加载 `dsh-plugin-dev-kb` 技能（技能清单里可见），调用 `dsh_kb_search`
+（或读 `kb/meta/topics.md`）定位文档后再动手——看到它引用 `kb/site/...` 路径即验证通过。
 
 ## 目录结构
 
@@ -112,7 +118,9 @@ dsh-plugin-dev-kb/
 ## 使用
 
 - **agent 侧**：写插件 / Tool / 配置 / 服务 / 事件 / 打包 / LLM 适配器时，加载
-  `dsh-plugin-dev-kb` 技能 → 读 `kb/meta/topics.md` 定位 → 按需 read/grep。
+  `dsh-plugin-dev-kb` 技能 → 首选调 `dsh_kb_search` 工具检索（一次拿命中文件 + 行号 + 片段，
+  `scope: api` 查 `ctx.*` API 签名）→ 用 read 按行号局部读原文；工具不可用时退回
+  grep `kb/` 兜底。
 - **人侧**：直接浏览 `kb/` 目录，或打开 `kb/INDEX.md` 按 URL 对照查阅。
 
 ## 自检

package/lib/index.js

@@ -1,30 +1,134 @@
 /**
- * dsh-plugin-dev-kb — 主机插件（纯技能载体，无工具/命令）。
+ * dsh-plugin-dev-kb — 主机插件（技能载体 + 知识库检索工具）。
  *
- * 挂载于 profile 根层（全局层），唯一职责：把 skills/ 目录下的
- * dsh-plugin-dev-kb 技能注册为 runtime skill，让每个会话的 agent
- * 在插件开发 / 查询 dsh 能力 / 写 Tool / 配置 cordis.yml 类任务时，
- * 能按技能 description 自动加载，从而获知知识库位置与阅读路径。
+ * 挂载于 profile 根层（全局层），两部分职责：
  *
- * 知识库数据（kb/ 目录：site/ 站点镜像 + extra/ 补充文档 + meta/
- * 主题导航与索引）是纯文档，模型通过文件工具按技能指示直接读取。
+ * A. 技能层：把 skills/ 目录下的 dsh-plugin-dev-kb / dsh-dev-sandbox 技能
+ *    注册为 runtime skill，让每个会话的 agent 在插件开发 / 查询 dsh 能力 /
+ *    写 Tool / 配置 cordis.yml 类任务时按技能 description 自动加载。
+ *
+ * B. 工具层（1.6.0 起）：注册 dsh_kb_search 工具——知识库本地打分检索，
+ *    一次调用返回命中文件 + 行号 + 上下文片段，替代 agent 多轮 grep/read。
+ *    索引在内存（宿主启动时构建中文索引，英文索引按需惰性构建），只读不写。
+ *
+ * 知识库数据（kb/ 目录）是纯文档，模型仍可通过文件工具按技能指示直接读取。
  *
  * 依赖纪律：本模块不 import 任何 @deepseek-ai/* 运行时包（插件以
  * link: 方式装入 profile，Node ESM 按 realpath 解析链接包，外部依赖
- * 从插件目录解析不到；这里本来也不需要）。
+ * 从插件目录解析不到）；工具走 ctx.tools.register 的原始 definition
+ * 形状（标准 JSON Schema，参照 dsh-plugin-windows-guard 的先例）。
  */
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { buildIndex, search as kbSearch } from './kb-search.js'
 
 export const name = 'dsh-plugin-dev-kb'
-export const inject = ['skills']
+export const inject = ['skills', 'tools']
 
 const PKG_DIR = dirname(fileURLToPath(import.meta.url))
 const SKILLS_DIR = join(PKG_DIR, '..', 'skills')
 const KB_DIR = join(PKG_DIR, '..', 'kb')
 
+const DEFAULT_CONFIG = {
+  /** 注册 dsh_kb_search 知识库检索工具（false = 只保留技能，不注册工具）。 */
+  searchTool: true,
+}
+
+// ---------------------------------------------------------------------------
+// dsh_kb_search 工具（原始 definition 形状，零依赖）
+// ---------------------------------------------------------------------------
+
+/** 把 search 结果渲染为模型可读 Markdown。 */
+function renderResult(value) {
+  if (value.kind === 'topics') {
+    return [
+      `【知识库主题导航】${value.topicsPath ?? ''}`,
+      value.text ?? '',
+      value.hint ?? '',
+    ].filter(Boolean).join('\n')
+  }
+  if (value.kind === 'empty') {
+    return `【无命中】query: ${value.query}\n${value.hint}`
+  }
+  const lines = [`【知识库检索】query: ${value.query}（scope=${value.scope}，命中 ${value.files.length} 个文件${value.truncatedFiles ? `，另有 ${value.truncatedFiles} 个未展示` : ''}）`]
+  for (const f of value.files) {
+    lines.push('')
+    lines.push(`### ${f.path}（score ${f.score}${f.title ? `，标题「${f.title}」` : ''}）`)
+    lines.push(`绝对路径：${f.absPath}｜命中行：${f.hitLines.join(', ')}`)
+    for (const s of f.snippets) {
+      lines.push('')
+      lines.push(`--- L${s.from} 起（命中行 L${s.line}）---`)
+      lines.push(s.text)
+    }
+  }
+  lines.push('')
+  lines.push(value.hint ?? '')
+  return lines.join('\n')
+}
+
+/** dsh_kb_search 工具定义。 */
+function kbSearchTool(getIndex) {
+  return {
+    name: 'dsh_kb_search',
+    description:
+      'dsh 插件开发知识库本地打分检索（零 token、毫秒级）：在官方文档完整镜像（站点 192 页 + 仓库补充文档）中' +
+      '按关键词检索，返回命中文件路径、行号与上下文片段，用 read 工具按行号局部读原文。' +
+      'query 为空或 "topics" 返回主题导航（任务场景 → 文档清单）。写 dsh 插件 / Tool / 配置 / 服务 / 事件 /' +
+      '查 ctx.* API 签名 / 打包发布 / LLM 适配器时先用本工具定位文档，找不到再用文件工具 grep。' +
+      '仅限 dsh（DeepSeek Harness）插件开发知识库。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['query'],
+      properties: {
+        query: {
+          type: 'string',
+          description:
+            '检索关键词，空白分隔多词（如 "ctx.tools.register"、"插件配置 发布"）；空串或 "topics" 返回主题导航。'
+        },
+        scope: {
+          type: 'string',
+          enum: ['all', 'api'],
+          description:
+            'all = 全部文档（默认）；api = 只搜 API 签名/目录类文档（tool-catalog、config-catalog、capability-seams、cordis-api、subsystems 等），适合查 ctx.* API。'
+        },
+        lang: {
+          type: 'string',
+          enum: ['zh', 'en'],
+          description: '文档语言（默认 zh；en 首次调用会现场建英文索引，稍慢）'
+        },
+        maxResults: {
+          type: 'integer',
+          description: '返回文件数上限（默认 8，最大 20）'
+        }
+      }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['kind', 'text'],
+        properties: {
+          kind: { type: 'string', enum: ['hits', 'empty', 'topics'] },
+          text: { type: 'string' }
+        }
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }]
+    },
+    async execute(args) {
+      const { index, error } = getIndex(args.lang === 'en' ? 'en' : 'zh')
+      if (error) throw new Error(error)
+      const result = kbSearch(index, args.query, {
+        scope: args.scope === 'api' ? 'api' : 'all',
+        maxResults: args.maxResults,
+      })
+      return { kind: result.kind, text: renderResult(result) }
+    }
+  }
+}
+
 /** logger 拿不到时降级 console。 */
 function makeLogger(ctx, tag) {
   return {
@@ -77,6 +181,11 @@ function loadSkills(log) {
 
 export function apply(ctx, config) {
   const log = makeLogger(ctx, '[dsh-plugin-dev-kb]')
+  const cfg = { ...DEFAULT_CONFIG, ...(config ?? {}) }
+  // 显式布尔归一（patch 配置可能是字符串）
+  for (const key of Object.keys(DEFAULT_CONFIG)) {
+    if (typeof cfg[key] === 'string') cfg[key] = cfg[key] === 'true'
+  }
 
   // 契约（dsh-skill validateDefinition）：定义必须含 name/description/
   // source/content 四个字符串；provider 缺省为 'runtime'。
@@ -98,5 +207,38 @@ export function apply(ctx, config) {
     log.info(`技能已注册：${skill.name}`)
   }
 
+  // B. 检索工具（1.6.0 起）：索引惰性构建（首次调用时建，宿主启动零开销），
+  //    zh/en 各缓存一份；kb 目录缺失 → 工具执行时报错并提示退回文件工具检索。
+  if (cfg.searchTool) {
+    if (typeof ctx.tools?.register === 'function') {
+      const indexCache = new Map()
+      const getIndex = (lang) => {
+        if (indexCache.has(lang)) return { index: indexCache.get(lang), error: undefined }
+        if (!existsSync(KB_DIR)) {
+          return {
+            index: undefined,
+            error: `知识库目录缺失：${KB_DIR.replaceAll('\\', '/')}（插件安装不完整？请改用文件工具 grep 检索，或重装插件）`
+          }
+        }
+        try {
+          const t0 = Date.now()
+          const index = buildIndex(KB_DIR, lang, log)
+          indexCache.set(lang, index)
+          log.info(`知识库${lang} 索引就绪：${index.files.length} 个文件（${Date.now() - t0}ms）`)
+          return { index, error: undefined }
+        } catch (err) {
+          return {
+            index: undefined,
+            error: `知识库索引构建失败：${err?.message ?? err}（请改用文件工具 grep 检索知识库目录）`
+          }
+        }
+      }
+      ctx.effect(() => ctx.tools.register(kbSearchTool(getIndex), 'dsh-plugin-dev-kb: register dsh_kb_search'), 'dsh-plugin-dev-kb: register dsh_kb_search')
+      log.info('工具已注册：dsh_kb_search')
+    } else {
+      log.warn('ctx.tools.register 不可用，dsh_kb_search 未注册（工具子系统的注入可能失败）')
+    }
+  }
+
   log.info(`已挂载（知识库在 kb/ 目录）`)
 }

package/lib/kb-search.js

@@ -0,0 +1,261 @@
+/**
+ * kb-search — 知识库本地打分检索（零依赖，纯函数）。
+ *
+ * 为 dsh_kb_search 工具提供两段式能力：
+ *   buildIndex(kbDir, log)  扫描 kb/ 构建 内存索引（每文件：相对路径、标题、行数组）。
+ *                           中文索引默认扫 site/（跳过 site/en/）+ extra/（跳过 *.zh.md
+ *                           的英文原文对？不——extra 中英成对，跳过无 .zh 后缀的英文版）
+ *                           + meta/topics.md；英文索引按需构建（lang=en）。
+ *   search(index, query, opts)  按空白分词打分：标题命中 ×8、路径命中 ×4、
+ *                           正文行命中 ×1（多词同现加权），返回 top N 文件，
+ *                           每文件附命中行号与上下文片段（每文件最多 maxSnippets 处）。
+ *
+ * 设计约束：
+ *   - 只读 kb/，绝不写任何文件；索引在内存，宿主重启重建（构建毫秒级）。
+ *   - 大文件不整读返回：只回片段 + 行号，模型再按行号 read 局部。
+ *   - 输出总量截断保护（renderChars），超出提示用文件工具局部读。
+ *   - 失败安全：任何文件读不了就跳过并计数警告，绝不让索引构建抛错崩掉宿主。
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+/** 单文件大小上限（1.5MB）：超过则跳过正文索引，只保留标题/路径（防止异常大文件拖慢启动）。 */
+const MAX_FILE_BYTES = 1_500_000
+
+/** 递归收集目录下全部 .md 文件（相对路径，正斜杠）。 */
+function listMarkdownFiles(dir, base) {
+  const out = []
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name)
+    if (e.isDirectory()) {
+      out.push(...listMarkdownFiles(full, base))
+    } else if (e.isFile() && e.name.endsWith('.md')) {
+      out.push(relative(base, full).split(sep).join('/'))
+    }
+  }
+  return out
+}
+
+/** 判断相对路径是否纳入指定语言的索引。 */
+function includeForLang(rel, lang) {
+  if (lang === 'en') {
+    // 英文：site/en/** 或 extra 下无 .zh.md 对应的英文原文；topics 导航保留（中文但导航有效）
+    if (rel.startsWith('site/en/')) return true
+    if (rel.startsWith('extra/')) return !isZhPair(rel)
+    if (rel === 'meta/topics.md') return true
+    return false
+  }
+  // 中文：site/ 下除 en/ 外全部；extra/ 下仅 *.zh.md；meta/topics.md
+  if (rel.startsWith('site/en/')) return false
+  if (rel.startsWith('site/')) return true
+  if (rel.startsWith('extra/')) return rel.endsWith('.zh.md')
+  if (rel === 'meta/topics.md') return true
+  return false
+}
+
+/** rel 是否为 extra 下成对的中文版（*.zh.md）——中文索引收 .zh.md，英文索引收无后缀原文。 */
+function isZhPair(rel) {
+  return rel.endsWith('.zh.md')
+}
+
+/** 读文件并切行；读失败返回 null。 */
+function readLines(absPath) {
+  try {
+    const st = statSync(absPath)
+    if (st.size > MAX_FILE_BYTES) return null
+    return readFileSync(absPath, 'utf8').split(/\r?\n/)
+  } catch {
+    return null
+  }
+}
+
+/** 取文件首个 ATX 标题作为 title。 */
+function firstHeading(lines) {
+  for (const line of lines) {
+    const m = /^#{1,6}\s+(.+)$/.exec(line)
+    if (m) return m[1].trim()
+  }
+  return ''
+}
+
+/**
+ * 构建索引。
+ * @param {string} kbDir 知识库根（插件内 kb/ 绝对路径）
+ * @param {'zh'|'en'} [lang] 中文索引（默认）：site/ 非 en + extra/*.zh.md + topics；
+ *                           英文索引：site/en/** + extra/ 无 .zh 后缀原文。
+ * @param {{warn:(...a:any[])=>void}} [log]
+ * @returns {{ kbDir: string, lang: string, files: Array<{rel:string, abs:string, title:string, lines:string[]}> }}
+ */
+export function buildIndex(kbDir, lang = 'zh', log) {
+  const warn = log?.warn ?? (() => {})
+  const files = []
+  const rels = listMarkdownFiles(kbDir, kbDir)
+  for (const rel of rels) {
+    if (!includeForLang(rel, lang)) continue
+    const lines = readLines(join(kbDir, ...rel.split('/')))
+    if (!lines) {
+      warn(`索引跳过（读取失败或过大）：${rel}`)
+      continue
+    }
+    files.push({ rel, abs: join(kbDir, ...rel.split('/')), title: firstHeading(lines), lines })
+  }
+  // topics.md 永远排最前候选位（搜索无结果时兜底展示）
+  files.sort((a, b) => (a.rel === 'meta/topics.md' ? -1 : b.rel === 'meta/topics.md' ? 1 : a.rel < b.rel ? -1 : 1))
+  return { kbDir, lang, files }
+}
+
+/** query 按空白分词 + 小写化；空结果返回 []。 */
+function tokenize(query) {
+  return String(query ?? '')
+    .toLowerCase()
+    .split(/\s+/)
+    .map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')) // 转成正则安全串
+    .filter((t) => t.length > 0)
+}
+
+/** 从主词派生标题/路径子词（ctx.tools.register → ctx/tools/register），用于路径与标题的弱匹配。 */
+function derivePathTerms(terms) {
+  const out = []
+  for (const t of terms) {
+    for (const seg of t.split(/[._/\\-]+/)) {
+      if (seg.length >= 3 && !out.includes(seg)) out.push(seg)
+    }
+  }
+  return out
+}
+
+/** API 类文件（scope='api' 时只搜这些）：签名/目录/缝合点文档。 */
+const API_PATH_RE = /(tool-catalog|config-catalog|capability-seams|cordis-api\/|subsystems\/|api-gateway|agent-lifecycle|persistence-catalog)/
+
+/**
+ * 检索。
+ * @param {{kbDir:string, files:Array}} index buildIndex 产物
+ * @param {string} query 关键词（空白分隔多词）；空或 'topics' 返回主题导航
+ * @param {{scope?:'all'|'api', maxResults?:number, maxSnippets?:number, renderChars?:number}} [opts]
+ */
+export function search(index, query, opts = {}) {
+  const maxResults = Math.min(Math.max(opts.maxResults ?? 8, 1), 20)
+  const maxSnippets = opts.maxSnippets ?? 3
+  const renderChars = opts.renderChars ?? 12000
+  const scope = opts.scope === 'api' ? 'api' : 'all'
+
+  const raw = String(query ?? '').trim()
+  if (!raw || raw.toLowerCase() === 'topics') {
+    return topicsDigest(index, renderChars)
+  }
+
+  const terms = tokenize(raw)
+  if (!terms.length) return topicsDigest(index, renderChars)
+  const termRes = terms.map((t) => new RegExp(t, 'i'))
+  const pathTermRes = derivePathTerms(terms).map((t) => new RegExp(t, 'i'))
+
+  const scored = []
+  for (const f of index.files) {
+    if (scope === 'api' && !API_PATH_RE.test(f.rel)) continue
+    let score = 0
+    const hitLineNums = []
+    for (let i = 0; i < f.lines.length; i++) {
+      let lineHit = 0
+      for (let k = 0; k < termRes.length; k++) {
+        if (termRes[k].test(f.lines[i])) lineHit++
+      }
+      if (lineHit > 0) {
+        // 多词同现的行更强：词数平方和近似
+        score += lineHit * lineHit
+        if (hitLineNums.length < 50) hitLineNums.push(i + 1)
+      }
+    }
+    if (score === 0) continue
+    // 教程优先：入门/开发/指南路径下的文档在同等得分时更靠前
+    if (/^site\/(develop|guide)\//.test(f.rel)) score += 2
+    const titleLower = f.title.toLowerCase()
+    const relLower = f.rel.toLowerCase()
+    for (let k = 0; k < termRes.length; k++) {
+      if (termRes[k].test(titleLower)) score += 8
+      if (termRes[k].test(relLower)) score += 4
+    }
+    for (let k = 0; k < pathTermRes.length; k++) {
+      if (pathTermRes[k].test(titleLower)) score += 2
+      if (pathTermRes[k].test(relLower)) score += 3
+    }
+    scored.push({ file: f, score, hitLineNums })
+  }
+
+  scored.sort((a, b) => b.score - a.score || (a.file.rel < b.file.rel ? -1 : 1))
+
+  const files = []
+  let used = 0
+  for (const s of scored.slice(0, maxResults)) {
+    const f = s.file
+    const snippets = []
+    // 挑前 maxSnippets 个命中行，每个给前后各 2 行上下文
+    for (const ln of s.hitLineNums.slice(0, maxSnippets)) {
+      const from = Math.max(1, ln - 2)
+      const to = Math.min(f.lines.length, ln + 2)
+      const text = f.lines.slice(from - 1, to).join('\n')
+      snippets.push({ line: ln, from, text })
+    }
+    const entry = {
+      path: f.rel,
+      absPath: f.abs.replaceAll('\\', '/'),
+      title: f.title,
+      score: s.score,
+      hitLines: s.hitLineNums.slice(0, 12),
+      snippets,
+    }
+    // 预算控制：超过 renderChars 就不再多塞文件
+    const est = JSON.stringify(entry).length
+    if (used + est > renderChars && files.length > 0) break
+    used += est
+    files.push(entry)
+  }
+
+  if (!files.length) {
+    return {
+      kind: 'empty',
+      query: raw,
+      scope,
+      hint: `无命中。建议：① 换更短的关键词（如 "tool" "config" "event"）；② query 传 "topics" 看主题导航；③ 用文件工具 grep 知识库目录。`,
+      topicsPath: absOf(index, 'meta/topics.md'),
+    }
+  }
+
+  return {
+    kind: 'hits',
+    query: raw,
+    scope,
+    truncatedFiles: scored.length > files.length ? scored.length - files.length : 0,
+    files,
+    hint: '用 read 工具按 absPath + 行号局部读取原文；大文件禁止整读。',
+  }
+}
+
+/** 主题导航摘要（query 空 / 'topics' / 无命中兜底）。 */
+function topicsDigest(index, renderChars) {
+  const f = index.files.find((x) => x.rel === 'meta/topics.md')
+  if (!f) {
+    return {
+      kind: 'topics',
+      hint: '知识库缺 meta/topics.md；请直接用文件工具 grep 知识库目录。',
+      kbRoot: index.kbDir.replaceAll('\\', '/'),
+    }
+  }
+  return {
+    kind: 'topics',
+    topicsPath: f.abs.replaceAll('\\', '/'),
+    text: f.lines.join('\n').slice(0, renderChars),
+    hint: '按主题里的文件清单直接 read 对应文档。',
+  }
+}
+
+function absOf(index, rel) {
+  const f = index.files.find((x) => x.rel === rel)
+  return f ? f.abs.replaceAll('\\', '/') : `${index.kbDir.replaceAll('\\', '/')}/${rel}`
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-dev-kb",
-  "description": "dsh 插件辅助：① dsh-plugin-dev-kb 技能 = DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 188 页）+ 182 篇仓库补充开发参考 + 主题导航与 373 文件全量搜索索引；② dsh-dev-sandbox 技能 = 独立 dev profile 开发沙箱工作流，开发中的插件隔离运行，agent 自主启动/重启/冒烟验证，插件崩了不影响主力 dsh。零运行时依赖。",
-  "version": "1.5.1",
+  "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": {

package/scripts/selfcheck.mjs

@@ -22,6 +22,16 @@ 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");
+}
+
 if (failures.length) {
   for (const f of failures) console.error(`[FAIL] ${f}`);
   console.error(`${failures.length} 项失败`);

package/skills/dsh-dev-sandbox.md

@@ -1,24 +1,25 @@
 ---
 name: dsh-dev-sandbox
-description: dsh 插件开发沙箱：用独立 dev profile 隔离开发中的插件，插件崩了只崩沙箱、绝不影响主力 dsh。所有启动 / 重启 / 看日志 / 冒烟验证都由 agent 自己完成，不要求用户重启。开发或调试 dsh 插件、需要验证插件能否加载、插件改完要重启验证时加载本技能。
+description: dsh 插件开发沙箱：agent 自建独立沙箱 profile 隔离开发中的插件，插件崩了只崩沙箱、绝不影响主力 dsh。所有启动 / 重启 / 看日志 / 冒烟验证都由 agent 自己完成，不要求用户重启。开发或调试 dsh 插件、需要验证插件能否加载、插件改完要重启验证时加载本技能。
 whenToUse: 开发/调试 dsh 插件需要启动、重启、验证插件加载，或插件疑似把 dsh 搞挂时
 ---
 # dsh 插件开发沙箱（dsh-dev-sandbox）
 
 核心原则：**开发中的插件永远装在独立沙箱 profile 里，不进主力 profile**。
-插件写崩 → 只有沙箱起不来，主力 dsh（desktop）照常运行，agent 还活着就能自己看日志、改代码、重启沙箱、再验证——闭环不需要用户参与。
+插件写崩 → 只有沙箱起不来，主力 dsh 照常运行，agent 还活着就能自己看日志、改代码、重启沙箱、再验证——闭环不需要用户参与。
 
-## 1. profile 约定
+## 1. 沙箱 profile：名字由 agent 自定
 
-- **默认沙箱 profile 名：`dev`**，目录 `%USERPROFILE%\.dsh\profiles\dev`（与 `desktop` / `web` 平级）。
-- **用户指定了别的名字就用用户的**（如「用 test 沙箱」→ `profiles\test`），下文的 `dev` 全部替换。
+- **不要使用固定名字**。每次建沙箱时按任务起一个可辨识的名字，如 `sb-<插件名或简称>`（`sb-image-tools`、`sb-table-zoom`），目录为 `$DSH_HOME/profiles/<名字>/`（Windows 默认 `%USERPROFILE%\.dsh\profiles\<名字>\`）。
+- 建之前先列 `~/.dsh/profiles/`：**不得与现有 profile 重名**（尤其 `web` / `desktop` 这类主力 profile，绝不复用、绝不写入）；重名就换一个名字。
+- 一次性验证可用完即删（删 profile 目录即可，沙箱与主力完全隔离）；跨天持续开发的插件保留同名沙箱复用。
 - 沙箱与主力 profile 完全隔离：插件、patch、会话、设置各一份；provider/模型配置可从主力 profile 的 `cordis.patch.yml` 拷贝 provider 段过来（用编辑工具，UTF-8 无 BOM，勿用 PowerShell 重定向写）。
 
 ## 2. 沙箱不存在时：初始化（一次）
 
 ```powershell
 # 版本与目标 dsh 对齐：先用主力安装的实际版本号替换下面的 <ver>（插件自身 peerDependencies 也要覆盖它）
-npx -y "@deepseek-ai/dsh@<ver>" plugin --profile dev add file:/绝对路径/插件目录
+npx -y "@deepseek-ai/dsh@<ver>" plugin --profile <沙箱名> add file:/绝对路径/插件目录
 ```
 
 - `add` 走兼容闸门：peerDependencies 不覆盖当前 dsh 版本会整体拒绝并回滚——这不是网络问题，改 peer 或按提示 `allow-version` 豁免。
@@ -29,30 +30,32 @@ npx -y "@deepseek-ai/dsh@<ver>" plugin --profile dev add file:/绝对路径/插
 
 ```powershell
 # 后台启动（run_in_background），端口避开主力；日志里找 token 行与报错
-npx -y "@deepseek-ai/dsh@<ver>" web --profile dev --port 3081
+npx -y "@deepseek-ai/dsh@<ver>" web --profile <沙箱名> --port <空闲端口>
 ```
 
-- 启动日志含 `dsh web: http://127.0.0.1:3081/?token=…`（token 每次启动轮换，用它开 GUI 验证 UI 类插件）。
+- 端口自选一个空闲高位端口（如 3081 起，被占就换下一个）；记住本次用的端口，后续重启/探活都用它。
+- 启动日志含 `dsh web: http://127.0.0.1:<port>/?token=…`（token 每次启动轮换，用它开 GUI 验证 UI 类插件）。
 - **逐条看 stderr 的 `dsh: skipping profile bundle "X"`**——被跳过 = 插件静默失效（不崩但功能没了），立即修，别当没看见。
 - **自主重启循环**（改代码 / 改配置后）：
-  1. 找进程：`Get-NetTCPConnection -LocalPort 3081 -State Listen | Select OwningProcess`；
+  1. 找进程：`Get-NetTCPConnection -LocalPort <port> -State Listen | Select OwningProcess`；
   2. 核对 PID 后 `Stop-Process -Id <pid> -Force`；
   3. 重新后台启动，读日志验证（无 skipping 警告、无崩溃栈、端口起来）。
-- **红线：沙箱操作只允许碰沙箱端口/profile；绝不 Stop 主力 dsh 进程、绝不改 `profiles\desktop` 下的东西。**
+- **红线：沙箱操作只允许碰沙箱端口/profile；绝不 Stop 主力 dsh 进程、绝不改主力 profile 下的东西。**
 
 ## 4. 冒烟验证（不起 GUI）
 
 一次性 headless 跑同 profile，验证插件能加载、工具能注册：
 
 ```powershell
-npx -y "@deepseek-ai/dsh@<ver>" --profile dev "列出你当前可用的工具，并调用 <插件工具名> 做一次最小调用"
+npx -y "@deepseek-ai/dsh@<ver>" --profile <沙箱名> "列出你当前可用的工具，并调用 <插件工具名> 做一次最小调用"
 ```
 
 启动即崩（exit 非 0 / 打印异常栈）= 插件破坏了 profile 启动，直接读栈修代码，主 dsh 无恙。
 
-## 5. 收尾：进主力 profile
+## 5. 收尾
 
-插件在沙箱里稳定后，才走正常流程挪进主力 profile：同步版本与 peerDependencies → 改主力 profile → `pnpm install` → 自检 → 由用户重启主力 dsh（主力重启永远由用户决定）。发布流程遵循该插件仓库自己的发布规范/CI。
+- 插件在沙箱里稳定后，才走正常流程挪进主力 profile：同步版本与 peerDependencies → 改主力 profile → `pnpm install` → 自检 → 由用户重启主力 dsh（主力重启永远由用户决定）。发布流程遵循该插件仓库自己的发布规范/CI。
+- 沙箱功成身退：删除对应 profile 目录即完全清理，不留残留。
 
 ## 6. 常见坑速查
 

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

@@ -35,11 +35,11 @@ kb/
 └── 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` 工具，一次拿到命中文件路径 + 行号 + 上下文片段，再用 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` 查对应本地文件。
 
 ## 3. 阅读原则