dsh-tool-folder 0.2.4 → 0.3.0

package/lib/index.js

@@ -37,10 +37,23 @@ import { selectionCoverage, isHotTool, prioritizeExact, touchWarm, evictWarm, mi
 import { tierForBudget } from "./budget.js";
 import { readState, writeState } from "./storage.js";
 import { expandQuery, fallbackCatalog, createSearchCache, recordDiscoveries, serializeDiscoveries, deserializeDiscoveries, siblingClosure, buildSchemaResponse } from "./ux.js";
-import { ChainGuard, verdict } from "./chainguard.js";
+import { ChainGuard, verdict, isExecTool } from "./chainguard.js";
 import { matchCategory } from "./category.js";
 import { toonifyValue } from "./toonify.js";
-import { configureSemantic, buildSemanticIndex, searchSemantic, rrfFuse } from "./semantic.js";
+import {
+  configureSemantic,
+  buildSemanticIndex,
+  searchSemantic,
+  searchSemanticCached,
+  embedQueryCached,
+  getCachedQueryVector,
+  rrfFuse,
+  adaptiveBmWeight,
+  DEFAULT_SEM_WEIGHT,
+  DEFAULT_BM_WEIGHT,
+} from "./semantic.js";
+import { rerankByBody, toolBodyText } from "./rerank.js";
+import { remoteEmbedState } from "./embed-remote.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 
 export const name = "tool-folder";
@@ -77,9 +90,21 @@ export const Config = z.object({
   maxFoldMs: z.number().min(0).max(1000).default(50).description("折叠超时上限（ms），超时回退完整工具列表"),
   feedbackFile: z.string().default("").description("反馈数据落盘路径（空=DSH_HOME/logs/tool-folder/）"),
   aliases: z.dict(z.array(z.string())).default({}).description("中文意图→server 别名表"),
-  semanticEnabled: z.boolean().default(true).description("语义检索腿（本地 Ollama bge-m3）：tools_search 用 BM25+语义 RRF 混合，中英跨语言命中"),
-  ollamaBase: z.string().default("http://127.0.0.1:11434").description("Ollama 地址（semanticEnabled 时使用）"),
-  embedModel: z.string().default("bge-m3").description("embedding 模型（semanticEnabled 时使用）"),
+  semanticEnabled: z.boolean().default(true).description("语义检索腿：tools_search 用 BM25+语义 加权 RRF 混合（远程 embedding 优先，失败回落本地 Ollama，再失败纯 BM25）"),
+  ollamaBase: z.string().default("http://127.0.0.1:11434").description("Ollama 地址（远程 embedding 不可用时的本地兜底）"),
+  embedModel: z.string().default("bge-m3").description("本地 Ollama embedding 模型（兜底腿）"),
+  embedTimeoutMs: z.number().min(100).default(12000).description("embedding 请求超时（毫秒）"),
+  embedApiBase: z.string().default("https://ark.cn-beijing.volces.com/api/plan/v3").description("远程 embedding 端点（OpenAI 兼容；默认火山方舟）"),
+  embedApiModel: z.string().default("doubao-embedding-vision").description("远程 embedding 模型"),
+  embedApiKey: z.string().default("").description("远程 embedding key；留空则读 DSH_EMBED_KEY / OPENVIKING_ARK_KEY"),
+  semanticWeight: z.number().min(0).max(20).default(3).description("RRF 中语义腿相对 BM25 的权重：1=等权，3=偏语义（默认），0=纯 BM25"),
+  adaptiveBm: z.boolean().default(true).description("自适应 BM25 权重：查询里有真实英文锚点（工具名/server/关键词）时 BM25 权重 1，纯中文查询降到 bmWeight（实测 6/18→11/18）"),
+  bmWeight: z.number().min(0).max(5).default(0.25).description("纯中文查询下 BM25 的 RRF 权重（adaptiveBm=false 时固定用这个值）"),
+  bodyRerank: z.boolean().default(false).description("正文精排：在召回候选集内用完整描述+参数 schema 重排（借鉴 SkillRouter 两阶段检索）。实测本语料 Hit@1 持平、Hit@3 -1，故默认关"),
+  bodyRerankWeight: z.number().min(0).max(1).default(0.35).description("正文精排权重：final=(1-w)·元数据名次 + w·正文覆盖"),
+  bodyRerankTopN: z.number().min(1).max(50).default(12).description("参与正文重排的候选数（不扩大候选，只在召回集内重排）"),
+  semanticDynamic: z.boolean().default(true).description("语义腿参与每轮自动注入：只用已缓存的查询向量，零额外延迟（首次查询由后台预热）"),
+  debugDump: z.string().default("").description("调试：把当前工具语料（名/描述/schema）dump 到该路径，用于离线评测（空=关闭）"),
   disclosureBudget: z.number().min(0).max(200000).default(0)
     .description("分级披露预算（字节）：0=关闭。开启后可见工具 schema 估算字节超预算时，动态段按 完整schema→name+desc→仅name→折叠进catalog 逐级降级（core/hot 永不降级）"),
   maxWarmTools: z.number().min(0).max(50).default(0)
@@ -121,9 +146,21 @@ const DEFAULTS = {
     "mcp__open-design": ["设计", "design"],
     "mcp__serena": ["代码搜索", "搜代码", "search code", "serena"],
   },
-  semanticEnabled: true, // P0-1: bge-m3 semantic leg for tools_search (RRF hybrid)
+  semanticEnabled: true, // v0.3.0: 远程优先 → Ollama → BM25 的语义腿
   ollamaBase: "http://127.0.0.1:11434",
   embedModel: "bge-m3",
+  embedTimeoutMs: 12000, // v0.3.0: 远程 embedding 首页可能较慢，8s 偏紧
+  embedApiBase: "https://ark.cn-beijing.volces.com/api/plan/v3", // v0.3.0 远程语义腿
+  embedApiModel: "doubao-embedding-vision",
+  embedApiKey: "", // 空则读 DSH_EMBED_KEY / OPENVIKING_ARK_KEY
+  semanticWeight: 3, // v0.3.0: RRF 语义权重（1=等权）
+  adaptiveBm: true, // v0.3.0: 纯中文查询自动降 BM25 权重
+  bmWeight: 0.25, // v0.3.0: 纯中文查询下的 BM25 权重（实测 1:1 融合只有 8/18）
+  bodyRerank: false, // v0.3.0: 实测 Hit@1 持平 / Hit@3 -1，默认关，可显式开
+  bodyRerankWeight: 0.35,
+  bodyRerankTopN: 12,
+  semanticDynamic: true, // v0.3.0: 语义腿参与自动注入（只用缓存查询向量）
+  debugDump: "", // v0.3.0: 工具语料 dump（离线评测用）；也认 DSH_TOOL_FOLDER_DUMP 环境变量
   disclosureBudget: 0, // v0.2.2: 分级披露预算（0=关闭）
   maxWarmTools: 0, // v0.2.2: warm LRU 上限（0=关闭，默认关=无配置升级逐字节等价）
   fallbackCatalogSize: 30, // P0: 零匹配回退轻目录条数（0=关闭）
@@ -200,24 +237,6 @@ function serverOf(name) {
   return "native";
 }
 
-/**
- * 是否「执行类工具」——参数是真实要执行的命令/脚本，需要高危硬拦。
- * 内容类工具（write/edit/read/apply_patch 等）的参数是文件内容/文本，
- * 本身不执行，含危险命令字面量（讨论/测试/文档）不应触发硬拦。
- * 2026-08-30：修复 ChainGuard 对所有工具参数跑高危正则导致的误拦。
- */
-function isExecTool(name) {
-  if (!name) return false;
-  const n = String(name).toLowerCase();
-  const EXEC_NAMES = ["pwsh", "shell", "bash", "cmd", "exec", "terminal", "run", "console"];
-  if (EXEC_NAMES.includes(n)) return true;
-  if (n.includes("powershell")) return true; // mcp__windows__PowerShell 等（参数即命令）
-  if (n.endsWith("__app")) return true; // mcp__windows__App：launch_executable 模式可启动任意可执行文件
-  if (n.startsWith("run_") || n.startsWith("exec_") || n.startsWith("execute_")) return true;
-  if (n.startsWith("ssh_") || n.startsWith("wsl")) return true;
-  return false;
-}
-
 function summarizeCaps(tools) {
   // Pull the first few distinct capability keywords from descriptions.
   const seen = new Set();
@@ -276,21 +295,112 @@ export function apply(ctx, config) {
     return;
   }
 
-  // Semantic leg (P0-1): point the shared module at our config; the index is
-  // built lazily on first tools_search call (doc embeddings cached on disk,
-  // so the ~10s cold start happens once, then it's a cache hit).
-  configureSemantic({ ollamaBase: cfg.ollamaBase, embedModel: cfg.embedModel });
+  // 语义腿（v0.3.0）：远程 embedding 优先，本地 Ollama 兜底。
+  // 索引在**后台**构建（首次约 30-40s，之后磁盘缓存命中 <100ms），
+  // 任何热路径都只读"已就绪的索引"，绝不阻塞 assemble 或工具调用。
+  configureSemantic({
+    ollamaBase: cfg.ollamaBase,
+    embedModel: cfg.embedModel,
+    embedTimeoutMs: cfg.embedTimeoutMs,
+    remoteBase: cfg.embedApiBase,
+    remoteModel: cfg.embedApiModel,
+    remoteKey: cfg.embedApiKey,
+  });
+  let semIndex = null; // 已就绪的索引 {vectors, available}
   let semIndexPromise = null;
-  const getSemanticIndex = () => {
-    if (!semIndexPromise) {
-      semIndexPromise = (async () => {
-        const docs = allTools.map((t) => ({ id: t.name, text: `${t.name} ${t.description || ""}` }));
-        return buildSemanticIndex(docs);
-      })();
-    }
-    return semIndexPromise;
+  let semStamp = "";
+
+  // 文档正文按工具集缓存：toolBodyText 要拼描述 + 全部参数，243 个工具每轮重算
+  // 会给 assemble 热路径带来无谓开销。
+  let semDocsCache = null;
+  let semDocsStamp = "";
+  const semanticDocs = () => {
+    const stamp = `${allTools.length}\u0001${allTools[0]?.name || ""}\u0001${allTools[allTools.length - 1]?.name || ""}`;
+    if (semDocsCache && semDocsStamp === stamp) return semDocsCache;
+    semDocsStamp = stamp;
+    semDocsCache = allTools.map((t) => ({ id: t.name, text: toolBodyText(t) }));
+    return semDocsCache;
+  };
+
+  /** 触发后台构建（幂等、非阻塞）。工具集变化时按 stamp 重建。 */
+  const ensureSemanticIndex = () => {
+    if (!cfg.semanticEnabled || allTools.length === 0) return;
+    const stamp = `${allTools.length}\u0001${allTools[0]?.name || ""}\u0001${allTools[allTools.length - 1]?.name || ""}`;
+    if (semIndexPromise && stamp === semStamp) return;
+    semStamp = stamp;
+    semIndexPromise = (async () => {
+      const t0 = Date.now();
+      const docs = semanticDocs();
+      // dump 放在构建之前：语料采集不该依赖 embedding 是否成功
+      const dumpPath = cfg.debugDump || process.env.DSH_TOOL_FOLDER_DUMP || "";
+      if (dumpPath) {
+        try {
+          fs.mkdirSync(path.dirname(dumpPath), { recursive: true });
+          fs.writeFileSync(
+            dumpPath,
+            JSON.stringify({ ts: Date.now(), count: allTools.length, tools: allTools }, null, 2),
+            "utf8",
+          );
+          logger.info("debug dump written: %s", dumpPath);
+        } catch (e) {
+          logger.warn("debug dump failed (%s)", e?.message);
+        }
+      }
+      let built;
+      try {
+        built = await buildSemanticIndex(docs, cfg.embedTimeoutMs, {
+          onProgress: (done, total) => {
+            if (done === total || done % 40 === 0) {
+              logger.info("semantic index progress %d/%d", done, total);
+            }
+          },
+        });
+      } catch (e) {
+        logger.warn("semantic index build failed (%s) — BM25 only", e?.message);
+        return null;
+      }
+      const st = remoteEmbedState();
+      logger.info(
+        "semantic index ready: %d/%d vectors (embedded=%d reused=%d) in %dms | provider=%s",
+        built.vectors.size, docs.length, built.embedded, built.reused, Date.now() - t0,
+        st.available ? "remote" : "ollama/offline",
+      );
+      if (!built.available && !built.vectors.size) {
+        logger.warn("semantic leg unavailable (no vectors) — tools_search degrades to BM25");
+      }
+
+      semIndex = built;
+      return built;
+    })();
+    // 后台跑，别让未处理的 rejection 冒泡
+    semIndexPromise.catch?.(() => {});
   };
 
+  // 查询向量后台预热（节流 15s）：让 semanticDynamic 在下一轮就能用缓存
+  let lastPrefetch = 0;
+  const prefetchQuery = (query) => {
+    if (!cfg.semanticEnabled || !cfg.semanticDynamic || !query) return;
+    if (getCachedQueryVector(query)) return;
+    const now = Date.now();
+    if (now - lastPrefetch < 15_000) return;
+    lastPrefetch = now;
+    embedQueryCached(query, cfg.embedTimeoutMs).catch(() => {});
+  };
+
+  // 首次 assemble 之后自动预热语义索引（allTools 只在 assemble 里才有值，
+  // 启动瞬间是空的）。每 15s 探一次，最多 5 分钟；unref 保证不阻止进程退出。
+  // 这样第一条 tools_search 之前索引通常已就绪，且不占启动时间。
+  let warmTicks = 0;
+  const warmTimer = setInterval(() => {
+    warmTicks += 1;
+    if (semIndex || semIndexPromise || warmTicks > 20) {
+      clearInterval(warmTimer);
+      return;
+    }
+    if (allTools.length) ensureSemanticIndex();
+  }, 15_000);
+  warmTimer.unref?.();
+
   const fbPath = feedbackPath(cfg);
   const feedback = loadFeedback(fbPath, logger);
   let index = null;
@@ -384,9 +494,12 @@ export function apply(ctx, config) {
   // P0-②: 检索结果缓存（同 query 60s 内稳定；LRU 200 条；进程级共享）。
   const searchCache = createSearchCache(200, 60000);
 
-  // "mcp__viking__remember" → "mcp__viking"; plain tools ("tool-bash") stay
-  // as themselves (single segment survives slice(0,2)).
-  const serverOf = (name) => String(name).split("__").slice(0, 2).join("__");
+  // serverOf is the module-level function defined above (mcp__server__tool →
+  // "mcp__server", openhands_* → "openhands", plain native tools → "native").
+  // P3-1 (2026-09-02): the previous apply-local copy (split("__").slice(0,2))
+  // let plain tools be their own "server", diverging from catalogText grouping
+  // and making sibling closure useless for native/openhands families. One
+  // definition, one口径.
 
   // Pattern matching shared by deny (P0) and include (P2-1): exact name or
   // "prefix*" matches any tool starting with that prefix.
@@ -460,6 +573,17 @@ export function apply(ctx, config) {
     if (cfg.topK > 0 && index) {
       for (const i of search(index, query, cfg.topK)) dyn.add(tools[i].name);
     }
+    // v0.3.0: 语义腿参与自动注入。**只用已缓存的查询向量**——热路径绝不等网络，
+    // 所以这里不会拖慢 assemble，也不会撞 maxFoldMs。查询向量由 prefetchQuery
+    // 在后台预热（同一条消息的第二轮及以后通常已命中缓存）。
+    if (cfg.semanticDynamic && cfg.topK > 0 && semIndex?.available) {
+      try {
+        const hits = searchSemanticCached(semIndex.vectors, semanticDocs(), query);
+        for (const h of hits.slice(0, cfg.topK)) dyn.add(h.id);
+      } catch {
+        /* 语义腿失败绝不影响折叠 */
+      }
+    }
     return dyn;
   }
 
@@ -514,7 +638,7 @@ export function apply(ctx, config) {
           if (!index) return { query: q, results: [], total: 0 };
         // P0-②: 同 query 内容指纹的结果缓存——重复搜索返回同一结果集（漂移的
         // 最小修）。进程级共享（非单会话隔离）；空 query（"*" 语义）不走缓存。
-        const cacheKey = `${lim}|${q}`;
+        const cacheKey = `${lim}|${q}|${indexStamp || ""}`;
         if (q) {
           const cached = searchCache.get(cacheKey);
           if (cached) return cached;
@@ -528,23 +652,59 @@ export function apply(ctx, config) {
           q,
           search(index, eq, lim * 2).map((i) => ({ id: allTools[i].name })),
         );
+        const byName = new Map(allTools.map((t) => [t.name, t]));
         let fused = bm25Hits;
-        // Semantic leg (P0-1): RRF-fuse BM25 with local bge-m3 similarity.
-        // Any failure (Ollama down / timeout / cache miss on error) degrades
-        // to BM25-only — the hybrid must never be slower or worse than today.
+        // 语义腿（v0.3.0）：远程优先，加权 RRF。索引在后台构建——这里绝不等待
+        // 冷启动（否则一次搜索能卡 30s+），尚未就绪就先返回 BM25 结果，
+        // 同时由 ensureSemanticIndex 继续在后台补，下一次搜索自然用上。
         if (cfg.semanticEnabled !== false) {
           try {
-            const sem = await getSemanticIndex();
-            if (sem?.available) {
-              const docs = allTools.map((t) => ({ id: t.name, text: `${t.name} ${t.description || ""}` }));
-              const semHits = await searchSemantic(sem.vectors, docs, eq);
-              fused = rrfFuse(bm25Hits, semHits.slice(0, lim * 2), lim);
+            ensureSemanticIndex();
+            if (semIndex?.available) {
+              const semHits = await searchSemantic(semIndex.vectors, semanticDocs(), eq);
+              // 自适应 BM25 权重：纯中文查询下 BM25 只有 CJK bigram 噪声，
+              // 降权 0.25；有真实英文锚点（工具名/server/关键词）时保持 1。
+              const topTool = bm25Hits[0] ? byName.get(bm25Hits[0].id) : null;
+              const bw =
+                cfg.adaptiveBm === false
+                  ? cfg.bmWeight
+                  : adaptiveBmWeight(q, bm25Hits[0]?.id, topTool?.description);
+              fused = rrfFuse(bm25Hits, semHits.slice(0, lim * 2), lim, {
+                semWeight: cfg.semanticWeight,
+                bmWeight: bw,
+              });
             }
           } catch (e) {
             logger.warn("semantic leg failed (%s) — BM25 only", e?.message);
           }
         }
-        const byName = new Map(allTools.map((t) => [t.name, t]));
+
+        // v0.3.0 正文精排（借鉴 SkillRouter 两阶段检索）：在已召回候选集内用
+        // 完整描述 + 参数 schema 重排，**不扩大候选**（技能侧实测扩大候选会
+        // 让泛化词把无关项顶上来）。候选之外的 BM25/语义命中保持原序接在后面。
+        if (cfg.bodyRerank && fused.length > 1) {
+          try {
+            const topN = Math.min(cfg.bodyRerankTopN, fused.length);
+            const head = fused.slice(0, topN);
+            const tail = fused.slice(topN);
+            const reranked = rerankByBody(q, head, byName, { weight: cfg.bodyRerankWeight });
+            fused = [...reranked.map((r) => ({ id: r.id })), ...tail];
+          } catch (e) {
+            logger.warn("body rerank failed (%s) — keep fused order", e?.message);
+          }
+        }
+
+        // 精确名/名字串命中永远钉在最前（正文重排也不许把它挤下去）。
+        const exact = bm25Hits.filter((h) => {
+          const name = String(h.id || "").toLowerCase();
+          const needle = q.trim().toLowerCase();
+          return needle && (name === needle || name.endsWith(needle) || name.includes(needle));
+        });
+        if (exact.length) {
+          const pinned = new Set(exact.map((h) => h.id));
+          fused = [...exact, ...fused.filter((h) => !pinned.has(h.id))];
+        }
+
         let results = fused.map((h) => {
           const t = byName.get(h.id) || {};
           return {
@@ -659,11 +819,18 @@ export function apply(ctx, config) {
       // Meta tools are exempt from include so a whitelist can never hide the
       // discovery tools themselves (that would break the always-visible loop).
       const isMetaTool = (n) => n === "tools_search" || n === "tools_schema";
-      const tools = assembledTools.filter(
-        (t) =>
-          !isDenied(t?.name) &&
-          (isMetaTool(t?.name) || includeAll || matchesAnyPattern(t?.name, includePatterns)),
-      );
+      // v0.3.0: 按名字去重。宿主的组装结果在极端情况下可能重复（同一工具被两个
+      // 插件注册），重复项会让 BM25/RRF 把同一 id 的分数算两次——实测能把正确项
+      // 从第一挤到第三以外。
+      const tools = [];
+      const seenToolNames = new Set();
+      for (const t of assembledTools) {
+        if (isDenied(t?.name)) continue;
+        if (!(isMetaTool(t?.name) || includeAll || matchesAnyPattern(t?.name, includePatterns))) continue;
+        if (seenToolNames.has(t.name)) continue;
+        seenToolNames.add(t.name);
+        tools.push(t);
+      }
       if (tools.length === 0) return { ...assembled, tools };
 
       const agentId = context?.agent?.id || "default";
@@ -702,6 +869,10 @@ export function apply(ctx, config) {
       }
 
       const query = extractQuery(context);
+      // v0.3.0：语义索引在后台构建（首次冷启动），查询向量也后台预热。
+      // 两处都是 fire-and-forget：assemble 是热路径，绝不因为 embedding 变慢。
+      ensureSemanticIndex();
+      prefetchQuery(query);
       const dynNames = buildDynamicSet(tools, query);
 
       // v0.2.2: warm 集合名（只取当前工具池里存在的，避免引用已不存在的工具）。

package/lib/obfuscation.js

@@ -65,7 +65,15 @@ const RE_BITSADMIN = /bitsadmin\s+\/transfer\s+\S+\s+\/download/i;
 
 // A long base64 blob co-located with an execution verb in the same command.
 const RE_B64_PAYLOAD = /[A-Za-z0-9+/]{40,}={0,2}/;
-const EXEC_VERB = /(?:iex|invoke-expression|invoke-command|iwr|irm|start-process|start-job|&|cmd\s*\/[cC]|sh\s+-c|bash\s+-c|python\s+-[cC]|node\s+-e|powershell|pwsh|mshta|rundll32|regsvr32|wscript|cscript)\b/i;
+// Path fingerprint: >=3 camel-case segments joined by '/' (C:/Users/L/AppData/...).
+// '/' is a base64 char, so long Windows/URL paths form fake base64 runs; real
+// base64 payloads almost never contain 3+ `/Upper`-word segments. Fixed 2026-09-02
+// (measured: 57-char WinGet path run + `2>&1` was blocked as base64-embedded-command).
+const RE_PATHISH_RUN = /(?:\/[A-Z][A-Za-z]{1,}){3,}/;
+// Exec verb used by the b64/hex legs. NOTE: no bare `&` — `2>&1` redirection
+// and `& ` call operators are not payload-exec evidence by themselves; the
+// verb must be an actual command word (fixed 2026-09-02, fp-repro 2/5).
+const EXEC_VERB = /(?:iex|invoke-expression|invoke-command|iwr|irm|start-process|start-job|&\s*(?:iex|invoke|iwr|irm|cmd|powershell|pwsh|sh|bash|python|node|mshta|rundll32|regsvr32|wscript|cscript)|cmd\s*\/[cC]|sh\s+-c|bash\s+-c|python\s+-[cC]|node\s+-e|powershell|pwsh|mshta|rundll32|regsvr32|wscript|cscript)\b/i;
 
 // Full-width Latin letters (ｃｕｒｌ) — never legit in a command line.
 const RE_FULLWIDTH = /[\uFF21-\uFF3A\uFF41-\uFF5A]/;
@@ -97,7 +105,8 @@ export function detectObfuscation(rawText, cleanText) {
   if (RE_BITSADMIN.test(probe)) {
     return { label: "bitsadmin-download-exec", detail: "bitsadmin /transfer 下载执行" };
   }
-  if (RE_B64_PAYLOAD.test(probe) && EXEC_VERB.test(probe)) {
+  const b64Run = RE_B64_PAYLOAD.exec(probe);
+  if (b64Run && !RE_PATHISH_RUN.test(b64Run[0]) && EXEC_VERB.test(probe)) {
     return { label: "base64-embedded-command", detail: "长 base64 载荷 + 执行动词共存" };
   }
   if (RE_FULLWIDTH.test(raw)) {

package/lib/rerank.js

@@ -0,0 +1,115 @@
+/**
+ * rerank.js — 正文精排（借鉴 SkillRouter 的「元数据召回 + 正文重排」两阶段）。
+ *
+ * 为什么工具也需要「正文」：`tools_search` 的召回声只看 name + description，
+ * 而真正决定「该用哪个工具」的信息常常在**参数**里。例：
+ *   mcp__playwright__browser_navigate  vs  browser_evaluate  vs  browser_take_screenshot
+ *   描述都是 "browser ..."，参数才是 url / function / filename 的区别。
+ *   再如一堆 `*_search`：query 还是 keyword、有没有 repo/limit，全在参数描述里。
+ * L1 压缩还会把描述截到 200 字、参数描述砍到 120 字——被裁掉的正是这部分信号。
+ *
+ * 做法（与技能侧 v0.4.0 的 deep-search 同构）：
+ *   - 在 BM25/语义召回的**候选集内**重排，绝不扩大候选
+ *     （技能侧实测：扩大候选会让泛化词把无关项顶上来，Hit@1 从 50% 掉到 25%）
+ *   - body 打分 = 查询词在正文里的 IDF 覆盖率 + 整句命中加分
+ *   - 融合：final = (1-w)·元数据名次分 + w·正文分
+ */
+
+import { tokenize } from "./bm25.js";
+
+const MAX_BODY_CHARS = 4000;
+
+/**
+ * 拼出一个工具的「正文」：完整描述（不截断）+ 参数名 + 参数描述 + 枚举 + server。
+ * @param {object} tool
+ * @returns {string}
+ */
+export function toolBodyText(tool) {
+  if (!tool || typeof tool !== "object") return "";
+  const parts = [];
+  if (tool.name) parts.push(String(tool.name));
+  if (tool.description) parts.push(String(tool.description));
+  const schema = tool.parameters || tool.inputSchema || null;
+  const props = schema && typeof schema === "object" ? schema.properties : null;
+  if (props && typeof props === "object") {
+    for (const [k, v] of Object.entries(props)) {
+      parts.push(k);
+      if (v && typeof v === "object") {
+        if (typeof v.title === "string") parts.push(v.title);
+        if (typeof v.description === "string") parts.push(v.description);
+        if (Array.isArray(v.enum)) parts.push(v.enum.slice(0, 12).join(" "));
+        if (v.items && typeof v.items === "object" && typeof v.items.description === "string") {
+          parts.push(v.items.description);
+        }
+      }
+    }
+    if (Array.isArray(schema.required) && schema.required.length) {
+      parts.push(`required ${schema.required.join(" ")}`);
+    }
+  }
+  if (tool.server) parts.push(String(tool.server));
+  return parts.join(" ").slice(0, MAX_BODY_CHARS);
+}
+
+/**
+ * 在候选集内按正文重排。
+ *
+ * @param {string} query
+ * @param {Array<{id: string}>} candidates  已按元数据名次排好序
+ * @param {Map<string, object>} byName
+ * @param {{weight?: number, bodyText?: Function}} [opts]
+ * @returns {Array<{id: string, score: number, metaRank: number, bodyScore: number}>}
+ */
+export function rerankByBody(query, candidates, byName, opts = {}) {
+  const list = Array.isArray(candidates) ? candidates.filter((c) => c && c.id) : [];
+  if (!list.length) return [];
+  const w = Number(opts.weight);
+  const weight = Number.isFinite(w) && w >= 0 && w <= 1 ? w : 0.35;
+  const bodyOf = typeof opts.bodyText === "function" ? opts.bodyText : toolBodyText;
+
+  const q = String(query || "").trim();
+  const qTokens = [...new Set(tokenize(q))];
+  const qLower = q.toLowerCase().replace(/\s+/g, " ");
+
+  if (!qTokens.length) {
+    return list.map((c, i) => ({ id: c.id, score: 1 / (1 + i), metaRank: i, bodyScore: 0 }));
+  }
+
+  // 候选集内的 df / idf（小集合上算，不依赖全局语料）
+  const bodies = new Map();
+  const df = new Map();
+  for (const c of list) {
+    const tool = byName.get(c.id);
+    const text = bodyOf(tool || { name: c.id });
+    const tokens = tokenize(text);
+    const set = new Set(tokens);
+    bodies.set(c.id, { text: text.toLowerCase(), tokens: set, len: tokens.length });
+    for (const t of set) df.set(t, (df.get(t) || 0) + 1);
+  }
+  const n = list.length;
+  const idf = (t) => Math.log((n - (df.get(t) || 0) + 0.5) / ((df.get(t) || 0) + 0.5) + 1);
+  // 分母只算「候选正文里真的出现过」的查询词。否则中文 bigram（工具描述多是英文，
+  // bigram 全 df=0）会把分母撑大，正文分被稀释到接近 0，精排等于没生效。
+  const matchedQ = qTokens.filter((t) => (df.get(t) || 0) > 0);
+  const qIdfSum = (matchedQ.length ? matchedQ.reduce((s, t) => s + idf(t), 0) : 0) || 1;
+
+  const scored = list.map((c, i) => {
+    const b = bodies.get(c.id);
+    if (!b) return { id: c.id, score: 1 / (1 + i), metaRank: i, bodyScore: 0 };
+    let hit = 0;
+    for (const t of qTokens) {
+      if (b.tokens.has(t)) hit += idf(t);
+    }
+    // 覆盖率 0..1，再乘一个「命中密度」修正：短正文命中更可信
+    let bodyScore = hit / qIdfSum;
+    if (bodyScore > 0 && b.len > 0) {
+      bodyScore *= 0.85 + 0.15 * Math.min(1, hit / Math.sqrt(b.len));
+    }
+    if (qLower.length >= 4 && b.text.includes(qLower)) bodyScore = Math.min(1, bodyScore + 0.15);
+    const metaNorm = 1 / (1 + i);
+    return { id: c.id, score: (1 - weight) * metaNorm + weight * bodyScore, metaRank: i, bodyScore };
+  });
+
+  scored.sort((a, b) => b.score - a.score || a.metaRank - b.metaRank);
+  return scored;
+}