dsh-engramory-recall 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.11.2] — 2026-10-15
+
+### 变更
+
+- **把「换措辞再搜一次」写进模型看得见的地方**：`engramory_search` 的工具描述补一句
+  「它匹配的是措辞不是意思 —— 没命中就自己换个说法再搜一次（同义词、术语英文、笔记里可能用的词）」，
+  未命中时的提示也从「换关键词再试」改成同一句话。依据是宿主模型改写那把尺子量出来的：
+  同一个意思换个说法能命中而原句命不中的比例是 **80.6%**（词面自身 72.2%），
+  而让插件内置去「融合模型改写」是负收益。所以这个能力交给调用方用，而不是塞进检索里。
+
+## [0.11.1] — 2026-10-15
+
+### 修复
+
+- **`expand` 型语义提供方改为「只补空位」**：词面排出来的顺序一个字不动，改写带来的新文档接在后面
+  （`semantic` 字段新增 `added`，报补了几条）。此前 `expand` 走的是与 `rerank` 相同的 RRF 融合 ——
+  用真宿主模型实测，那是**负收益**：模型给的 3 条改写融合进来后，真库探针 hit@1 从 72.2% 掉到 52.8%
+  （RRF k=60），归一化取最大更是掉到 27.8%。原因是投票数变成 4 倍，而词面那 1 票并不比模型那 3 票
+  更该被信任。证据与全部变体见 README「让宿主模型当改写提供方」一节。
+- 回归测试：`test/semantic.test.mjs` 把 expand 的两种情形分别钉住（词面占满 `limit` 时必须逐字相同；
+  词面不足时只许接在后面）；`test/semantic-corpus.test.mjs` 新增一例 —— 用「同一篇笔记的其它问法」
+  当**真实的好改写**（这正是能把旧实现打出 -7 hit@1 的那类输入），在 117 条真语料查询上断言命中与
+  词面逐条相同、`added` 恒为 0。
+
+### 新增
+
+- **宿主模型改写尺子**（`bench/host-rewrite.mjs`，`npm run bench:rewrite`）：以本机 harness 为
+  「真宿主模型」逐条采集改写（提示词与解析直接 `import` 产品代码，缓存可续跑、`--offline` 可只重算），
+  再离线重放给真接缝。量三件事：逐条延迟、词面 vs 接缝的命中、以及「任意一条改写单独检索」的上界。
+  实测：延迟中位 3.8~4.2 秒、**70/70 与 36/36 都超出默认 2000ms 预算**；收益 0（与词面逐条相同）；
+  上界 50.0% / 80.6%（词面 70.0% / 72.2%）⇒ 信号在改写里，但宿主没有打分器，用不上。
+  `semantic.js` 为此导出 `hostLlmPrompt()` / `normalizeExpansions()`，保证尺子问的就是产品要问的那句话。
+- README：新增「实测：让宿主模型当改写提供方」小节（代价/收益/融合变体三张表 + 什么时候才值得开），
+  并把「拿模型改写去融合」记进「被实测证伪的路」（现十条）。
+
 ## [0.11.0] — 2026-10-15
 
 ### 新增

package/README.md

@@ -591,7 +591,7 @@ export async function rerank({ query, docs, limit, signal }) {
   return [{ id: 'reference-publish-plugin-to-npm.md', score: 0.91 }];
 }
 
-// 2) 扩展：把问题改写成几句别的说法，由插件分别检索再融合
+// 2) 扩展：把问题改写成几句别的说法，只用来**补空位**（词面排出来的顺序一个字不动）
 export async function expand({ query, signal }) {
   return ['npm 发布 token 403', '怎么把包发到 npm'];
 }
