dsh-tool-folder 0.3.0 → 0.3.2

package/README.md

@@ -107,7 +107,10 @@ were never unregistered, so nothing else changes.
 | include | [] | whitelist: exact name or `prefix*`. Non-empty → only matching tools are injected (meta tools exempt; deny still wins). Execution is NOT gated by include. |
 | toonifyResults | false | compact long JSON results after execution (drop empty fields + truncate strings; only when the text block is >2000 chars and parses as JSON) |
 | maxFoldMs | 50 | hard cap; beyond this keep the full list |
-| semanticEnabled | true | **v0.1.8**: tools_search semantic leg — BM25 + local bge-m3 (Ollama) RRF hybrid. Chinese intents hit English-only tools (the documented BM25 gap). Index lazily built + disk-cached (`~/.dsh/state/semantic-cache.json`); Ollama offline/timeout degrades to BM25-only, never slower or worse. |
+| semanticEnabled | true | 语义腿总开关。检索融合顺序：**本地静态嵌入（`lib/static-embed/`）→ 远程 embedding → 本地 Ollama → 纯 BM25**；任一层缺失或失败自动降级，绝不比纯 BM25 更慢或更差 |
+| staticWeight | 0.15 | **v0.3.2**: 本地静态嵌入腿在 RRF 中的权重。实测最优 0.15 —— 静态腿只负责补词法查不到的坑，压过词法会引入噪声（留出集 w=0.15 → recall@3 0.621，w=2 → 0.517） |
+| staticEmbedDir | '' | **v0.3.2**: 静态嵌入目录（含 `vocab.json` / `vectors.bin` / `scales.bin` / `meta.json`）。留空 = 用插件自带的 `lib/static-embed`；目录不存在则该腿自动跳过 |
+| semanticWeight | 3 | **远程** embedding 腿在 RRF 中的权重：1=等权，3=偏语义（默认），0=纯 BM25。与 `staticWeight` 分开配置，因为远程 bge-m3 质量更高 |
 | ollamaBase | http://127.0.0.1:11434 | Ollama endpoint for the semantic leg |
 | embedModel | bge-m3 | embedding model for the semantic leg |
 | feedbackFile | '' | feedback JSON path (default `$DSH_HOME/logs/tool-folder/`) |
@@ -115,7 +118,11 @@ were never unregistered, so nothing else changes.
 
 ## Files
 
-- `lib/bm25.js` — zero-dep BM25 (k1=1.2, b=0.75; CN bigrams + EN tokens)
+- `lib/bm25.js` — zero-dep BM25 (k1=1.2, b=0.75; camelCase split + CN bigrams + EN tokens)
+- `lib/expand.js` — **v0.3.1**: CN/EN dev-intent thesaurus + reverse alias expansion
+- `lib/rerank.js` — **v0.3.1**: body-level rerank (weight 0.45) + optional RRF fusion
+- `lib/static-embed.js` — **v0.3.2**: offline static embedding (lookup + mean-pool + cosine, zero deps)
+- `lib/static-embed/` — **v0.3.2**: 7760 × 256 int8 table, 2.01 MB, built by `tools/build-static-embed.py`
 - `lib/semantic.js` — v0.2.0 semantic leg: local bge-m3 embeddings (Ollama) + RRF fusion, disk-cached
 - `lib/chainguard.js` — ChainGuard firewall: literal patterns + exfil-chain detection + deobfuscation
 - `lib/obfuscation.js` — v0.2.0 anti-obfuscation: concat rebuild, `-enc`/certutil/bitsadmin shapes, homoglyphs
@@ -149,6 +156,65 @@ were never unregistered, so nothing else changes.
 
 ## Changelog
 
