dsh-plugin-dev-kb 1.5.2 → 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

@@ -1,30 +1,237 @@
 /**
- * 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 { 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']
+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_read 知识库局部阅读工具（1.8.0 起，false = 只用 search）。 */
+  readTool: 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, hostVersion) {
+  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,
+      })
+      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 {
@@ -77,6 +284,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 +310,50 @@ export function apply(ctx, config) {
     log.info(`技能已注册：${skill.name}`)
   }
 
+  // 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) => {
+        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, 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 未注册（工具子系统的注入可能失败）')
+    }
+  }
+
   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}`
+}