dsh-engramory-recall 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.11.0] — 2026-10-15
+
+### 新增
+
+- **同义表 / aliases 的覆盖率尺子**（`bench/bridge-coverage.mjs`，`npm run bench:bridges`）：
+  把「这张手写桥表到底有没有在工作」从感觉变成可复算的数字，四件事一起量 ——
+  - **死值**：真库与合成语料各算一份 `df`，每个值落进四个格：两边都活 90 · 只对真库有用 312 ·
+    **只对基准有用 39** · 两边都死 78（519 个值里 15.0%）。真库口径的全死值 117（22.5%），
+    整键全死 9 个键（`下载`、`轮转`、`并发`、`乱码`…）。
+  - **覆盖**：低 `df`（≤5）锚点词 2732 个，被桥值接住 118（4.3%）；一个桥都接不住的 chunk 占 50%。
+  - **使用面**：合成语料 704 条走到 69 个键，探针 36 条真实 query 走到 44 个键，两卷都没走到的 76 个。
+  - **逐键消融**（`--ablate`）：被走到的 101 个键里 57 个零贡献；整表拔掉在合成卷上是
+    hit@1 355→327、hit@4 475→365，在**真探针**上是 27→24 / 36→31。
+  `--json` 把结果落 `bench/.bridge-coverage.json`；`--store <path>` 可以对着任意一份记忆库跑。
+- `scripts/probe-queries.mjs`：探针的三张配对表（口径 22 / 桥 10 / 别名 5）抽成共享模块，
+  探针与尺子跑**同一张卷子**，避免「改了探针忘了改尺子」。
+
+### 文档
+
+- README 的「去掉同义表」消融行加了折算说明：合成卷上的 -4.0pt 是**上界**（口语组/桥组查询本身就是
+  照着「需要桥」造的，39 个同义值只在这份卷子上有落点），真人查询上的同口径数字是 -3 @1 / -5 @4。
+- README「桥和别名是怎么挖出来的」补第 6 条（覆盖率尺子）与上面那张表，并写明**表不动**的理由：
+  78 个「两边都死」的值是 `permission` / `idempotent` / `mojibake` / `xpath` 这类通用工程词，
+  插件是发布出去的，要服务任意一份记忆库；尺子的用途是把「自用可裁剪、发布留通用词」这笔账
+  量出来（`--store` 直接列出别人那份库的死值清单）。
+- 自检清单补 `npm run bench:bridges`。
+
+### 说明
+
+- 本轮**没有改检索代码**：`bm25.js` 一个字节都没动。试过按「两卷都死」删掉那 78 个值，
+  实测两张卷子的分数逐字不变（正因为它逐字不变，就说明删与不删对**本机**质量没有影响，
+  而它对别人的库有影响），所以保留原样并把账记在 README 与 CHANGELOG 里。
+
 ## [0.10.0] — 2026-10-15
 
 ### 改进

package/README.md

@@ -119,6 +119,12 @@ CI 里再跑一遍 `npm run bench:check` 跟 `bench/expectations.json` 对账。
 | 同义键碎片不降权（回到改动前） | 49.0% | -1.4pt |
 | 桥权重与同义表一致（都算 0.5） | 51.4% | +1.0pt |
 
+「去掉同义表」这一行要打个折读：合成语料的口语组 / 桥组查询本身就是照着「需要桥」造的，
+同义表也为它们补过词，所以 **-4.0pt 是这张表在**这份**卷子上的上界，不是它的通用价值**。
+同口径在真人查询上的数字小得多：探针那 36 条真实 query，拔掉整表 hit@1 27 → 24、hit@4 36 → 31
+（`npm run bench:bridges --ablate`）。成因也量出来了：519 个同义值里 **39 个只在合成语料里有落点**，
+在真库上一个词项都不存在（见「覆盖率尺子」一节）。
+
 「去掉笔记别名」是 **+6.7pt**，在总分上反而更好看 —— 这个语料里别名是把双刃剑：
 它帮自己（写了别名的 37 篇 hit@1 94.6%，没写的 187 篇 23.0%），
 也把同域别的笔记的口语查询抢过来（语料里同域的别名共用同一个口语域词，而别名是程序按比例随机发的）。
