dsh-tool-folder 0.2.4 → 0.3.0

package/lib/semantic.js

@@ -1,31 +1,34 @@
 /**
- * semantic.js — local semantic retrieval leg via Ollama bge-m3 (2026-08-30).
+ * semantic.js — 语义检索腿（远程优先 → 本地 Ollama → 纯 BM25 降级）。
  *
- * Complements the BM25 lexical leg (bm25.js) with a cross-lingual semantic
- * leg: Chinese intents can hit English-only tool/skill descriptions that
- * share no surface tokens (the documented BM25 gap). Uses the machine's
- * local Ollama (`http://127.0.0.1:11434/api/embed`, model bge-m3 — 1024 dims,
- * ~1.2GB, already installed per ~/.dsh config). No npm deps, no network egress.
+ * 历史：v0.1.8 只走本地 Ollama bge-m3；v0.3.0 起改为**远程优先**。
+ * 原因（2026-10-17 实测）：本机没装 Ollama，`127.0.0.1:11434` 返回 000，
+ * 语义腿恒为 null，`tools_search` 实际只剩 BM25，中英跨语言命中率极低。
  *
- * Hard-fail design: every external path (fetch, fs cache) is optional. If
- * Ollama is down, the cache is unreadable, or anything throws, callers get
- * null/[] and their existing BM25 path just keeps working.
+ * 结构：
+ *   embedText       单条：远程 → Ollama → null
+ *   embedBatch      批量：远程批量（4 条/批、2 并发、429 退避）→ 逐条降级
+ *   buildSemanticIndex  增量索引（逐 doc sha1 指纹 + 磁盘缓存，部分成功也落盘）
+ *   searchSemantic  查询向量（带内存缓存）→ cosine 排序
+ *   rrfFuse         加权 RRF（语义权重可调，默认 3.0）
  *
- * Cache: document embeddings are keyed by text and persisted to
- * `~/.dsh/state/semantic-cache.json` (fingerprint = hash of all doc texts), so
- * the ~10s cold start for 300+ tools happens once, not per session.
- * Query embeddings are cached in memory only (per-process, tiny).
+ * 硬失败设计：任何外部路径（fetch / fs / 缓存）失败都只会让调用方回退到 BM25。
  */
 
-const OLLAMA_BASE = "http://127.0.0.1:11434";
-const DEFAULT_MODEL = "bge-m3";
-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";
 
+import { remoteEmbed, remoteEmbedBatch, remoteEmbedAvailable, configureRemoteEmbed } from "./embed-remote.js";
+
+const OLLAMA_BASE = "http://127.0.0.1:11434";
+const DEFAULT_MODEL = "bge-m3";
+const EMBED_TIMEOUT_MS = 12000;
+const CACHE_FILE = "state/semantic-cache.json";
+const INDEX_DEADLINE_MS = 180_000; // 243 个工具 × 2048 维，4 条/批 ≈ 25-40s
+const QUERY_CACHE_MAX = 64;
+const QUERY_TTL_MS = 10 * 60 * 1000;
+
 /* ------------------------------------------------------------------ */
 /* hash + fs helpers (all fail-safe)                                   */
 /* ------------------------------------------------------------------ */
@@ -46,7 +49,7 @@ function sha1(text) {
   try {
     return crypto.createHash("sha1").update(String(text || ""), "utf8").digest("hex");
   } catch {
-    return hash(text); // node:crypto 不可用时的降级指纹
+    return hash(text);
   }
 }
 
@@ -54,8 +57,22 @@ function homeDir() {
   return process.env.USERPROFILE || process.env.HOME || "";
 }
 
