dsh-tool-folder 0.2.5 → 0.3.2

package/lib/rerank.js

@@ -0,0 +1,165 @@
+/**
+ * rerank.js — 正文精排（借鉴 SkillRouter 的「元数据召回 + 正文重排」两阶段）。
+ *
+ * 为什么工具也需要「正文」：`tools_search` 的召回声只看 name + description，
+ * 而真正决定「该用哪个工具」的信息常常在**参数**里。例：
+ *   mcp__playwright__browser_navigate  vs  browser_evaluate  vs  browser_take_screenshot
+ *   描述都是 "browser ..."，参数才是 url / function / filename 的区别。
+ *   再如一堆 `*_search`：query 还是 keyword、有没有 repo/limit，全在参数描述里。
+ * L1 压缩还会把描述截到 200 字、参数描述砍到 120 字——被裁掉的正是这部分信号。
+ *
+ * 做法（与技能侧 v0.4.0 的 deep-search 同构）：
+ *   - 在 BM25/语义召回的**候选集内**重排，绝不扩大候选
+ *     （技能侧实测：扩大候选会让泛化词把无关项顶上来，Hit@1 从 50% 掉到 25%）
+ *   - body 打分 = 查询词在正文里的 IDF 覆盖率 + 整句命中加分
+ *   - 融合：默认 **RRF 排名融合**；保留 `linear` 兼容旧行为
+ *
+ * ---- 2026-10-31 升级（v0.3.1）----
+ * 原融合是线性加权：`(1-w)·metaNorm + w·bodyScore`，其中 metaNorm = 1/(1+metaRank)。
+ * w=0.35 时**元数据第 0 位的底分就是 0.65，而正文满分仅 0.35**——正文信号
+ * 数学上永远翻不了盘。实测：
+ *     「查找代码里的函数定义」
+ *       mcp__git     body 0.00 → 0.650  （排第一）
+ *       mcp__serena  body 0.91 → 0.448  （排第二，正文赢了 0.91 分却输）
+ * 换成 RRF（Cormack et al. 2009）后，两路只贡献**名次**，不贡献分数量纲，
+ * 天花板问题消失，且不需要为 meta 与 body 两路的分数量级做校准。
+ * 参考 ratel 的做法：「基于排名的融合意味着各通道分数无需校准」。
+ */
+
+import { tokenize } from "./bm25.js";
+
+const MAX_BODY_CHARS = 4000;
+
+/**
+ * 拼出一个工具的「正文」：完整描述（不截断）+ 参数名 + 参数描述 + 枚举 + server。
+ * @param {object} tool
+ * @returns {string}
+ */
+export function toolBodyText(tool) {
+  if (!tool || typeof tool !== "object") return "";
+  const parts = [];
+  if (tool.name) parts.push(String(tool.name));
+  if (tool.description) parts.push(String(tool.description));
+  const schema = tool.parameters || tool.inputSchema || null;
+  const props = schema && typeof schema === "object" ? schema.properties : null;
+  if (props && typeof props === "object") {
+    for (const [k, v] of Object.entries(props)) {
+      parts.push(k);
+      if (v && typeof v === "object") {
+        if (typeof v.title === "string") parts.push(v.title);
+        if (typeof v.description === "string") parts.push(v.description);
+        if (Array.isArray(v.enum)) parts.push(v.enum.slice(0, 12).join(" "));
+        if (v.items && typeof v.items === "object" && typeof v.items.description === "string") {
+          parts.push(v.items.description);
+        }
+      }
+    }
+    if (Array.isArray(schema.required) && schema.required.length) {
+      parts.push(`required ${schema.required.join(" ")}`);
+    }
+  }
+  if (tool.server) parts.push(String(tool.server));
+  return parts.join(" ").slice(0, MAX_BODY_CHARS);
+}
+
+/**
+ * 在候选集内按正文重排。
+ *
+ * @param {string} query
+ * @param {Array<{id: string}>} candidates  已按元数据名次排好序
+ * @param {Map<string, object>} byName
+ * @param {{weight?: number, bodyText?: Function}} [opts]
+ * @returns {Array<{id: string, score: number, metaRank: number, bodyScore: number}>}
+ */
+export function rerankByBody(query, candidates, byName, opts = {}) {
+  const list = Array.isArray(candidates) ? candidates.filter((c) => c && c.id) : [];
+  if (!list.length) return [];
+  const w = Number(opts.weight);
+  // 默认 0.45：eval/sweep.mjs 扫描 40 条标注查询得 82.5% top-1 / 0.9021 MRR（最优）。
+  // 旧值 0.35 是 80.0% / 0.8896。0.50 起开始掉。见文件头 2026-10-31 升级说明。
+  const weight = Number.isFinite(w) && w >= 0 && w <= 1 ? w : 0.45;
+  const bodyOf = typeof opts.bodyText === "function" ? opts.bodyText : toolBodyText;
+
+  const q = String(query || "").trim();
+  const qTokens = [...new Set(tokenize(q))];
+  const qLower = q.toLowerCase().replace(/\s+/g, " ");
+
+  if (!qTokens.length) {
+    return list.map((c, i) => ({ id: c.id, score: 1 / (1 + i), metaRank: i, bodyScore: 0 }));
+  }
+
+  // 候选集内的 df / idf（小集合上算，不依赖全局语料）
+  const bodies = new Map();
+  const df = new Map();
+  for (const c of list) {
+    const tool = byName.get(c.id);
+    const text = bodyOf(tool || { name: c.id });
+    const tokens = tokenize(text);
+    const set = new Set(tokens);
+    bodies.set(c.id, { text: text.toLowerCase(), tokens: set, len: tokens.length });
+    for (const t of set) df.set(t, (df.get(t) || 0) + 1);
+  }
+  const n = list.length;
+  const idf = (t) => Math.log((n - (df.get(t) || 0) + 0.5) / ((df.get(t) || 0) + 0.5) + 1);
+  // 分母只算「候选正文里真的出现过」的查询词。否则中文 bigram（工具描述多是英文，
+  // bigram 全 df=0）会把分母撑大，正文分被稀释到接近 0，精排等于没生效。
+  const matchedQ = qTokens.filter((t) => (df.get(t) || 0) > 0);
+  const qIdfSum = (matchedQ.length ? matchedQ.reduce((s, t) => s + idf(t), 0) : 0) || 1;
+
+  const scored = list.map((c, i) => {
+    const b = bodies.get(c.id);
+    if (!b) return { id: c.id, score: 1 / (1 + i), metaRank: i, bodyScore: 0 };
+    let hit = 0;
+    for (const t of qTokens) {
+      if (b.tokens.has(t)) hit += idf(t);
+    }
+    // 覆盖率 0..1，再乘一个「命中密度」修正：短正文命中更可信
+    let bodyScore = hit / qIdfSum;
+    if (bodyScore > 0 && b.len > 0) {
+      bodyScore *= 0.85 + 0.15 * Math.min(1, hit / Math.sqrt(b.len));
+    }
+    if (qLower.length >= 4 && b.text.includes(qLower)) bodyScore = Math.min(1, bodyScore + 0.15);
+    return { id: c.id, score: 0, metaRank: i, bodyScore };
+  });
+
+  // ---- 融合 ----
+  // 默认线性 w=0.45。这个数不是拍的，是 eval/sweep.mjs 在 40 条标注查询上扫出来的：
+  //   w=0.35（旧默认）top-1 80.0% / MRR 0.8896
+  //   w=0.45（新默认）top-1 82.5% / MRR 0.9021   ← 最优
+  //   w=0.50 起开始掉（77.5%），w=0.60 掉到 75%
+  // 同时修掉了旧权重的病态案例：正文 0.91 的 serena 输给正文 0.00 的 git。
+  //
+  // RRF 保留为可选（fusion:'rrf'），但**实测在本语料上不优于线性**：
+  // 最高 80.0%，与「纯元数据」持平。原因是候选集只有 6 个、正文分噪声大，
+  // 排名融合表达不了「元数据远比正文可信」这件事，而小权重线性可以。
+  // 保留它的理由：当 meta 与 body 的分数量纲不可比时（例如接入语义腿后
+  // 余弦相似度 0~1 与 BM25 分数 0~20 混在一起），RRF 才是正确工具。
+  const fusion = opts.fusion === "rrf" ? "rrf" : "linear";
+
+  if (fusion === "linear") {
+    // 旧行为（保留兼容）：分数线性加权。注意 w 存在天花板问题，见文件头注释。
+    for (const s of scored) {
+      s.score = (1 - weight) * (1 / (1 + s.metaRank)) + weight * s.bodyScore;
+    }
+  } else {
+    // RRF（默认）：只融合名次，不做分数校准。
+    //   score = Σ_lists  w_list / (k + rank_list)
+    const k = Number.isFinite(opts.rrfK) && opts.rrfK > 0 ? opts.rrfK : 60;
+    const wMeta = Number.isFinite(opts.rrfMetaWeight) ? opts.rrfMetaWeight : 1;
+    const wBody = Number.isFinite(opts.rrfBodyWeight) ? opts.rrfBodyWeight : 1;
+
+    // 正文名次：按 bodyScore 降序；同分时沿用元数据名次，保证确定性
+    const bodyOrder = [...scored]
+      .sort((a, b) => b.bodyScore - a.bodyScore || a.metaRank - b.metaRank)
+      .map((s) => s.id);
+    const bodyRank = new Map(bodyOrder.map((id, i) => [id, i]));
+
+    for (const s of scored) {
+      const br = bodyRank.get(s.id) ?? scored.length;
+      s.score = wMeta / (k + s.metaRank) + wBody / (k + br);
+    }
+  }
+
+  scored.sort((a, b) => b.score - a.score || a.metaRank - b.metaRank);
+  return scored;
+}

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,27 +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; // P3-2 (2026-09-02): configurable via configureSemantic
+let _timeout = EMBED_TIMEOUT_MS;
 
 /**
- * Configure the endpoint (called by plugin apply with cfg.ollamaBase/model).
- * @param {{ollamaBase?: string, embedModel?: string, embedTimeoutMs?: number}} 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 (Number.isFinite(cfg.embedTimeoutMs) && cfg.embedTimeoutMs >= 100) _timeout = cfg.embedTimeoutMs;
+  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 = _timeout) {
+/** 缓存的身份键：换了端点或模型就必须整体重建，不能复用旧向量。 */
+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 {
@@ -122,10 +157,42 @@ export async function embedText(text, timeoutMs = _timeout) {
       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;
@@ -141,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 = _timeout, opts = {}) {
-  const out = { vectors: new Map(), available: false };
+  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
-      }
+    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) {
-      v = await embed(d.text, timeoutMs);
-      if (v) fresh[d.id] = v;
-    }
-    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
@@ -236,8 +351,20 @@ export async function buildSemanticIndex(docs, timeoutMs = _timeout, opts = {})
 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);
@@ -250,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 };