dsh-tool-folder 0.2.2 → 0.2.4

package/README.md

@@ -149,6 +149,48 @@ were never unregistered, so nothing else changes.
 
 ## Changelog
 
+### v0.2.4 — P1: batch tools_schema + sibling closure (2026-08-31)
+1. **Batch expand** — `tools_schema` accepts `names: [...]` to expand several
+   tools in one call (`{ found, results: [...] }`); a single `name` keeps the
+   legacy 6-field shape byte-for-byte.
+2. **Sibling closure** (`closureSize`, default 0 = off, mirrors the
+   `maxWarmTools` compat precedent): when enabled, expanding a tool also lists
+   lightweight sibling entries (name + 120-char description) from the same
+   server prefix, so the model can batch-expand what it actually needs —
+   kills the "expanded A, now I need B" round-trip. `closure: false` opts out
+   per call.
+3. Output contract moved to a pure function (`buildSchemaResponse`, ux.js) —
+   11 new tests pin single/batch/missing/siblings branches (94 total green).
+4. Two-axis audit (Standards + Spec): 1 Critical fixed during review — the
+   single/batch routing condition was inverted (old `name`-only calls would
+   have returned the batch shape); contract tests now catch that class
+   instantly. `siblingClosure` dead code removed.
+
+### 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

@@ -32,10 +32,11 @@ import fs from "node:fs";
 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 { compressTool, normalizeDescription } from "./schema.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, siblingClosure, buildSchemaResponse } from "./ux.js";
 import { ChainGuard, verdict } from "./chainguard.js";
 import { matchCategory } from "./category.js";
 import { toonifyValue } from "./toonify.js";
@@ -83,6 +84,12 @@ 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/语义召回；精确名匹配不受影响）"),
+  closureSize: z.number().min(0).max(20).default(0)
+    .description("P1: tools_schema 展开时附带同 server 兄弟工具的轻目录条数（name+120字描述，名字典序）；0=关闭（默认关=无配置升级输出逐字段等价，显式开启才启用，与 maxWarmTools 先例一致）"),
 });
 
 const DEFAULTS = {
@@ -119,6 +126,9 @@ 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 扩展
+  closureSize: 0, // P1: tools_schema 同 server 兄弟闭包（默认关=逐字段等价，显式开启）
 };
 
 function feedbackPath(cfg) {
@@ -330,7 +340,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 +351,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 +484,7 @@ export function apply(ctx, config) {
           },
         },
         total: { type: "integer", required: true },
