dsh-engramory-recall 0.11.2 → 0.12.1

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [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
+
+### 新增
+
+- **语义提供方现在看的是宽池**（`semanticPool`，默认 50、上限 200）：池子等于输出窗口时，提供方只能
+  在词面已经挑中的那几条里排序，语义再准也捞不动排在第 12 名的正确笔记。合成 704 条上池内召回从
+  70.3%（池 5）涨到 97.3%（池 50），真库探针从池 5 起就是 36/36（`npm run bench:seam`）。
+- **默认融合模式改成 `trust`**（提供方的顺序即结果，词面只用来补满窗口），`semanticFusion: rrf` 保留为
+  「不确定提供方靠不靠谱」时的安全档。依据：完美的全量排名提供方在等权 RRF 下 hit@1 只有 52.7%
+  （纯词面 50.4%，几乎没赚），`trust` 下 86.6%；而倒排提供方反过来是 trust 1.0% / rrf 26.0%。
+- **新增参考提供方 `providers/openai-embeddings.mjs`**：OpenAI 兼容的 `/embeddings` 客户端，零依赖、
+  批请求 + 按文本缓存、错误带 HTTP 状态与服务端原话、**密钥不进日志**。配置走环境变量或
+  `~/.config/engramory/embed.json`（0600），`npm run embed:check` 一条命令自检。
+- **新增 `provider: 'host-embed'`**：复用 DSH 设置页里已经配好的那条路由（`baseURL` + 模型 + 密钥），
+  不用再填一遍环境变量。四步（路由 / baseURL / 模型 / 密钥）都从宿主读，每步失败都给可照做的提示；
+  凭据每次检索现解析（不跨操作缓存）；MCP 等没有宿主的场景明确报 `no-host`。
+- 新测试：`test/embed-provider.test.mjs`（7 例，含假 embeddings 服务）、`test/host-embed.test.mjs`
+  （5 例，含宿主三个服务的最小替身）、`test/semantic.test.mjs` 增加池宽与融合模式 3 例。
+
+### 说明
+
+- 参考提供方与 `host-embed` 的**召回收益还没有在真 key 上量过**（要花 token，等用户点头）。已量的是
+  接缝本身的上限与代价，以及默认值为什么这么定 —— 这两组数字都在 `npm run bench:seam` 里可复算。
+- 默认池 50 的代价：每次检索多算一次词面（50 条），实测平均仍是毫秒级；提供方多收到 45 条候选，
+  embeddings 按文本缓存，重复检索不重复付费。
+
 ## [0.11.2] — 2026-10-15
 
 ### 变更

package/README.md

@@ -578,8 +578,11 @@ idempotent / mojibake / xpath / selenium / watchdog / dsn / backoff` 这一类**
 接缝（seam）而不是内置向量库：用户自己指一个提供方，指了才生效，指错了也不会把检索弄坏。
 
 ```yaml
-        semanticProvider: ''      # 留空 = 纯词面（默认）。可填本地模块路径，或字面量 host-llm
+        semanticProvider: ''      # 留空 = 纯词面（默认）。可填本地模块路径，或字面量 host-llm / host-embed
         semanticTimeoutMs: 2000   # 单次预算；超时/抛错/返回垃圾一律降级回词面结果
+        semanticPool: 50          # 提供方看多宽的候选池（默认 50，上限 200）
+        semanticFusion: trust     # trust = 提供方说了算（默认）；rrf = 词面有一票否决权
+        semanticHostRoute: ''     # 只有 host-embed 用：复用哪条 DSH 路由（留空 = 当前默认模型的路由）
 ```
 
 提供方就是一个本地 ESM 模块，导出两个函数里的任意一个：
@@ -604,9 +607,10 @@ export async function expand({ query, signal }) {
 
 | 行为 | 为什么 |
 |---|---|
-| `rerank` 走 **RRF 融合**，`expand` **只补空位** | 同一个 limit 下 rerank 输出就是同一批文档的重排（不会凭空多出、也不会丢；`test/semantic-corpus.test.mjs` 在真语料上钉这条）。`expand` 若也拿去融合，实测 hit@1 掉 7~19pt（原因见下面「让宿主模型当改写提供方」）：词面那 1 票没有任何理由比模型那 3 票更该被信任。所以它只把词面没排上的文档**接在后面**，`added` 报补了几条。两种提供方返回候选之外的文件名一律丢弃并报数 |
+| `rerank` 默认 **trust 融合**（提供方的顺序即结果，词面只用来补满窗口），`expand` **只补空位** | 真提供方返回的是一份**全量排名**，等权 RRF 会让它自己第 2 名以后的名次反过来稀释第 1 名 —— 合成 704 条上这是 86.6% 对 52.7%（下表）。`semanticFusion: rrf` 保留给「不确定提供方靠不靠谱」的场景（那时它是安全档：26.0% 对 1.0%）。`expand` 若也拿去融合，实测 hit@1 掉 7~19pt（原因见下面「让宿主模型当改写提供方」）：词面那 1 票没有任何理由比模型那 3 票更该被信任。所以它只把词面没排上的文档**接在后面**，`added` 报补了几条。`expand` 若也拿去融合，实测 hit@1 掉 7~19pt（原因见下面「让宿主模型当改写提供方」）：词面那 1 票没有任何理由比模型那 3 票更该被信任。所以它只把词面没排上的文档**接在后面**，`added` 报补了几条。两种提供方返回候选之外的文件名一律丢弃并报数 |
 | 超时**硬兜一层** `Promise.race` | 提供方可以完全忽略 `AbortSignal`（第三方代码什么都干得出来），只靠 abort 会让检索永远等下去 |
 | 失败**不抛错**，降级回词面并如实报 `code` | `off` / `not-found` / `unsupported` / `provider-error` / `timeout` / `provider-empty`，检索工具返回值里的 `semantic` 字段直接给出这次到底用没用上 |
+| **提供方看的是宽池**（`semanticPool`，默认 50） | 池子等于输出窗口时，提供方只能在词面已经挑中的那几条里排序 —— 语义再准也捞不动排在第 12 名的正确笔记。池宽从 5 抬到 50，池内召回从 70.3% 涨到 97.3%（`npm run bench:seam`） |
 | **只管按需检索工具**，不碰每轮自动注入 | 自动召回每个用户轮都跑；挂一个要 200ms 的外部件等于给每一轮加税。热路径永远纯词面 |
 
 
@@ -641,7 +645,105 @@ RRF 只能在池内重排，所以 hit@4 一动都不动（67.5%），坏的提
 `test/semantic-wiring.test.mjs`（关着时连 import 都不发生、开着时真的融合、自动注入不碰接缝）
 就是钉这四条的。
 
-#### 实测：让宿主模型当改写提供方（`npm run bench:rewrite`）
+#### 实测：候选池与融合模式（同一个 `npm run bench:seam`）
+
+合成语料 704 条、输出窗口 top-4。池宽决定「提供方最多能捞多远」——池内召回就是它的天花板：
+
+| 候选池 `semanticPool` | 5 | 20 | **50（默认）** | 100 |
+|---|---|---|---|---|
+| 池内召回（合成 704 条） | 70.3% | 86.6% | **97.3%** | 97.9% |
+| 池内召回（真库探针 36 条） | 36/36 | 36/36 | **36/36** | 36/36 |
+
+融合模式决定「提供方的话算不算数」（同一张卷子，只换提供方与融合）：
+
+| 提供方 | `trust`（默认） | `rrf` |
+|---|---|---|
+| 完美：全量排名（真 embedding 的形态） | **86.6% / 86.6%** | 52.7% / 73.6% |
+| 完美：只投 gold 一票 | 86.6% / 86.6% | 86.6% / 86.6% |
+| 词面倒排（最坏的可信提供方） | 1.0% / 3.8% | 26.0% / 59.7% |
+| 与语义无关的稳定顺序 | 3.1% / 16.8% | 18.8% / 43.9% |
+| 纯词面（不看提供方） | 50.4% / 67.5% | 50.4% / 67.5% |
+
+（每格 = hit@1 / hit@4。）三点结论：
+
+1. **默认 `trust`**：真提供方一定会排完整个池，等权 RRF 下它自己的低名次条目会把第 1 名挤下去 —— 完美提供方因此只拿到 52.7%（比纯词面 50.4% 几乎没有赚），`trust` 是 86.6%。
+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 的小文件进，**不进仓库、不进日志**：
+
+```bash
+node providers/openai-embeddings.mjs --check     # 先自检：报维度与耗时（不打印密钥）
+```
+
+```yaml
+        semanticProvider: 'dsh-engramory-recall/providers/openai-embeddings'
+        semanticTimeoutMs: 15000   # 远端接口要给足预算（默认 2000ms 是给本机小模型的）
+        semanticPool: 50
+        semanticFusion: trust
+```
+
+```bash
+export ENGRAMORY_EMBED_API_KEY=sk-…                                  # 或写 ~/.config/engramory/embed.json
+export ENGRAMORY_EMBED_BASE_URL=https://api.openai.com/v1            # 换一家就换这两行
+export ENGRAMORY_EMBED_MODEL=text-embedding-3-small
+```
+
+**embeddings 只有 OpenAI 这一种接口形状**（`POST {base}/embeddings`）：Anthropic 没有 embedding 接口，
+所谓「Claude 协议」在这里用不上。国产替代填 `BASE_URL` + `MODEL` 即可，例如阿里百炼
+`https://dashscope.aliyuncs.com/compatible-mode/v1` + `text-embedding-v4`、智谱
+`https://open.bigmodel.cn/api/paas/v4` + `embedding-3`、硅基流动 `https://api.siliconflow.cn/v1` + `BAAI/bge-m3`。
+
+**一句实话**：这条路径的代码、测试、失败降级都有，但**还没有在真 key 上量过召回**（要花token，得你先点头）。
+接缝本身的上限是量过的（上表 86.6%），提供方的质量只能真调一次才知道。
+
+#### 复用 DSH 里已经配好的那条路由（`provider: "host-embed"`）
+
+不想再填一遍环境变量：DSH 设置页 → 模型里配好的路由（`baseURL` + 模型 + API 密钥）可以**直接借来用**：
+
+```yaml
+        semanticProvider: 'host-embed'
+        semanticHostRoute: ''      # 留空 = 用当前默认模型的那条路由；也可指名（如 openai / zhipu）
+        semanticTimeoutMs: 15000
+```
+
+它按四步读宿主，每步失败都给**可照做**的提示（而不是一句「配置错误」），失败一律降级回词面：
+
+| 步骤 | 从哪读 | 读不到时 |
+|---|---|---|
+| 路由 | `semanticHostRoute` → 插件的 `llmProvider` → `agentDefaultModel.currentSelection()` | 提示写 `semanticHostRoute` |
+| `baseURL` | 该路由配置里的 `baseURL`；目录自带路由（openai / mistral / together / 智谱）有内置兜底 | 提示去「自定义模型 API」加一条路由，或写 `semanticHostBaseUrl` |
+| 模型 | 路由 `models[]` 里名字含 embed 的那个；单模型路由直接用它；内置兜底 | 提示写 `semanticHostModel` |
+| 密钥 | 路由的 `apiKeyEnv`（没有就按 `<ROUTE>_API_KEY` 派生）→ `ctx.credentials.resolve()` | 提示去设置页填密钥，并说清 ref 名字 |
+
+三条纪律：密钥**只在这四步里过一遍**，不进返回值、不进日志、不进错误信息；凭据**每次检索现解析**
+（宿主规范：不许跨操作缓存）；MCP 那种没有宿主的场景会明确报 `no-host` 并提示改用本地模块提供方。
+
+
 
 `host-llm` 能跑通不等于划算，所以这条尺子用**真宿主模型**量了一遍（2026-10-15，逐条调用本机
 harness，提示词直接 `import` 产品的 `hostLlmPrompt()` —— 尺子问的就是产品要问的那句话；
@@ -707,9 +809,12 @@ harness，提示词直接 `import` 产品的 `hostLlmPrompt()` —— 尺子问
         indexMaxLines: 200       # 索引 MEMORY.md 的行数上限
         indexMaxBytes: 25600     # 索引的字节上限
         registerSkill: true      # 注册 engramory 技能（写入纪律的正文）
-        # 语义检索接缝（默认关闭）：本地模块路径，或 host-llm（走宿主模型做查询改写）
+        # 语义检索接缝（默认关闭）：本地模块路径，或 host-llm / host-embed
         semanticProvider: ''
         semanticTimeoutMs: 2000
+        semanticPool: 50          # 提供方看多宽的候选池
+        semanticFusion: trust     # trust = 提供方说了算；rrf = 词面有一票否决权
+        semanticHostRoute: ''     # 只有 host-embed 用
 ```
 
 `autoArchive` 打开后归档会在两处自动跑：每轮 pre-step 兜底（10 分钟 TTL，不会每轮扫库），
@@ -841,13 +946,15 @@ stdout 上只准有 JSON-RPC 帧，混进任何一行非 JSON，这次运行就
 ## 测试与自检
 
 ```bash
-npm test        # 分词 / BM25 / 切桶 / 门控 / 闸门 / 索引闸门 / 技能注册 / 体检 / 审计 / 沉淀提醒 / 归档 / 打包 / 路由 / 公开基准 harness / MCP 服务器
+npm test        # 分词 / BM25 / 切桶 / 门控 / 闸门 / 索引闸门 / 技能注册 / 体检 / 审计 / 沉淀提醒 / 归档 / 打包 / 路由 / 公开基准 harness / MCP 服务器 / 语义接缝（含 host-embed）
 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:seam        # 语义接缝的代价与天花板（四种坏提供方 + 作弊上界 + 融合模式对照）
+npm run bench:ceiling     # 池宽天花板：任一提供方在公开数据集上的上界 + 每查询要发多少东西
+npm run embed:check       # 参考提供方自检：探一次 embeddings 接口，报维度与耗时（不打印密钥）
 npm run bench:rewrite     # 宿主模型当改写提供方：真调用量代价与收益（要本机有 dsh；--offline 只重算）
 npm run bench:mcp         # MCP 这一层：冷启动、每步往返、协议帧字节数
 npm run mcp:smoke         # 拿脚本当 MCP 客户端，把服务器拉起来走一遍真实对话
@@ -904,7 +1011,7 @@ CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄
 | DSH-SEP | 每步 ~1250 字符 guidance + ≤4200 字符快照 | 同上 | 抽取走 `api.deepseek.com` |
 | **本插件** | **0** | **≤480 字符，且只有指针** | **无** |
 
-## 十条被实测证伪的路
+## 十一条被实测证伪的路
 
 | 尝试 | 结果 |
 |---|---|
@@ -917,6 +1024,7 @@ CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄
 | 时间乘性加权（学 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`） |
+| 拿等权 RRF 当语义提供方的默认融合 | 合成 704 条、池 20、窗口 4：**完美的全量排名提供方**（真 embedding 的形态）在等权 RRF 下 hit@1 只有 52.7%，比纯词面（50.4%）几乎没赚；同一个提供方在 `trust` 下是 86.6%。机制：提供方返回的是全量排名，它自己第 2 名以后的名次也会拿到票，于是把第 1 名挤下去 —— 稀释来自它**自己的低名次**，不是来自融合本身（「只投一票」的完美提供方两种融合同为 86.6%）。默认已改成 `trust`，`rrf` 保留为「不确定提供方靠不靠谱」时的安全档（倒排提供方：trust 1.0% vs rrf 26.0%） |
 | 拿偏袒的对照当护栏：用对照 A/B 证明「抬高标题权重是安全的」 | 它们都拿标题当查询，对标题权重结构性偏袒，抬高它必然让两组变好。这不是证据，是同义反复。`TITLE_EXTRA` 第一次定成 3 就是被这个漏洞困住的（「口径在 3 之后不再动，所以后面的增量全来自对照」，而对照根本测不出这件事）。补了中立的对照 C 之后，数据说 3 太保守：C 从 0 到 96 一路不降，在 24 到达平台。已按 C 的拐点改成 24 |
 
 ## 许可

package/index.js

@@ -175,6 +175,23 @@ const DEFAULTS = {
   semanticProvider: '',
   /** 接缝的单次超时预算（毫秒）。超时/抛错/返回垃圾一律降级回词面结果。 */
   semanticTimeoutMs: 2000,
+  /**
+   * `rerank` 提供方看到的候选池宽度（默认 50，上限 200）。
+   *
+   * 池宽 = 输出窗口时，提供方只能重排词面已经挑中的那几条，天花板被词面钉死；放宽池子
+   * 才给语义信号留出「把排名靠后的正确笔记捞上来」的空间。实测（2026-10-15，合成 704 条）：
+   * 池内召回 P=5 时 70.3%、P=20 86.6%、P=50 97.3%。代价只是词面多算几条候选 + 提供方多算
+   * 几十条（embedding 按篇计费，50 条约几千 token，一次查询级别）。
+   */
+  semanticPool: 50,
+  /**
+   * 融合方式：`rrf`（默认）= 词面与提供方各一票，少赚不赔；`trust` = 提供方的顺序即最终顺序，
+   * 天花板最高（合成 @1 86.6% vs 词面 50.4%），但提供方不靠谱时结果会比纯词面更差。
+   * 两个数都是量出来的，见 semantic.js 文件头与 README「语义接缝」小节。
+   */
+  semanticFusion: 'trust',
+  // 只有 `semanticProvider: 'host-embed'` 用得上：指定复用哪条 DSH 路由（留空 = 当前默认模型的路由）。
+  semanticHostRoute: '',
 };
 
 /** 只在用户句子里出现明确的「长期记住」意图时才追加一行提示（默认开）。 */
@@ -357,14 +374,20 @@ export function apply(ctx, config = {}) {
       }
       const limit = Math.min(Math.max(Number(args?.limit) || 5, 1), 20);
       // 接缝关着（默认）就走原来那条同步路径：不 await、不 import、零额外开销。
-      // 开着也只是「融合」：语义提供方插进来的顺序与词面顺序做 RRF，词面命中的文档一条不丢。
+      // 开着时提供方看到的是宽于 limit 的候选池（semanticPool），融合方式见 semanticFusion。
       const seam = describeSeam({ provider: settings.semanticProvider });
       const result = seam.enabled
         ? await semanticSearch({
             index: indexOf(storePath),
             query,
             limit,
-            config: { provider: settings.semanticProvider, timeoutMs: settings.semanticTimeoutMs },
+            config: {
+              provider: settings.semanticProvider,
+              timeoutMs: settings.semanticTimeoutMs,
+              pool: settings.semanticPool,
+              fusion: settings.semanticFusion,
+              hostRoute: settings.semanticHostRoute,
+            },
             runtime: llmRuntime(),
           })
         : { hits: search(indexOf(storePath), query, limit), used: false, code: 'off', message: '语义接缝未启用（默认）' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "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",
@@ -39,7 +39,8 @@
     "./llm": "./llm.js",
     "./index": "./index.js",
     "./mcp": "./mcp.js",
-    "./semantic": "./semantic.js"
+    "./semantic": "./semantic.js",
+    "./providers/openai-embeddings": "./providers/openai-embeddings.mjs"
   },
   "files": [
     "index.js",
@@ -55,6 +56,7 @@
     "llm.js",
     "semantic.js",
     "mcp.js",
+    "providers/openai-embeddings.mjs",
     "CHANGELOG.md",
     "cordis.patch.yml",
     "README.md"
@@ -79,10 +81,12 @@
     "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: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",
+    "embed:check": "node providers/openai-embeddings.mjs --check",
     "release:verify": "node scripts/verify-release.mjs"
   },
   "bin": {

package/providers/openai-embeddings.mjs

@@ -0,0 +1,301 @@
+/**
+ * 参考提供方：OpenAI 兼容的 embeddings 接口（零依赖、可选、密钥只从环境变量进）。
+ *
+ * 它存在的意义是把「语义接缝」从「你自己写一个」变成「填三个环境变量就能试」：
+ *
+ * ```jsonc
+ * // DSH 插件配置
+ * {
+ *   "semanticProvider": "dsh-engramory-recall/providers/openai-embeddings",
+ *   "semanticTimeoutMs": 15000,
+ *   "semanticPool": 50,
+ *   "semanticFusion": "rrf"
+ * }
+ * ```
+ *
+ * 配置来源（优先级：环境变量 > 配置文件 > 内置默认），密钥**不进仓库、不进日志**：
+ * · `~/.config/engramory/embed.json`（可用 `ENGRAMORY_EMBED_CONFIG` 换路径）：
+ *   `{"apiKey": "…", "baseUrl": "…", "model": "…"}` —— 推荐这条：macOS 上 GUI 启动的应用
+ *   读不到 `~/.zshrc` 里的环境变量，一个 0600 的小文件最省事：
+ *   `mkdir -p ~/.config/engramory && printf '{"apiKey":"sk-…"}' > ~/.config/engramory/embed.json && chmod 600 ~/.config/engramory/embed.json`
+ * · `ENGRAMORY_EMBED_API_KEY`        或 `ENGRAMORY_EMBED_API_KEY_FILE` 指一个只放密钥的文件
+ * · `ENGRAMORY_EMBED_BASE_URL`       默认 `https://api.openai.com/v1`（base 里带 `/v1`）
+ * · `ENGRAMORY_EMBED_MODEL`          默认 `text-embedding-3-small`
+ * · `ENGRAMORY_EMBED_BATCH`          默认 32（一次请求塞多少条）
+ * · `ENGRAMORY_EMBED_MAX_CHARS`      每篇笔记送多少字，默认 1200
+ * · `ENGRAMORY_EMBED_QUERY_PREFIX` / `ENGRAMORY_EMBED_DOC_PREFIX`
+ *                                    有些模型要指令前缀（如 `query: ` / `passage: `），默认空
+ *
+ * 换一家提供商就是换 `BASE_URL` + `MODEL`（阿里百炼 `https://dashscope.aliyuncs.com/compatible-mode/v1`
+ * + `text-embedding-v4`、智谱 `https://open.bigmodel.cn/api/paas/v4` + `embedding-3`、硅基流动
+ * `https://api.siliconflow.cn/v1` + `BAAI/bge-m3` 等）。注意：**embeddings 只有 OpenAI 这一种
+ * 接口形状**，Anthropic 没有 embedding 接口，所谓「Claude 协议」在这里用不上。
+ *
+ * 自检（不打印密钥）：
+ * ```bash
+ * node providers/openai-embeddings.mjs --check          # 探一次接口，报维度与耗时
+ * node providers/openai-embeddings.mjs --check --json
+ * ```
+ *
+ * 纪律：接口失败一律 **throw**（接缝会降级回词面结果并如实报 `provider-error`），
+ * 绝不返回一个「凑合」的顺序；错误信息里绝不含密钥。
+ */
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const name = 'openai-embeddings';
+
+const DEFAULTS = {
+  baseUrl: 'https://api.openai.com/v1',
+  model: 'text-embedding-3-small',
+  batch: 32,
+  maxChars: 1200,
+  queryPrefix: '',
+  docPrefix: '',
+};
+
+/** 默认配置文件位置（可用 ENGRAMORY_EMBED_CONFIG 换）。 */
+export const DEFAULT_CONFIG_PATH = '~/.config/engramory/embed.json';
+
+function expandHome(value) {
+  const text = String(value ?? '').trim();
+  if (text === '~') return homedir();
+  return text.startsWith('~/') ? join(homedir(), text.slice(2)) : text;
+}
+
+/** 读小配置文件；不存在就当空（这是正常状态，不是错误）；坏 JSON 要说清楚。 */
+export function readConfigFile(env = process.env) {
+  const full = expandHome(env.ENGRAMORY_EMBED_CONFIG || DEFAULT_CONFIG_PATH);
+  if (!full) return { path: '', data: {} };
+  try {
+    const text = readFileSync(full, 'utf8');
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('顶层必须是一个对象');
+    return { path: full, data };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { path: full, data: {} };
+    throw new Error(`配置文件 ${full} 读不了：${error?.message ?? error}`);
+  }
+}
+
+/** 进程内缓存：同一篇笔记在不同查询里不必重复付费（键含模型与前缀，换模型自动失效）。 */
+const CACHE_LIMIT = 5000;
+const cache = new Map();
+
+function num(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+/** 从环境变量读配置（导出是为了自检与测试能显式传 env，不读进程全局）。 */
+export function readConfig(env = process.env) {
+  const { path: configPath, data } = readConfigFile(env);
+  // trim=false 是给指令前缀用的：`query: ` 末尾那个空格是模型约定的一部分，不能被吃掉
+  const pick = (envName, fileKey, fallback, { trim = true } = {}) => {
+    const clean = (value) => (trim ? String(value).trim() : String(value));
+    const fromEnv = String(env[envName] ?? '');
+    if (fromEnv.trim()) return clean(fromEnv);
+    const fromFile = data[fileKey] ?? data[envName];
+    if (fromFile !== undefined && fromFile !== null && String(fromFile).trim()) return clean(fromFile);
+    return fallback;
+  };
+  const base = String(pick('ENGRAMORY_EMBED_BASE_URL', 'baseUrl', DEFAULTS.baseUrl)).replace(/\/+$/, '');
+  return {
+    configPath,
+    baseUrl: base || DEFAULTS.baseUrl,
+    model: pick('ENGRAMORY_EMBED_MODEL', 'model', DEFAULTS.model) || DEFAULTS.model,
+    batch: Math.min(128, Math.max(1, num(pick('ENGRAMORY_EMBED_BATCH', 'batch', DEFAULTS.batch), DEFAULTS.batch))),
+    maxChars: Math.max(64, num(pick('ENGRAMORY_EMBED_MAX_CHARS', 'maxChars', DEFAULTS.maxChars), DEFAULTS.maxChars)),
+    queryPrefix: pick('ENGRAMORY_EMBED_QUERY_PREFIX', 'queryPrefix', DEFAULTS.queryPrefix, { trim: false }),
+    docPrefix: pick('ENGRAMORY_EMBED_DOC_PREFIX', 'docPrefix', DEFAULTS.docPrefix, { trim: false }),
+    apiKey: readKey(env, data),
+    keySource: keySource(env, data),
+  };
+}
+
+function keySource(env, data) {
+  if (String(env.ENGRAMORY_EMBED_API_KEY ?? '').trim()) return 'ENGRAMORY_EMBED_API_KEY';
+  if (String(env.ENGRAMORY_EMBED_API_KEY_FILE ?? '').trim()) return 'ENGRAMORY_EMBED_API_KEY_FILE';
+  if (String(data?.apiKey ?? '').trim()) return `配置文件 ${expandHome(env.ENGRAMORY_EMBED_CONFIG || DEFAULT_CONFIG_PATH)}`;
+  return '';
+}
+
+function readKey(env, data = {}) {
+  const inline = String(env.ENGRAMORY_EMBED_API_KEY ?? '').trim();
+  if (inline) return inline;
+  const file = String(env.ENGRAMORY_EMBED_API_KEY_FILE ?? '').trim();
+  if (file) {
+    try {
+      return readFileSync(expandHome(file), 'utf8').trim();
+    } catch (error) {
+      throw new Error(`读不到密钥文件 ${file}（${error?.code ?? error?.message}）`);
+    }
+  }
+  return String(data?.apiKey ?? '').trim();
+}
+
+function endpoint(baseUrl) {
+  return /\/embeddings$/.test(baseUrl) ? baseUrl : `${baseUrl}/embeddings`;
+}
+
+function textOf(doc, cfg) {
+  const raw = [doc?.snippet, doc?.title].filter(Boolean).join('\n') || String(doc?.id ?? '');
+  return (cfg.docPrefix + raw.replace(/\s+/g, ' ').trim()).slice(0, cfg.maxChars);
+}
+
+async function embedBatch(cfg, texts, signal) {
+  const response = await fetch(endpoint(cfg.baseUrl), {
+    method: 'POST',
+    signal,
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${cfg.apiKey}`,
+    },
+    body: JSON.stringify({ model: cfg.model, input: texts }),
+  });
+  const body = await response.text();
+  if (!response.ok) {
+    // 状态码 + 服务端原话（截断）：密钥绝不进消息。
+    throw new Error(`embeddings HTTP ${response.status}：${body.replace(/\s+/g, ' ').slice(0, 200)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error(`embeddings 返回的不是 JSON：${body.slice(0, 120)}`);
+  }
+  const rows = parsed?.data;
+  if (!Array.isArray(rows) || rows.length !== texts.length) {
+    throw new Error(`embeddings 返回的数据条数不对：想 ${texts.length} 条，拿到 ${Array.isArray(rows) ? rows.length : '非数组'}`);
+  }
+  return rows
+    .sort((a, b) => (a?.index ?? 0) - (b?.index ?? 0))
+    .map((row) => {
+      const vector = row?.embedding;
+      if (!Array.isArray(vector) || !vector.length) throw new Error('embeddings 返回了空向量');
+      return vector;
+    });
+}
+
+/** 批量取向量，带进程内缓存。文本相同（含前缀与模型）就不重复请求。 */
+export async function embedTexts(cfg, texts, signal) {
+  const out = new Array(texts.length);
+  const todo = [];
+  texts.forEach((text, index) => {
+    const key = `${cfg.model}\u0000${text}`;
+    if (cache.has(key)) out[index] = cache.get(key);
+    else todo.push({ index, text, key });
+  });
+  for (let start = 0; start < todo.length; start += cfg.batch) {
+    const slice = todo.slice(start, start + cfg.batch);
+    const vectors = await embedBatch(cfg, slice.map((item) => item.text), signal);
+    slice.forEach((item, offset) => {
+      const vector = vectors[offset];
+      out[item.index] = vector;
+      if (cache.size >= CACHE_LIMIT) cache.delete(cache.keys().next().value);
+      cache.set(item.key, vector);
+    });
+  }
+  return out;
+}
+
+function cosine(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i += 1) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (!na || !nb) return 0;
+  return dot / Math.sqrt(na * nb);
+}
+
+/**
+ * 接缝的 `rerank` 接口：给候选池，按余弦相似度排序。
+ * 返回**全部**候选（不是只给 limit 条）—— 融合方式（rrf / trust）由接缝决定，不由提供方越权决定。
+ */
+/** 用一份**显式配置**跑重排（密钥来自调用方，而不是环境变量）—— `host-embed` 复用宿主凭据时走这条路。 */
+export async function rerankWith(cfg, { query, docs, signal } = {}) {
+  if (!cfg?.apiKey) {
+    throw new Error('没配密钥：设置 ENGRAMORY_EMBED_API_KEY（或 ENGRAMORY_EMBED_API_KEY_FILE）后重试');
+  }
+  const list = Array.isArray(docs) ? docs : [];
+  if (!list.length) return [];
+  const vectors = await embedTexts(cfg, [cfg.queryPrefix + String(query ?? ''), ...list.map((doc) => textOf(doc, cfg))], signal);
+  const queryVector = vectors[0];
+  return list
+    .map((doc, index) => ({ id: doc.id, score: cosine(queryVector, vectors[index + 1]) }))
+    .sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)));
+}
+
+/** 默认配置（env + 配置文件）下的提供方，供 `provider: '<包名>/providers/openai-embeddings'` 直接使用。 */
+export async function rerank(args) {
+  return rerankWith(readConfig(), args);
+}
+
+/**
+ * 用显式配置造一个提供方对象（`host-embed` 与 `--check` 之外的集成都用它）。
+ * overrides 里常见：`baseUrl` / `model` / `apiKey` / `batch` / `maxChars` / `queryPrefix` / `docPrefix`。
+ */
+export function createProvider(overrides = {}) {
+  const cfg = { ...readConfig(), ...overrides };
+  return {
+    name: overrides.providerName ?? `${name}(${cfg.model})`,
+    kind: 'rerank',
+    config: cfg,
+    rerank: (args) => rerankWith(cfg, args),
+  };
+}
+
+/** 自检：探一次接口，报配置（不含密钥）、维度与耗时。 */
+export async function check(env = process.env) {
+  const cfg = readConfig(env);
+  if (!cfg.apiKey) {
+    throw new Error(`没配密钥：设置 ENGRAMORY_EMBED_API_KEY，或写一份 ${cfg.configPath}（{"apiKey":"…"}，chmod 600）`);
+  }
+  const started = Date.now();
+  const vectors = await embedTexts(cfg, ['engramory 自检：这一段会被送进 embeddings 接口。'], undefined);
+  return {
+    ok: true,
+    baseUrl: cfg.baseUrl,
+    model: cfg.model,
+    keySource: cfg.keySource,
+    configPath: cfg.configPath,
+    dimensions: vectors[0].length,
+    ms: Date.now() - started,
+  };
+}
+
+const isMain = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain || process.argv.includes('--check')) {
+  if (!process.argv.includes('--check')) {
+    console.log('用法：node providers/openai-embeddings.mjs --check [--json]');
+  } else {
+    try {
+      const result = await check();
+      if (process.argv.includes('--json')) console.log(JSON.stringify(result, null, 2));
+      else {
+        console.log(`✓ embeddings 可用：${result.model} @ ${result.baseUrl}`);
+        console.log(`  密钥来源：${result.keySource} · 维度：${result.dimensions} · 耗时：${result.ms}ms`);
+      }
+    } catch (error) {
+      console.error(`✗ ${error?.message ?? error}`);
+      process.exitCode = 1;
+    }
+  }
+}