+### v0.3.2 — 离线静态嵌入语义腿（不装 Ollama / 不续 Ark 也能有语义，2026-10-31）
+
+**动机**：v0.3.0 的语义腿两条路全断——Ark `doubao-embedding` 返回 400
+`InvalidSubscription`（订阅过期），Ollama 未安装（`11434` HTTP 000）。
+在 29 条**留出查询**上实测，`v0.3.1` 的纯词法+词表只能到 **recall@3 = 0.448**，
+剩下 55% 是词表覆盖不到的改写。
+
+**做法**（`MinishLab/model2vec` 思路：把 sentence transformer 压成一张查找表）：
+
+- 源模型 `minishlab/potion-multilingual-128M`（分词器 `BAAI/bge-m3`），
+  50 万 token × 256 维 = 512 MB fp32
+- **剪枝**：只保留 ① 领域文本用到的 token ② 全部单字 CJK（7688）→ 7760 行
+- **int8 量化**：每行独立 scale，行先 L2 归一化，平均余弦保真度 **0.99995**
+- 产物 **2.01 MB**（`lib/static-embed/`），运行期只做 查表 + 均值池化 + 余弦
+  —— 无推理图、无 onnx、无 WASM、无网络、无外部依赖，单次 embed < 1 ms
+
+构建脚本 `tools/build-static-embed.py`（纯本地计算，读本地 safetensors）。
+
+**融合权重单列**：新增 `staticWeight`（默认 **0.15**），与远程腿的
+`semanticWeight`（默认 3）分开。整组压测（`eval/sweep-static.mjs`，留出集）：
+
+| bm25 : static | 1:0 | **1:0.15** | 1:0.3 | 1:0.5 | 1:1 | 1:2 |
+|---|---|---|---|---|---|---|
+| recall@3 | 0.448 | **0.621** | 0.586 | 0.586 | 0.552 | 0.517 |
+
+**静态腿的价值是「补词法查不到的坑」，不是压过词法**——权重一高，它的噪声就会
+把本来对的词法结果挤下去。本地腿同时固定 `bmWeight = 1`，不叠加 `adaptiveBm` 的中文降权。
+
+**实测（29 条留出查询 / 40 条标注查询）**
+
+| 指标 | v0.3.1 | v0.3.2 |
+|---|---|---|
+| 留出集 recall@3 | 0.448 | **0.621** |
+| 留出集 recall@6 | 0.448 | **0.655** |
+| 留出集 MRR | 0.379 | **0.506** |
+| 标注集 recall@3 | 1.000 | 1.000 |
+| 标注集 MRR | 0.888 | **0.904** |
+
+**修掉一个会让结果变差的隐患**：查询向量为空时（整句 token 全在词表外）原会照常进融合，
+所有文档余弦都是 0，排序退化为插入顺序，给 topK 塞进一批无关工具。现在直接跳过本地腿。
+
+**测过但否掉的方案**（负结果同样重要）：等权/高权重 RRF、按词法证据量自适应打折、
+SIF 加权池化 + 去主成分——均无可靠收益，详见 `CHANGELOG-v0.3.2.md`。
+
+### v0.3.1 — 分词器 + 意图词表 + 精排权重（2026-10-31）
+
+新增 `eval/` 评测基础设施（36 个混合工具 / 40 条查询 + 29 条留出集 /
+`run.mjs` `rerank.mjs` `sweep.mjs`），此后每次调参都有数据依据。
+
+1. **`bm25.js` 修分词**：camelCase 拆分原先在 `toLowerCase()` 之后跑，
+   `searchNotes` 变成整串 `searchnotes`，查 "notes" 零命中；补 CJK 高频功能词
+   bigram 黑名单（`这个/一下/怎么` 等，IDF≈0 却撑大 `avgdl`）。
+2. **`expand.js`（新增）**：约 60 组中英开发意图词表 + 反向别名扩展。
+   这是唯一能救「首轮零命中」的手段——标注集 recall@3 0.725 → 1.000。
+3. **`rerank.js`**：修掉权重天花板（w=0.35 时元数据第 0 位底分 0.65、正文满分仅 0.35，
+   正文以 0.91 输给 0.00），扫描最优值 **0.45**；新增 `fusion: 'rrf'` 选项。
+4. **`index.js`**：把 `eq` 拆成 `eqStr`（喂语义腿，字符串）与 `eq`（喂 BM25，token 数组），
+   修掉一处「语义腿一激活就崩」的隐患。
+
 ### v0.3.0 — 语义腿真正可用 + 融合修正（2026-10-17）
 
 **动机（实测发现的真问题，不是推测）**：本机没装 Ollama（`127.0.0.1:11434` 返回

package/lib/bm25.js

