@avantf/dsh-mem 0.3.1 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # @avantf/dsh-mem
 
 DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的**记忆**和一个**文档知识库**，
-以进程内 Cordis 插件的形式提供 8 个模型工具、三段用法提示和两个设置页。
+以进程内 Cordis 插件的形式提供 8 个模型工具、三段用法提示和两个主窗口标签页。
 
 ## 主要功能
 
@@ -12,7 +12,7 @@ DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的
     矛盾补扫与裁决 / 维护
   - `kb_add` / `kb_list` / `kb_remove` / `kb_reindex`：新增文档（文本 / 文件 / URL，或批量导入目录，
     同名拒绝）、列表（带出受管 `.md` 的绝对路径与切片详情）、删除、重建索引；
-    **改一篇既有文档就是改那份 `.md`**（用 `edit`，索引自动跟随）
+    **改一篇既有文档就是改那份 `.md`**（用文件工具改，索引自动跟随）
   - `kb_query`：跨「记忆事实 + 文档切片」的统一检索，结果带来源标注
 - **混合检索 + 联合融合**：库内三路（语义 / FTS bm25 / 实体 Jaccard，另有 HRR 实体探查腿），
   跨库在合并候选池上做联合归一化——记忆与文档切片因此处于同一分数刻度。
@@ -27,8 +27,9 @@ DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的
   `.doc`/`.xls`/`.ppt` / 可执行文件）会被拒绝并说明检测到的类型；GBK/GB18030 等中文旧编码会自动解码
   并在结果里标出 `encoding`。
 - **知识可维护**：每篇文档在 `~/.avantf/knowledge/docs/<domain>/<source>/<title>.md` 留一份可编辑副本
-  （frontmatter 记着它属于哪篇文档）——用你自己的编辑器改，回到「知识」页点「重新摄入」即把改动拉回
-  索引；删除文档会连同这份副本一起删除，`source_uri` 指向的原文件始终不被改动。
+  （frontmatter 记着它属于哪篇文档）——用你自己的编辑器改，插件会在**其后任一工具调用结束时**自动把改动同步
+  回索引（先一次 `stat` 判漂移、再用正文哈希裁决，只重摄入真正改过的），「知识」页的「重新摄入」是手动兜底；
+  删除文档会连同这份副本一起删除，`source_uri` 指向的原文件始终不被改动。
 - **可插拔、可降级**：语义后端 / 重排 / 向量库都走内部注册表；模型、hnswlib、分词器任一缺失都自动降级
   （FTS + 实体 / numpy 向量库 / 正则抽取），不会因此退出。
 - **两个主窗口标签页**（排在 对话 / 轨迹 之后）：**记忆**（浏览、编辑、归档恢复、反馈、矛盾裁决）与
@@ -40,20 +41,34 @@ DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的
 ## 接入 dsh
 
 ```bash
-# 1) 装这两个包（在 profile 目录里各装一次）：插件本身，以及家族底座。
-#    底座是插件的 peer；npm 这类会自动装 peer 的包管理器会跟着装上，pnpm（关掉 autoInstallPeers）
-#    与 yarn 不会，所以要显式装。
-dsh plugin --profile <PROFILE> add @avantf/dsh-plugin-base
-dsh plugin --profile <PROFILE> add @avantf/dsh-mem
-
-# 2) 放行原生依赖的构建：pnpm 10+ 默认忽略 postinstall，而 better-sqlite3 是记忆库的存储层。
-#    不放行时插件仍会正常挂载，但 8 个工具都会回 "memory unavailable"（自动降级，不拖垮宿主启动）。
+# 1) 装这两个包：插件本身，以及家族底座。底座是插件的 peer；不开 autoInstallPeers 的包管理器
+#    （pnpm / yarn）不会跟着装上，所以要显式装。
+#    版本号建议写死：pnpm ≥ 10 的 minimumReleaseAge 会避开刚发布的版本，解析到的旧版本可能不认识
+#    当前宿主（它的 peer 区间不含这个 dsh），那一单会被宿主的安装门禁直接拒绝并把 profile 回滚。
+dsh plugin --profile <PROFILE> add @avantf/dsh-plugin-base@<version>
+dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
+
+# 2) 原生依赖只剩**可选**的加速件（分词 / 向量索引 / 嵌入模型）。它们缺失只会降级检索质量，
+#    不影响记忆库本身——存储层用的是运行时自带的 node:sqlite，没有需要编译的数据库模块。
 cd ~/.dsh/profiles/<PROFILE>
-pnpm approve-builds --all     # 至少勾选 better-sqlite3；nodejieba / hnswlib-node 可选
+pnpm approve-builds --all     # 勾选 nodejieba / hnswlib-node / onnxruntime，可按需
 ```
 
 ```yaml
-# 3) 挂载插件：编辑 ~/.dsh/profiles/<PROFILE>/cordis.patch.yml（不存在就新建）
+# 3) 挂载插件：装完通常什么都不用做。
+#
+# 本包声明了组合包（dsh.bundle.patch → 随包的 cordis.patch.yml），所以 `dsh plugin add` 装它时会
+# 顺手把这个包选进 profile 的 dsh.profile.bundles（实测），挂载行由随包的 patch 插入；DSH Desktop
+# 的「插件」页走的也是这条。只有两种情况才需要自己写那一行：
+#   · 用 npm / yarn 装（它们不认识 dsh.profile.bundles）；
+#   · 手工编辑 profile 的包清单，而没有把本包选进 bundles。
+# 两条路都做也不会挂两次：当前 dsh（0.1.7 / 0.2.0 线）的 loader 按条目 id 去重，只挂载一次（实测）；
+# 但 0.1.5 线（仍在本包 peer 区间内）上重复的行 id 会让 profile 树加载失败——所以始终二选一。
+#   · 前提：自动选中只在 `dsh plugin add` **跑完**那一刻发生。若它中途被构建提示（pnpm 的
+#     approve-builds）拦下（ERR_PNPM_IGNORED_BUILDS、非零退出），依赖装上了但组合包**不会被选中**，
+#     事后再 add / install 也不会补选——先答完提示再装，或到 DSH Desktop 的「插件」页启用这个组合包。
+#
+# 手写的那一行，放在 ~/.dsh/profiles/<PROFILE>/cordis.patch.yml（不存在就新建）：
 - insert:
     - id: avantf-mem
       name: '@avantf/dsh-mem'
@@ -67,9 +82,27 @@ pnpm approve-builds --all     # 至少勾选 better-sqlite3；nodejieba / hnswli
 dsh web
 ```
 