@@ -604,7 +604,7 @@ export async function expand({ query, signal }) {
 
 | 行为 | 为什么 |
 |---|---|
-| 结果是 **RRF 融合**，不是替换 | 同一个 limit 下输出就是同一批文档的重排（不会凭空多出、也不会丢；`test/semantic-corpus.test.mjs` 在真语料上钉这条）。Rerank 返回候选之外的文件名一律丢弃并报数 |
+| `rerank` 走 **RRF 融合**，`expand` **只补空位** | 同一个 limit 下 rerank 输出就是同一批文档的重排（不会凭空多出、也不会丢；`test/semantic-corpus.test.mjs` 在真语料上钉这条）。`expand` 若也拿去融合，实测 hit@1 掉 7~19pt（原因见下面「让宿主模型当改写提供方」）：词面那 1 票没有任何理由比模型那 3 票更该被信任。所以它只把词面没排上的文档**接在后面**，`added` 报补了几条。两种提供方返回候选之外的文件名一律丢弃并报数 |
 | 超时**硬兜一层** `Promise.race` | 提供方可以完全忽略 `AbortSignal`（第三方代码什么都干得出来），只靠 abort 会让检索永远等下去 |
 | 失败**不抛错**，降级回词面并如实报 `code` | `off` / `not-found` / `unsupported` / `provider-error` / `timeout` / `provider-empty`，检索工具返回值里的 `semantic` 字段直接给出这次到底用没用上 |
 | **只管按需检索工具**，不碰每轮自动注入 | 自动召回每个用户轮都跑；挂一个要 200ms 的外部件等于给每一轮加税。热路径永远纯词面 |
@@ -622,10 +622,10 @@ export async function expand({ query, signal }) {
 | 提供方卡住不返回 | 50.4% | 67.5% | **53.0 ms**（预算 50ms） | `timeout`×704 |
 | 提供方返回编造的 id | 50.4% | 67.5% | 1.4 ms | `provider-empty`×704 |
 | 离线字符三元组重排（真打分） | 47.4% | 65.5% | 1.4 ms | `reranked`×704 |
+| 按 gold 重排（**作弊上界**，只验管线） | 86.6% | 86.6% | 1.4 ms | `reranked`×610 |
 
 （候选池 = 20，评测看前 4 名。`node bench/semantic-seam.mjs --pool 4` 是另一种用法：池子等于输出量时
 RRF 只能在池内重排，所以 hit@4 一动都不动（67.5%），坏的提供方只赔 hit@1。两种都量过。）
-| 按 gold 重排（**作弊上界**，只验管线） | 86.6% | 86.6% | 1.4 ms | `reranked`×610 |
 
 三个数字值得单独说：
 
@@ -641,6 +641,43 @@ RRF 只能在池内重排，所以 hit@4 一动都不动（67.5%），坏的提
 `test/semantic-wiring.test.mjs`（关着时连 import 都不发生、开着时真的融合、自动注入不碰接缝）
 就是钉这四条的。
 
+#### 实测：让宿主模型当改写提供方（`npm run bench:rewrite`）
+
+`host-llm` 能跑通不等于划算，所以这条尺子用**真宿主模型**量了一遍（2026-10-15，逐条调用本机
+harness，提示词直接 `import` 产品的 `hostLlmPrompt()` —— 尺子问的就是产品要问的那句话；
+采集结果缓存在 `bench/.tmp/`，`--offline` 可以只重算不重采）：
+
+| 卷子 | 条数 | 延迟（中位 / p90 / 最大） | 超过默认 2000ms 预算 | 词面 → 接缝（hit@1 / hit@4） | 池内有 gold | 任意一条改写单独检索命中 gold@1 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 合成基准子集 | 70 | 3796ms / 11379ms / 14043ms | **70/70** | 70.0% / 87.1% → 逐条相同 | 68/70 | 50.0% |
+| 真库探针（36 条真实口语） | 36 | 4230ms / 9937ms / 10978ms | **36/36** | 72.2% / 100% → 逐条相同 | 36/36 | 80.6% |
+
+代价和收益在同一张表里，结论就一句：**信号在，但用不上**。
+
+- **延迟**：中位 3.8~4.2 秒，没有一次落在插件默认的 2000ms 预算里。这不是「把超时调大」能解决的 ——
+  按需检索是人等着的那种调用，挂 4 秒等于把插件废掉（自动召回每轮都跑，更不能挂）。
+- **收益**：改写**一条也没把 gold 从前 4 名里救出来**（两种卷子都与词面逐条相同）。
+- **上界**：模型给的 3 条改写里「任意一条单独检索」能命中 gold@1 的比例是 50.0% / 80.6%，
+  而词面是 70.0% / 72.2% —— 真库那卷高 8.4pt，说明**改写里确实有信号**；但要用上它，
+  得先有一个能判断「哪条改写更好」的打分器，而宿主只给对话接口、没有 embedding。
+
+「不知道好坏就投票」的后果也量了（同一批改写离线重放，`--json` 里是全部逐条数字）：
+
+| 融合策略 | 合成基准子集 hit@1 / hit@4 | 真库探针 hit@1 / hit@4 |
+| --- | --- | --- |
+| `append`（**当前实现**：词面顺序不动，只用改写补空位） | 70.0% / 87.1% | **72.2% / 100%** |
+| `gate`（只有词面什么也没查到时才用改写） | 70.0% / 87.1% | 72.2% / 100% |
+| RRF，k = 1 / 3 / 5 / 60 | 51.4% / 48.6% / 51.4% / 47.1% | 69.4% / 63.9% / 61.1% / 52.8% |
+| 归一化分数：求和 / 取最大 | 57.1% / 28.6% | 63.9% / 27.8% |
+
+模型写了 3 条「更好的查询」，融合却让 hit@1 掉 7~19 个百分点（真库 72.2% → 52.8%）：投票数变成
+4 倍，而词面那 1 票并不比模型那 3 票更该被信任。所以 0.11.1 起 `expand` 的语义就是**只补空位**，
+`semantic` 字段里的 `added` 会告诉你补了几条。
+
+**那 `host-llm` 还开不开？** 只有两种场合值得：你要一次拿满 limit 条（它补位不排序），
+或者你在自己写的脚本里拿它当**候选生成器**。插件这条路上更实际的做法是
+**你（agent）自己换个说法再检索一次** —— 你有能力判断哪条结果对，而且你的模型调用不是逐条同步的。
+
 ## 配置
 
 改 profile 的 `cordis.patch.yml`（改完要重启 App 才生效，宿主进程会缓存 ESM 模块）：
@@ -811,6 +848,7 @@ npm run probe -- --save   # 把这次结果存成基线，之后每次跑自动
 npm run bench:check       # 合成基准 + 和 bench/expectations.json 对账（CI 跑的就是它）
 npm run bench:bridges     # 同义表覆盖率尺子：死值、覆盖、使用面、逐键消融（--ablate / --json / --store）
 npm run bench:seam        # 语义接缝的代价与天花板（四种坏提供方 + 作弊上界）
+npm run bench:rewrite     # 宿主模型当改写提供方：真调用量代价与收益（要本机有 dsh；--offline 只重算）
 npm run bench:mcp         # MCP 这一层：冷启动、每步往返、协议帧字节数
 npm run mcp:smoke         # 拿脚本当 MCP 客户端，把服务器拉起来走一遍真实对话
 node bench/longmemeval.mjs --data bench/.tmp/longmemeval_s_cleaned.json   # 公开基准（数据要自己下，264MB）
@@ -866,7 +904,7 @@ CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄
 | DSH-SEP | 每步 ~1250 字符 guidance + ≤4200 字符快照 | 同上 | 抽取走 `api.deepseek.com` |
 | **本插件** | **0** | **≤480 字符，且只有指针** | **无** |
 
-## 九条被实测证伪的路
+## 十条被实测证伪的路
 
 | 尝试 | 结果 |
 |---|---|
@@ -878,6 +916,7 @@ CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄
 | freshness 时间衰减（学灵枢 / dsh-mneme） | 六档半衰期扫描：recall 恒为 28/28、top-1 只有一档 +1（噪声级）。库里「旧」的那批恰好是基础事实，衰减就是误伤 |
 | 时间乘性加权（学 hindsight） | 五档扫描净收益为零，`w ≥ 0.1` 起反而伤对照组 |
 | 给一个已有同义桥继续加词（`主题` 从 `['theme']` 扩到含 `light-dark / color-mix / data-theme / token`） | 看着全是相关的技术词，实测对照 B 掉 3 分（136→133）。机制：把词加进查询扩展后，同一篇笔记自己的其它 chunk 会把「标题里真的写着这个词」的那个 chunk 挤下去，长笔记里这叫自己跟自己抢。判据不是「这词相不相关」，而是「加了它，谁会往上浮」。这 4 个词已全部退回 |
+| 拿宿主模型的改写去和词面结果融合（RRF / 归一化求和 / 取最大） | 用真宿主模型（逐条调用本机 harness，提示词取自产品代码）在合成子集 70 条 + 真库探针 36 条上量：改写里**确实有信号**（任意一条单独检索命中 gold@1 达 50.0% / 80.6%，词面是 70.0% / 72.2%），但融合发展一律变差 —— RRF 真库 72.2% → 52.8%、取最大 → 27.8%。机制：投票数变成 4 倍，而词面那 1 票并不比模型那 3 票更该被信任，宿主又没有打分器判断改写好坏。修法是让 `expand` **只补空位**（0.11.1），并且承认「模型能写出更好的查询」≠「检索变好」（`npm run bench:rewrite`） |
 | 拿偏袒的对照当护栏：用对照 A/B 证明「抬高标题权重是安全的」 | 它们都拿标题当查询，对标题权重结构性偏袒，抬高它必然让两组变好。这不是证据，是同义反复。`TITLE_EXTRA` 第一次定成 3 就是被这个漏洞困住的（「口径在 3 之后不再动，所以后面的增量全来自对照」，而对照根本测不出这件事）。补了中立的对照 C 之后，数据说 3 太保守：C 从 0 到 96 一路不降，在 24 到达平台。已按 C 的拐点改成 24 |
 
 ## 许可

package/index.js

@@ -292,7 +292,12 @@ export function apply(ctx, config = {}) {
       'Search the local Engramory markdown memory store with BM25 (offline, read-only). ' +
       'Use it when the automatic recall did not surface what you need — for example before ' +
       'answering a question about past decisions, pitfalls or user preferences. It returns ' +
-      'matching note filenames with a matched snippet and a score; open the ones you need with read.',
+      'matching note filenames with a matched snippet and a score; open the ones you need with read. ' +
+      // 这条不是文风，是量出来的：模型改写融合净赔，而「换措辞再搜一次」的收益=改写里最好那条
+      // （真库探针 80.6% vs 词面 72.2%）。措辞敏感是 BM25 的本性，所以交给调用方换词最划算。
+      'It matches wording, not meaning: if it misses, rephrase the query in your own words and ' +
+      'search once more (synonyms, the term in English, the wording a note would use) — cheaper and ' +
+      'more effective than expecting one phrasing to land.',
     parameters: {
       type: 'object',
       properties: {
@@ -373,7 +378,7 @@ export function apply(ctx, config = {}) {
         hits,
         note: hits.length
           ? '用 read 打开需要的文件；正文在笔记里，不在这个结果里'
-          : '没有命中：换关键词再试（中文可以换相邻词）',
+          : '没有命中：换个说法再搜一次（同义词、术语的英文写法、笔记里可能用的那个词）—— 它只认措辞不认意思',
         semantic: { used: result.used, code: result.code, message: result.message },
       };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Local BM25 auto-recall, fail-closed write guard, static doctor and a memory panel for the Engramory markdown store — no network, no model, no daemon.",
   "keywords": [
     "dsh",
@@ -79,10 +79,11 @@
     "bench": "node bench/run.mjs",
     "bench:check": "node bench/run.mjs --check",
     "bench:seam": "node bench/semantic-seam.mjs",
+    "bench:rewrite": "node bench/host-rewrite.mjs",
+    "bench:bridges": "node bench/bridge-coverage.mjs",
     "bench:mcp": "node bench/mcp-overhead.mjs",
     "mcp:smoke": "node scripts/mcp-smoke.mjs",
-    "release:verify": "node scripts/verify-release.mjs",
-    "bench:bridges": "node bench/bridge-coverage.mjs"
+    "release:verify": "node scripts/verify-release.mjs"
   },
   "bin": {
     "engramory-recall-mcp": "mcp.js"

package/semantic.js

@@ -19,14 +19,20 @@
  *   return [{ id: 'some-note.md', score: 0.9 }, ...];
  * }
  *
- * // 2) 扩展：把问题改写成几句别的说法，由我分别检索再融合
+ * // 2) 扩展：把问题改写成几句别的说法，由我分别检索（**只用于补空位**）
  * export async function expand({ query, signal }) {
  *   return ['另一种说法', '关键词组合'];
  * }
  * ```
  *
- * 两种结果都不是「替换」而是「融合」（RRF）：词面命中的文档永远还在池子里，
- * 提供方只能改变顺序，删不掉东西。
+ * 两种接口的边界**不一样**，这是量出来的、不是拍出来的：
+ * · `rerank` 声称自己有打分器 ⇒ 结果与词面走 RRF 融合，**允许改顺序**（同 limit 下不增不减）；
+ * · `expand` 只是「换个说法再查一遍」⇒ **只补空位，永不改动词面顺序**。
+ *   实测（2026-10-15，真库探针 36 条 + 合成 70 条，改写由宿主模型逐条产生）：
+ *   RRF 融合让 3 条改写以 1:1 的票数盖过原查询的 1 票，真库 hit@1 26/36 → 19/36、
+ *   hit@4 36/36 → 30/36；把原查询加权到 3 票 / 5 票、或改成归一化打分，全都仍不如基线；
+ *   只有「只补空位」「池子合并（原查询打分优先）」「命中不足才用」三种保守规则能逐字打平基线。
+ *   结论：改写能扩候选，改不了排序，那就别让它碰排序。详见 README「宿主模型改写实测」。
  */
 
 import { readFileSync } from 'node:fs';
@@ -119,13 +125,21 @@ function normalizeModule(module, source) {
   return null;
 }
 
-/** 宿主模型的「扩展」实现：问模型要几句别的说法，别的什么都不做。 */
-async function hostLlmExpand(module, route, query, config, signal) {
-  const prompt = [
+/**
+ * 宿主模型改写的提示词。**导出**是给 `bench/host-rewrite.mjs` 用的：
+ * 那把尺子得用同一句话去问真宿主模型，否则量出来的不是产品行为。
+ */
+export function hostLlmPrompt(query) {
+  return [
     '把用户的问题改写成 3 条更可能命中本地记忆库的检索短句（同义词、术语、英文对照都可以）。',
     '只输出 JSON 数组，元素是字符串，不要解释、不要编号。',
     `问题：${query}`,
   ].join('\n');
+}
+
+/** 宿主模型的「扩展」实现：问模型要几句别的说法，别的什么都不做。 */
+async function hostLlmExpand(module, route, query, config, signal) {
+  const prompt = hostLlmPrompt(query);
   const result = await module.collectText(
     { stream: (options) => route.llm.stream(options) },
     {
@@ -208,7 +222,8 @@ function normalizeRanking(raw, docs) {
   return { ids, dropped };
 }
 
-function normalizeExpansions(raw, query) {
+/** 改写结果的宽松解析（同样导出给尺子复用：解析口径不一致，数字就不可比）。 */
+export function normalizeExpansions(raw, query) {
   const rows = Array.isArray(raw) ? raw : [];
   const out = [];
   const seen = new Set([String(query).trim().toLowerCase()]);
@@ -293,22 +308,32 @@ export async function semanticSearch(options = {}) {
     if (!expansions.length) {
       return fail(lexical, started, 'provider-empty', `提供方 ${provider.name} 没给出任何可用的改写，已降级`, { provider: provider.name });
     }
-    const lists = [lexical.map((hit) => hit.id)];
+    // 词面顺序原样保留：改写只按自己的名次往后补，绝不插队。理由见文件头（实测：融合会以多欺少）。
+    const order = lexical.map((hit) => hit.id);
+    const seen = new Set(order);
     const byId = new Map(lexical.map((hit) => [hit.id, hit]));
+    const extra = [];
     for (const text of expansions) {
-      const hits = runSearch(options.index, text, limit);
-      for (const hit of hits) if (!byId.has(hit.id)) byId.set(hit.id, hit);
-      lists.push(hits.map((hit) => hit.id));
+      for (const hit of runSearch(options.index, text, limit)) {
+        if (seen.has(hit.id)) continue;
+        seen.add(hit.id);
+        if (!byId.has(hit.id)) byId.set(hit.id, hit);
+        extra.push(hit.id);
+      }
     }
-    const order = mergeRRF(lists, limit);
-    const hits = order.map((id) => byId.get(id)).filter(Boolean);
+    const room = Math.max(0, limit - order.length);
+    const filled = extra.slice(0, room);
+    const hits = [...order, ...filled].map((id) => byId.get(id)).filter(Boolean);
     return {
       hits,
       used: true,
       code: 'expanded',
-      message: `已用 ${expansions.length} 条改写融合（RRF）`,
+      message: filled.length
+        ? `已用 ${expansions.length} 条改写补位（新增 ${filled.length} 条，词面顺序未动）`
+        : `已用 ${expansions.length} 条改写，但没有可补的空位（词面结果已占满 ${limit} 条，顺序未动）`,
       provider: provider.name,
       expansions,
+      added: filled.length,
       ms: Date.now() - started,
     };
   } catch (error) {