dsh-tool-folder 0.2.3 → 0.2.5

package/README.md

@@ -149,6 +149,44 @@ were never unregistered, so nothing else changes.
 
 ## Changelog
 
+### v0.2.5 — red-team firewall fixes + retrieval hardening (2026-09-02)
+1. **Exec-tool recognition (red-team F1)** — bare-name matching let MCP-prefixed
+   exec tools (`mcp__windows__Cmd`) bypass the high-risk gate; `isExecTool` now
+   tokenizes the full name and matches every segment (all segments participate —
+   conservative by design, over-recognition is ~free on the gate).
+2. **False-positive roots A/B** — Windows paths are base64-shaped (57-char fake
+   runs) and the bare `&` of `2>&1` looked like an exec verb; a legit gitleaks
+   staged scan was blocked. Path-fingerprint exclusion + `EXEC_VERB` tightening.
+   2/5 measured FPs → 0/5; regression suite `chainguard-fp.test.js` (114 total green).
+3. **Command-substitution download-exec legs** — `$(curl …)` / backtick /
+   `iwr` shapes (no pipe, invisible to the download-pipe pattern).
+4. **BM25 sub-word split** — hyphen/underscore tool names were single index
+   terms (`mcp__codegraph__codegraph_explore`); measured recall 0/10 → 10/10.
+5. **fallbackCatalog round-robin** — pure lexicographic slice hid whole servers
+   (`mcp__*`) from the fallback catalog; now round-robins across servers.
+6. **serverOf unified** — apply-local `split("__")` copy deleted; module-level
+   grouping (native/openhands families) is the single source for search results
+   and sibling closure. `embedTimeoutMs` configurable (default 8000).
+7. Two-axis audit (2026-09-02): comments/tests now match the real conservative
+   design; one-shot repro script removed.
+
+### 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/bm25.js

