dsh-tool-folder 0.2.2 → 0.2.3

package/README.md

@@ -149,6 +149,31 @@ 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

package/lib/index.js

@@ -36,6 +36,7 @@ import { compressTool, normalizeDescription, sanitizeLossless } from "./schema.j
 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";
@@ -83,6 +84,10 @@ export const Config = z.object({
     .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 = {
@@ -119,6 +124,8 @@ const DEFAULTS = {
   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) {
@@ -330,7 +337,8 @@ export function apply(ctx, config) {
   };
   const persistWarmState = () => {
     if (!warmEnabled) return;
-    const payload = { warm: [...warm.entries()], ts: Date.now() };
+    // merge 写：与 discoveries 共用 state 文件，整写会互抹（Standards 轴 P1）。
+    const payload = { ...readState(activeStateFile, {}), warm: [...warm.entries()], ts: Date.now() };
     let ok = writeState(activeStateFile, payload);
     if (!ok) {
       // 首选目录不可写 → 降到 ~/.dsh/state/
@@ -340,6 +348,39 @@ export function apply(ctx, config) {
   };
   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("__");
@@ -440,6 +481,7 @@ export function apply(ctx, config) {
           },
         },
         total: { type: "integer", required: true },
+        fallback: { type: "boolean", description: "true = 零匹配，结果回退为按名字典序的轻目录" },
       },
     };
     const toolsSearch = defineTool({
@@ -461,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.
@@ -480,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) {
@@ -488,7 +542,7 @@ export function apply(ctx, config) {
           }
         }
         const byName = new Map(allTools.map((t) => [t.name, t]));
-        const results = fused.map((h) => {
+        let results = fused.map((h) => {
           const t = byName.get(h.id) || {};
           return {
             name: h.id,
@@ -496,13 +550,31 @@ export function apply(ctx, config) {
             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));
-        return {
+        // P0-④: 发现率统计（节流落盘，低频工具名单反哺描述改进）。
+        recordDiscoveries(discoveries, results.map((r) => r.name));
+        persistDiscoveries();
+        const out = {
           query: q,
           results,
-          total: fused.length,
+          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 {

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.2",
+    "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",
@@ -45,4 +45,4 @@
                     ".":  "./lib/index.js",
                     "./lib/*":  "./lib/*"
                 }
-}
+}