-- 插件的 `@deepseek-ai/*` peer 由 profile 上层 `~/.dsh/profiles/node_modules` 解析
-  （`dsh plugin add` 不会另装一份）。**不要在 profile 里再装** `cordis` / `schemastery` / `dsh-tools`
-  ——两份对象身份会让工具与 typert 注册表对不上。
+### DSH Desktop
+
+Desktop 用的是同一套 profile（profile 名 `desktop`），差别只有三点：
+
+- **界面上只能装组合包**。Desktop 的「插件」页与 `plugin_manager` 只接受声明了 `dsh.bundle.patch`
+  的包（本包已声明）：在页面上装它，它会把这个包选进 `dsh.profile.bundles`，并应用随包的
+  `cordis.patch.yml`——不用手写挂载行。
+- **用它自带的 dsh**：`<安装目录>/resources/runtime/cli/bin/dsh.cmd`（或在设置里把 `dsh` 装进 PATH）。
+- **重启应用**才生效：Desktop 的宿主半边与浏览器半边一起启动，不像 Web 那样热更。
+
+Desktop 的宿主进程是 **Electron**（`NODE_MODULE_VERSION` 与同版本 Node 不同）。这正是本插件不依赖任何
+SQLite 绑定的原因：存储层用运行时自带的 `node:sqlite`，它就在跑插件的那个进程里，没有预编译产物要匹配、
+也不需要用户装 C++ 工具链。启动日志里 `sqlite=node:sqlite <版本>` 就是它；两个宿主写的是同一个 SQLite
+文件格式，换宿主不需要迁移数据。
+
+- 插件的 `@deepseek-ai/*` peer 由宿主提供（profile 上层的运行时解析表），`dsh plugin add` 不会另装一份。
+  **不要在 profile 里再装** `cordis` / `schemastery` / `dsh-tools`——两份对象身份会让工具与 typert
+  注册表对不上。
+- `zod` 同样是**宿主提供的 required peer**（区间 `>=4.4.3 <5`，宿主的 dsh 自带）：工具的 wire 与参数
+  schema 都用**这一份**。**不要在 profile 里单独装一份 `zod`**——两个副本的 schema 类型身份不同，
+  跨副本传 schema 对象会在运行期对不上。
 
 ## 怎么用
 
@@ -91,8 +124,8 @@ dsh web
 看看知识库里关于「内存保护」的原文。（→ kb_query，结果带 source_ref，可据此引用）
 ```
 
-改一篇已经入库的文档：先用 `kb_list` 拿到那份 `.md` 的路径，再用编辑器改它，回到「知识」页点
-「重新摄入」；或直接对模型说"更新这篇文档"。
+改一篇已经入库的文档：先用 `kb_list` 拿到那份 `.md` 的路径，再用**任意文件工具**改它——改完不必手动回填，
+插件会在其后任一工具调用结束时自动同步（「重新摄入」是手动兜底）；或直接对模型说"更新这篇文档"。
 
 常见维护动作：
 
@@ -101,6 +134,24 @@ dsh web
 把矛盾检测的积压扫一遍。（→ mem_admin contradict_check，再对每条判 true_positive / false_positive）
 ```
 