@@ -1,6 +1,12 @@
 /**
  * bm25.js — zero-dependency BM25 lexical search for tool retrieval.
  *
+ * VENDOR SOURCE (2026-09-02): dsh-skill-folder/lib/bm25.js vendors this file
+ * verbatim (comments may diverge per repo). Modify here, then mirror the code
+ * change into the skill repo. Sync gate: `node E:\DSH-Data\scripts\check-vendor-sync.mjs`.
+ * semantic.js is intentionally DIVERGED (tool has incremental cache/sha1) and
+ * is NOT covered by the gate.
+ *
  * Design (ported from the xiaowan agent's ToolBM25Index idea; the algorithm is
  * the reference, this code is a clean-room JS implementation):
  *   - BM25 with standard k1=1.2, b=0.75 (RAG-MCP / BoR validated the
@@ -32,6 +38,15 @@ function tokenize(text) {
   for (const m of s.matchAll(/[a-z0-9][a-z0-9_+-]{1,}/g)) {
     const t = m[0];
     if (!EN_STOP.has(t)) out.push(t);
+    // Sub-words of hyphen/underscore compounds. Without this, a tool name like
+    // "mcp__open-design__start_run" is ONE term, so querying "design" scores
+    // zero. The whole token is kept too, so exact-name matches and existing
+    // IDF are unchanged; sub-words only ADD recall.
+    if (t.length > 2 && (t.includes("-") || t.includes("_"))) {
+      for (const part of t.split(/[-_]+/)) {
+        if (part.length > 1 && part !== t && !EN_STOP.has(part)) out.push(part);
+      }
+    }
   }
   // CJK bigrams: "开源框架" -> "开源","源框","框架". Bigrams beat single
   // chars for short tool descriptions and are dependency-free.

package/lib/chainguard.js

@@ -24,6 +24,9 @@ const HIGH_RISK_PATTERNS = [
   // download → execute chain
   [/(wget|curl|powershell|pwsh).{0,80}(\||;|&&).{0,30}(sh|bash|powershell|pwsh|cmd|start)\b/i, "download-pipe-execute"],
   [/invoke-expression|iex\s*\(|iwr\s+.*\|.*iex/i, "powershell download-exec"],
+  // command substitution download → execute (bash $() and backticks; no pipe,
+  // so the download-pipe pattern above cannot see it). Added 2026-09-02.
+  [/\$\s*\(\s*(?:curl|wget|iwr)[^)]{0,120}\)|\`(?:curl|wget|iwr)[^\`]{0,120}\`/i, "download-exec via command substitution"],
   // credential / exfil
   // NOTE: `\\+` (one-or-more literal backslashes) instead of `\\` — argv text
   // reaches verdict() both as a raw string (single backslash) and as
@@ -58,6 +61,43 @@ function matchHighRisk(text) {
   return null;
 }
 
+/**
+ * 是否「执行类工具」——参数是真实要执行的命令/脚本，需要高危硬拦。
+ * 内容类工具（write/edit/read/apply_patch 等）的参数是文件内容/文本，
+ * 本身不执行，含危险命令字面量（讨论/测试/文档）不应触发硬拦。
+ *
+ * 2026-08-30: 修复 ChainGuard 对所有工具参数跑高危正则导致的误拦。
+ * 2026-09-02 (red-team F1): bare-name matching let MCP-prefixed exec tools
+ * (`mcp__windows__Cmd`) bypass the gate — tokenize the full name and match
+ * every segment against the verb list. Over-recognition is ~free here: the
+ * gate only decides "run this argv past the firewall", and a non-command
+ * argv has no high-risk literals to trip; missing one tool is a bypass.
+ * @param {string} name - full tool name (mcp__<server>__<tool> or bare).
+ */
+export function isExecTool(name) {
+  if (!name) return false;
+  const n = String(name).toLowerCase();
+  const EXEC_TOKENS = new Set([
+    "cmd", "command", "console", "terminal", "shell", "bash", "pwsh", "powershell",
+    "exec", "execute", "executor", "run", "runner", "sh", "zsh", "script", "ps1",
+  ]);
+  // Legacy fast paths kept for bare names and native prefixes.
+  const EXEC_NAMES = ["pwsh", "shell", "bash", "cmd", "exec", "terminal", "run", "console"];
+  if (EXEC_NAMES.includes(n)) return true;
+  if (n.endsWith("__app")) return true; // mcp__windows__App：launch_executable 模式可启动任意可执行文件
+  if (n.startsWith("run_") || n.startsWith("exec_") || n.startsWith("execute_")) return true;
+  if (n.startsWith("ssh_") || n.startsWith("wsl")) return true;
+  // Segment match: tokenize on mcp__ separator and _ - . (runbook-style names).
+  // All segments except the `mcp` marker participate — a server name carrying
+  // an exec word (e.g. `pwsh` in mcp__pwsh__list_tools) is itself an exec
+  // signal, while `mcp__github__get_file_contents` has none. Over-recognition
+  // is ~free (gate only); under-recognition is a bypass.
+  const tokens = n.split(/__|_|-|\./).filter((t) => t.length > 0);
+  const meaningful = n.startsWith("mcp") && tokens[0] === "mcp" ? tokens.slice(1) : tokens;
+  if (meaningful.length === 0) return false;
+  return meaningful.some((t) => EXEC_TOKENS.has(t));
+}
+
 export function verdict(argvText) {
   if (!argvText) return null;
 

package/lib/index.js

@@ -32,12 +32,12 @@ 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 { ChainGuard, verdict } from "./chainguard.js";
+import { expandQuery, fallbackCatalog, createSearchCache, recordDiscoveries, serializeDiscoveries, deserializeDiscoveries, siblingClosure, buildSchemaResponse } from "./ux.js";
+import { ChainGuard, verdict, isExecTool } from "./chainguard.js";
 import { matchCategory } from "./category.js";
 import { toonifyValue } from "./toonify.js";
 import { configureSemantic, buildSemanticIndex, searchSemantic, rrfFuse } from "./semantic.js";
@@ -80,6 +80,7 @@ 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 时使用）"),
+  embedTimeoutMs: z.number().min(100).default(8000).description("embedding 请求超时（毫秒；Ollama 慢时可调大）"),
   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)