@@ -17,6 +17,17 @@
  *
  * Cordis sandbox note: this module only does string/number math. It never
  * touches fs/net/process, so it is safe in any host or sandbox context.
+ *
+ * ---- 2026-10-31 升级（v0.3.1）----
+ *   1. camelCase / PascalCase 拆分：`searchNotes` 之前的正则在 lowercase 后
+ *      拿到的是整串 `searchnotes`，查询 "notes" 零命中；现在先按驼峰拆再降小写。
+ *   2. CJK 功能词 bigram 过滤：「这个 / 一下 / 怎么 / 帮我」这类 bigram 几乎每句
+ *      都有，IDF 接近 0 却会撑大 avgdl，把真正有区分度的词稀释掉。
+ *   3. BM25+ delta 项（可选，默认 0）：标准 BM25 对「命中但频次低」的文档给分
+ *      偏低；delta 给每个命中词一个下限分，短查询召回更稳。
+ *      参考 ratel ADR-0023 的实测：改 b 只重排已召回的（recall 不变、MRR 上升），
+ *      而 delta 是真正补召回的手段，两者不冲突。
+ *   4. k1 / b 可配置（默认仍 1.2 / 0.75，与 ratel 收敛后的取值一致）。
  */
 
 const K1 = 1.2;
@@ -31,28 +42,67 @@ const EN_STOP = new Set([
   "your", "my", "our", "their", "its", "all", "any", "some", "each",
 ]);
 