+### 相关性门槛（严格 / 宽松）
+
+检索对每条腿都有一条**绝对**相关性门槛（打在每条腿的原始分上、融合之前）：语义余弦
+`min_semantic_similarity`（默认 `0.5`）、FTS 腿逐行命中的**不同查询词元数** `min_fts_terms`（默认 `2`）、
+实体 Jaccard `min_jaccard`（默认 `0.2`）——分数等于门槛保留，`0` = 关闭该腿（改在
+`~/.avantf/configs/common.yaml` 的 `retriever` 节）。
+
+- **两个档位（UI 选择器 / `floors` 参数）**：「知识」「记忆」页的查询面板有「严格 / 宽松」选择，`mem_recall.search`
+  与 `kb_query` 也接受 `floors: 'strict' | 'loose'`。`strict` = 用配置值、**不**自动放宽（面板默认它，好让空结果
+  有明确说法）；`loose` = 直接宽松档，换成一组仍有绝对底线的值（`0.40 / ⌈词元数/2⌉ / 0.15`）——所以宽松档
+  一样答得出"确实没有相关结果"，不是"无门槛"。
+- **不传 `floors` 时的默认策略：严格档为空就自动放宽一次**：先按严格档跑；**仅当**它一条都没命中、且确实有
+  条目被门槛丢掉时，才用宽松档补跑一遍。只有宽松档真的产出结果才替换答案，结果里置 `relaxed: true`，面板显示
+  「（已自动放宽门槛）」；放宽也救不回时**原样返回严格档结果**（含"被门槛丢掉 N 条"的报告）。跨库查询只对
+  **合并后**的结果做这个决定，免得一条空库把放宽后的尾部混进另一条库的严格命中。
+- **可解释性**：结果带生效门槛 `floors` 与每腿丢弃数 `dropped_by_floor`，所以「门槛挡掉的空」与「本来就没有」
+  能分开说——面板因此分别给出「严格门槛丢弃了 N 条，可切「宽松」重试」与「（宽松档下）确实没有相关结果」。
+
 ## 配置、数据与提示词
 
 - **数据目录**：默认 `~/.avantf`。记忆库、知识库（含 `knowledge/docs` 下的受管文档副本）与模型缓存
@@ -109,7 +160,12 @@ dsh web
   `memory.yaml`、`knowledge.yaml`；只写你要改的项，其余取内置默认。`dataHome` 也可以写在 profile 的
   config 里，但环境变量 `AVANTF_HOME` 会压过它。
 - **提示词文件**：`~/.avantf/prompts/mem-memory-usage.md`、`mem-knowledge-usage.md`、`mem-kb-edit.md`。
-  缺失或为空时插件写入默认内容，**只在启动时读一次**，改完重启生效。
+  缺失或为空时插件写入默认内容，**只在启动时读一次**，改完重启生效。正文可以**按领域改写**——内置默认
+  刻意不出现任何领域名词（它同时服务开发、投研、日常等场景），只给判据与"事实型 / 规则型"两种形状：
+  - 事实型：`用户不吃香菜；订餐默认备注不要香菜。`（谁 / 什么范围 / 偏好或要求或术语是什么）
+  - 规则型：`只有「注销式回购」减少总股本，库存股回购不减少——比较 EPS 影响时要区分。`（当……时，应……，附条件与例外）
+  - 反例（不该写成事实）：一次调查的过程叙述、数据表、命令与链接——依据属于知识库文档，记忆里只留**结论 + 位置**
+    （路径 / 来源 / 名称）；敏感信息同理，只记存放位置，不记明文。
 - **语义模型**：默认从 `hf-mirror.com` 下载并缓存，也可指向本地模型目录离线运行。
 - **升级前先备份 `~/.avantf`**：数据库迁移是单向的，用旧版本打开新库会被明确拒绝。
 
@@ -119,21 +175,26 @@ dsh web
 # 升级（或重装）到某个版本：同一条命令，换版本号即可
 dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 
-# 卸载：先删掉 profile 依赖
+# 卸载：先删掉 profile 依赖（这一步同时会取消该组合包的选中）
 dsh plugin --profile <PROFILE> remove @avantf/dsh-mem
