dsh-tool-folder 0.2.0 → 0.2.2

package/README.md

@@ -149,6 +149,37 @@ were never unregistered, so nothing else changes.
 
 ## Changelog
 
+### 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 —
+   the old code promoted forever, so any tool used 3 times was permanently
+   resident and the fold silently decayed to zero over time. Legacy
+   `feedback.json` number entries are read as out-of-window → their stale
+   heat expires naturally. Set `hotWindowDays: 0` to keep the old behavior.
+2. **Exact-name priority in `tools_search`**: exact tool-name match always
+   ranks first, a ≥4-char query that is a name substring is pulled ahead of
+   BM25/semantic hits (deterministic fallback chain). Results stay
+   deduplicated.
+3. 40 tests green (11 new: window decay / legacy compat / priority order).
+
 ### v0.2.0 — first npm release (2026-08-30)
 This is the first version published to npm. It bundles the v0.1.7 firewall
 scope fix (exec-only hard block) and the v0.1.8 semantic leg +

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,9 @@ 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 } 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 { ChainGuard, verdict } from "./chainguard.js";
 import { matchCategory } from "./category.js";
 import { toonifyValue } from "./toonify.js";
@@ -59,6 +61,8 @@ export const Config = z.object({
   deny: z.array(z.string()).default([]).description("禁用工具：精确名或 prefix* 前缀，命中不注入+拒绝执行"),
   topK: z.number().min(0).max(50).default(6).description("BM25 动态检索每轮最多注入的工具数"),
   hotThreshold: z.number().min(1).default(3).description("被折叠工具调用几次后自动晋升为常驻"),
+  hotWindowDays: z.number().min(0).max(365).default(3)
+    .description("hot 热度的滑动窗口（天）：窗口内达标才常驻，超窗自动衰减；0=永不过期"),
   catalogEnabled: z.boolean().default(true).description("折叠安全网：把被藏工具列表写进提示词，模型知道它们存在"),
   compressLevel: z.union(COMPRESS_LEVELS).default("off").description("L1 schema 压缩级别：off 不压缩 / light 裁描述 / standard 裁描述+参数说明 / aggressive 删可选参数"),
   compressEnabled: z.boolean().default(false).description("兼容开关：compressLevel=off 且此开=true 时按 standard 处理"),
@@ -75,6 +79,10 @@ 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=关闭（默认关，无配置升级逐字节等价，显式开启才启用）"),
 });
 
 const DEFAULTS = {
@@ -84,6 +92,7 @@ const DEFAULTS = {
   deny: [], // never inject + refuse execution (exact name or "prefix*")
   topK: 6,
   hotThreshold: 3,
+  hotWindowDays: 3, // v0.2.1: sliding-window heat decay (0 = never expire)
   catalogEnabled: true, // safety net: folded tools stay discoverable by name
   compressEnabled: false, // deprecated compat: compressLevel "off" + true → "standard"
   compressLevel: "off", // "off" | "light" | "standard" | "aggressive"
@@ -108,6 +117,8 @@ 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=关闭，默认关=无配置升级逐字节等价）
 };
 
 function feedbackPath(cfg) {
@@ -279,6 +290,56 @@ 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;
+    const payload = { warm: [...warm.entries()], ts: Date.now() };
+    let ok = writeState(activeStateFile, payload);
+    if (!ok) {
+      // 首选目录不可写 → 降到 ~/.dsh/state/
+      activeStateFile = fallbackStateFile();
+      writeState(activeStateFile, payload);
+    }
+  };
+  restoreWarm();
+
   // "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("__");
@@ -403,7 +464,13 @@ export function apply(ctx, config) {
         const q = String(args.query || "");
         const lim = args.limit ?? 8;
         if (!index || !q) return { query: q, results: [], total: 0 };
-        const bm25Hits = search(index, q, lim * 2).map((i) => ({ id: allTools[i].name }));
+        // 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 })),
+        );
         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
@@ -421,16 +488,19 @@ export function apply(ctx, config) {
           }
         }
         const byName = new Map(allTools.map((t) => [t.name, t]));
+        const results = fused.map((h) => {
+          const t = byName.get(h.id) || {};
+          return {
+            name: h.id,
+            description: (t.description || "").slice(0, 160),
+            server: serverOf(h.id),
+          };
+        });
+        // v0.2.2: 被搜到的工具名进入 warm 集合，下一轮注入完整 schema。
+        touchWarmNames(results.map((r) => r.name));
         return {
           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),
-            };
-          }),
+          results,
           total: fused.length,
         };
       },
@@ -475,6 +545,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,
@@ -519,10 +591,12 @@ export function apply(ctx, config) {
 
       const agentId = context?.agent?.id || "default";
       const coreNames = new Set(cfg.perAgent?.[agentId]?.core || cfg.core || []);
+      // v0.2.1: hot = sliding-window decay (hotWindowDays). Tools not called
+      // inside the window lose their historical heat — the old code promoted
+      // forever, which slowly nullified the fold.
       const hotNames = new Set(
-        Object.entries(feedback.calls || {})
-          .filter(([, c]) => c >= cfg.hotThreshold)
-          .map(([n]) => n),
+        Object.keys(feedback.calls || {}).filter((n) =>
+          isHotTool(feedback.calls, n, cfg.hotThreshold, cfg.hotWindowDays * 86400000)),
       );
 
       const stamp = tools.map((t) => t.name).join("\u0001");
@@ -553,6 +627,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));
@@ -564,12 +643,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) => {
@@ -583,7 +674,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).
@@ -598,6 +722,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() };
 