+        fallback: { type: "boolean", description: "true = 零匹配，结果回退为按名字典序的轻目录" },
       },
     };
     const toolsSearch = defineTool({
@@ -461,15 +506,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 +537,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 +545,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 +553,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 {
@@ -525,15 +600,24 @@ export function apply(ctx, config) {
     const schemaTool = defineTool({
       name: "tools_schema",
       description:
-        "Get the complete parameter schema of one tool by name. Use after " +
+        "Get the complete parameter schema of one or more tools by name. Use after " +
         "tools_search narrows candidates, or before calling a tool whose exact " +
         "arguments you need. Returns the full JSON schema of parameters plus the " +
-        "full description.",
+        "full description; sibling tools from the same server are listed alongside " +
+        "(lightweight) so you can batch-expand what you need.",
       parameters: {
         name: {
           type: "string",
-          required: true,
-          description: "Exact tool name, e.g. 'mcp__viking__remember'.",
+          description: "Exact tool name, e.g. 'mcp__viking__remember' (either name or names).",
+        },
+        names: {
+          type: "array",
+          items: { type: "string" },
+          description: "Batch: exact tool names to expand in one call (either name or names).",
+        },
+        closure: {
+          type: "boolean",
+          description: "Include lightweight sibling tools from the same server (default true).",
         },
       },
       output: {
@@ -542,21 +626,14 @@ export function apply(ctx, config) {
       },
       isConcurrencySafe: () => true,
       async execute(args) {
-        const name = String(args?.name || "");
-        const t = allTools.find((x) => x.name === name);
-        if (!t) return { name, found: false, reason: "unknown tool" }; // never throw
+        // P1: 批量展开（names 数组）+ 同 server 兄弟闭包（closureSize 条轻目录）。
+        // 输出契约全部在 buildSchemaResponse（纯函数，lib/ux.js 可单测）。
+        const res = buildSchemaResponse(allTools, args, { closureSize: cfg.closureSize, serverOf });
         // v0.2.2: 展开过 schema 的工具名进入 warm 集合，下一轮保持注入。
-        touchWarmNames([name]);
-        return {
-          name: t.name,
-          found: true,
-          server: serverOf(t.name),
-          description: t.description || "",
-          // C4 defense: even a schema containing `const: -0` must come back as
-          // lossless JSON.
-          parameters: sanitizeLossless(t.parameters ?? {}),
-          required: Array.isArray(t.parameters?.required) ? t.parameters.required : [],
-        };
+        touchWarmNames(
+          Array.isArray(res.results) ? res.results.map((r) => r.name) : res.found && res.name ? [res.name] : [],
+        );
+        return res;
       },
     });
     try {

package/lib/ux.js

@@ -0,0 +1,285 @@
+/**
+ * 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，落盘可恢复）——低频工具名单
+ *                        反哺描述改进（官方「监控发现率」建议的本地等价物）
+ *   P1 ⑤ siblingClosure 同 server 兄弟闭包 ⑥ buildSchemaResponse tools_schema
+ *                        输出契约（单数/批量/siblings/missing 全分支，可单测）
+ */
+import { sanitizeLossless } from "./schema.js";
+
+/* ------------------------- ① 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;
+}
+
+/* ------------------------- P1: 依赖闭包 ------------------------- */
+
+/**
+ * 同 server 兄弟闭包（graph-tool-call 的本地简化：server 前缀 = 依赖分组代理）。
+ * 展开目标工具时顺带返回同 server 的其它工具轻目录（name+120 字描述），
+ * 模型看到兄弟名字后可批量展开——减少「展开 A 发现还要 B」的往返税。
+ * ponytail: server 前缀是粗粒度依赖近似；精确 producer 图需要宿主工具元数据，
+ * 真需要时再按参数类型启发补。
+ * @param {Array<{name:string,description?:string}>} allTools
+ * @param {Array<string>} expandedNames 已展开的工具名
+ * @param {number} limit 附带兄弟总数上限（0=关闭）
+ * @param {(name:string)=>string} [serverOf] server 前缀提取
+ * @returns {Array<{name:string,description:string}>}
+ */
+export function siblingClosure(allTools, expandedNames, limit, serverOf) {
+  const lim = Math.max(0, Number(limit) || 0);
+  if (!lim || !Array.isArray(allTools) || !Array.isArray(expandedNames) || expandedNames.length === 0) return [];
+  const svc = typeof serverOf === "function" ? serverOf : (n) => String(n).split("__").slice(0, 2).join("__");
+  const servers = new Set(expandedNames.map((n) => svc(String(n))).filter(Boolean));
+  if (servers.size === 0) return [];
+  const skip = new Set(expandedNames);
+  const out = [];
+  for (const t of [...allTools].sort((a, b) => String(a.name).localeCompare(String(b.name)))) {
+    if (out.length >= lim) break;
+    const nm = String(t.name || "");
+    if (!nm || skip.has(nm)) continue;
+    if (servers.has(svc(nm))) {
+      out.push({ name: nm, description: String(t.description || "").slice(0, 120) });
+    }
+  }
+  return out;
+}
+
+/* ------------------------- P1: tools_schema 输出契约 ------------------------- */
+
+const defaultServerOf = (name) => String(name).split("__").slice(0, 2).join("__");
+
+/**
+ * tools_schema 的纯输出构造（从 index.js execute 提取，契约可单测——single 判定
+ * 写反曾逃过 87 条纯函数测试，根因是 execute 无测试；提取后契约分支全部可钉死）。
+ * 单数调用（name 或 names 单元素，去重后 1 个）→ 旧版逐字段结构；
+ * 批量（去重后 >1 个）→ { found, results: [...], siblings?, missing? }。
+ * @param {Array<{name:string,description?:string,parameters?:object}>} allTools
+ * @param {{name?:string,names?:Array<string>,closure?:boolean}} args
+ * @param {{closureSize?:number,serverOf?:Function}} [opts]
+ */
+export function buildSchemaResponse(allTools, args, opts = {}) {
+  const closureSize = Math.max(0, Number(opts.closureSize) || 0);
+  const svc = typeof opts.serverOf === "function" ? opts.serverOf : defaultServerOf;
+  const primary = String(args?.name || "");
+  const batch = (Array.isArray(args?.names) ? args.names : []).map((n) => String(n)).filter(Boolean);
+  const want = [...new Set([...batch, ...(primary ? [primary] : [])])];
+  if (want.length === 0) return { found: false, reason: "no name" };
+  const expanded = [];
+  const missing = [];
+  for (const n of want) {
+    const t = (allTools || []).find((x) => x && x.name === n);
+    if (!t) {
+      missing.push(n);
+      continue;
+    }
+    expanded.push({
+      name: t.name,
+      server: svc(t.name),
+      description: t.description || "",
+      // C4 defense: even a schema containing `const: -0` must come back as
+      // lossless JSON.
+      parameters: sanitizeLossless(t.parameters ?? {}),
+      required: Array.isArray(t.parameters?.required) ? t.parameters.required : [],
+    });
+  }
+  // ⚠️ 判定只看 want.length——旧实现用 !primary 导致只传 name 的调用误走批量结构。
+  const single = want.length === 1;
+  if (single) {
+    if (expanded.length === 0) return { name: want[0], found: false, reason: "unknown tool" };
+    const e = expanded[0];
+    const out = {
+      name: e.name,
+      found: true,
+      server: e.server,
+      description: e.description,
+      parameters: e.parameters,
+      required: e.required,
+    };
+    if (closureSize > 0 && args?.closure !== false) {
+      out.siblings = siblingClosure(allTools, [e.name], closureSize, svc);
+    }
+    return out;
+  }
+  const out = {
+    found: expanded.length > 0,
+    ...(expanded.length > 0
+      ? {
+          results: expanded,
+          ...(closureSize > 0 && args?.closure !== false
+            ? { siblings: siblingClosure(allTools, expanded.map((e) => e.name), closureSize, svc) }
+            : {}),
+        }
+      : {}),
+    ...(missing.length > 0 ? { missing } : {}),
+  };
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-tool-folder",
-    "version":  "0.2.2",
+    "version":  "0.2.4",
     "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/*"
                 }
-}
+}