-# 再删掉 ~/.dsh/profiles/<PROFILE>/cordis.patch.yml 里那段 `- id: avantf-mem` 挂载项
-#（该文件顶层必须是 YAML 数组：删空就写 `[]`，否则 dsh 启动会拒绝加载）
+# 再清掉挂载项：用组合包装的，包名已随上一步从 profile 的 `dsh.profile.bundles` 里去掉，无需再动；
+# 自己手写过那一行的，删掉 ~/.dsh/profiles/<PROFILE>/cordis.patch.yml 里那段 `- id: avantf-mem`
+#（该文件顶层必须是 YAML 数组：删空就写 `[]`，否则 dsh 启动会拒绝加载）。
+# DSH Desktop 的「插件」页上卸载会连着取消选中与依赖一起做。
 ```
 
 两者都需要重启 dsh 才生效。卸载**不动 `~/.avantf`**：记忆库、知识库、模型缓存全部保留。
 
 ## 环境要求
 
-- **Node ≥ 22**、**pnpm**
-- `better-sqlite3` 必需（原生模块，记忆库的存储层）；`nodejieba` / `hnswlib-node` /
-  `@huggingface/transformers` 可选，缺失时自动降级
-- 插件自包含：检索与知识引擎在构建时已内联进产物，安装不需要额外的家族包（只要底座，
-  由宿主以 peer 提供）
+- **Node `>=22.15.0 <23 || >=23.11.0`**、**pnpm**。记忆与知识两个库都建在运行时自带的 `node:sqlite`
+  上，这个区间是它的两个下限的交集：模块免 flag（22.13 / 23.4）与"忽略语句未用到的命名参数"
+  （22.15 / 23.11）。低于该下限（或该构建缺 FTS5）时插件照常挂载，但 8 个工具都回
+  `memory unavailable` 并给出原因，不会拖垮宿主启动
+- `nodejieba` / `hnswlib-node` / `@huggingface/transformers` 都可选：缺失时分别降级为正则抽取 /
+  numpy 向量库 / 纯词法检索
+- 插件自包含：检索与知识引擎在构建时已内联进产物，安装不需要额外的家族包。宿主提供的 peer 有两个：
+  底座 `@avantf/dsh-plugin-base`（安装时随插件一起装）与 `zod`（宿主的 dsh 自带那份）
 
 ## 从源码构建
 

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# The BUNDLE layer of @avantf/dsh-mem: one row, inserted over whatever the profile root holds.
+#
+# A bundle is how a DSH host installs a plugin without hand-editing the profile: selecting this
+# package in `dsh.profile.bundles` (the plugin manager does that when it installs it, and DSH Desktop's
+# 插件 page only installs packages that declare `dsh.bundle.patch`) applies THIS file as its own patch
+# layer. Installing the package as a plain dependency and adding the same row to the profile's own
+# `cordis.patch.yml` by hand is the other, equally supported route — the two are alternatives; do
+# exactly one. Doing both is never a double mount, but it is not harmless either: on the 0.1.5 line
+# (still inside this package's peer range) the duplicate row id makes the profile tree fail to load,
+# and on the 0.1.7/0.2.0 lines the loader keys entries by id and merely leaves a redundant row.
+- insert:
+    - id: avantf-mem
+      name: '@avantf/dsh-mem'
+      config:
+        # The in-process Cordis plugin (the only mode a DSH host can mount). `dataHome` is deliberately
+        # left out: its default is `~/.avantf`, and `$AVANTF_HOME` outranks a configured value anyway.
+        mode: cordis

package/lib/client.js

@@ -5328,7 +5328,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				second_pred: optionalText.optional(),
 				category: optionalText.optional(),
 				limit: count.optional(),
-				max_tokens: count.optional()
+				max_tokens: count.optional(),
+				floors: optionalText.optional()
 			})),
 			direct("admin", object({
 				action: optionalText.optional(),
@@ -5364,7 +5365,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				domain: optionalText.optional(),
 				source: optionalText.optional(),
 				limit: count.optional(),
-				max_tokens: count.optional()
+				max_tokens: count.optional(),
+				floors: optionalText.optional()
 			})),
 			direct("classifySource", object({ text: optionalText.optional() })),
 			direct("browseDir", object({ path: optionalText.optional() })),
@@ -5417,6 +5419,14 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		* `unwrapRemoteEnvelope` peels both, in order, and also tolerates a bare payload
 		* (a gateway that returns raw values, or a future protocol change), so the pages
 		* never render an envelope as if it were data.
+		*
+		* The application envelope also carries the **wire revision** (`wire`, optional): the host stamps
+		* the revision of the Remote FACE it publishes onto every answer (see `@avantf/dsh-mem`'s
+		* `remote.ts` `WIRE_VERSION`), and the client half reads it back to tell a rebuilt browser bundle
+		* from the host process that `dsh web` loaded before it. It rides the envelope rather than one
+		* method's payload because this plugin has no single entry point — each tab makes its own first
+		* call — while the envelope is the one object every answer shares. Absent means "a host older
+		* than the marker": still readable, but the client may not assume a method it knows about exists.
 		*/
 		function isRecord(value) {
 			return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -5450,17 +5460,20 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			};
 			const inner = result["value"];
 			if (isRecord(inner) && typeof inner["ok"] === "boolean") {
+				const wire = typeof inner["wire"] === "number" ? inner["wire"] : void 0;
 				if (inner["ok"] === false) {
 					const violations = Array.isArray(inner["violations"]) ? inner["violations"].map(String) : void 0;
 					return {
 						ok: false,
 						error: remoteErrorText(inner["error"]),
-						...violations && violations.length > 0 ? { violations } : {}
+						...violations && violations.length > 0 ? { violations } : {},
+						...wire === void 0 ? {} : { wire }
 					};
 				}
 				return {
 					ok: true,
-					value: inner["value"]
+					value: inner["value"],
+					...wire === void 0 ? {} : { wire }
 				};
 			}
 			return {
@@ -5631,6 +5644,71 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 ` + lines.join("\n") + (rest > 0 ? `\n… 另有 ${String(rest)} 篇` : "") + "\n\n选择「取消」不会写入任何内容。";
 		}
 		//#endregion