@@ -608,6 +747,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) {
@@ -673,8 +813,14 @@ export function apply(ctx, config) {
           });
         }
 
-        // Heat counting (L4 feedback).
-        feedback.calls[name] = (feedback.calls[name] || 0) + 1;
+        // Heat counting (L4 feedback). v0.2.1: upgrade to { n, ts } so the
+        // hot gate can decay stale heat; legacy number entries are kept
+        // readable by isHotTool (ts=0 → outside any positive window).
+        const prev = feedback.calls[name];
+        feedback.calls[name] = {
+          n: (typeof prev === "number" ? prev : prev?.n || 0) + 1,
+          ts: Date.now(),
+        };
 
         // Firewall: record the call sequence and flag exfil chains.
         if (cfg.firewallEnabled !== false) {
@@ -700,6 +846,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

@@ -59,3 +59,149 @@ export function selectionCoverage(visibleNames, calledNames) {
     uncovered,
   };
 }
+
+/**
+ * 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:
+ *   - new shape { n, ts } — n calls, ts = last call epoch ms;
+ *   - legacy shape (number) — pre-v0.2.1 counts with no timestamp.
+ * A tool is hot when n >= hotThreshold AND (windowMs <= 0 OR the last call
+ * is inside the window). Legacy numbers carry ts=0 → outside any positive
+ * window → not hot (a tool that hasn't been called since the upgrade
+ * naturally loses its historical heat — this is the decay the old code
+ * lacked). windowMs=0 keeps the legacy forever-hot behavior for opt-out.
+ * @param {object|null} calls - feedback.calls map.
+ * @param {string} name - tool name.
+ * @param {number} hotThreshold - min calls to be hot.
+ * @param {number} windowMs - decay window; <=0 disables time checks.
+ * @returns {boolean}
+ */
+export function isHotTool(calls, name, hotThreshold, windowMs) {
+  if (!calls || typeof calls !== "object") return false;
+  const v = calls[name];
+  if (v == null) return false;
+  const n = typeof v === "number" ? v : v.n;
+  const ts = typeof v === "number" ? 0 : v.ts;
+  if (!(n >= hotThreshold)) return false;
+  if (windowMs > 0 && !(ts > 0 && Date.now() - ts <= windowMs)) return false;
+  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
+ * exact tool-name match always ranks first; a ≥4-char query that is a
+ * substring of a tool name is pulled ahead of BM25/semantic hits. Everything
+ * else keeps the given hit order, deduplicated.
+ * @param {Array<{name: string}>} docs - the tool corpus (allTools).
+ * @param {string} q - the search query.
+ * @param {Array<{id: string, score: number}>} hits - ranked hits.
+ * @returns {Array<{id: string, score: number}>} re-ordered hits.
+ */
+export function prioritizeExact(docs, q, hits) {
+  const query = String(q || "").trim().toLowerCase();
+  if (!query || !Array.isArray(docs) || !Array.isArray(hits)) return hits;
+  const ordered = [];
+  const seen = new Set();
+  const exact = docs.find((d) => String(d.name || "").toLowerCase() === query);
+  if (exact) {
+    ordered.push({ id: exact.name, score: 0 });
+    seen.add(exact.name);
+  }
+  if (query.length >= 4) {
+    for (const d of docs) {
+      if (seen.has(d.name)) continue;
+      if (String(d.name || "").toLowerCase().includes(query)) {
+        ordered.push({ id: d.name, score: 0 });
+        seen.add(d.name);
+      }
+    }
+  }
+  for (const h of hits) {
+    if (!h || seen.has(h.id)) continue;
+    ordered.push(h);
+    seen.add(h.id);
+  }
+  return ordered;
+}

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/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "dsh-tool-folder",
-  "version": "0.2.0",
-  "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",
-    "dsh",
-    "deepseek-harness",
-    "cordis",
-    "tool-selection",
-    "token-optimization",
-    "bm25",
-    "semantic-search",
-    "security",
-    "firewall",
-    "obfuscation"
-  ],
-  "type": "module",
-  "main": "lib/index.js",
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
-  },
-  "scripts": {
-    "test": "node --test \"test/*.test.js\""
-  },
-  "exports": {
-    ".": "./lib/index.js",
-    "./lib/*": "./lib/*"
-  }
+{
+    "name":  "dsh-tool-folder",
+    "version":  "0.2.2",
+    "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",
+                     "dsh",
+                     "deepseek-harness",
+                     "cordis",
+                     "tool-selection",
+                     "token-optimization",
+                     "bm25",
+                     "semantic-search",
+                     "security",
+                     "firewall",
+                     "obfuscation"
+                 ],
+    "type":  "module",
+    "main":  "lib/index.js",
+    "files":  [
+                  "lib",
+                  "cordis.patch.yml",
+                  "README.md"
+              ],
+    "dsh":  {
+                "bundle":  {
+                               "patch":  "./cordis.patch.yml"
+                           }
+            },
+    "license":  "MIT",
+    "engines":  {
+                    "node":  "\u003e=18"
+                },
+    "dependencies":  {
+                         "@deepseek-ai/schemastery":  "^3.18.1"
+                     },
+    "peerDependencies":  {
+                             "@deepseek-ai/cordis":  "^4.0.1",
+                             "@deepseek-ai/dsh-tools":  "^0.1.0-rc.6"
+                         },
+    "scripts":  {
+                    "test":  "node --test \"test/*.test.js\""
+                },
+    "exports":  {
+                    ".":  "./lib/index.js",
+                    "./lib/*":  "./lib/*"
+                }
 }