dsh-engramory-recall 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.12.2] — 2026-10-15
+
+### 新增
+
+- **embeddings 接缝的实测尺子**（`npm run bench:embed`）：`--fake` 起本机假服务把管线与代价量清楚
+  （池子实际大小、每次检索耗时、HTTP 调用数、发出文本条数、缓存省下多少），`--real` 换成真端点量质量。
+  真库那半边要显式 `--store`，因为**它会把笔记片段发给端点**。
+- 提供方模块现在也接受**默认导出对象**（`export default { rerank }`）——第三方提供方最自然的写法，
+  不必改成命名导出。命名导出照旧。
+
+### 说明
+
+- 假向量（哈希向量 = 最坏提供方）把融合表的结论变成实测：真库探针 hit@1 从 72.2%（词面）掉到
+  5.6%（`trust`）与 19.4%（`rrf`）—— `trust` 对垃圾提供方是灾难，**第一次接第三方接口建议先 `rrf`**。
+- 缓存实测：26925 条候选只发出 1994 条（省 92.6%），因为同一篇笔记在不同查询里反复出现。
+- 池子实际大小中位 31~39 条（不是 50）：词面只回有分的文档，所以 `semanticPool` 是上限不是常态。
+
+## [0.12.1] — 2026-10-15
+
+### 新增
+
+- **池宽天花板尺子**（`npm run bench:ceiling`）：把「候选池放宽到 N 条时，任何提供方最多能拿到几分」
+  单独量出来，含按题型拆分与「每查询要发给提供方多少东西」（条数 / 片段字符数 → token 估算，离线可算）。
+
+### 说明
+
+- 量出一个反直觉的事实并写进 README：**公开数据集上池宽买不到分数** —— LongMemEval-S 每题的 haystack
+  只有 30~50 个 session，池内召回 top-5 就已经 98.2%、top-20 99.6%；池宽的价值在「库比窗口大得多」时
+  （合成 704 条 70.3% → 97.3%）。所以默认 50 是给大库留的余量，不是公共基准上的分数。
+- `bench/longmemeval.mjs` 的 session→笔记映射抽到 `bench/sessions.mjs`（与尺子共用一份，避免口径漂移），
+  20 题输出逐字未变。
+
 ## [0.12.0] — 2026-10-15
 
 ### 新增

package/README.md

@@ -670,6 +670,28 @@ RRF 只能在池内重排，所以 hit@4 一动都不动（67.5%），坏的提
 2. **`rrf` 是安全档**：提供方不靠谱时，`trust` 会一路砸到底（倒排 1.0%），`rrf` 至少保住词面的一部分（26.0%）。拿不准就用它。
 3. **「只投一票」两种融合同分**：稀释来自提供方**自己的低名次**，不是来自「它参与了融合」。所以问题不在「要不要融合」，而在「按谁的顺序」。
 
+#### 池宽在公开数据集上量不出差别（`npm run bench:ceiling`）
+
+LongMemEval-S 500 题，每题自带的 haystack 只有 30~50 个 session（数据 `sha256_12 = d6f21ea9d60a`）：
+
+| 候选池 | 5 | 20 | 50 | 100 |
+|---|---|---|---|---|
+| 池内召回 | 98.2% | 99.6% | 99.8% | 99.8% |
+
+按题型看，唯一在 top-5 有明显缺口的是偏好题（90.0%），它在 top-20 就补满。所以这份公开卷子上
+**top-5 已经够了，池宽放宽买不到分数**——它的意义在库比窗口大得多的时候（合成 704 条 70.3% → 97.3%；
+真库 66 篇 / 200 chunk 从池 5 起就是 36/36）。一句话：**池宽是给大库留的余量，不是公共基准上的分数。**
+
+代价（离线估算，按池 100 算，即最坏情况）：
+
+| 项 | 中位 | p90 | 最大 |
+|---|---|---|---|
+| 候选条数 | 27 | 41 | 48 |
+| 片段字符数 | 1916 | 2921 | 3425 |
+
+按英文 ≈4 字符/token 粗估：一条查询约 479 token（中位）、730 token（p90）。提供方按文本缓存，
+同一篇笔记反复出现只付一次；**真延迟要在有端点时量**（`npm run embed:check` 会报一次往返耗时）。
+
 #### 内置参考提供方：OpenAI 兼容的 embeddings（`providers/openai-embeddings.mjs`）
 
 填两个环境变量就能试；密钥只从环境变量或一个 0600 的小文件进，**不进仓库、不进日志**：