+		//#region src/client/wire.ts
+		/**
+		* The client half's wire-revision diagnostics.
+		*
+		* WHY THE TWO HALVES DRIFT. The browser bundle is re-read on every page load; the host half is loaded
+		* once, when `dsh web` starts. So a rebuilt client routinely talks to an older host, and the ONE
+		* failure this must never produce is a bare gateway 404 — it reads exactly like "the record or the
+		* file is gone", which it does not mean. The host stamps `WIRE_VERSION` (see `src/remote.ts`) onto
+		* every answer; `unwrapRemoteEnvelope` carries it back; these functions turn "the numbers disagree"
+		* into a sentence that names the remedy, and are also the gate a call added AFTER the marker uses to
+		* refuse itself against a host that cannot have registered it.
+		*
+		* Kept free of React (this package's tests stay free of the DSH client runtime): the transport
+		* edge is plain data in, plain text out.
+		*
+		* @module @avantf/dsh-mem/client/wire
+		*/
+		/**
+		* The version-skew note for a host's reported revision, or `undefined` when the two halves agree.
+		*
+		* A NOTE, not a throw: an unrecognized revision usually still carries the fields the panels render,
+		* and blanking them is exactly the degradation the marker exists to avoid. `hostWire` is read off
+		* the DECODED envelope (`unwrapRemoteEnvelope`), so `undefined` means "an older host that predates
+		* the marker", never a decode failure.
+		*/
+		function hostSkew(hostWire) {
+			if (hostWire === 1) return void 0;
+			if (hostWire === void 0) return `宿主没有回报 wire 版本（它比本客户端旧）：面板可能缺少新字段，重启 dsh web 让两半对齐。（本客户端说 wire=${String(1)}）`;
+			return `宿主回报的 wire 版本是 ${String(hostWire)}，本客户端只认识 ${String(1)}：面板继续显示，但两半可能已经错位——重启 dsh web 后再试。`;
+		}
+		/**
+		* Whether a host reporting `hostWire` can have registered a method introduced at `required`.
+		*
+		* `undefined` is "no revision observed yet", and is reported as NOT supported by this predicate —
+		* the caller decides whether "unknown" means "refuse" (see the gate in `client/index.ts`, which only
+		* refuses when it has actually SEEN an older revision).
+		*/
+		function hostSupports(hostWire, required) {
+			return hostWire !== void 0 && hostWire >= required;
+		}
+		/**
+		* The sentence for a call this client refuses to SEND because the host's REPORTED revision predates
+		* the method.
+		*
+		* The call is never sent, so this must not read as a transport failure: the host's own revision says
+		* the method does not exist, and the remedy (restart dsh web) is specific. Only called with a known
+		* revision — an unobserved one is sent and diagnosed by {@link transportHint} instead.
+		*/
+		function staleHostText(hostWire, required, what) {
+			return `宿主仍在运行旧版本（wire ${String(hostWire)} < ${String(required)}）：它还没有注册 ${what} 这条调用，所以这次请求没有发出去。重启 dsh web 后再试。`;
+		}
+		/**
+		* Name a transport failure that is really a VERSION SKEW.
+		*
+		* A gateway answers a method the host never published with an HTTP 404, which reads exactly like
+		* "the record or the file is gone". The sentence therefore names the missing REGISTRATION (an older
+		* host, or one never restarted) rather than only repeating the transport text; anything that is not
+		* a 404 is returned verbatim, because then the transport's own words are the useful ones.
+		*/
+		function transportHint(cause) {
+			const text = cause instanceof Error ? cause.message : String(cause);
+			if (!/404|not found/iu.test(text)) return text;
+			return `宿主可能没有注册这个接口（旧版本 / 未重启）：客户端会随页面刷新，宿主只在 dsh web 启动时加载一次，所以 dsh web 很可能还在跑旧的宿主代码。重启 dsh web 后再试。（原始错误：${text}）`;
+		}
+		//#endregion
 		//#region src/client/index.ts
 		/**
 		* @avantf/dsh-mem — DSH client half.
@@ -5688,18 +5766,48 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		/** One page of the 知识 tab's document list; the 记忆 tab pages at 50 for the same reason. */
 		const DOC_PAGE_SIZE = 50;
 		/**
+		* The wire revision the host last reported, and whether its absence/mismatch was logged.
+		*
+		* Module state, not React state, on purpose: EVERY call goes through {@link callRemote}, so the
+		* first answer teaches the client which host process it is talking to, whichever panel asked. The
+		* host is loaded once, so this cannot change under a session — one write is the whole story.
+		*/
+		let hostWire;
+		let skewLogged = false;
+		/**
 		* Run one Remote call and normalize every shape it can take: the transport's
 		* `{ok,value}` envelope wrapping the gateway's own `{ok,value}` /
 		* `{ok,error,violations}` envelope, a bare value, or a thrown carrier failure.
 		* Both layers are peeled (see `unwrapRemoteEnvelope`), so `value` is always the
 		* payload and `error` is always the host's message. Failures are returned, never
 		* swallowed.
+		*
+		* `requires` is the wire revision that FIRST carried this method, and is how the version marker
+		* becomes a gate: a host whose REPORTED revision predates the method is never asked (the call is not
+		* sent), and the failure names the remedy instead of surfacing the gateway's 404. No current method
+		* needs it — all ten predate the marker — but a method added later MUST pass its revision here; see
+		* `src/remote.ts` `WIRE_VERSION`'s bump rule.
+		*
+		* An UNKNOWN revision (no answer observed yet: this is the first call) does not block — refusing
+		* there would deadlock a gated method that happens to be first, and would refuse every host during
+		* an upgrade. It is sent, and a host that really is too old answers with the 404 that
+		* {@link transportHint} explains.
 		*/