+/**
+ * 中文高频功能词 bigram。这些词在几乎每个中文工具描述/查询里都出现，
+ * 信息量接近 0，留在索引里只会抬高 avgdl、稀释有区分度的词。
+ * 只过滤 bigram 层，不影响单字信息（单字本来就不进索引）。
+ */
+const CJK_STOP_BIGRAM = new Set([
+  "这个", "那个", "这些", "那些", "一个", "一下", "一种", "一些",
+  "什么", "怎么", "怎样", "如何", "可以", "是否", "然后", "所以",
+  "但是", "而且", "或者", "还是", "如果", "因为", "虽然", "已经",
+  "我们", "你们", "他们", "自己", "现在", "刚才", "帮我", "给我",
+  "看看", "试一下", "用的", "的是", "了的", "了吗", "的话",
+  "这里", "那里", "里面", "上面", "下面", "之后", "之前", "时候",
+]);
+
+/** camelCase / PascalCase / 数字边界拆分：searchNotes -> search, notes */
+function splitCamel(word) {
+  if (!/[A-Z]/.test(word)) return [];
+  // 在「小写/数字 → 大写」和「连续大写 → 大写+小写」处断
+  const parts = word
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/\s+/)
+    .filter(Boolean);
+  return parts.length > 1 ? parts : [];
+}
+
 /** Tokenize mixed CN/EN text into lowercase tokens. */
 function tokenize(text) {
   const out = [];
-  const s = String(text || "").toLowerCase();
-  for (const m of s.matchAll(/[a-z0-9][a-z0-9_+-]{1,}/g)) {
-    const t = m[0];
+  const raw = String(text || "");
+  const lower = raw.toLowerCase();
+
+  // --- ASCII（在原文上跑，保留大小写信息以便拆驼峰）---
+  for (const m of raw.matchAll(/[A-Za-z0-9][A-Za-z0-9_+-]{1,}/g)) {
+    const word = m[0];
+    const t = word.toLowerCase();
     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.
+
+    // 驼峰拆分（v0.3.1 新增）：searchNotes -> searchnotes + search + notes
+    for (const part of splitCamel(word)) {
+      const p = part.toLowerCase();
+      if (p.length > 1 && p !== t && !EN_STOP.has(p)) out.push(p);
+    }
+
+    // 连字符/下划线拆分。没有这一步，工具名
+    // "mcp__open-design__start_run" 是 ONE term，查 "design" 零分。
+    // 整词保留，子词只增加召回，不动精确匹配与既有 IDF。
     if (t.length > 2 && (t.includes("-") || t.includes("_"))) {
-      for (const part of t.split(/[-_]+/)) {
+      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.
-  const cjk = s.replace(/[^\u4e00-\u9fff]/g, "");
+
+  // --- CJK bigram ---
+  const cjk = lower.replace(/[^\u4e00-\u9fff]/g, "");
   if (cjk.length >= 2) {
-    for (let i = 0; i + 2 <= cjk.length; i++) out.push(cjk.slice(i, i + 2));
+    for (let i = 0; i + 2 <= cjk.length; i++) {
+      const bg = cjk.slice(i, i + 2);
+      if (!CJK_STOP_BIGRAM.has(bg)) out.push(bg);
+    }
   }
   return out;
 }
@@ -81,8 +131,15 @@ function buildIndex(docs) {
   return { n, docTokens, df, avgdl };
 }
 
-/** Score one doc's token list against the query's IDF map. */
-function score(tokens, queryIdf, n, avgdl) {
+/**
+ * Score one doc's token list against the query's IDF map.
+ * opts.delta 启用 BM25+ 的 TF 下限项（默认 0 = 标准 BM25）。
+ */
+function score(tokens, queryIdf, n, avgdl, opts = {}) {
+  const k1 = Number.isFinite(opts.k1) ? opts.k1 : K1;
+  const b = Number.isFinite(opts.b) ? opts.b : B;
+  const delta = Number.isFinite(opts.delta) ? opts.delta : 0;
+
   const tf = new Map();
   for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
   let acc = 0;
@@ -90,7 +147,8 @@ function score(tokens, queryIdf, n, avgdl) {
   for (const [term, idf] of queryIdf) {
     const f = tf.get(term);
     if (!f) continue;
-    acc += idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + (B * dl) / avgdl)));
+    const sat = (f * (k1 + 1)) / (f + k1 * (1 - b + (b * dl) / avgdl));
+    acc += idf * (sat + delta);
   }
   return acc;
 }
@@ -98,14 +156,16 @@ function score(tokens, queryIdf, n, avgdl) {
 /**
  * Search an index. Returns up to topK doc ids sorted by BM25 score desc.
  * @param index   result of buildIndex
- * @param query   raw query string (mixed CN/EN ok)
+ * @param query   raw query string (mixed CN/EN ok) 或已扩展的 token 数组
  * @param topK    max results (default 10)
- * @param opts    {filter: (docId) => boolean}
+ * @param opts    {filter: (i)=>boolean, k1, b, delta}
  */
 function search(index, query, topK = 10, opts = {}) {
   const { n, docTokens, df, avgdl } = index;
   if (!n || !query) return [];
-  const qTerms = tokenize(query);
+
+  // 支持「已扩展的多词查询」：数组直接当 token 用，字符串走分词
+  const qTerms = Array.isArray(query) ? query : tokenize(query);
   if (qTerms.length === 0) return [];
 
   const queryIdf = new Map();
@@ -117,11 +177,31 @@ function search(index, query, topK = 10, opts = {}) {
 
   const scored = [];
   for (let i = 0; i < n; i++) {
-    const s = score(docTokens[i], queryIdf, n, avgdl);
+    const s = score(docTokens[i], queryIdf, n, avgdl, opts);
     if (s > 0 && (!opts.filter || opts.filter(i))) scored.push([i, s]);
   }
-  scored.sort((a, b) => b[1] - a[1]);
+  scored.sort((a, b2) => b2[1] - a[1]);
   return scored.slice(0, topK).map(([i]) => i);
 }
 
-export { tokenize, buildIndex, search, score };
+/** 带分数的版本，供 RRM / 融合类算法使用。 */
+function searchScored(index, query, topK = 10, opts = {}) {
+  const { n, docTokens, df, avgdl } = index;
+  if (!n || !query) return [];
+  const qTerms = Array.isArray(query) ? query : tokenize(query);
+  if (qTerms.length === 0) return [];
+  const queryIdf = new Map();
+  for (const t of qTerms) {
+    const d = df.get(t) || 0;
+    queryIdf.set(t, Math.log((n - d + 0.5) / (d + 0.5) + 1));
+  }
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const s = score(docTokens[i], queryIdf, n, avgdl, opts);
+    if (s > 0 && (!opts.filter || opts.filter(i))) out.push([i, s]);
+  }
+  out.sort((a, b2) => b2[1] - a[1]);
+  return out.slice(0, topK);
+}
+
+export { tokenize, buildIndex, search, searchScored, score, splitCamel, CJK_STOP_BIGRAM };

package/lib/expand.js

@@ -0,0 +1,276 @@
+/**
+ * expand.js — 查询扩展（零依赖、纯本地）
+ *
+ * 解决的核心问题（2026-10-31 评测实测）：
+ *   「上网查一下这个报错怎么解决」→ 期望 web_search，实得 **空**
+ *   「谁在调这个方法」          → 期望 find_references，实得 **空**
+ *   「把这个配置改成新的值」     → 期望 write/edit，实得 **空**
+ *
+ * 根因：纯字面 bigram 匹配没有同义桥接。「上网」和工具描述里的「联网」是两个
+ * 不相交的 bigram；「方法」和「符号」也是。字面不重合 = 零分 = 召回为 0。
+ *
+ * 三条互补的扩展路径：
+ *
+ *   1. 内置开发词表（thesaurus）——覆盖最高频的意图词，中英双向。
+ *      这是唯一能救「首轮零命中」的手段：RM3 需要先有结果才能反馈，
+ *      零命中时它无从下手（鸡生蛋问题）。
+ *
+ *   2. 反向别名扩展（alias 反向）——配置里的 aliases 是
+ *      canonical → [同义词]，只用于「工具能被哪些词命中」。这里做反查：
+ *      查询里出现某个同义词时，把 canonical 也加进查询。
+ *
+ *   3. RM3 伪相关反馈（Lavrenko & Croft 2001，Anserini / Lucene 同款思路）——
+ *      首轮 top-k 结果里抽高权重的词，与原查询加权拼接后二次检索。
+ *      只在首轮有结果时生效，用来扩大召回并纠正漂移。
+ *
+ * 设计约束：不碰 fs / net，纯字符串与数字运算；单次扩展 < 0.1ms。
+ */
+
+/**
+ * 内置中英开发词表。
+ * key 是会被用户在查询里打出来的词；value 是要注入查询的扩展词
+ * （已小写、已分词形态：英文单词 + 中文 bigram）。
+ */
+const THESAURUS = {
+  // ---- 文件读写 ----
+  "看看": ["read", "读取", "内容", "查看"],
+  "查看": ["read", "读取", "内容"],
+  "读取": ["read", "读取"],
+  "打开": ["read", "open", "读取"],
+  "内容": ["read", "读取", "content"],
+  "写入": ["write", "写入", "保存"],
+  "保存": ["write", "保存"],
+  "改成": ["write", "edit", "修改"],
+  "修改": ["edit", "write", "修改", "替换"],
+  "替换": ["edit", "替换"],
+  "删掉": ["edit", "delete", "删除"],
+  "删除": ["delete", "remove", "删除", "移除"],
+  "移除": ["remove", "删除"],
+
+  // ---- 搜索 ----
+  "搜": ["search", "搜索", "查找", "grep"],
+  "搜索": ["search", "搜索", "查找"],
+  "查找": ["search", "find", "查找", "grep"],
+  "找": ["find", "search", "查找"],
+  "上网": ["web", "联网", "搜索", "search"],
+  "联网": ["web", "联网"],
+  "网络": ["web", "网络"],
+  "网页": ["web", "fetch", "抓取"],
+  "抓": ["fetch", "抓取"],
+
+  // ---- 代码符号 ----
+  "方法": ["symbol", "function", "符号", "定义"],
+  "函数": ["symbol", "function", "符号"],
+  "符号": ["symbol", "符号"],
+  "定义": ["symbol", "definition", "定义"],
+  "调用": ["references", "caller", "引用"],
+  "引用": ["references", "引用"],
+  "调": ["references", "call", "引用"],
+  "谁": ["references", "caller", "引用"],
+
+  // ---- Git ----
+  "改动": ["diff", "status", "差异", "改动"],
+  "改了": ["diff", "edit", "改动"],
+  "改": ["edit", "write", "diff", "修改", "改动"],
+  "行": ["line", "diff", "行"],
+  "哪些行": ["diff", "line"],
+  "差异": ["diff", "差异"],
+  "提交": ["commit", "提交"],
+  "历史": ["log", "history", "历史"],
+  "分支": ["branch", "分支"],
+  "工作区": ["status", "工作区"],
+
+  // ---- 安全 ----
+  "安全": ["security", "安全", "semgrep", "审计"],
+  "漏洞": ["vulnerability", "security", "漏洞"],
+  "审计": ["audit", "审计"],
+  "扫描": ["scan", "扫描"],
+
+  // ---- 笔记 / 知识 ----
+  "笔记": ["note", "笔记", "notes"],
+  "文档": ["note", "document", "文档"],
+  "资料": ["document", "资料", "笔记"],
+  "记一条": ["note", "create", "新建"],
+
+  // ---- 交互 / 杂项 ----
+  "报错": ["error", "错误", "异常"],
+  "错误": ["error", "错误"],
+  "异常": ["error", "异常", "exception"],
+  "解决": ["error", "fix", "解决"],
+  "问": ["ask", "question", "提问"],
+  "截屏": ["screenshot", "截图", "screen"],
+  "截图": ["screenshot", "截图"],
+  "截": ["screenshot", "截屏"],
+  "屏": ["screenshot", "screen", "截屏"],
+  "个屏": ["screenshot", "截屏"],
+  "剪贴板": ["clipboard", "剪贴板"],
+  "复制": ["clipboard", "复制"],
+  "讲": ["explain", "讲解", "概念"],
+  "讲讲": ["explain", "讲解"],
+  "概念": ["explain", "concept", "概念"],
+  "浏览器": ["browser", "navigate", "浏览器"],
+  "网址": ["navigate", "url", "网址"],
+  "按钮": ["click", "点击", "按钮"],
+  "点击": ["click", "点击"],
+  "画布": ["canvas", "frame", "画布"],
+  "画框": ["frame", "画框"],
+  "技能": ["skill", "技能"],
+  "交给": ["delegate", "委派"],
+  "委派": ["delegate", "委派"],
+  "拆开": ["subagent", "delegate", "并行"],
+  "并行": ["subagent", "并行"],
+  "跑": ["exec", "run", "执行", "命令"],
+  "执行": ["exec", "执行", "命令"],
+  "命令": ["exec", "command", "命令"],
+  "想想": ["thinking", "reason", "推理"],
+  "一步步": ["thinking", "step", "推理"],
+  "影响": ["impact", "影响", "波及"],
+  "文件": ["file", "文件"],
+};
+
+/** 从中文/英文原文里抽候选词（供词表查表用，不做 IDF 计算） */
+function probeTerms(text) {
+  const out = new Set();
+  const raw = String(text || "");
+  const lower = raw.toLowerCase();
+
+  for (const m of raw.matchAll(/[A-Za-z0-9][A-Za-z0-9_+-]{1,}/g)) {
+    out.add(m[0].toLowerCase());
+  }
+  const cjk = lower.replace(/[^\u4e00-\u9fff]/g, "");
+  // 单字 + bigram 都作为探针，词表的 key 以 1~3 字为主
+  for (let i = 0; i < cjk.length; i++) {
+    out.add(cjk[i]);
+    if (i + 1 < cjk.length) out.add(cjk.slice(i, i + 2));
+    if (i + 2 < cjk.length) out.add(cjk.slice(i, i + 3));
+  }
+  return out;
+}
+
+/**
+ * 用内置词表 + 反向别名扩展查询。
+ * @param {string} query
+ * @param {{aliases?: object, extra?: object}} [opts]
+ * @returns {string[]} 扩展后的 token 数组（可直接喂 bm25.search）
+ */
+function expandQuery(query, opts = {}) {
+  const probes = probeTerms(query);
+  const added = new Set();
+
+  // 1) 内置词表
+  for (const p of probes) {
+    const syn = THESAURUS[p];
+    if (syn) for (const s of syn) added.add(s);
+  }
+
+  // 2) 反向别名：aliases = { canonical: [syn...] }
+  //    查询里出现某个 syn → 把 canonical 加进来
+  const aliases = opts.aliases || {};
+  for (const [canonical, syns] of Object.entries(aliases)) {
+    if (!Array.isArray(syns)) continue;
+    const canon = String(canonical).toLowerCase();
+    for (const s of syns) {
+      const syn = String(s).toLowerCase();
+      if (probes.has(syn)) {
+        added.add(canon);
+        break;
+      }
+    }
+  }
+
+  // 3) 额外词表（调用方可注入）
+  for (const p of probes) {
+    const syn = (opts.extra || {})[p];
+    if (syn) for (const s of syn) added.add(s);
+  }
+
+  return [...added];
+}
+
+/**
+ * RM3 伪相关反馈检索。
+ *
+ * 首轮用原查询取 top-k，从这些文档里按 tf·idf 抽 top-N 词，
+ * 与原查询按 mu 加权融合后二次检索。
+ * 首轮零命中时直接返回空（RM3 无从反馈）。
+ *
+ * @param index    bm25.buildIndex 的产物
+ * @param query    原始查询字符串
+ * @param bm25     bm25 模块（要能拿到 tokenize / score）
+ * @param {{topK?:number, fbDocs?:number, fbTerms?:number, mu?:number, expanded?:string[]}} opts
+ * @returns {number[]} doc 索引数组
+ */
+function searchWithFeedback(index, query, bm25, opts = {}) {
+  const topK = opts.topK ?? 6;
+  const fbDocs = opts.fbDocs ?? 5;
+  const fbTerms = opts.fbTerms ?? 8;
+  const mu = opts.mu ?? 0.65; // 原查询权重
+
+  const { n, docTokens, df, avgdl } = index;
+  if (!n) return [];
+
+  const orig = bm25.tokenize(query);
+  if (!orig.length) return [];
+
+  // 若调用方已给定扩展词，直接并进原查询
+  const baseTerms = orig.concat(opts.expanded || []);
+  const first = bm25.searchScored
+    ? bm25.searchScored(index, baseTerms, topK)
+    : bm25.search(index, baseTerms, topK).map(i => [i, 0]);
+
+  if (!first.length) return [];
+
+  // ---- 从 top 文档抽反馈词 ----
+  const fb = new Map(); // term -> weight
+  const topDocs = first.slice(0, fbDocs);
+  let totalScore = 0;
+  for (const [, s] of topDocs) totalScore += s;
+
+  for (const [di, s] of topDocs) {
+    const docWeight = totalScore > 0 ? s / totalScore : 1 / topDocs.length;
+    const tf = new Map();
+    for (const t of docTokens[di]) tf.set(t, (tf.get(t) || 0) + 1);
+    const seen = new Set(orig);
+    for (const [t, f] of tf) {
+      if (seen.has(t)) continue; // 原查询已有的词不重复加
+      const d = df.get(t) || 0;
+      const idf = Math.log((n - d + 0.5) / (d + 0.5) + 1);
+      fb.set(t, (fb.get(t) || 0) + docWeight * f * idf);
+    }
+  }
+
+  const expansion = [...fb.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, fbTerms)
+    .map(([t]) => t);
+
+  if (!expansion.length) return first.map(([i]) => i);
+
+  // ---- 加权融合：原查询词权重 mu，反馈词权重 (1-mu) 均分 ----
+  // 注意：不能靠「重复词」加权——search 内部用 Map 按词去重，重复无效。
+  // 这里自己构造 queryIdf，把权重直接乘进 idf。
+  const queryIdf = new Map();
+  const origSet = new Set(baseTerms);
+  for (const t of origSet) {
+    const d = df.get(t) || 0;
+    const idf = Math.log((n - d + 0.5) / (d + 0.5) + 1);
+    queryIdf.set(t, idf * mu);
+  }
+  const perTerm = (1 - mu) / Math.max(1, expansion.length);
+  for (const t of expansion) {
+    const d = df.get(t) || 0;
+    const idf = Math.log((n - d + 0.5) / (d + 0.5) + 1);
+    const prev = queryIdf.get(t) || 0;
+    queryIdf.set(t, prev + idf * perTerm);
+  }
+
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const s = bm25.score(docTokens[i], queryIdf, n, avgdl);
+    if (s > 0) out.push([i, s]);
+  }
+  out.sort((a, b) => b[1] - a[1]);
+  return out.slice(0, topK).map(([i]) => i);
+}
+
+export { expandQuery, searchWithFeedback, probeTerms, THESAURUS };