dsh-tool-folder 0.2.3 → 0.2.4

package/README.md

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

package/lib/index.js

@@ -32,11 +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 } from "./ux.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";
@@ -88,6 +88,8 @@ export const Config = z.object({
     .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 = {
@@ -126,6 +128,7 @@ const DEFAULTS = {
   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) {
@@ -597,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: {
@@ -614,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

@@ -10,7 +10,10 @@
  *                        同会话重复搜索返回同一结果集（漂移的最小修）
  *   ④ recordDiscoveries 发现率统计（name→count，落盘可恢复）——低频工具名单
  *                        反哺描述改进（官方「监控发现率」建议的本地等价物）
+ *   P1 ⑤ siblingClosure 同 server 兄弟闭包 ⑥ buildSchemaResponse tools_schema
+ *                        输出契约（单数/批量/siblings/missing 全分支，可单测）
  */
+import { sanitizeLossless } from "./schema.js";
 
 /* ------------------------- ① query 扩展词表 ------------------------- */
 
@@ -176,3 +179,107 @@ export function deserializeDiscoveries(list) {
   }
   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.3",
+    "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",