-		async function callRemote(label, pending) {
+		async function callRemote(label, pending, requires) {
+			if (requires !== void 0 && hostWire !== void 0 && !hostSupports(hostWire, requires)) return {
+				ok: false,
+				error: staleHostText(hostWire, requires, label)
+			};
 			try {
 				const result = await pending;
 				console.log(`[avantf-mem] ${label} ->`, result);
 				const decoded = unwrapRemoteEnvelope(result);
+				if (typeof decoded.wire === "number") hostWire = decoded.wire;
+				const skew = decoded.ok || decoded.wire !== void 0 ? hostSkew(decoded.wire) : void 0;
+				if (skew !== void 0 && !skewLogged) {
+					skewLogged = true;
+					console.warn(`[avantf-mem] ${skew}`);
+				}
 				if (decoded.ok) return {
 					ok: true,
 					value: decoded.value
@@ -5713,7 +5821,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				console.error(`[avantf-mem] ${label} failed`, error);
 				return {
 					ok: false,
-					error: error instanceof Error ? error.message : String(error)
+					error: transportHint(error)
 				};
 			}
 		}
@@ -6368,13 +6476,36 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			if (domain !== "" && source !== "") return `${domain} → ${source}`;
 			return domain || source || "文档切片";
 		}
+		/**
+		* How many candidates one reply's relevance floors removed, across every leg.
+		*
+		* This is the difference between the two readings of an empty result ("the floors removed N" vs
+		* "there was nothing to remove"), and it is what makes the panel's 宽松 hint actionable rather than
+		* a suggestion to retry blindly.
+		*/
+		function droppedByFloor(value) {
+			const drops = value.dropped_by_floor;
+			if (drops === void 0) return 0;
+			return drops.semantic + drops.fts + drops.jaccard + drops.hrr;
+		}
 		function KnowledgePanel(props) {
 			const [showQuery, setShowQuery] = react.useState(false);
 			const [query, setQuery] = react.useState("");
 			const [kind, setKind] = react.useState("all");
+			/**
+			* The relevance-floor profile (contract `FLOOR_PROFILES`): 严格 = the configured floors with NO
+			* automatic fallback, 宽松 = the relaxed floors. Default 严格 — the panel must not silently trade
+			* precision for recall, and sending `strict` explicitly is what makes the empty-result hint
+			* actionable ("N were dropped, switch to 宽松") instead of the retry having already happened.
+			* The value is always sent; an omitted profile is the engine's default policy (auto-relax once),
+			* which the 严格/宽松 labels would misdescribe.
+			*/
+			const [floors, setFloors] = react.useState("strict");
 			const [domain, setDomain] = react.useState("");
 			const [source, setSource] = react.useState("");
 			const [hits, setHits] = react.useState([]);
+			/** Candidates the last reply's floors removed; drives the 宽松 hint on an empty result. */
+			const [floorDropped, setFloorDropped] = react.useState(0);
 			const [queryStatus, setQueryStatus] = react.useState("输入关键词后按回车检索");
 			const [error, setError] = react.useState();
 			const [notice, setNotice] = react.useState();
@@ -6430,6 +6561,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				if (text.length === 0) {
 					setQueryStatus("请输入查询关键词");
 					setHits([]);
+					setFloorDropped(0);
 					setError(void 0);
 					return;
 				}
@@ -6440,17 +6572,22 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					kind,
 					domain: domain.trim() || void 0,
 					source: source.trim() || void 0,
-					limit: 10
+					limit: 10,
+					floors
 				})).then((outcome) => {
 					if (!queryGuard.isCurrent(seq)) return;
 					if (outcome.ok) {
-						const found = outcome.value?.hits ?? [];
+						const value = outcome.value;
+						const found = value?.hits ?? [];
 						setHits(found);
-						const degraded = outcome.value?.degraded === true ? "（语义降级，仅 FTS+实体）" : "";
-						setQueryStatus(`命中 ${String(found.length)} 条${degraded}`);
+						setFloorDropped(value === void 0 ? 0 : droppedByFloor(value));
+						const degraded = value?.degraded === true ? "（语义降级，仅 FTS+实体）" : "";
+						const profile = value?.relaxed === true ? "（已自动放宽门槛）" : floors === "loose" ? "（宽松门槛）" : "";
+						setQueryStatus(`命中 ${String(found.length)} 条${profile}${degraded}`);
 						setError(void 0);
 					} else {
 						setHits([]);
+						setFloorDropped(0);
 						setQueryStatus("查询失败");
 						setError(outcome.error);
 					}
@@ -6880,7 +7017,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				onChange: (e) => {
 					setKind(e.target.value);
 				}
-			}, h("option", { value: "all" }, "全部"), h("option", { value: "fact" }, "仅记忆"), h("option", { value: "doc_chunk" }, "仅文档"))), h(DomainField, {
+			}, h("option", { value: "all" }, "全部"), h("option", { value: "fact" }, "仅记忆"), h("option", { value: "doc_chunk" }, "仅文档"))), h("label", { className: pages_module_css_default.field }, "门槛", h("select", {
+				className: pages_module_css_default.input,
+				value: floors,
+				onChange: (e) => {
+					setFloors(e.target.value);
+				}
+			}, h("option", { value: "strict" }, "严格"), h("option", { value: "loose" }, "宽松"))), h(DomainField, {
 				label: "知识域（domain）",
 				value: domain,
 				onChange: setDomain,
@@ -6896,7 +7039,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				label: "检索",
 				disabled: queryLoading,
 				onClick: run
-			})), props.remote === void 0 ? null : h("div", { className: pages_module_css_default.status }, queryLoading ? "查询中…" : queryStatus), props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") ? h("div", { className: pages_module_css_default.status }, "没有匹配项。知识库为空时先用「入库/导入」添加文档；记忆里也只包含已写入的事实。") : null, groups.map(([groupName, groupHits]) => h("div", { key: groupName }, h("div", { className: pages_module_css_default.groupHead }, groupName), h("ul", { className: pages_module_css_default.list }, groupHits.map((hit) => h("li", {
+			})), props.remote === void 0 ? null : h("div", { className: pages_module_css_default.status }, queryLoading ? "查询中…" : queryStatus), props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") && floors === "strict" && floorDropped > 0 ? h("div", { className: pages_module_css_default.status }, `没有达到相关性门槛的结果（严格门槛丢弃了 ${String(floorDropped)} 条）——可切「宽松」重试。`) : null, props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") && floors === "loose" && floorDropped > 0 ? h("div", { className: pages_module_css_default.status }, `确实没有相关结果（宽松门槛下仍丢弃了 ${String(floorDropped)} 条）。`) : null, props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") && floorDropped === 0 ? h("div", { className: pages_module_css_default.status }, "没有匹配项。知识库为空时先用「入库/导入」添加文档；记忆里也只包含已写入的事实。") : null, groups.map(([groupName, groupHits]) => h("div", { key: groupName }, h("div", { className: pages_module_css_default.groupHead }, groupName), h("ul", { className: pages_module_css_default.list }, groupHits.map((hit) => h("li", {
 				key: `${hit.source_ref}:${String(hit.ref_id)}`,
 				className: pages_module_css_default.item
 			}, hit.text, h("span", { className: pages_module_css_default.meta }, `${hit.kind} · score ${hit.score.toFixed(3)} · ${hit.source_ref}` + (hit.entities && hit.entities.length > 0 ? ` · 实体：${hit.entities.join("、")}` : "") + ` · 创建于 ${hit.created_at}` + (hit.updated_at !== null && hit.updated_at !== hit.created_at ? ` · 更新于 ${hit.updated_at}` : "")))))))) : null, showIngest ? h("div", { className: `${pages_module_css_default.item} ${pages_module_css_default.form}` }, h("div", { className: pages_module_css_default.toolbar }, h(DomainField, {
@@ -7082,5 +7225,3 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		return module.exports;
 	}
 });
-
-//# sourceMappingURL=client.js.map

package/lib/engine/mem/config/config_files.d.ts

@@ -0,0 +1,26 @@
+import type { AvantfLogger } from '../../mem-contract/index.js';
+/**
+ * The default `configs/common.yaml`, written when the file is missing or blank.
+ *
+ * It is **comments only**, on purpose: the built-in defaults are already in force, so an all-comment
+ * file changes NOTHING about how the engine behaves — it only puts the knobs, their defaults and the
+ * two managed keys' escape hatches where a reader will find them. Uncommenting a line is the edit;
+ * deleting the file brings the defaults straight back.
+ *
+ * The rule mirrors the prompt files (the plugins' `src/prompt_files.ts`): missing or blank is an
+ * unfinished edit, not an empty configuration, so it is filled in. A file with ANY content is the
+ * user's and is never rewritten.
+ *
+ * Keys must match the schema in `@avantf/mem-contract` (`ConfigSchema`): an unknown key in an
+ * UNCOMMENTED line is warned about by the loader, so a wrong name here would be a trap rather than a
+ * hint. `config_files.spec.ts` pins the ones this template names.
+ */
+export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml / knowledge.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u6216 CLI --data-home\u3001\u63D2\u4EF6 profile \u7684 dataHome\uFF09\u51B3\u5B9A \u2014\u2014\n# \u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u7684\u65F6\u5019\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-small-zh-v1.5   # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 512\n#   auto_download: true\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# rerank:                             # \u91CD\u6392\u7684\u552F\u4E00\u5F00\u5173\uFF1Bnone = \u4E0D\u52A0\u8F7D\u4EFB\u4F55\u91CD\u6392\u6A21\u578B\n#   backend: none\n#   local_model: Xenova/bge-reranker-base\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u7EDD\u5BF9\u95E8\u69DB\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF08\u878D\u5408\u5206\u53EA\u5728\u4E00\u6B21\u67E5\u8BE2\u5185\u53EF\u6BD4\uFF0C\u4E0D\u80FD\u5F53\u95E8\u69DB\uFF09\u3002\n#   # 0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF1B\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-small-zh-v1.5/512 \u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F Jaccard \u6BD4\u503C\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
+/**
+ * Ensure the common config exists with content, and hand back the path either way.
+ *
+ * Never throws: an unwritable data home must not keep the engine (or the plugin mount) from working
+ * — the built-in defaults are always available, and a missing file is the same thing to the loader
+ * as an empty one.
+ */
+export declare function ensureCommonConfigFile(path: string, logger?: AvantfLogger): void;

package/lib/engine/mem/config/domains.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Append one 知识域 to the STORE config's top-level `domains` allowlist
+ * (`~/.avantf/configs/knowledge.yaml`, layer ③ of `loader.ts`) and return the new list.
+ *
+ * This is the write half of the UI-only `kbAddDomain` path, so the user adds a domain once in the
+ * 知识 tab instead of hand-editing YAML. It writes to the STORE config rather than the common one:
+ * `knowledge.domains` is resolved from layer ③ (the file the loader parses with
+ * `KnowledgeConfigSchema`), and a second source of truth would make "where do I change it?" a
+ * question again.
+ *
+ * `parseDocument` + `toString` (never `parse`/`stringify`): the comments in that file are the
+ * documentation for the keys around them, and a round-trip that drops them quietly turns a
+ * documented config into a bare list. When `domains` is already a sequence the node is mutated IN
+ * PLACE (`seq.add`), which keeps the comments attached to the key and its items; a missing key is
+ * created.
+ *
+ * The write is temp file + atomic rename, the same shape as the managed document copy
+ * (`doc_files.ts`): a crash mid-write must not leave a truncated config the next boot cannot parse.
+ */
+export declare function addKnowledgeDomain(configPath: string, domain: string): string[];

package/lib/engine/mem/config/loader.d.ts

@@ -0,0 +1,35 @@
+import { type AvantfLogger, type Config, type MemoryConfig, type KnowledgeConfig } from '../../mem-contract/index.js';
+export interface LoadedConfig {
+    home: string;
+    common: Config;
+    memory: MemoryConfig;
+    knowledge: KnowledgeConfig;
+}
+export interface LoadConfigOptions {
+    dataHome?: string;
+    /** Sink for load-time warnings (unknown keys). Defaults to the console logger. */
+    logger?: AvantfLogger;
+    /**
+     * The MANAGED ROOTS the caller wants as this process's built-in defaults.
+     *
+     * This is layer ① (built-in defaults), not a new precedence level: the DSH plugin replaces the
+     * default locations with the family framework's root (`<home>/tools`, `<home>/models`) because
+     * `@avantf/dsh-plugin-base` — not this engine — now fetches pandoc and the embedding model.
+     *
+     * `tools.dir` is still an ordinary configurable location, so a `config.yaml` entry or an
+     * `AVANTF_*` escape hatch keeps winning. The MODEL locations are different: they are managed, so
+     * {@link MANAGED_MODEL_KEYS} are stripped from `config.yaml` before it is merged (the environment
+     * escape hatch stays). When the framework is unavailable the plugin passes nothing and the schema
+     * defaults (the legacy directories) apply unchanged.
+     */
+    managedRoots?: {
+        readonly tools?: string;
+        readonly models?: string;
+    };
+}
+/**
+ * Load config with layering: ① built-in defaults → ② `~/.avantf/configs/common.yaml`
+ * (common) → ③ `~/.avantf/{memory,knowledge}/config.yaml` (store) → ④ env →
+ * ⑤ explicit. Returns the resolved per-store config + data home.
+ */
+export declare function loadConfig(opts?: LoadConfigOptions): LoadedConfig;