@@ -88,6 +89,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 = {
@@ -122,10 +125,12 @@ 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",
+  embedTimeoutMs: 8000, // P3-2: embedding 请求超时（毫秒）
   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) {
@@ -197,24 +202,6 @@ function serverOf(name) {
   return "native";
 }
 
-/**
- * 是否「执行类工具」——参数是真实要执行的命令/脚本，需要高危硬拦。
- * 内容类工具（write/edit/read/apply_patch 等）的参数是文件内容/文本，
- * 本身不执行，含危险命令字面量（讨论/测试/文档）不应触发硬拦。
- * 2026-08-30：修复 ChainGuard 对所有工具参数跑高危正则导致的误拦。
- */
-function isExecTool(name) {
-  if (!name) return false;
-  const n = String(name).toLowerCase();
-  const EXEC_NAMES = ["pwsh", "shell", "bash", "cmd", "exec", "terminal", "run", "console"];
-  if (EXEC_NAMES.includes(n)) return true;
-  if (n.includes("powershell")) return true; // mcp__windows__PowerShell 等（参数即命令）
-  if (n.endsWith("__app")) return true; // mcp__windows__App：launch_executable 模式可启动任意可执行文件
-  if (n.startsWith("run_") || n.startsWith("exec_") || n.startsWith("execute_")) return true;
-  if (n.startsWith("ssh_") || n.startsWith("wsl")) return true;
-  return false;
-}
-
 function summarizeCaps(tools) {
   // Pull the first few distinct capability keywords from descriptions.
   const seen = new Set();
@@ -276,7 +263,7 @@ export function apply(ctx, config) {
   // Semantic leg (P0-1): point the shared module at our config; the index is
   // built lazily on first tools_search call (doc embeddings cached on disk,
   // so the ~10s cold start happens once, then it's a cache hit).
-  configureSemantic({ ollamaBase: cfg.ollamaBase, embedModel: cfg.embedModel });
+  configureSemantic({ ollamaBase: cfg.ollamaBase, embedModel: cfg.embedModel, embedTimeoutMs: cfg.embedTimeoutMs });
   let semIndexPromise = null;
   const getSemanticIndex = () => {
     if (!semIndexPromise) {
@@ -381,9 +368,12 @@ export function apply(ctx, config) {
   // 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("__");
+  // serverOf is the module-level function defined above (mcp__server__tool →
+  // "mcp__server", openhands_* → "openhands", plain native tools → "native").
+  // P3-1 (2026-09-02): the previous apply-local copy (split("__").slice(0,2))
+  // let plain tools be their own "server", diverging from catalogText grouping
+  // and making sibling closure useless for native/openhands families. One
+  // definition, one口径.
 
   // Pattern matching shared by deny (P0) and include (P2-1): exact name or
   // "prefix*" matches any tool starting with that prefix.
@@ -597,15 +587,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 +613,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/obfuscation.js

@@ -65,7 +65,15 @@ const RE_BITSADMIN = /bitsadmin\s+\/transfer\s+\S+\s+\/download/i;
 
 // A long base64 blob co-located with an execution verb in the same command.
 const RE_B64_PAYLOAD = /[A-Za-z0-9+/]{40,}={0,2}/;
-const EXEC_VERB = /(?:iex|invoke-expression|invoke-command|iwr|irm|start-process|start-job|&|cmd\s*\/[cC]|sh\s+-c|bash\s+-c|python\s+-[cC]|node\s+-e|powershell|pwsh|mshta|rundll32|regsvr32|wscript|cscript)\b/i;
+// Path fingerprint: >=3 camel-case segments joined by '/' (C:/Users/L/AppData/...).
+// '/' is a base64 char, so long Windows/URL paths form fake base64 runs; real
+// base64 payloads almost never contain 3+ `/Upper`-word segments. Fixed 2026-09-02
+// (measured: 57-char WinGet path run + `2>&1` was blocked as base64-embedded-command).
+const RE_PATHISH_RUN = /(?:\/[A-Z][A-Za-z]{1,}){3,}/;
+// Exec verb used by the b64/hex legs. NOTE: no bare `&` — `2>&1` redirection
+// and `& ` call operators are not payload-exec evidence by themselves; the
+// verb must be an actual command word (fixed 2026-09-02, fp-repro 2/5).
+const EXEC_VERB = /(?:iex|invoke-expression|invoke-command|iwr|irm|start-process|start-job|&\s*(?:iex|invoke|iwr|irm|cmd|powershell|pwsh|sh|bash|python|node|mshta|rundll32|regsvr32|wscript|cscript)|cmd\s*\/[cC]|sh\s+-c|bash\s+-c|python\s+-[cC]|node\s+-e|powershell|pwsh|mshta|rundll32|regsvr32|wscript|cscript)\b/i;
 
 // Full-width Latin letters (ｃｕｒｌ) — never legit in a command line.
 const RE_FULLWIDTH = /[\uFF21-\uFF3A\uFF41-\uFF5A]/;
@@ -97,7 +105,8 @@ export function detectObfuscation(rawText, cleanText) {
   if (RE_BITSADMIN.test(probe)) {
     return { label: "bitsadmin-download-exec", detail: "bitsadmin /transfer 下载执行" };
   }
-  if (RE_B64_PAYLOAD.test(probe) && EXEC_VERB.test(probe)) {
+  const b64Run = RE_B64_PAYLOAD.exec(probe);
+  if (b64Run && !RE_PATHISH_RUN.test(b64Run[0]) && EXEC_VERB.test(probe)) {
     return { label: "base64-embedded-command", detail: "长 base64 载荷 + 执行动词共存" };
   }
   if (RE_FULLWIDTH.test(raw)) {

package/lib/semantic.js

@@ -86,20 +86,22 @@ function writeCacheFileAt(p, obj) {
 
 let _model = DEFAULT_MODEL;
 let _base = OLLAMA_BASE;
+let _timeout = EMBED_TIMEOUT_MS; // P3-2 (2026-09-02): configurable via configureSemantic
 
 /**
  * Configure the endpoint (called by plugin apply with cfg.ollamaBase/model).
- * @param {{ollamaBase?: string, embedModel?: string}} cfg
+ * @param {{ollamaBase?: string, embedModel?: string, embedTimeoutMs?: number}} cfg
  */
 export function configureSemantic(cfg = {}) {
   if (cfg && typeof cfg === "object") {
     if (typeof cfg.ollamaBase === "string" && cfg.ollamaBase) _base = cfg.ollamaBase;
     if (typeof cfg.embedModel === "string" && cfg.embedModel) _model = cfg.embedModel;
+    if (Number.isFinite(cfg.embedTimeoutMs) && cfg.embedTimeoutMs >= 100) _timeout = cfg.embedTimeoutMs;
   }
 }
 
 /** One embedding vector for a text, or null on any failure. */
-export async function embedText(text, timeoutMs = EMBED_TIMEOUT_MS) {
+export async function embedText(text, timeoutMs = _timeout) {
   const s = String(text || "").trim();
   if (!s) return null;
   try {
@@ -164,7 +166,7 @@ export function cosine(a, b) {
  *                 real ~/.dsh/state unless omitted).
  * @returns {Promise<{vectors: Map<string, number[]>, available: boolean}>}
  */
-export async function buildSemanticIndex(docs, timeoutMs = EMBED_TIMEOUT_MS, opts = {}) {
+export async function buildSemanticIndex(docs, timeoutMs = _timeout, 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;

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 扩展词表 ------------------------- */
 
@@ -84,8 +87,14 @@ export function expandQuery(q) {
 /* ------------------------- ② 零匹配回退轻目录 ------------------------- */
 
 /**
- * 轻目录：按名字典序排序取前 limit 个（name + 描述截 80 + server）。
+ * 轻目录：跨 server 轮转配额（name + 描述截 80 + server）。
  * limit<=0 → []（关闭回退，行为与旧版一致）。
+ *
+ * 2026-09-02（审计修复）：纯字典序 slice(0, limit) 会让名字靠后的 server
+ * （mcp__windows 等）在截断后全部不可见 → 模型零匹配回退时误判"没有该能力"。
+ * 改为：按 server 分组（组内字典序）→ round-robin 出队——小 server 必有代表、
+ * 大 server 拿多数、同输入同输出（确定性）。server 函数为每工具独立名时行为
+ * 与旧字典序一致（每组 1 个，轮转 = 字典序）。
  * @param {Array<{name:string,description?:string}>} allTools
  * @param {number} limit
  * @param {(name:string)=>string} [serverOf]
@@ -95,14 +104,28 @@ 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),
-    }));
+  const byServer = new Map();
+  for (const t of allTools) {
+    const s = svc(t.name) || "(none)";
+    if (!byServer.has(s)) byServer.set(s, []);
+    byServer.get(s).push(t);
+  }
+  // Deterministic: server order by name, tools inside each server sorted by name.
+  const queues = [...byServer.entries()]
+    .sort((a, b) => String(a[0]).localeCompare(String(b[0])))
+    .map(([, ts]) => ts.slice().sort((a, b) => String(a.name).localeCompare(String(b.name))));
+  const out = [];
+  while (out.length < lim && queues.some((q) => q.length > 0)) {
+    for (const q of queues) {
+      if (out.length >= lim) break;
+      if (q.length > 0) out.push(q.shift());
+    }
+  }
+  return out.map((t) => ({
+    name: String(t.name || ""),
+    description: String(t.description || "").slice(0, 80),
+    server: svc(t.name),
+  }));
 }
 
 /* ------------------------- ③ 检索结果缓存 ------------------------- */
@@ -176,3 +199,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.5",
     "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",