+/**
+ * 缓存路径：优先 `$DSH_HOME/state/`，再退 `~/.dsh-community`、`~/.dsh`。
+ * v0.3.0 修正：旧实现只认 USERPROFILE，DSH_HOME 指向 .dsh-community 时
+ * 缓存会落到另一个目录（和 dsh-recall 早期踩的是同一个坑）。
+ */
 function defaultCachePath() {
-  return homeDir() + "/" + CACHE_FILE;
+  const roots = [];
+  if (process.env.DSH_HOME) roots.push(process.env.DSH_HOME);
+  const community = path.join(homeDir(), ".dsh-community");
+  try {
+    if (fs.existsSync(community)) roots.push(community);
+  } catch {
+    /* ignore */
+  }
+  roots.push(path.join(homeDir(), ".dsh"));
+  return path.join(roots[0] || homeDir(), CACHE_FILE);
 }
 
 function readCacheFileAt(p) {
@@ -81,25 +98,45 @@ function writeCacheFileAt(p, obj) {
 }
 
 /* ------------------------------------------------------------------ */
-/* Ollama embedding (fail-safe fetch)                                  */
+/* config + provider identity                                          */
 /* ------------------------------------------------------------------ */
 
 let _model = DEFAULT_MODEL;
 let _base = OLLAMA_BASE;
+let _timeout = EMBED_TIMEOUT_MS;
 
 /**
- * Configure the endpoint (called by plugin apply with cfg.ollamaBase/model).
- * @param {{ollamaBase?: string, embedModel?: string}} cfg
+ * Configure both legs. `remote*` 可选；不传则远程腿沿用环境变量/默认值。
+ * @param {{ollamaBase?: string, embedModel?: string, embedTimeoutMs?: number,
+ *          remoteBase?: string, remoteModel?: string, remoteKey?: string}} 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 (!cfg || typeof cfg !== "object") return;
+  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;
+  if (cfg.remoteBase || cfg.remoteModel || typeof cfg.remoteKey === "string") {
+    configureRemoteEmbed({
+      apiBase: cfg.remoteBase,
+      model: cfg.remoteModel,
+      apiKey: cfg.remoteKey,
+      timeoutMs: cfg.embedTimeoutMs,
+    });
   }
 }
 
-/** One embedding vector for a text, or null on any failure. */
-export async function embedText(text, timeoutMs = EMBED_TIMEOUT_MS) {
+/** 缓存的身份键：换了端点或模型就必须整体重建，不能复用旧向量。 */
+export function semanticProvider() {
+  return remoteEmbedAvailable()
+    ? `remote|${process.env.DSH_EMBED_BASE || "ark"}|${process.env.DSH_EMBED_MODEL || _model}`
+    : `ollama|${_base}|${_model}`;
+}
+
+/* ------------------------------------------------------------------ */
+/* embedding legs                                                      */
+/* ------------------------------------------------------------------ */
+
+async function ollamaEmbed(text, timeoutMs) {
   const s = String(text || "").trim();
   if (!s) return null;
   try {
@@ -120,10 +157,42 @@ export async function embedText(text, timeoutMs = EMBED_TIMEOUT_MS) {
       clearTimeout(timer);
     }
   } catch {
-    return null; // offline / timeout / bad response → lexical leg only
+    return null;
   }
 }
 
+/** 单条 embedding：远程优先，失败回落本地 Ollama，最后 null。 */
+export async function embedText(text, timeoutMs = _timeout) {
+  const s = String(text || "").trim();
+  if (!s) return null;
+  if (remoteEmbedAvailable()) {
+    const rv = await remoteEmbed(s, timeoutMs);
+    if (rv) return rv;
+  }
+  return ollamaEmbed(s, timeoutMs);
+}
+
+/**
+ * 批量 embedding：远程可用时走批量（4 条/批 + 退避），否则逐条 embedText。
+ * @param {string[]} texts
+ * @param {number} [timeoutMs]
+ * @param {{batchSize?: number, concurrency?: number, onProgress?: Function}} [opts]
+ * @returns {Promise<Array<number[]|null>>}
+ */
+export async function embedBatch(texts, timeoutMs = _timeout, opts = {}) {
+  const list = Array.isArray(texts) ? texts : [];
+  if (!list.length) return [];
+  if (remoteEmbedAvailable()) {
+    const vecs = await remoteEmbedBatch(list, { timeoutMs, ...opts });
+    if (vecs.some(Boolean)) return vecs;
+  }
+  const out = new Array(list.length).fill(null);
+  for (let i = 0; i < list.length; i++) {
+    out[i] = await embedText(list[i], timeoutMs);
+  }
+  return out;
+}
+
 /** Cosine similarity in [0,1] (both vectors plain arrays). */
 export function cosine(a, b) {
   if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length) return 0;
@@ -139,93 +208,141 @@ export function cosine(a, b) {
   return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
 
+/* ------------------------------------------------------------------ */
+/* query embedding cache (fold 路径不能等网络)                          */
+/* ------------------------------------------------------------------ */
+
+const queryCache = new Map(); // norm text -> {vec, ts}
+
+function normQuery(q) {
+  return String(q || "").trim().toLowerCase().replace(/\s+/g, " ").slice(0, 400);
+}
+
+/**
+ * 同步读取已缓存的查询向量（供 assemble 热路径使用，绝不等网络）。
+ * @returns {number[]|null}
+ */
+export function getCachedQueryVector(query) {
+  const k = normQuery(query);
+  if (!k) return null;
+  const hit = queryCache.get(k);
+  if (!hit) return null;
+  if (Date.now() - hit.ts > QUERY_TTL_MS) {
+    queryCache.delete(k);
+    return null;
+  }
+  return hit.vec;
+}
+
+/** 查询向量（带缓存）；失败返回 null。 */
+export async function embedQueryCached(query, timeoutMs = _timeout) {
+  const k = normQuery(query);
+  if (!k) return null;
+  const hit = queryCache.get(k);
+  if (hit && Date.now() - hit.ts <= QUERY_TTL_MS) return hit.vec;
+  const vec = await embedText(query, timeoutMs);
+  if (vec) {
+    queryCache.set(k, { vec, ts: Date.now() });
+    if (queryCache.size > QUERY_CACHE_MAX) {
+      const oldest = [...queryCache.entries()].sort((a, b) => a[1].ts - b[1].ts)[0];
+      if (oldest) queryCache.delete(oldest[0]);
+    }
+  }
+  return vec;
+}
+
 /* ------------------------------------------------------------------ */
 /* Semantic index with persistent doc-embedding cache                  */
 /* ------------------------------------------------------------------ */
 
 /**
- * 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.
+ * Build a semantic index over docs with per-doc fingerprint incremental diff.
+ * 与旧实现的差别：
+ *   1. 走 embedBatch（批量 + 并发），243 个工具从「数百次串行 HTTP」变成 ~60 次批调用
+ *   2. **部分成功也落盘**（旧实现要求全部成功才写缓存 → 一次失败永远重建）
+ *   3. 缓存身份键带 provider（远程/本地切换不会复用错向量）
+ *   4. 覆盖率 ≥80% 即视为可用（cosine 只对已有向量的 doc 生效）
  *
  * @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}>}
+ * @param {number} [timeoutMs]
+ * @param {{embed?: Function, cacheFile?: string, onProgress?: Function}} [opts]
+ * @returns {Promise<{vectors: Map<string, number[]>, available: boolean, embedded: number, reused: number}>}
  */
-export async function buildSemanticIndex(docs, timeoutMs = EMBED_TIMEOUT_MS, opts = {}) {
-  const out = { vectors: new Map(), available: false };
+export async function buildSemanticIndex(docs, timeoutMs = _timeout, opts = {}) {
+  const out = { vectors: new Map(), available: false, embedded: 0, reused: 0 };
   const list = Array.isArray(docs) ? docs.filter((d) => d && d.id && d.text) : [];
   if (list.length === 0) return out;
 
-  const embed = typeof opts.embed === "function" ? opts.embed : embedText;
+  const injectable = typeof opts.embed === "function" ? opts.embed : null;
   const cachePath = opts.cacheFile || defaultCachePath();
+  const provider = semanticProvider();
 
-  // 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";
+    cache &&
+    cache.model &&
+    (cache.model.provider === provider ||
+      (!cache.model.provider && cache.model.model === _model && cache.model.base === _base)) &&
+    cache.docs &&
+    typeof cache.docs === "object";
   const cachedDocs = modelMatch ? cache.docs : null;
 
-  // 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;
+  // 1) 复用缓存里指纹未变的向量，收集需要重算的 doc
+  const need = [];
+  const fpById = new Map();
   for (const d of list) {
-    if (Date.now() > deadline) break;
-    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;
+    const fp = fpOf(d);
+    fpById.set(d.id, fp);
+    const hit = cachedDocs && cachedDocs[fp];
+    if (hit && Array.isArray(hit.vec) && hit.vec.length > 0 && hit.id === d.id) {
+      out.vectors.set(d.id, hit.vec);
+      out.reused += 1;
+    } else {
+      need.push(d);
     }
-    if (v) out.vectors.set(d.id, v);
   }
 
-  if (out.vectors.size === list.length) {
-    out.available = true;
-    // 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] };
+  // 2) 批量补算缺失向量
+  if (need.length) {
+    let fresh = new Array(need.length).fill(null);
+    if (injectable) {
+      for (let i = 0; i < need.length; i++) {
+        fresh[i] = await injectable(need[i].text, timeoutMs);
       }
+    } else {
+      const texts = need.map((d) => d.text);
+      fresh = await embedBatch(texts, timeoutMs, {
+        batchSize: 4,
+        concurrency: 2,
+        onProgress: opts.onProgress,
+      });
     }
-    writeCacheFileAt(cachePath, { model: { base: _base, model: _model }, docs: newDocs });
+    for (let i = 0; i < need.length; i++) {
+      if (fresh[i]) {
+        out.vectors.set(need[i].id, fresh[i]);
+        out.embedded += 1;
+      }
+    }
+  }
+
+  // 3) 落盘（部分成功也写，避免「一次失败永远重建」）
+  const newDocs = {};
+  for (const d of list) {
+    const v = out.vectors.get(d.id);
+    if (v) newDocs[fpById.get(d.id)] = { id: d.id, vec: v };
   }
+  if (Object.keys(newDocs).length) {
+    writeCacheFileAt(cachePath, { model: { provider, base: _base, model: _model }, docs: newDocs });
+  }
+
+  out.available = out.vectors.size > 0 && out.vectors.size >= Math.ceil(list.length * 0.8);
   return out;
 }
 
 /**
- * Rank docs by semantic similarity to a query.
+ * Rank docs by semantic similarity to a query (查询向量走缓存).
  * @param {Map<string, number[]>} vectors  id → vector
  * @param {Array<{id: string, text: string}>} docs
  * @param {string} query
@@ -234,8 +351,20 @@ export async function buildSemanticIndex(docs, timeoutMs = EMBED_TIMEOUT_MS, opt
 export async function searchSemantic(vectors, docs, query) {
   const q = String(query || "").trim();
   if (!q || !vectors || vectors.size === 0) return [];
-  const qv = await embedText(q);
+  const qv = await embedQueryCached(q);
+  if (!qv) return [];
+  return rankByVector(qv, vectors, docs);
+}
+
+/** 同步版：只用已缓存的查询向量（fold 热路径用）。 */
+export function searchSemanticCached(vectors, docs, query) {
+  if (!vectors || vectors.size === 0) return [];
+  const qv = getCachedQueryVector(query);
   if (!qv) return [];
+  return rankByVector(qv, vectors, docs);
+}
+
+function rankByVector(qv, vectors, docs) {
   const scored = [];
   for (const d of docs) {
     const v = vectors.get(d.id);
@@ -248,35 +377,79 @@ export async function searchSemantic(vectors, docs, query) {
 }
 
 /* ------------------------------------------------------------------ */
-/* RRF hybrid: merge a BM25 ranking and a semantic ranking             */
+/* Weighted RRF: merge BM25 ranking and semantic ranking               */
 /* ------------------------------------------------------------------ */
 
 const RRF_K = 60;
+const DEFAULT_SEM_WEIGHT = 3;
+const DEFAULT_BM_WEIGHT = 0.25;
+
+/**
+ * 自适应 BM25 权重（v0.3.0）。
+ *
+ * 实测依据（43 个真实工具 / 18 条真实中文意图）：
+ *   BM25 单腿 Hit@1 6/18 · 语义单腿 11/18 · 1:1 融合 8/18
+ *   语义 3 : BM25 0.25 → 11/18（与语义单腿同水平，且保留 BM25 的精确词兜底）
+ *
+ * 判据：查询里的 ASCII 词（>=3 字符）是否出现在 BM25 首条的 名称/描述 中。
+ *   - 有 → 这是真词匹配（工具名、server 名、英文关键词），BM25 可信，权重 1
+ *   - 没有（纯中文，BM25 只靠 CJK bigram 命中英文描述）→ 降权到 0.25，
+ *     否则噪声项会和语义腿"双命中"，被 RRF 加成顶到正确项前面
+ */
+export function adaptiveBmWeight(query, topHitName, topHitText) {
+  const ascii = String(query || "").toLowerCase().match(/[a-z0-9][a-z0-9_+-]{2,}/g) || [];
+  if (!ascii.length) return DEFAULT_BM_WEIGHT;
+  const hay = `${topHitName || ""} ${topHitText || ""}`.toLowerCase();
+  return ascii.some((t) => hay.includes(t)) ? 1 : DEFAULT_BM_WEIGHT;
+}
 
 /**
  * Reciprocal-rank fusion of two ranked id lists.
- * @param {Array<{id: string}>} bm25Ranked  BM25 hits in rank order
- * @param {Array<{id: string}>} semRanked   semantic hits in rank order
+ *
+ * v0.3.0：语义腿不再是 1:1 等权。技能侧重测（131 技能 / 12 意图）显示
+ * 语义明显更准（Hit@1 83% vs 58%），工具侧同样存在「中文意图 / 英文工具」
+ * 的跨语言鸿沟，所以给语义腿更高权重；BM25 退化为「精确词与工具名匹配」。
+ *
+ * 但**单纯调高语义权重不够**（2026-10-17 实测）：纯中文查询下 BM25 只靠 CJK
+ * bigram 命中一堆无关工具，这些噪声项同时出现在两条腿里，RRF 的"双命中"加成
+ * 会把它们顶到正确项前面（Hit@1 从 11/18 掉到 0/18）。所以 BM25 腿也要可降权：
+ * 调用方按「BM25 的命中是否含真实 ASCII 词匹配」决定 bmWeight（1 或 0.25）。
+ *
+ * @param {Array<{id: string}>} bm25Ranked
+ * @param {Array<{id: string}>} semRanked
  * @param {number} topK
- * @returns {Array<{id: string, rrf: number, from: string}>} fused, sorted desc
+ * @param {{semWeight?: number, bmWeight?: number}} [opts]
  */
-export function rrfFuse(bm25Ranked, semRanked, topK) {
+export function rrfFuse(bm25Ranked, semRanked, topK, opts = {}) {
+  const w = Number(opts.semWeight);
+  const semWeight = Number.isFinite(w) && w >= 0 ? w : DEFAULT_SEM_WEIGHT;
+  const bw = Number(opts.bmWeight);
+  const bmWeight = Number.isFinite(bw) && bw >= 0 ? bw : DEFAULT_BM_WEIGHT;
   const scores = new Map();
   const from = new Map();
-  bm25Ranked.forEach((h, i) => {
-    const key = h.id;
-    scores.set(key, (scores.get(key) || 0) + 1 / (RRF_K + i + 1));
-    from.set(key, (from.get(key) || "") + "bm25 ");
+  const seen = new Set();
+  // v0.3.0 修复：同名 id 只取首次出现。语料里若出现重复项（实测工具语料里
+  // list_sessions / get_config 各两份），RRF 会把同一 id 的分数累加两次，
+  // 直接把无关工具顶到第一——纯语义单腿 11/18 被拉到 2/18 的就是这个。
+  (Array.isArray(bm25Ranked) ? bm25Ranked : []).forEach((h, i) => {
+    if (!h || !h.id || seen.has(h.id)) return;
+    seen.add(h.id);
+    scores.set(h.id, bmWeight / (RRF_K + i + 1));
+    from.set(h.id, `${from.get(h.id) || ""}bm25 `);
   });
-  semRanked.forEach((h, i) => {
-    const key = h.id;
-    scores.set(key, (scores.get(key) || 0) + 1 / (RRF_K + i + 1));
-    from.set(key, (from.get(key) || "") + "sem ");
+  (Array.isArray(semRanked) ? semRanked : []).forEach((h, i) => {
+    if (!h || !h.id) return;
+    // 语义腿的名次必须按**去重后的位置**计，否则重复项会挤占后面的名次
+    if (scores.has(h.id) && from.get(h.id)?.includes("sem")) return;
+    scores.set(h.id, (scores.get(h.id) || 0) + semWeight / (RRF_K + i + 1));
+    from.set(h.id, `${from.get(h.id) || ""}sem `);
   });
   const k = Number(topK);
   const n = Number.isFinite(k) && k > 0 ? Math.floor(k) : 5;
   return [...scores.entries()]
     .sort((a, b) => b[1] - a[1])
     .slice(0, n)
-    .map(([id, r]) => ({ id, rrf: r, from: from.get(id)?.trim() || "" }));
+    .map(([id, r]) => ({ id, rrf: r, from: (from.get(id) || "").trim() }));
 }
+
+export { DEFAULT_SEM_WEIGHT, DEFAULT_BM_WEIGHT };

package/lib/ux.js

@@ -87,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]
@@ -98,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),
+  }));
 }
 
 /* ------------------------- ③ 检索结果缓存 ------------------------- */

package/package.json

@@ -1,48 +1,56 @@
-{
-    "name":  "dsh-tool-folder",
-    "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",
-                     "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/*"
-                }
-}
+{
+  "name": "dsh-tool-folder",
+  "version": "0.3.0",
+  "description": "Fold the DSH tool surface per request + ChainGuard firewall. v0.3.0: remote-first semantic retrieval (Ark doubao-embedding / Ollama fallback), weighted RRF with adaptive BM25 downweight, batched incremental index (partial results cached), body-level rerank (opt-in), duplicate-id fusion fix.",
+  "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/*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
+}