package/semantic.js

@@ -8,6 +8,7 @@
  * 1. **默认关闭**：`provider` 为空时，这里连 `import()` 都不会执行；
  * 2. **不 import 任何宿主包**：提供方只能是「本地模块路径」（用户在配置里写），
  *    或者内置的 `host-llm` —— 后者也走 `llm.js` 的动态 import，静态依赖图里没有它；
+ *    （也可以写成裸模块名，如 `dsh-engramory-recall/providers/openai-embeddings`——包里自带）
  * 3. **挂掉的提供方不许影响检索**：超时、抛错、返回垃圾形状、编造不存在的文件名，
  *    一律降级回词面结果，并把原因如实放进返回值（`code` / `message`）。
  *
@@ -26,8 +27,23 @@
  * ```
  *
  * 两种接口的边界**不一样**，这是量出来的、不是拍出来的：
- * · `rerank` 声称自己有打分器 ⇒ 结果与词面走 RRF 融合，**允许改顺序**（同 limit 下不增不减）；
- * · `expand` 只是「换个说法再查一遍」⇒ **只补空位，永不改动词面顺序**。
+ * · `rerank` 声称自己有打分器 ⇒ 它看到的是一个**宽于输出窗口的候选池**（`pool`，默认 50），
+ *   融合方式由 `fusion` 决定：`rrf`（默认，词面与提供方各一票，谁也别想翻天）或
+ *   `trust`（提供方说了算，词面只负责出候选与补空位）；
+ * · `expand` 只是「换个说法再查一遍」⇒ **只补空位，永不改动词面顺序**（它仍然只按 `limit` 检索）。
+ *
+ * 「池子宽于窗口」这条是 0.12.0 加的，动机：池宽 = 输出窗口时，提供方只能重排词面已经挑中的
+ * 那几条，天花板被词面钉死。实测（`bench/.tmp/pool-oracle.mjs`，2026-10-15，合成 704 条 +
+ * 真库探针 36 条，`limit=4`，提供方 = 完美排序 / 乱序排序两个极端）：
+ * · 池内召回随池宽上升：合成 P=5 495/704 → P=20 610/704 → P=50 685/704 → P=100 689/704；
+ *   真库 36 条在 P≥5 就全在池内。池宽就是「完美提供方」的天花板。
+ * · `rrf` + 宽池（P≥20）能把完美提供方兑现一半：合成 @1 52.7%（P=5/20 一样，因为 RRF 里
+ *   词面第 1 名还压着提供方第 1 名）→ @4 73.6%；真库 @1 72.2% → 80.6%。
+ * · `trust` 才拿到全部：合成 @1 86.6%（= 池内召回 610/704）、真库 @1 100%（36/36）。
+ * · 代价同样量过：提供方若把顺序**倒过来**，`rrf` 合成 @1 50.4% → 26.0%，`trust` 更惨；
+ *   把提供方票数加到 2/3 票能让完美提供方涨到 63.2%/67.5%，但乱序提供方会直接把 @1 打到
+ *   1.0%（合成）/ 0.0%（真库）—— 所以**票数永远留 1**，谁想更激进就用 `trust` 明说。
+ * 一句话：`rrf` = 少赚不赔，`trust` = 把天花板交给提供方。
  *   实测（2026-10-15，真库探针 36 条 + 合成 70 条，改写由宿主模型逐条产生）：
  *   RRF 融合让 3 条改写以 1:1 的票数盖过原查询的 1 票，真库 hit@1 26/36 → 19/36、
  *   hit@4 36/36 → 30/36；把原查询加权到 3 票 / 5 票、或改成归一化打分，全都仍不如基线；
@@ -48,6 +64,41 @@ export const DEFAULT_TIMEOUT_MS = 2000;
 export const MAX_EXPANSIONS = 8;
 export const MAX_EXPANSION_CHARS = 120;
 export const HOST_LLM = 'host-llm';
+/** 复用 DSH 设置页里已配好的模型路由（baseURL + 模型 + 密钥），不用再填一遍环境变量。 */
+export const HOST_EMBED = 'host-embed';
+
+/**
+ * 目录自带路由的地址与 embedding 模型（pi-ai catalog 里，宿主设置读不到，只能在这里兜底）。
+ * 只收「确定提供 OpenAI 形状 /embeddings 接口」的几家；其余一律要求用户显式写 baseURL。
+ */
+const HOST_EMBED_BASE_URLS = {
+  openai: 'https://api.openai.com/v1',
+  mistral: 'https://api.mistral.ai/v1',
+  together: 'https://api.together.xyz/v1',
+  zai: 'https://open.bigmodel.cn/api/paas/v4',
+};
+const HOST_EMBED_MODELS = {
+  openai: 'text-embedding-3-small',
+  mistral: 'mistral-embed',
+  together: 'BAAI/bge-large-en-v1.5',
+  zai: 'embedding-3',
+};
+/** `rerank` 提供方看到的候选池宽度（`pool` 配置，默认 50；上限 200）。 */
+export const DEFAULT_POOL = 50;
+export const MAX_POOL = 200;
+/**
+ * 融合模式：
+ * · `trust`（默认）= 提供方给了顺序就按它的顺序走，词面只用来补满窗口；
+ * · `rrf` = 词面与提供方各一票（等权），词面因此有一票否决权。
+ *
+ * 默认选 `trust` 是量出来的（合成 704 条、池 20、窗口 5；`npm run bench:seam` 可复算）：
+ * 真提供方返回的是一份**全量排名**，等权 RRF 会让它自己第 2 名以后的名次去稀释第 1 名 ——
+ * 完美提供方在 rrf 下只有 52.7%/76.3%（比纯词面 50.4%/70.3% 几乎没赚），trust 下是 86.6%/86.6%；
+ * 反过来，坏提供方在 trust 下会一路砸到底（倒排：1.0%/4.7%），这时 rrf 是安全档（26.0%/63.9%）。
+ * 结论：可信的提供方配 trust；不确定它靠不靠谱时配 rrf。
+ */
+export const FUSION_MODES = ['rrf', 'trust'];
+export const DEFAULT_FUSION = 'trust';
 
 /** 配置里能写的提供方：空 = 关闭；`host-llm` = 走宿主模型（llm.js）；其余当本地模块路径。 */
 export function describeSeam(config = {}) {
@@ -56,20 +107,116 @@ export function describeSeam(config = {}) {
   if (spec === HOST_LLM) {
     return { enabled: true, kind: 'host-llm', spec, message: '语义接缝指向宿主模型（llm.js，动态 import）' };
   }
+  if (spec === HOST_EMBED) {
+    return { enabled: true, kind: 'host-embed', spec, message: '语义接缝复用 DSH 里已配好的模型路由（设置页的 baseURL + 模型 + 密钥）' };
+  }
   return { enabled: true, kind: 'module', spec, message: `语义接缝指向本地模块：${spec}` };
 }
 
+/** 候选池宽度：至少等于输出窗口，默认 DEFAULT_POOL，上限 MAX_POOL。 */
+export function poolLimit(config = {}, limit = 5) {
+  const want = Number(config.pool);
+  const pool = Number.isFinite(want) && want > 0 ? want : DEFAULT_POOL;
+  return Math.min(MAX_POOL, Math.max(Number(limit) || 1, Math.floor(pool)));
+}
+
+/** 融合模式：只认 FUSION_MODES 里的值，其余一律回默认（配置写错不该让检索变怪）。 */
+export function fusionMode(config = {}) {
+  const want = String(config.fusion ?? '').trim().toLowerCase();
+  return FUSION_MODES.includes(want) ? want : DEFAULT_FUSION;
+}
+
 function expandHome(value) {
   if (value === '~') return homedir();
   return value.startsWith('~/') ? join(homedir(), value.slice(2)) : value;
 }
 
+/**
+ * `provider` 可以写成三种形式，这里判断它是不是「裸模块名」（交给 Node 解析）：
+ * · `dsh-engramory-recall/providers/openai-embeddings` —— 裸名（包自引用 / 依赖解析）；
+ * · `./my-provider.mjs`、`~/x/y.mjs`、`/abs/path.mjs` —— 路径。
+ */
+export function isBareSpecifier(spec) {
+  const text = String(spec ?? '').trim();
+  if (!text) return false;
+  if (text.startsWith('.') || text.startsWith('/') || text.startsWith('~')) return false;
+  return !/^[A-Za-z]:[\\/]/.test(text);
+}
+
 export function resolveProviderPath(spec, baseDir = process.cwd()) {
   const text = expandHome(String(spec ?? '').trim());
   if (!text) return '';
   return isAbsolute(text) ? text : resolve(baseDir, text);
 }
 
+/**
+ * 从宿主设置里读出「用哪条路由做 embedding」：路由 → baseURL → 模型 → 密钥。
+ * 每一步都给出**可照做的失败信息**（而不是一句「配置错误」），并且**绝不把密钥写进任何返回值以外的路径**。
+ */
+async function readHostEmbedProfile(runtime, config = {}) {
+  const ctx = runtime?.ctx;
+  const settings = ctx && typeof ctx.get === 'function' ? ctx.get('settings') : undefined;
+  if (!settings || typeof settings.describe !== 'function') {
+    return { ok: false, code: 'no-host', message: 'host-embed 需要宿主设置服务（ctx.settings）；MCP 等没有宿主的场景请改用本地模块提供方' };
+  }
+  let route = String(config.hostRoute ?? runtime?.config?.provider ?? '').trim();
+  if (!route) {
+    try {
+      route = String(ctx.get('agentDefaultModel')?.currentSelection?.()?.provider ?? '').trim();
+    } catch {
+      route = '';
+    }
+  }
+  if (!route) return { ok: false, code: 'no-route', message: '拿不到宿主默认模型的路由：请在插件配置里写 semanticHostRoute' };
+
+  let row;
+  try {
+    const rows = settings.describe({ redactSecrets: true });
+    row = (Array.isArray(rows) ? rows : []).find((item) => item?.ns === 'llm-pi-ai');
+  } catch (error) {
+    return { ok: false, code: 'load-error', message: `读宿主设置失败：${error?.message ?? error}` };
+  }
+  const profile = row?.value?.providers?.[route] ?? row?.user?.providers?.[route] ?? {};
+  const baseUrl = String(config.hostBaseUrl ?? profile.baseURL ?? HOST_EMBED_BASE_URLS[route] ?? '').trim();
+  if (!baseUrl) {
+    return {
+      ok: false,
+      code: 'no-base-url',
+      message: `路由 ${route} 没写 baseURL，插件也猜不到它（目录自带路由的地址在 pi-ai catalog 里）。请在 DSH 设置 → 模型 →「自定义模型 API」里加一条 OpenAI 兼容的 embedding 路由，或在本插件配置里写 semanticHostBaseUrl`,
+    };
+  }
+  const declared = Array.isArray(profile.models) ? profile.models : [];
+  const model =
+    String(config.hostModel ?? '').trim() ||
+    String(declared.find((item) => /embed/i.test(String(item?.id ?? '')))?.id ?? '').trim() ||
+    (declared.length === 1 ? String(declared[0]?.id ?? '').trim() : '') ||
+    HOST_EMBED_MODELS[route] ||
+    '';
+  if (!model) {
+    return { ok: false, code: 'no-model', message: `路由 ${route} 里找不出 embedding 模型：请在插件配置里写 semanticHostModel（例如 text-embedding-3-small）` };
+  }
+  // 宿主侧凭据的 ref 就是环境变量名本身（custom 路由保存时按 <ROUTE>_API_KEY 派生，catalog 路由由 pi-ai 声明）。
+  const keyRef = String(profile.apiKeyEnv ?? '').trim() || `${route.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`;
+  const credentials = typeof ctx.get === 'function' ? ctx.get('credentials') : undefined;
+  let apiKey = '';
+  if (credentials && typeof credentials.resolve === 'function') {
+    try {
+      // 宿主规范：凭据**每次调用现解析、不许跨操作缓存**（值可能被用户随时改）。
+      apiKey = String((await credentials.resolve(keyRef))?.value ?? '');
+    } catch {
+      apiKey = '';
+    }
+  }
+  if (!apiKey) {
+    return {
+      ok: false,
+      code: 'no-key',
+      message: `宿主凭据里没有 ${keyRef}：在 DSH 设置 → 模型 →「${route}」里填 API 密钥（落到 ~/.dsh/.credentials.yaml 的 refs.${keyRef}），或给本插件配 ENGRAMORY_EMBED_API_KEY`,
+    };
+  }
+  return { ok: true, route, baseUrl, model, apiKey, keyRef };
+}
+
 /** 加载提供方。任何失败都返回 `{ ok: false }` —— 调用方负责降级，这里绝不抛。 */
 export async function loadProvider(config = {}, deps = {}) {
   const seam = describeSeam(config);
@@ -89,6 +236,28 @@ export async function loadProvider(config = {}, deps = {}) {
       return { ok: true, provider, kind: 'expand', code: 'host-llm', message: seam.message, seam };
     }
 
+    if (seam.kind === 'host-embed') {
+      const profile = await readHostEmbedProfile(deps.runtime, config);
+      if (!profile.ok) return { ok: false, code: profile.code, message: profile.message, seam };
+      const module = await import('./providers/openai-embeddings.mjs');
+      const provider = module.createProvider({
+        baseUrl: profile.baseUrl,
+        model: profile.model,
+        apiKey: profile.apiKey,
+        providerName: `${HOST_EMBED}:${profile.route}/${profile.model}`,
+      });
+      return { ok: true, provider, kind: 'rerank', code: 'host-embed', message: seam.message, seam, hostRoute: profile.route };
+    }
+
+    if (isBareSpecifier(seam.spec)) {
+      const module = await import(seam.spec);
+      const provider = normalizeModule(module, seam.spec);
+      if (!provider) {
+        return { ok: false, code: 'unsupported', message: `提供方模块必须导出 rerank 或 expand 函数：${seam.spec}`, seam, path: seam.spec };
+      }
+      return { ok: true, provider, kind: provider.kind, code: 'module', message: seam.message, seam, path: seam.spec };
+    }
+
     const full = resolveProviderPath(seam.spec, deps.baseDir);
     if (!full) return { ok: false, code: 'empty-path', message: '提供方路径是空的', seam };
     try {
@@ -109,6 +278,14 @@ export async function loadProvider(config = {}, deps = {}) {
     }
     return { ok: true, provider, kind: provider.kind, code: 'module', message: seam.message, seam, path: full };
   } catch (error) {
+    if (error?.code === 'ERR_MODULE_NOT_FOUND' || error?.code === 'MODULE_NOT_FOUND') {
+      return {
+        ok: false,
+        code: 'not-found',
+        message: `找不到提供方模块：${seam.spec}（裸名要装在同一个 node_modules 里，否则写绝对路径）`,
+        seam,
+      };
+    }
     return { ok: false, code: 'load-error', message: `加载提供方失败：${error?.message ?? error}`, seam };
   }
 }
@@ -274,7 +451,10 @@ export async function semanticSearch(options = {}) {
 
   try {
     if (provider.kind === 'rerank') {
-      const docs = lexical.map((hit, index) => ({
+      // 提供方看的是宽池：池子 = 输出窗口时它只能重排词面已挑中的那几条（天花板被词面钉死）。
+      const poolSize = poolLimit(config, limit);
+      const pool = poolSize > limit ? runSearch(options.index, query, poolSize) : lexical;
+      const docs = pool.map((hit, index) => ({
         id: hit.id,
         snippet: hit.snippet,
         matched: hit.matched,
@@ -286,17 +466,28 @@ export async function semanticSearch(options = {}) {
       if (!ranking.ids.length) {
         return fail(lexical, started, 'provider-empty', `提供方 ${provider.name} 没给出任何可用排序，已降级`, { provider: provider.name });
       }
-      const order = mergeRRF([lexical.map((hit) => hit.id), ranking.ids], limit);
-      const byId = new Map(lexical.map((hit) => [hit.id, hit]));
+      const byId = new Map(pool.map((hit) => [hit.id, hit]));
+      const fusion = fusionMode(config);
+      let order;
+      if (fusion === 'trust') {
+        // 提供方说了算：它给过分的按它的顺序走，剩下的坑用词面顺序补满。
+        order = [...ranking.ids, ...pool.map((hit) => hit.id).filter((id) => !ranking.ids.includes(id))].slice(0, limit);
+      } else {
+        order = mergeRRF([pool.map((hit) => hit.id), ranking.ids], limit);
+      }
       const hits = order.map((id) => byId.get(id)).filter(Boolean);
-      // 词面没排进前 limit、却被提供方拉进来的文档不在池子里 —— 如实报数，别假装融合了。
+      // 提供方编造的、池子里没有的文件名 —— 如实报数，别假装融合了。
       const missing = order.filter((id) => !byId.has(id)).length;
       return {
         hits,
         used: true,
         code: 'reranked',
-        message: `已按 ${provider.name} 的顺序融合（RRF）`,
+        message: fusion === 'trust'
+          ? `已按 ${provider.name} 的顺序取前 ${hits.length} 条（池 ${pool.length}，Trusted 融合）`
+          : `已按 ${provider.name} 的顺序融合（RRF，池 ${pool.length}）`,
         provider: provider.name,
+        fusion,
+        pool: pool.length,
         dropped: ranking.dropped,
         missing,
         ms: Date.now() - started,