@@ -699,6 +721,27 @@ export ENGRAMORY_EMBED_MODEL=text-embedding-3-small
 **一句实话**：这条路径的代码、测试、失败降级都有，但**还没有在真 key 上量过召回**（要花token，得你先点头）。
 接缝本身的上限是量过的（上表 86.6%），提供方的质量只能真调一次才知道。
 
+#### 真端点怎么量：`npm run bench:embed`
+
+一条命令，两种模式：`--fake`（默认）起一个**本机假 embeddings 服务**，只读「管线与代价」；
+`--real` 用 `providers/openai-embeddings.mjs` 的配置读法找真端点，那时质量列才是真的。
+真库那半边要显式加 `--store ~/memory/engramory` —— 加了就意味着**你的笔记片段会发给那个端点**，
+所以默认不开。
+
+假向量（哈希向量 = 最坏提供方）跑出来的两组数字，正好把上面那张融合表变成实测：
+
+| 卷子 | 词面 hit@1 / hit@4 | 假向量 + `trust` | 假向量 + `rrf` |
+|---|---|---|---|
+| 合成基准 704 条 | 50.4% / 67.5% | 18.3% / 25.4% | 26.8% / 43.6% |
+| 真库探针 36 条 | 72.2% / 97.2% | 5.6% / 16.7% | 19.4% / 52.8% |
+
+`trust` 对垃圾提供方是**灾难**（真库上 72.2% → 5.6%），`rrf` 也一样亏但守住一半。
+所以：**不确定提供方靠不靠谱就别开 `trust`**（这也是第一次接第三方接口时的默认建议）。
+
+代价侧（同一次运行数的）：池子实际大小中位 31~39 条（不是 50，因为词面只回有分的文档）、
+每次检索 p50 19~20 ms（假服务在本机，真延迟看端点）；提供方按文本缓存让
+**26925 条候选只发了 1994 条（省 92.6%）** —— 同一篇笔记在不同查询里反复出现时只付一次钱。
+
 #### 复用 DSH 里已经配好的那条路由（`provider: "host-embed"`）
 
 不想再填一遍环境变量：DSH 设置页 → 模型里配好的路由（`baseURL` + 模型 + API 密钥）可以**直接借来用**：
@@ -931,6 +974,8 @@ 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:ceiling     # 池宽天花板：任一提供方在公开数据集上的上界 + 每查询要发多少东西
+npm run bench:embed       # embeddings 接缝：--fake 量管线与代价 / --real 用真端点量质量
 npm run embed:check       # 参考提供方自检：探一次 embeddings 接口，报维度与耗时（不打印密钥）
 npm run bench:rewrite     # 宿主模型当改写提供方：真调用量代价与收益（要本机有 dsh；--offline 只重算）
 npm run bench:mcp         # MCP 这一层：冷启动、每步往返、协议帧字节数

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.12.0",
+  "version": "0.12.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",
@@ -81,6 +81,8 @@
     "bench": "node bench/run.mjs",
     "bench:check": "node bench/run.mjs --check",
     "bench:seam": "node bench/semantic-seam.mjs",
+    "bench:ceiling": "node bench/pool-ceiling.mjs",
+    "bench:embed": "node bench/embed-live.mjs",
     "bench:rewrite": "node bench/host-rewrite.mjs",
     "bench:bridges": "node bench/bridge-coverage.mjs",
     "bench:mcp": "node bench/mcp-overhead.mjs",

package/semantic.js

@@ -291,13 +291,14 @@ export async function loadProvider(config = {}, deps = {}) {
 }
 
 function normalizeModule(module, source) {
-  const rerank = module?.rerank;
-  const expand = module?.expand;
-  if (typeof rerank === 'function') {
-    return { name: String(module.name ?? source.split('/').pop()), kind: 'rerank', rerank, source };
-  }
-  if (typeof expand === 'function') {
-    return { name: String(module.name ?? source.split('/').pop()), kind: 'expand', expand, source };
+  // 两种写法都收：命名导出（`export function rerank`）与默认导出对象（`export default { rerank }`）。
+  // 后者是第三方提供方最自然的写法（工厂函数 + 默认导出），不必逼人家改风格。
+  const fallback = String(source).split('/').pop();
+  for (const target of [module, module?.default]) {
+    if (!target || typeof target !== 'object') continue;
+    const name = String(target.name ?? module?.name ?? fallback);
+    if (typeof target.rerank === 'function') return { name, kind: 'rerank', rerank: target.rerank, source };
+    if (typeof target.expand === 'function') return { name, kind: 'expand', expand: target.expand, source };
   }
   return null;
 }