dsh-tool-folder 0.2.1 → 0.2.3

package/README.md

@@ -149,6 +149,49 @@ were never unregistered, so nothing else changes.
 
 ## Changelog
 
+### v0.2.3 — fold-ux: search fallback catalog + query expansion + stable results + discovery stats (2026-08-30)
+1. **Zero-match fallback catalog** (`fallbackCatalogSize`, default 30): when
+   `tools_search` finds nothing, it returns a name-sorted lightweight catalog
+   (name + 80-char description) instead of an empty list — the model never
+   concludes a capability doesn't exist just because its wording missed.
+   `total` reports the real catalog size (not the listed slice); the output
+   carries `fallback: true`. `0` restores the legacy empty result.
+2. **CN→EN query expansion** (`queryExpandEnabled`, default on): a 48-term
+   high-frequency intent table appends English synonyms to the search text
+   (search/find, file, image/ocr, database, deploy, schedule…). Only adds
+   terms, never rewrites the original query; exact-name priority still uses
+   the raw query, so precise lookups are byte-identical to v0.2.2.
+3. **Stable results** (`createSearchCache`, 60s TTL / LRU 200): the same query
+   returns the same result set across turns — kills per-turn candidate drift.
+4. **Discovery stats** (`recordDiscoveries`): every found tool is counted and
+   persisted (30s-throttled, merged into tool-folder-state.json); on restart
+   the top-5 are logged so low-discovery tools can be identified and their
+   descriptions improved (Anthropic's "monitor discovery rate" loop).
+5. 83 tests green (11 new: ux module).
+6. Three-axis audit (Standards / Spec / compatibility): 1 P1 fixed — warm and
+   discovery state now merge-write the shared state file instead of clobbering
+   each other; P2 hardening — `tools_search` execute got a whole-body
+   fail-open catch, fallback `total` semantics clarified, comments corrected
+   to process-level scope.
+
+### v0.2.2 — tiered disclosure budget + warm LRU + incremental semantic cache (2026-08-30)
+1. **Tiered disclosure budget** (`disclosureBudget`, default 0 = off): caps how
+   many tool names + descriptions are disclosed per request. Over budget, tools
+   are demoted tier by tier (T2 name+desc → T3 name-only → T4 hidden) instead
+   of being dropped wholesale; core/hot/meta tools stay tier-1 and never demote.
+2. **Warm LRU** (`maxWarmTools`, default 0 = off): recently used tools are kept
+   visible within a bounded LRU, persisted to state so a restart keeps them
+   warm. `0` keeps the exact legacy injection surface.
+3. **Incremental semantic cache**: the bge-m3 embedding cache now diffs by
+   content fingerprint — only docs whose text changed get re-embedded, and a
+   model change rebuilds once. A failed refresh never clobbers a good cache.
+4. **Config persistence**: `lib/storage.js` reads/writes state with a
+   settings → state → memory fallback chain (never touches cordis.patch.yml).
+5. **Explicit fail-open**: `missingMetaTools` gates meta-tool availability —
+   any snapshot oddity returns the full tool list rather than a folded one.
+6. 72 tests green (new: budget 8 / warm 8 / semantic-incremental 5 / storage 7
+   / fail-open 4).
+
 ### v0.2.1 — heat decay + exact-name priority (2026-08-30)
 1. **Hot heat decay** (`hotWindowDays`, default 3): a tool is promoted to
    always-visible only when its call count stays inside the sliding window —

package/lib/budget.js

@@ -0,0 +1,94 @@
+/**
+ * budget.js — 分级披露预算（v0.2.2，借鉴 Letter2025/dsh-tool-search）。
+ *
+ * 现状背景：折叠后工具面大小 = core + hot + 动态 topK(6)，固定裁剪，无预算感知。
+ * 本模块引入 `disclosureBudget`：开启后（>0），当可见工具 schema 的估算字节
+ * 超过预算时，按「溢出降级」：
+
+ *   层级1（默认）  完整 schema（当前行为）
+ *   层级2          name + description（描述压缩至 100 字符）
+ *   层级3          name（一行一个）
+ *   层级4          整组折叠进 catalog（不注入，靠 tools_search 发现）
+
+ * 关键约定（P0 红线）：
+ *   - 降级只作用于「动态段」（dynTools）；core/hot 永不降级（由调用方把
+ *     core+hot 名字传作 protectedNames）。
+ *   - 全部可降级工具按同一全局层级降级（"降级层级"语义）。即使层级 4 仍超预算，
+ *     也绝不降级 protected——预算是对动态段的软约束，core/hot 恒为层级 1。
+ *   - budget <= 0（含 undefined）视为「关闭」，全部返回层级 1（行为不变）。
+ *
+ * 字节估算（本模块的实现选择，写进注释作为契约）：
+ *   - 层级1：JSON.stringify(tool).length（完整 schema 序列化字节数）
+ *   - 层级2：name.length + min(desc,100).length + 2（引号/空格开销）
+ *   - 层级3：name.length + 1（一行一个 name）
+ *   - 层级4：0（折叠进 catalog，本体不注入）
+ * 说明：JSON 序列化（而非 str_len 估算）更贴近实际 token 成本，选它作为层级1
+ * 的主衡准；层级2/3 是压缩形态，直接用字段长度。
+ */
+
+/** 层级 2 描述截断上限 */
+const DESC_CAP = 100;
+
+/**
+ * 估算一批工具在给定层级的注入字节数。
+ * @param {Array<object>} tools  tool defs（含 name/description）
+ * @param {number} tier 1|2|3|4
+ * @returns {number}
+ */
+export function estimateBytes(tools, tier) {
+  let total = 0;
+  for (const t of tools) {
+    if (tier === 1) {
+      try {
+        total += JSON.stringify(t).length;
+      } catch {
+        total += String(t.name || "").length + 4;
+      }
+    } else if (tier === 2) {
+      total += String(t.name || "").length + Math.min(String(t.description || "").length, DESC_CAP) + 2;
+    } else if (tier === 3) {
+      total += String(t.name || "").length + 1;
+    }
+    // tier 4 → 0 字节（不注入）
+  }
+  return total;
+}
+
+/**
+ * 计算可见工具面的降级层级与每工具层级。
+ * @param {Array<object>} visible        折叠后的可见工具（可能已达 core+hot+动态）
+ * @param {number} [budget]              disclosureBudget（<=0 = 关闭）
+ * @param {Set<string>|Array<string>} [protectedNames] core+hot 名字，永不降级
+ * @returns {{tier: number, byName: Record<string, number>}}
+ */
+export function tierForBudget(visible, budget, protectedNames = []) {
+  const list = Array.isArray(visible) ? visible : [];
+  const prot = new Set(Array.isArray(protectedNames) ? protectedNames : Array.from(protectedNames || []));
+  const degrade = list.filter((t) => !prot.has(t.name));
+
+  const byName = {};
+  for (const t of list) byName[t.name] = 1;
+
+  // budget <= 0 = 关闭 → 不降级
+  if (!(budget > 0)) return { tier: 1, byName };
+
+  const protectedTools = list.filter((t) => prot.has(t.name));
+
+  // 无可降级的动态段（全 core/hot）→ 无从降级，恒层级 1
+  if (degrade.length === 0) return { tier: 1, byName };
+
+  // 全量仍在预算内 → 层级 1
+  if (estimateBytes(list, 1) <= budget) return { tier: 1, byName };
+
+  // 从层级 2 起逐级找第一个放得下的层级（层级 4 恒允许——折叠本体不注入）
+  for (let tier = 2; tier <= 3; tier++) {
+    const cost = estimateBytes(protectedTools, 1) + estimateBytes(degrade, tier);
+    if (cost <= budget) {
+      for (const t of degrade) byName[t.name] = tier;
+      return { tier, byName };
+    }
+  }
+  // 层级 4：动态段整体折叠
+  for (const t of degrade) byName[t.name] = 4;
+  return { tier: 4, byName };
+}

package/lib/index.js

@@ -33,7 +33,10 @@ import path from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { buildIndex, search } from "./bm25.js";
 import { compressTool, normalizeDescription, sanitizeLossless } from "./schema.js";
-import { selectionCoverage, isHotTool, prioritizeExact } from "./metrics.js";
+import { selectionCoverage, isHotTool, prioritizeExact, touchWarm, evictWarm, missingMetaTools } from "./metrics.js";
+import { tierForBudget } from "./budget.js";
+import { readState, writeState } from "./storage.js";
+import { expandQuery, fallbackCatalog, createSearchCache, recordDiscoveries, serializeDiscoveries, deserializeDiscoveries } from "./ux.js";
 import { ChainGuard, verdict } from "./chainguard.js";
 import { matchCategory } from "./category.js";
 import { toonifyValue } from "./toonify.js";
@@ -77,6 +80,14 @@ export const Config = z.object({
   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 时使用）"),
+  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)
+    .description("warm LRU 上限：tools_search/schema 发现或折叠后被调用的工具进入 warm 集合，下一轮注入（完整 schema）；达上限逐出最久未用；0=关闭（默认关，无配置升级逐字节等价，显式开启才启用）"),
+  fallbackCatalogSize: z.number().min(0).max(200).default(30)
+    .description("P0: tools_search 零匹配时回退的轻目录条数（name+80字描述，名字典序）；0=关闭回退（返回空=旧行为）"),
+  queryExpandEnabled: z.boolean().default(true)
+    .description("P0: 中文意图→英文同义词扩展（只加词不改原词，扩大 BM25/语义召回；精确名匹配不受影响）"),
 });
 
 const DEFAULTS = {
@@ -111,6 +122,10 @@ const DEFAULTS = {
   semanticEnabled: true, // P0-1: bge-m3 semantic leg for tools_search (RRF hybrid)
   ollamaBase: "http://127.0.0.1:11434",
   embedModel: "bge-m3",
+  disclosureBudget: 0, // v0.2.2: 分级披露预算（0=关闭）
+  maxWarmTools: 0, // v0.2.2: warm LRU 上限（0=关闭，默认关=无配置升级逐字节等价）
+  fallbackCatalogSize: 30, // P0: 零匹配回退轻目录条数（0=关闭）
+  queryExpandEnabled: true, // P0: 中文→英文 query 扩展
 };
 
 function feedbackPath(cfg) {
@@ -282,6 +297,90 @@ export function apply(ctx, config) {
   const disposers = [];
   const chain = new ChainGuard({ window: 30 }); // firewall: exfil-chain + high-risk
 
+  /* ------------------------------------------------------------------ */
+  /* v0.2.2: warm LRU + 配置三级持久化                                    */
+  /* ------------------------------------------------------------------ */
+  // warm：Map<name, {last}>，LRU 顺序由 last 单调递增序号决定。被
+  // tools_search 搜到 / tools_schema 展开 / 折叠后仍被调用的工具进入集合，
+  // 下一轮注入完整 schema。maxWarmTools=0 时整个 warm 失效（仍不 touch）。
+  const warm = new Map();
+  const warmEnabled = cfg.maxWarmTools > 0;
+  const touchWarmNames = (names) => {
+    if (!warmEnabled || !Array.isArray(names) || names.length === 0) return;
+    touchWarm(warm, names, Date.now(), cfg.maxWarmTools);
+    persistWarmState();
+  };
+
+  // 三级持久化：① feedbackPath 同目录（首选）→ ② ~/.dsh/state/ → ③ 进程内。
+  // ⚠️ 绝不写 cordis.patch.yml（宿主配置，插件只读宿主、只落自有 state 文件）。
+  const primaryStateFile = () => path.join(path.dirname(fbPath), "tool-folder-state.json");
+  const fallbackStateFile = () => {
+    const home = process.env.DSH_HOME || process.env.USERPROFILE || process.env.HOME || "";
+    return home ? `${home}/.dsh/state/tool-folder-state.json` : "tool-folder-state.json";
+  };
+  let activeStateFile = primaryStateFile();
+  const restoreWarm = () => {
+    if (!warmEnabled) return; // 关闭态绝不载入磁盘残留（Spec 2: maxWarmTools=0=彻底关闭）
+    let cloud = readState(activeStateFile, null);
+    if (!cloud) {
+      activeStateFile = fallbackStateFile();
+      cloud = readState(activeStateFile, null);
+    }
+    if (cloud && Array.isArray(cloud.warm)) {
+      for (const [name, meta] of cloud.warm) {
+        if (typeof name === "string" && meta && typeof meta.last === "number") {
+          warm.set(name, { last: meta.last });
+        }
+      }
+      evictWarm(warm, cfg.maxWarmTools); // 载入即按上限裁剪
+    }
+  };
+  const persistWarmState = () => {
+    if (!warmEnabled) return;
+    // merge 写：与 discoveries 共用 state 文件，整写会互抹（Standards 轴 P1）。
+    const payload = { ...readState(activeStateFile, {}), warm: [...warm.entries()], ts: Date.now() };
+    let ok = writeState(activeStateFile, payload);
+    if (!ok) {
+      // 首选目录不可写 → 降到 ~/.dsh/state/
+      activeStateFile = fallbackStateFile();
+      writeState(activeStateFile, payload);
+    }
+  };
+  restoreWarm();
+
+  // P0-④: 发现率统计（独立于 warm 门控——maxWarmTools=0 时统计照常工作）。
+  // 与 warm 共用同一个 state 文件；落盘节流 30s（工具输出非注入面，频率低）。
+  let discoveries = new Map();
+  let lastPersistTs = 0;
+  const restoreDiscoveries = () => {
+    let cloud = readState(activeStateFile, null);
+    if (!cloud) {
+      activeStateFile = fallbackStateFile();
+      cloud = readState(activeStateFile, null);
+    }
+    discoveries = deserializeDiscoveries(cloud && Array.isArray(cloud.discoveries) ? cloud.discoveries : null);
+  };
+  const persistDiscoveries = () => {
+    const now = Date.now();
+    if (now - lastPersistTs < 30000) return; // 节流：30s 内只写一次
+    lastPersistTs = now;
+    // merge 写：与 warm 共用 state 文件，整写会互抹（Standards 轴 P1）。
+    const payload = { ...readState(activeStateFile, {}), discoveries: serializeDiscoveries(discoveries), ts: now };
+    let ok = writeState(activeStateFile, payload);
+    if (!ok) {
+      activeStateFile = fallbackStateFile();
+      writeState(activeStateFile, payload);
+    }
+  };
+  restoreDiscoveries();
+  if (discoveries.size > 0) {
+    const top = serializeDiscoveries(discoveries, 5).map((e) => `${e.name}(${e.count})`).join(", ");
+    logger.info("discovery stats restored: %d tools, top: %s", discoveries.size, top);
+  }
+
+  // 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("__");
@@ -382,6 +481,7 @@ export function apply(ctx, config) {
           },
         },
         total: { type: "integer", required: true },
+        fallback: { type: "boolean", description: "true = 零匹配，结果回退为按名字典序的轻目录" },
       },
     };
     const toolsSearch = defineTool({
@@ -403,15 +503,27 @@ export function apply(ctx, config) {
       output: { schema: outputSchema, render: (_a, v) => [{ type: "text", text: JSON.stringify(v, null, 2) }] },
       isConcurrencySafe: () => true,
       async execute(args) {
-        const q = String(args.query || "");
-        const lim = args.limit ?? 8;
-        if (!index || !q) return { query: q, results: [], total: 0 };
+        // 整体 fail-open 兜底（Spec 轴 P2）：任何未来 helper 意外抛错 → 空结果
+        // 而非硬失败，保持"折叠绝不误伤能力"的底线。
+        try {
+          const q = String(args.query || "");
+          const lim = args.limit ?? 8;
+          if (!index) return { query: q, results: [], total: 0 };
+        // P0-②: 同 query 内容指纹的结果缓存——重复搜索返回同一结果集（漂移的
+        // 最小修）。进程级共享（非单会话隔离）；空 query（"*" 语义）不走缓存。
+        const cacheKey = `${lim}|${q}`;
+        if (q) {
+          const cached = searchCache.get(cacheKey);
+          if (cached) return cached;
+        }
+        // P0-③: 中文意图→英文同义词扩展（只加词不改原词；精确名匹配用原 q）。
+        const eq = cfg.queryExpandEnabled !== false ? expandQuery(q) : q;
         // v0.2.1: exact-name > name-substring > BM25 priority (deterministic
         // fallback chain, borrowed from Hermes-style tool search).
         const bm25Hits = prioritizeExact(
           allTools,
           q,
-          search(index, q, lim * 2).map((i) => ({ id: allTools[i].name })),
+          search(index, eq, lim * 2).map((i) => ({ id: allTools[i].name })),
         );
         let fused = bm25Hits;
         // Semantic leg (P0-1): RRF-fuse BM25 with local bge-m3 similarity.
@@ -422,7 +534,7 @@ export function apply(ctx, config) {
             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, q);
+              const semHits = await searchSemantic(sem.vectors, docs, eq);
               fused = rrfFuse(bm25Hits, semHits.slice(0, lim * 2), lim);
             }
           } catch (e) {
@@ -430,18 +542,39 @@ export function apply(ctx, config) {
           }
         }
         const byName = new Map(allTools.map((t) => [t.name, t]));
-        return {
+        let results = fused.map((h) => {
+          const t = byName.get(h.id) || {};
+          return {
+            name: h.id,
+            description: (t.description || "").slice(0, 160),
+            server: serverOf(h.id),
+          };
+        });
+        // P0-①: 零匹配回退轻目录（name+80字描述，名字典序）——根治「搜词不对
+        // 就以为没有该能力」。fallbackCatalogSize=0 关闭（返回空=旧行为）。
+        // total 在回退时=全量目录大小（而非列出条数），避免模型误以为目录总容量=limit。
+        let fallback = false;
+        if (results.length === 0 && cfg.fallbackCatalogSize > 0) {
+          results = fallbackCatalog(allTools, cfg.fallbackCatalogSize, serverOf);
+          fallback = true;
+        }
+        // v0.2.2: 被搜到的工具名进入 warm 集合，下一轮注入完整 schema。
+        touchWarmNames(results.map((r) => r.name));
+        // P0-④: 发现率统计（节流落盘，低频工具名单反哺描述改进）。
+        recordDiscoveries(discoveries, results.map((r) => r.name));
+        persistDiscoveries();
+        const out = {
           query: q,
-          results: fused.map((h) => {
-            const t = byName.get(h.id) || {};
-            return {
-              name: h.id,
-              description: (t.description || "").slice(0, 160),
-              server: serverOf(h.id),
-            };
-          }),
-          total: fused.length,
+          results,
+          total: fallback ? allTools.length : results.length,
+          ...(fallback ? { fallback: true } : {}),
         };
+        if (q) searchCache.set(cacheKey, out);
+        return out;
+        } catch (e) {
+          logger.warn("tools_search failed (%s) — empty results", e?.message);
+          return { query: String(args.query || ""), results: [], total: 0 };
+        }
       },
     });
     try {
@@ -484,6 +617,8 @@ export function apply(ctx, config) {
         const name = String(args?.name || "");
         const t = allTools.find((x) => x.name === name);
         if (!t) return { name, found: false, reason: "unknown tool" }; // never throw
+        // v0.2.2: 展开过 schema 的工具名进入 warm 集合，下一轮保持注入。
+        touchWarmNames([name]);
         return {
           name: t.name,
           found: true,
@@ -564,6 +699,11 @@ export function apply(ctx, config) {
       const query = extractQuery(context);
       const dynNames = buildDynamicSet(tools, query);
 
+      // v0.2.2: warm 集合名（只取当前工具池里存在的，避免引用已不存在的工具）。
+      const warmNamesSet = new Set(
+        [...warm.keys()].filter((n) => tools.some((t) => t.name === n)),
+      );
+
       // L5: stable ordering — core by config order, hot by name, dyn by name.
       // A deterministic byte order keeps the prompt prefix cacheable.
       const coreTools = tools.filter((t) => coreNames.has(t.name));
@@ -575,12 +715,24 @@ export function apply(ctx, config) {
           (t) =>
             !coreNames.has(t.name) &&
             !hotNames.has(t.name) &&
+            !warmNamesSet.has(t.name) &&
             dynNames.has(t.name),
         )
         .sort((a, b) => (a.name < b.name ? -1 : 1));
 
+      // v0.2.2: warm = 上一轮被 tools_search/schema 发现或折叠后被调用的工具。
+      // 属主动晋升（接近 hot），完整 schema 注入，不作为 budget 可降级段。
+      const warmTools = tools
+        .filter(
+          (t) =>
+            !coreNames.has(t.name) &&
+            !hotNames.has(t.name) &&
+            warmNamesSet.has(t.name),
+        )
+        .sort((a, b) => (a.name < b.name ? -1 : 1));
+
       // L1: schema compression + description normalization on the dynamic
-      // segment only. core/hot never pass through this pipe (P0 red line).
+      // segment only. core/hot/warm never pass through this pipe (P0 red line).
       const trimmed =
         effectiveLevel !== "off" || cfg.normalizeDescriptions
           ? dynTools.map((t) => {
@@ -594,7 +746,40 @@ export function apply(ctx, config) {
             })
           : dynTools;
 
-      const visible = [...coreTools, ...hotTools, ...trimmed];
+      // v0.2.2 分级披露预算：动态段（trimmed）是唯一可降级段。core/hot/warm
+      // 作为 protected 恒层级 1。tierForBudget 返回每个可见名字的降级层级；
+      // 层级 2/3 组装压缩形态，层级 4 不再注入（由 catalog 兜底发现）。
+      let visible = [...coreTools, ...hotTools, ...warmTools, ...trimmed];
+      if (cfg.disclosureBudget > 0) {
+        const protectedNames = new Set([
+          ...coreNames,
+          ...hotNames,
+          ...warmNamesSet,
+          // meta 工具永远完整可见
+          "tools_search",
+          "tools_schema",
+        ]);
+        const tiers = tierForBudget(visible, cfg.disclosureBudget, protectedNames);
+        // Effective budget = min(disclosureBudget, context estimate). We do not
+        // separately measure context here, so the hard disclosureBudget stands.
+        // Rebuild visible honoring per-tool tiers (they are already ordered).
+        visible = visible.map((t) => {
+          const tier = tiers.byName[t.name] || 1;
+          if (tier === 1) return t; // 完整 schema
+          if (tier === 2) {
+            // name + description（描述压缩至 100 字符）
+            return {
+              name: t.name,
+              description: String(t.description || "").slice(0, 100),
+            };
+          }
+          if (tier === 3) {
+            // 仅 name（一行一个）
+            return { name: t.name };
+          }
+          return null; // 层级 4：折叠进 catalog，不注入
+        }).filter(Boolean);
+      }
 
       // The meta-tools must always stay visible or the model can never ask
       // for folded tools (they would be hidden by their own fold).
@@ -609,6 +794,21 @@ export function apply(ctx, config) {
         }
       }
 
+      // v0.2.2 fail-open 硬保证（借鉴 fan56/dsh-mcp-adapter）：启用的发现
+      // 元工具仍缺失（注册失败/名冲突/部分启动）→ 折叠后工具不可发现，
+      // 比不折叠更糟——显式回退官方全量工具列表，绝不静默吞掉发现路径。
+      const missingMeta = missingMetaTools(
+        new Set(visible.map((t) => t.name)),
+        { tools_search: cfg.toolSearchEnabled, tools_schema: cfg.schemaToolEnabled },
+      );
+      if (missingMeta.length > 0) {
+        logger.warn(
+          "fail-open: meta tool(s) %s missing after fold — falling back to full tool list",
+          missingMeta.join(","),
+        );
+        return next();
+      }
+
       const visibleNames = visible.map((t) => t.name);
       lastVisible = { agentId, names: visibleNames, ts: Date.now() };
 
@@ -619,6 +819,7 @@ export function apply(ctx, config) {
             !isMetaTool(t.name) &&
             !coreNames.has(t.name) &&
             !hotNames.has(t.name) &&
+            !warmNamesSet.has(t.name) &&
             !dynNames.has(t.name),
         );
         if (folded.length > 0) {
@@ -717,6 +918,8 @@ export function apply(ctx, config) {
             "folded tools called (coverage=%.2f): %s — promoting via heat",
             cov.coverage, cov.uncovered.join(", "),
           );
+          // v0.2.2: 折叠后仍被调用的工具名也进 warm，下一轮避免再折叠。
+          touchWarmNames(cov.uncovered);
         }
 
         // L3: record the last 50 sessions for offline evaluation.

package/lib/metrics.js

@@ -60,6 +60,24 @@ export function selectionCoverage(visibleNames, calledNames) {
   };
 }
 
+/**
+ * Fail-open gate (v0.2.2, borrowed from fan56/dsh-mcp-adapter): the discovery
+ * meta-tools must be visible or folded tools become undiscoverable — which is
+ * worse than not folding at all. Returns the names of ENABLED meta-tools that
+ * are missing from the visible set (registration failure / name conflict).
+ * @param {Set<string>|Array<string>} visibleNames - names in the folded surface.
+ * @param {object} enabled - { toolName: boolean } enabled flags.
+ * @returns {string[]} missing enabled meta-tool names ([] = all present).
+ */
+export function missingMetaTools(visibleNames, enabled) {
+  const vis = visibleNames instanceof Set ? visibleNames : new Set(visibleNames || []);
+  const out = [];
+  for (const [n, on] of Object.entries(enabled || {})) {
+    if (on && !vis.has(n)) out.push(n);
+  }
+  return out;
+}
+
 /**
  * Hot-promotion gate with sliding-window decay (v0.2.1).
  * feedback.calls entries may be:
@@ -87,6 +105,69 @@ export function isHotTool(calls, name, hotThreshold, windowMs) {
   return true;
 }
 
+/* ------------------------------------------------------------------ */
+/* warm LRU 预热集合（v0.2.2，借鉴 Letter2025/dsh-tool-search）        */
+/*                                                                    */
+/* 现状背景：折叠后模型用 tools_search / tools_schema 发现工具，但发现 */
+/* 后该 schema 不保留在注入面，下一轮又折叠。warm 集合把「被搜到的」   */
+/* 「被展开 schema 的」「被折叠却仍被调用的」工具名暂存进一个进程内    */
+/* LRU Map，下一轮注入（完整或按当前降级层级）。                       */
+/*                                                                    */
+/* 数据结构：Map<name, { last: number }>——last 单调递增（用毫秒时间   */
+/* 戳或调用方给的递增序号），LRU 即按 last 升序逐出最久未用。注意      */
+/* Map 的自身插入序不可用作 LRU 序（Map 本身有序，但 touch 已存在键    */
+/* 不改变插入位置），显式 last 字段才是判据。                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * 把一组名字 touch 进 warm 集合。已存在则刷新 last（置为最新，不重复），
+ * 不存在则新增。可随 last 一起把上限也一次收进来——调用方可在此后自行
+ * evictWarm，或依赖后续 evictWarm。
+ * @param {Map<string,{last:number}>} warm  进程内 warm Map
+ * @param {Array<string>} names
+ * @param {number} now  单调递增时钟（如 Date.now()）
+ * @param {number} [max]  可选：touch 后若超限自动逐出
+ */
+export function touchWarm(warm, names, now, max) {
+  const list = Array.isArray(names) ? names.filter(Boolean) : [];
+  for (const n of list) {
+    // 用「单调递增序号 = max(now, 上一次+1)」保证同一批内/跨批绝不并列：
+    // 每次 touch 都取得严格大于 warm 里现有最大 last 的序号，LRU 判据稳定。
+    let next = now;
+    for (const v of warm.values()) {
+      if (typeof v === "object" && typeof v.last === "number" && v.last >= next) next = v.last + 1;
+    }
+    warm.set(n, { last: next });
+  }
+  if (typeof max === "number" && max > 0 && warm.size > max) evictWarm(warm, max);
+}
+
+/**
+ * 逐出最久未用直到 size <= max。max<=0 = 关闭（不逐出）。
+ * @param {Map<string,{last:number}>} warm
+ * @param {number} max
+ * @returns {Array<string>} 被逐出的名字（仅信息用途）
+ */
+export function evictWarm(warm, max) {
+  const evicted = [];
+  if (!(max > 0)) return evicted;
+  while (warm.size > max) {
+    let oldest = null;
+    let oldestLast = Infinity;
+    for (const [name, v] of warm) {
+      const l = v && typeof v.last === "number" ? v.last : 0;
+      if (l < oldestLast) {
+        oldestLast = l;
+        oldest = name;
+      }
+    }
+    if (oldest == null) break;
+    warm.delete(oldest);
+    evicted.push(oldest);
+  }
+  return evicted;
+}
+
 /**
  * Deterministic retrieval priority (v0.2.1, borrowed from Hermes-style
  * "exact name > name token > description" fallback chains): the query's

package/lib/obfuscation.js

@@ -111,14 +111,3 @@ export function detectObfuscation(rawText, cleanText) {
   }
   return null;
 }
-
-/**
- * Combined check used by verdict(): returns the first obfuscation hit, or
- * null when the text looks clean.
- */
-export function checkObfuscation(text) {
-  const raw = String(text || "");
-  if (!raw) return null;
-  const clean = deobfuscate(raw);
-  return detectObfuscation(raw, clean);
-}

package/lib/semantic.js

@@ -23,6 +23,8 @@ const EMBED_TIMEOUT_MS = 8000;
 const CACHE_FILE = ".dsh/state/semantic-cache.json";
 
 import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
 
 /* ------------------------------------------------------------------ */
 /* hash + fs helpers (all fail-safe)                                   */
@@ -39,13 +41,25 @@ function hash(text) {
   return h.toString(16).padStart(8, "0");
 }
 
+/** sha1 hex — per-doc content fingerprint for incremental diff (v0.2.2). */
+function sha1(text) {
+  try {
+    return crypto.createHash("sha1").update(String(text || ""), "utf8").digest("hex");
+  } catch {
+    return hash(text); // node:crypto 不可用时的降级指纹
+  }
+}
+
 function homeDir() {
   return process.env.USERPROFILE || process.env.HOME || "";
 }
 
-function readCacheFile() {
+function defaultCachePath() {
+  return homeDir() + "/" + CACHE_FILE;
+}
+
+function readCacheFileAt(p) {
   try {
-    const p = homeDir() + "/" + CACHE_FILE;
     if (!p || !fs.existsSync(p)) return null;
     const raw = fs.readFileSync(p, "utf8");
     const j = JSON.parse(raw);
@@ -56,11 +70,10 @@ function readCacheFile() {
   return null;
 }
 
-function writeCacheFile(obj) {
+function writeCacheFileAt(p, obj) {
   try {
-    const p = homeDir() + "/" + CACHE_FILE;
-    const dir = p.slice(0, p.lastIndexOf("/"));
-    fs.mkdirSync(dir, { recursive: true });
+    if (!p) return;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(obj), "utf8");
   } catch {
     /* cache write is best-effort */
@@ -131,52 +144,82 @@ export function cosine(a, b) {
 /* ------------------------------------------------------------------ */
 
 /**
- * Build a semantic index over docs. Doc embeddings come from the on-disk
- * cache when the fingerprint matches; otherwise they are computed once and
- * persisted. Never blocks forever: total batch time is bounded and a failure
- * returns an index whose vectors are simply empty (lexical leg still works).
+ * Build a semantic index over docs with content-fingerprint incremental diff
+ * (v0.2.2). Doc embeddings come from the on-disk cache when the per-doc
+ * fingerprint (sha1 of id+text) matches; otherwise they are recomputed and
+ * the cache is patched incrementally — tools that didn't change are never
+ * re-embedded (the old code rebuilt the whole index on any set change).
+ *
+ * Any failure returns an index whose vectors are simply empty (lexical leg
+ * still works). Short-circuits on an overall deadline and only persists the
+ * cache on full success, so a half-built/offline run can never corrupt the
+ * prior cache.
  *
  * @param {Array<{id: string, text: string}>} docs
  * @param {number} [timeoutMs] per-embed timeout
+ * @param {{embed?: Function, cacheFile?: string}} [opts]
+ *   - embed:      injectable embedding fn(text, timeoutMs)->vector|null (tests);
+ *                 defaults to embedText (real Ollama).
+ *   - cacheFile:  explicit cache path (tests use a temp file; never touch the
+ *                 real ~/.dsh/state unless omitted).
  * @returns {Promise<{vectors: Map<string, number[]>, available: boolean}>}
  */
-export async function buildSemanticIndex(docs, timeoutMs = EMBED_TIMEOUT_MS) {
+export async function buildSemanticIndex(docs, timeoutMs = EMBED_TIMEOUT_MS, opts = {}) {
   const out = { vectors: new Map(), available: false };
   const list = Array.isArray(docs) ? docs.filter((d) => d && d.id && d.text) : [];
   if (list.length === 0) return out;
 
-  // Fast path: cache hit.
-  const fp = hash(list.map((d) => d.id + "\u0000" + d.text).join("\u0001"));
-  const cache = readCacheFile();
-  const cached = cache && cache.fp === fp && cache.vec && typeof cache.vec === "object" ? cache.vec : null;
-  if (cached) {
-    for (const d of list) {
-      const v = cached[d.id];
-      if (Array.isArray(v) && v.length > 0) out.vectors.set(d.id, v);
-    }
-    if (out.vectors.size === list.length) {
-      out.available = true;
-      return out;
-    }
-  }
+  const embed = typeof opts.embed === "function" ? opts.embed : embedText;
+  const cachePath = opts.cacheFile || defaultCachePath();
+
+  // Per-doc content fingerprint: sha1 of id+text (name+description). A doc
+  // whose text changed gets a new fp → only that doc is re-embedded.
+  const fpOf = (d) => sha1(d.id + "\u0000" + d.text);
+
+  const cache = readCacheFileAt(cachePath);
+  // Liveness/lock: cache is only reusable if the provider/model that produced
+  // it equals the currently configured ones. Any mismatch (or old whole-index
+  // format, which has no .model) → full invalidation reconstruction.
+  const modelMatch =
+    cache && cache.model &&
+    cache.model.model === _model && cache.model.base === _base &&
+    cache.docs && typeof cache.docs === "object";
+  const cachedDocs = modelMatch ? cache.docs : null;
 
-  // Miss: embed each doc (sequential — CPU-bound local model, avoids
-  // overloading Ollama), bounded by an overall deadline.
+  // Embed every doc whose fingerprint misses the cache; reuse cached vectors.
+  const fresh = {}; // id -> vector, only for newly embedded
   const deadline = Date.now() + 60_000;
-  const fresh = {};
-  let ok = 0;
   for (const d of list) {
     if (Date.now() > deadline) break;
-    const v = await embedText(d.text, timeoutMs);
-    if (v) {
-      fresh[d.id] = v;
-      out.vectors.set(d.id, v);
-      ok++;
+    let v = null;
+    if (cachedDocs) {
+      const hit = cachedDocs[fpOf(d)];
+      if (hit && Array.isArray(hit.vec) && hit.vec.length > 0 && hit.id === d.id) {
+        v = hit.vec; // unchanged → reuse cache, zero Ollama calls
+      }
     }
+    if (!v) {
+      v = await embed(d.text, timeoutMs);
+      if (v) fresh[d.id] = v;
+    }
+    if (v) out.vectors.set(d.id, v);
   }
-  if (ok === list.length) {
+
+  if (out.vectors.size === list.length) {
     out.available = true;
-    writeCacheFile({ fp, vec: fresh }); // persist only on full success
+    // Rebuild the docs map: keep reusable cached entries + newly embedded,
+    // dropping docs no longer in `list` (tool removal handled by set change).
+    const newDocs = {};
+    for (const d of list) {
+      const fp = fpOf(d);
+      const hit = cachedDocs && cachedDocs[fp];
+      if (hit && Array.isArray(hit.vec) && hit.vec.length > 0) {
+        newDocs[fp] = { id: d.id, vec: hit.vec };
+      } else if (fresh[d.id]) {
+        newDocs[fp] = { id: d.id, vec: fresh[d.id] };
+      }
+    }
+    writeCacheFileAt(cachePath, { model: { base: _base, model: _model }, docs: newDocs });
   }
   return out;
 }

package/lib/storage.js

@@ -0,0 +1,54 @@
+/**
+ * storage.js — 插件自有配置状态的 JSON 持久化原语（v0.2.2，借鉴 Minecraftbe/dsh-toolfold）。
+ *
+ * 现状背景：插件持有 warm 集合、上次折叠统计等自有状态，但此前无处可靠落盘。
+ * 语义缓存已落盘 `~/.dsh/state/`，本模块提供通用的 read/write JSON 原语，
+ * 供 index.js 实现「三级持久化」降级：
+ *
+ *   1. `~/.dsh/settings.yaml`（或 feedbackPath 同目录）
+ *   2. `~/.dsh/state/`
+ *   3. 进程内（最后兜底）
+ *
+ * 本模块只做一件事：对单个 JSON 文件的健壮读写。任何文件系统异常都以
+ * 「降级返回值」处理，绝不向调用方抛错——持久化失败不等于插件崩溃。
+ * ⚠️ 不碰 cordis.patch.yml：那是宿主配置，插件从不写。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 把 data 以 JSON 落盘到 file（自动创建父目录）。
+ * @param {string} file  目标文件绝对路径
+ * @param {unknown} data  可 JSON 序列化的值
+ * @returns {boolean} true = 已写入；false = 任何失败（调用方降级到下一级存储）
+ */
+export function writeState(file, data) {
+  if (!file) return false;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data), "utf8");
+    return true;
+  } catch {
+    return false; // 目录不可写 / 权限 / 磁盘满 → 降级
+  }
+}
+
+/**
+ * 从 file 读取 JSON；任何失败（不存在/损坏/无权限/非对象）都返回 def。
+ * @param {string} file
+ * @param {unknown} def  默认值（读失败时的兜底）
+ * @returns {unknown} 解析出的值（独立副本）或 def
+ */
+export function readState(file, def) {
+  if (!file) return def;
+  try {
+    if (!fs.existsSync(file)) return def;
+    const raw = fs.readFileSync(file, "utf8");
+    const j = JSON.parse(raw);
+    if (j && typeof j === "object") return JSON.parse(JSON.stringify(j)); // 独立副本
+    return def;
+  } catch {
+    return def; // 损坏 JSON / 权限 → 默认值降级
+  }
+}

package/lib/ux.js

@@ -0,0 +1,178 @@
+/**
+ * ux.js — P0 折叠体验改进（2026-08-30 第二轮调研落地，来源见 AGENTS.md §0.3）。
+ *
+ * 四个纯函数/工厂，全部不触碰注入面（每轮 prompt 字节零变化，兼容红线保持）：
+ *   ① expandQuery       中文高频意图 → 追加英文检索词（只加词不改原词；BM25 召回
+ *                        更宽，精确名匹配 prioritizeExact 仍用原 query，不受影响）
+ *   ② fallbackCatalog   tools_search 零匹配时回退的全量轻目录（name + 80 字描述，
+ *                        按名字典序稳定排序）——根治「搜词不对就以为没有」
+ *   ③ createSearchCache 同 query 内容指纹的结果缓存（固定 TTL + LRU 上限）——
+ *                        同会话重复搜索返回同一结果集（漂移的最小修）
+ *   ④ recordDiscoveries 发现率统计（name→count，落盘可恢复）——低频工具名单
+ *                        反哺描述改进（官方「监控发现率」建议的本地等价物）
+ */
+
+/* ------------------------- ① query 扩展词表 ------------------------- */
+
+/** 中文高频意图 → 英文检索词。只做「包含即追加」，不做分词/替换。 */
+const EXPAND = {
+  搜索: "search find lookup",
+  查找: "search find lookup",
+  文件: "file files read write edit",
+  图片: "image picture photo vision ocr",
+  截图: "screenshot screen capture image",
+  识别: "ocr recognize extract text",
+  文字: "text ocr recognize",
+  数据库: "database db sql query",
+  查询: "query select fetch search",
+  网络: "network web http fetch url",
+  浏览器: "browser chrome page navigate",
+  下载: "download fetch get",
+  上传: "upload put push",
+  发布: "publish deploy release",
+  部署: "deploy release publish",
+  测试: "test run verify",
+  运行: "run execute start",
+  执行: "run execute command",
+  命令: "command shell exec terminal",
+  安装: "install setup configure",
+  配置: "config configure setup",
+  错误: "error fail exception debug",
+  修复: "fix repair patch debug",
+  删除: "delete remove rm",
+  创建: "create new make init",
+  修改: "edit update modify change",
+  查看: "view show list inspect read",
+  列表: "list enumerate show",
+  记忆: "memory remember recall viking",
+  技能: "skill search catalog",
+  工具: "tool search schema",
+  定时: "schedule cron timer",
+  提醒: "remind schedule alert",
+  邮件: "email mail send",
+  键盘: "keyboard type input",
+  鼠标: "mouse click move",
+  窗口: "window open close",
+  进程: "process task list kill",
+  服务: "service server daemon",
+  日志: "log trace tail",
+  监控: "monitor watch observe",
+  版本: "version release tag git",
+  提交: "commit push git",
+  分支: "branch git merge",
+  仓库: "repo repository git",
+  会话: "session agent",
+  对话: "chat session message",
+};
+
+/**
+ * 中文意图 → 扩展查询串：命中的每个中文词追加其英文同义词组到尾部。
+ * 无中文（或词表未命中）时原样返回——旧行为零变化。
+ * @param {string} q
+ * @returns {string}
+ */
+export function expandQuery(q) {
+  const s = String(q || "").trim();
+  if (!s) return s;
+  const extra = [];
+  for (const [cn, en] of Object.entries(EXPAND)) {
+    if (s.includes(cn)) extra.push(en);
+  }
+  return extra.length ? `${s} ${extra.join(" ")}` : s;
+}
+
+/* ------------------------- ② 零匹配回退轻目录 ------------------------- */
+
+/**
+ * 轻目录：按名字典序排序取前 limit 个（name + 描述截 80 + server）。
+ * limit<=0 → []（关闭回退，行为与旧版一致）。
+ * @param {Array<{name:string,description?:string}>} allTools
+ * @param {number} limit
+ * @param {(name:string)=>string} [serverOf]
+ * @returns {Array<{name:string,description:string,server:string}>}
+ */
+export function fallbackCatalog(allTools, limit, serverOf) {
+  const lim = Math.max(0, Number(limit) || 0);
+  if (!lim || !Array.isArray(allTools) || allTools.length === 0) return [];
+  const svc = typeof serverOf === "function" ? serverOf : () => "";
+  return [...allTools]
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)))
+    .slice(0, lim)
+    .map((t) => ({
+      name: String(t.name || ""),
+      description: String(t.description || "").slice(0, 80),
+      server: svc(t.name),
+    }));
+}
+
+/* ------------------------- ③ 检索结果缓存 ------------------------- */
+
+/**
+ * 结果缓存工厂：同 key 在 TTL 内返回同一结果（确定性），超 TTL 或超上限逐出。
+ * @param {number} [maxSize]  LRU 上限（默认 200）
+ * @param {number} [ttlMs]    有效期（默认 60s）
+ */
+export function createSearchCache(maxSize = 200, ttlMs = 60000) {
+  const map = new Map();
+  return {
+    get(key) {
+      const e = map.get(key);
+      if (!e) return null;
+      if (Date.now() - e.ts > ttlMs) {
+        map.delete(key);
+        return null;
+      }
+      return e.value;
+    },
+    set(key, value) {
+      map.set(key, { ts: Date.now(), value });
+      if (map.size > maxSize) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined) map.delete(oldest);
+      }
+    },
+    size() {
+      return map.size;
+    },
+  };
+}
+
+/* ------------------------- ④ 发现率统计 ------------------------- */
+
+/**
+ * 记录一次发现的工具名（name→count）。
+ * @param {Map<string,number>} stats
+ * @param {Array<string>} names
+ * @returns {number} 当前去重工具数
+ */
+export function recordDiscoveries(stats, names) {
+  const list = Array.isArray(names) ? names.filter(Boolean) : [];
+  for (const n of list) stats.set(n, (stats.get(n) || 0) + 1);
+  return stats.size;
+}
+
+/**
+ * 序列化为按 count 降序的数组（cap 截断），供落盘。
+ * @param {Map<string,number>} stats
+ * @param {number} [cap]
+ */
+export function serializeDiscoveries(stats, cap = 200) {
+  return [...stats.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, Math.max(1, cap))
+    .map(([name, count]) => ({ name, count }));
+}
+
+/**
+ * 从落盘数组恢复 Map；坏条目跳过（fail-safe）。
+ * @param {Array<{name:string,count:number}>} [list]
+ */
+export function deserializeDiscoveries(list) {
+  const m = new Map();
+  for (const e of list || []) {
+    if (e && typeof e.name === "string" && e.name.length > 0 && Number.isFinite(e.count) && e.count > 0) {
+      m.set(e.name, e.count);
+    }
+  }
+  return m;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-tool-folder",
-    "version":  "0.2.1",
+    "version":  "0.2.3",
     "description":  "Fold the DSH tool surface per request + ChainGuard firewall (high-risk block + exfil-chain detection + anti-obfuscation) + BM25/bge-m3 hybrid tools_search. Shrinks schema tokens 80-90% while keeping selection accuracy. v0.2.0 adds a semantic retrieval leg (local Ollama bge-m3, RRF hybrid) and ChainGuard obfuscation detection (concat-rebuild / -enc / certutil / bitsadmin / homoglyphs).",
     "keywords":  [
                      "dsh-plugin",