@@ -472,6 +478,25 @@ aliases: 梯子, 翻墙, 科学上网, 节点, 代理
 5. **死值自检**：同义桥的每个值都要在语料里真的存在才有分。指向一个库里根本没有的词，
    效果是写了等于没写：不报错、不降级，最安静的那种失效。探针每次跑都数一遍。
 
+第 6 条是 0.11.0 补的：**覆盖率尺子**（`npm run bench:bridges`，`bench/bridge-coverage.mjs`）。
+它把第 5 条从「数一个总数」变成「分格里看」，三张卷子各量各的：
+
+| 量什么 | 数字 |
+|---|---|
+| 死值（真库口径） | **117 / 519（22.5%）**，整键全死 9 个键（`下载`、`轮转`、`并发`、`乱码`…） |
+| 死值分格（真库 × 合成语料各一份 `df`） | 两边都活 **90** · 只对真库有用 **312** · **只对基准有用 39** · 两边都死 **78** |
+| 覆盖：低 `df`（≤5）锚点词被桥接住 | **118 / 2732（4.3%）**；一个桥都接不住的 chunk 占 **50%** |
+| 使用面 | 合成语料 704 条 → 走到 **69** 个键；探针 36 条真实 query → 走到 **44** 个键；两张卷子都没走到的键 **76（43%）** |
+| 逐键消融 | 被走到的 101 个键里 **57 个**拔掉不影响任何名次；整表拔掉——合成 hit@1 355→327、hit@4 475→365，**真探针 27→24 / 36→31** |
+
+**这轮量完的结论是「表不动」。** 78 个两边都死的值看着像该删的，但它们是 `permission /
+idempotent / mojibake / xpath / selenium / watchdog / dsn / backoff` 这一类**通用工程词** ——
+插件是发布出去的，要服务任意一份记忆库，别人库里当然可能有它们。尺子的用途不是自动删词，
+而是把这笔账**量出来、摆明**：谁想按自己的库裁剪，`npm run bench:bridges --store <自己的库>`
+会直接列出他那一份的死值清单。覆盖率的 4.3% 同理 —— 它量的是表的大小，不是表的好坏：
+手写表永远盖不住几千个锚点，真问题是「没被接住的锚点里有多少条真人 query 会问」，
+而那要靠探针的口径/桥组回答（现在 21/21 与 10/10）。
+
 第 5 条当场抓出 32 个值指向不存在的词（`latency`、`slide`、`cert`、`gpt`…），
 其中 7 个是同一轮刚加的，也就是说「按语料锚点写桥」这件事当时并没有做到。删掉后剩 25 个，
 但那 25 个不该删：它们随插件一起发布，要服务的是任意一份记忆库（别人库里当然可能有
@@ -784,6 +809,7 @@ npm run check   # 接线自检：配置键认不认、库路径对不对、装
 npm run probe   # 召回质量探针：3 组 query + 三道对照，跑在真实记忆库上
 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:mcp         # MCP 这一层：冷启动、每步往返、协议帧字节数
 npm run mcp:smoke         # 拿脚本当 MCP 客户端，把服务器拉起来走一遍真实对话

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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",
@@ -81,7 +81,8 @@
     "bench:seam": "node bench/semantic-seam.mjs",
     "bench:mcp": "node bench/mcp-overhead.mjs",
     "mcp:smoke": "node scripts/mcp-smoke.mjs",
-    "release:verify": "node scripts/verify-release.mjs"
+    "release:verify": "node scripts/verify-release.mjs",
+    "bench:bridges": "node bench/bridge-coverage.mjs"
   },
   "bin": {
     "engramory-recall-mcp": "mcp.js"