@modusensus/dsh-mneme 0.14.0-beta.1 → 0.14.0-beta.2

package/docs/FORGET.md

@@ -1,77 +1,77 @@
-# 选择性遗忘与事实更正（#532）
-
-> 这篇回答 #532 的三个确认请求：现象的根因链、当前机制能承诺什么、以及修复方向需要维护者拍板的取舍。全部结论出自 `main`（514d238）源码逐行核实与一个**零 LLM 的合成轨迹**——不需要真实用户库，任何人按 §4 的步骤能在空库上重现同一结构性结果。
-
-## 1. 现象与根因链
-
-#532 的观察：更正两个事实（颜色 + 整理时间）→ 只要求忘掉颜色 → 新对话里颜色确实不知道，**但整理时间答回了更正前的旧值**。
-
-根因是三段机制的接缝，每一段单独看都符合自己的契约：
-
-1. **更正落成新行，旧行保持活跃。** `autoSummarize` 写入走 `saveWithDedupe` 的 `(type, title, scope)` 三元组去重——更正行的标题与原行不同（蒸馏器按内容起标题），去重不命中，于是**同一事实的两个版本同时活跃**。会清理这种并存的是 dream 的冲突裁决（loser 归档）——但它是阈值门控的（`dreamThresholdCount` 默认 100，#532 现场 13 条、`dream_runs` 0 行，裁决从未运行）。`summarizeDedupeMode`（#127，默认 off）帮不上：它只在**同会话**的时间窗内并（`findSessionDuplicate` 按 `type+source+时间窗` 找候选），而 #532 的更正发生在另一个会话。
-2. **`memory_forget` 是行粒度的。** 它按 ID 翻 `forgotten` 标志（抑制注入/检索/列表，原文留存可恢复）——这是接口契约，**不是**「忘掉某个事实」：事实散在几行里，它就只管被点名的那一行。#532 的更正把两个新值合流在一行（蒸馏器把「颜色改成浅橙色 + 时间改成周六 09:00」写进同一条），忘掉「颜色」的操作抑制了这一行，**新的整理时间跟它一起退出可见面**。
-3. **旧值行成了唯一幸存的载体。** 旧值（雾蓝色 + 周三 20:00）至少还活在另一行里（6 次蒸馏 × 每次 ≤3 条 = 13 行的库完全装得下独立的旧时间行）。新值行被抑制后，检索/注入面只剩旧值行——模型如实回答了它唯一能看到的东西。旧值行里同样有旧颜色，模型答「不知道颜色」是因为该行也已被抑制（或未入召回窗）——两半行为各自都有解释，合起来才是「保留的更正事实答回旧值」。
-
-**一句话定性：这不是某一行写错了，而是「更正的失效关系」在 dream 第一次运行之前根本不存在。** 旧行与新行之间没有任何持久链接，任何一方的隐藏都不会波及另一方；趁虚而入的是结构，不是某个 bug 的触发。
-
-## 2. 三个确认请求的源码级回答
-
-**Q1：更正两个事实、只忘一个时，推荐怎样保住另一个？**
-
-当前机制下的推荐做法（不需要新配置）：
-
-- **更正时点名旧行**：用 `memory_update` 直接改原行的内容（同标题走 `saveWithDedupe` 的更新分支，`content_history` 留痕），或用 `memory_archive` 归档旧行后再让新事实自然入库——归档可恢复，且两行不再并存。
-- **遗忘时按行操作并核对行内容**：`memory_forget` 之前先 `memory_get` 看这一行还装着什么；一行装着多个要分开处置的事实时，`memory_update` 先拆、再对单行遗忘。
-- 工具描述已补一句行粒度警示（本 PR）：模型在「忘掉 X」的请求下，应当先意识到一行可能载着多个事实，并在回复里说清它抑制的是哪一行、连带了什么。
-
-**Q2：更正所取代的旧事实，有没有持久失效关系，使隐藏新条目后旧值不会重新成为当前答案？**
-
-**没有——这是插件层面的真实缺口，不是配置遗漏。** 失效关系今天只存在于两处：① `memory_register_document` 的同路径/同标题 supersede（#230，只覆盖 document 行）；② dream 冲突裁决的 loser 归档（阈值门控）。普通蒸馏行在 dream 第一次运行之前，旧行与新行之间**没有任何链接**。历史回溯与「当前答案」也因此无法区分：检索面对两行一视同仁，先后关系只体现在 `updated_at` 的排序权重里——模型答对（如 #532 对话 C）靠的是模型自己对比两行，不是机制保证。
-
-**Q3：配置是否遗漏了该语义必需的原生设置？**
-
-没有。`lightMode` / 阈值配置都在正常范围内；0.9.5 的已发变更（溯源读出口 #509、蒸馏围栏 #501、merge 逃生门 #521 等）都不触碰这条接缝。**#532 报告的现象在当前 main 上结构性地成立**，与 0.9.4 还是 0.9.5 无关。
-
-## 3. 修复方向的取舍（需要维护者拍板，本 PR 不擅自实现）
-
-| 方向 | 能修掉什么 | 代价 / 风险 |
-|---|---|---|
-| **A. 蒸馏提示词拆分粒度**（一事实一条） | 合流行被整条遗忘的连带伤 | 提示词级、行为面全变；行数增多（注入预算/检索排序全受影响）；LLM 遵从度不确定 |
-| **B. 写侧更正失效关系**（蒸馏窗口内识别「同主题改值」→ 归档被取代行） | Q2 的缺口本体 | 「同主题」判据是 LLM 判断（dream 冲突裁决同款），放写入热路径要配阈值与误杀面测量——正是 dream 已经在做的事，重复建一套不如把 dream 的触发条件前移 |
-| **C. dream 触发前移**（更正类写入直接计 dream 优先级 / 降低阈值） | 让现成的裁决机制更早介入 | dream 有成本（LLM 调用）；「更正类写入」的确定性判据同样不存在 |
-| **D. 遗忘回执带同侪提示**（`memory_forget` 答复列出同 type+scope 的高相似活跃行） | 让模型在遗忘当下看到「别处还有旧值」 | 相似度判据要么依赖嵌入（可能未配）、要么是弱启发（误报面要测）；对已发生的遗忘只是事后提示 |
-
-本 PR 只落地了零争议的一小块（工具描述的行粒度警示，见 §5）；A–D 的取舍涉及 LLM 判断进入哪条路径、误杀面怎么量，按 R2/R3 纪律停下等人拍板。
-
-## 4. 有界复测的最小合成轨迹（零 LLM）
-
-不依赖任何模型行为，直接用存储/服务层复现「更正落新行 → 遗忘新行 → 旧值行幸存」：
-
-```js
-// 空库；严格 scope 不影响本现象，默认配置即可
-const store = createStore(":memory:");
-const service = createService({ store, mirror: null, config: {} });
-// ① 原始陈述（模拟对话 A 的蒸馏产物：颜色 + 时间合流一行）
-const r1 = service.saveWithDedupe({ type: "preference", title: "纸模工具的收纳与整理",
-  content: "纸模工具放在雾蓝色收纳盒，每周三晚上八点整理一次", importance: 3 });
-// ② 更正（模拟对话 B：标题由蒸馏器另起 → 三元组不命中 → 新行）
-const r2 = service.saveWithDedupe({ type: "preference", title: "收纳盒颜色与整理时间的更正",
-  content: "收纳盒换成浅橙色，整理时间改为每周六上午九点", importance: 3 });
-// ③ 结构断言：两行同时活跃，二者之间没有任何失效链接
-const activeCount = () => store.db.prepare(
-  "SELECT COUNT(*) AS n FROM memories WHERE forgotten = 0 AND archived = 0"
-).get().n;
-assert.equal(activeCount(), 2);
-// ④ 「忘掉颜色」= 按行遗忘新值行（模型在 R1/R2 里看到的颜色载体）
-service.setForget(r2.memory.id, true);
-// ⑤ 现象复现：新值行退出注入/检索面后，旧值行仍是唯一幸存载体
-assert.equal(store.getById(r1.memory.id).forgotten, false, "旧行从未被任何机制波及");
-assert.match(store.getById(r1.memory.id).content, /每周三晚上八点/, "旧值仍在召回面");
-```
-
-完整可跑版本见 `test/forget-corrections.test.js`（本 PR 附），其中 ④⑤ 两条断言就是 #532 现象的存储层等价物——机制修复（§3 的 B/C）落地时，这条测试的 ⑤ 应当翻转：更正行写入后，旧行要么被记上失效关系、要么退出活跃面；遗忘新行不应让旧值重新成为「当前答案」。
-
-## 5. 本 PR 落地的零争议部分
-
-- **`memory_forget` 工具描述补行粒度警示**（`src/tools.js`）：「抑制的是**一行**——多个事实合流在同一行里时，它们会一起退出可见面；请求只针对其中一个事实时，先看行内容、用 `memory_update` 拆分或在回复里说清连带了什么」。这是 #532 对话 5 里模型误用工具的直接对策：请求的语义粒度（一个事实）与工具的能力粒度（一行）之间的落差，模型无从得知，除非描述告诉它。
-- **本文档**与 §4 的合成轨迹测试。
+# 选择性遗忘与事实更正（#532）
+
+> 这篇回答 #532 的三个确认请求：现象的根因链、当前机制能承诺什么、以及修复方向需要维护者拍板的取舍。全部结论出自 `main`（514d238）源码逐行核实与一个**零 LLM 的合成轨迹**——不需要真实用户库，任何人按 §4 的步骤能在空库上重现同一结构性结果。
+
+## 1. 现象与根因链
+
+#532 的观察：更正两个事实（颜色 + 整理时间）→ 只要求忘掉颜色 → 新对话里颜色确实不知道，**但整理时间答回了更正前的旧值**。
+
+根因是三段机制的接缝，每一段单独看都符合自己的契约：
+
+1. **更正落成新行，旧行保持活跃。** `autoSummarize` 写入走 `saveWithDedupe` 的 `(type, title, scope)` 三元组去重——更正行的标题与原行不同（蒸馏器按内容起标题），去重不命中，于是**同一事实的两个版本同时活跃**。会清理这种并存的是 dream 的冲突裁决（loser 归档）——但它是阈值门控的（`dreamThresholdCount` 默认 100，#532 现场 13 条、`dream_runs` 0 行，裁决从未运行）。`summarizeDedupeMode`（#127，默认 off）帮不上：它只在**同会话**的时间窗内并（`findSessionDuplicate` 按 `type+source+时间窗` 找候选），而 #532 的更正发生在另一个会话。
+2. **`memory_forget` 是行粒度的。** 它按 ID 翻 `forgotten` 标志（抑制注入/检索/列表，原文留存可恢复）——这是接口契约，**不是**「忘掉某个事实」：事实散在几行里，它就只管被点名的那一行。#532 的更正把两个新值合流在一行（蒸馏器把「颜色改成浅橙色 + 时间改成周六 09:00」写进同一条），忘掉「颜色」的操作抑制了这一行，**新的整理时间跟它一起退出可见面**。
+3. **旧值行成了唯一幸存的载体。** 旧值（雾蓝色 + 周三 20:00）至少还活在另一行里（6 次蒸馏 × 每次 ≤3 条 = 13 行的库完全装得下独立的旧时间行）。新值行被抑制后，检索/注入面只剩旧值行——模型如实回答了它唯一能看到的东西。旧值行里同样有旧颜色，模型答「不知道颜色」是因为该行也已被抑制（或未入召回窗）——两半行为各自都有解释，合起来才是「保留的更正事实答回旧值」。
+
+**一句话定性：这不是某一行写错了，而是「更正的失效关系」在 dream 第一次运行之前根本不存在。** 旧行与新行之间没有任何持久链接，任何一方的隐藏都不会波及另一方；趁虚而入的是结构，不是某个 bug 的触发。
+
+## 2. 三个确认请求的源码级回答
+
+**Q1：更正两个事实、只忘一个时，推荐怎样保住另一个？**
+
+当前机制下的推荐做法（不需要新配置）：
+
+- **更正时点名旧行**：用 `memory_update` 直接改原行的内容（同标题走 `saveWithDedupe` 的更新分支，`content_history` 留痕），或用 `memory_archive` 归档旧行后再让新事实自然入库——归档可恢复，且两行不再并存。
+- **遗忘时按行操作并核对行内容**：`memory_forget` 之前先 `memory_get` 看这一行还装着什么；一行装着多个要分开处置的事实时，`memory_update` 先拆、再对单行遗忘。
+- 工具描述已补一句行粒度警示（本 PR）：模型在「忘掉 X」的请求下，应当先意识到一行可能载着多个事实，并在回复里说清它抑制的是哪一行、连带了什么。
+
+**Q2：更正所取代的旧事实，有没有持久失效关系，使隐藏新条目后旧值不会重新成为当前答案？**
+
+**没有——这是插件层面的真实缺口，不是配置遗漏。** 失效关系今天只存在于两处：① `memory_register_document` 的同路径/同标题 supersede（#230，只覆盖 document 行）；② dream 冲突裁决的 loser 归档（阈值门控）。普通蒸馏行在 dream 第一次运行之前，旧行与新行之间**没有任何链接**。历史回溯与「当前答案」也因此无法区分：检索面对两行一视同仁，先后关系只体现在 `updated_at` 的排序权重里——模型答对（如 #532 对话 C）靠的是模型自己对比两行，不是机制保证。
+
+**Q3：配置是否遗漏了该语义必需的原生设置？**
+
+没有。`lightMode` / 阈值配置都在正常范围内；0.9.5 的已发变更（溯源读出口 #509、蒸馏围栏 #501、merge 逃生门 #521 等）都不触碰这条接缝。**#532 报告的现象在当前 main 上结构性地成立**，与 0.9.4 还是 0.9.5 无关。
+
+## 3. 修复方向的取舍（需要维护者拍板，本 PR 不擅自实现）
+
+| 方向 | 能修掉什么 | 代价 / 风险 |
+|---|---|---|
+| **A. 蒸馏提示词拆分粒度**（一事实一条） | 合流行被整条遗忘的连带伤 | 提示词级、行为面全变；行数增多（注入预算/检索排序全受影响）；LLM 遵从度不确定 |
+| **B. 写侧更正失效关系**（蒸馏窗口内识别「同主题改值」→ 归档被取代行） | Q2 的缺口本体 | 「同主题」判据是 LLM 判断（dream 冲突裁决同款），放写入热路径要配阈值与误杀面测量——正是 dream 已经在做的事，重复建一套不如把 dream 的触发条件前移 |
+| **C. dream 触发前移**（更正类写入直接计 dream 优先级 / 降低阈值） | 让现成的裁决机制更早介入 | dream 有成本（LLM 调用）；「更正类写入」的确定性判据同样不存在 |
+| **D. 遗忘回执带同侪提示**（`memory_forget` 答复列出同 type+scope 的高相似活跃行） | 让模型在遗忘当下看到「别处还有旧值」 | 相似度判据要么依赖嵌入（可能未配）、要么是弱启发（误报面要测）；对已发生的遗忘只是事后提示 |
+
+本 PR 只落地了零争议的一小块（工具描述的行粒度警示，见 §5）；A–D 的取舍涉及 LLM 判断进入哪条路径、误杀面怎么量，按 R2/R3 纪律停下等人拍板。
+
+## 4. 有界复测的最小合成轨迹（零 LLM）
+
+不依赖任何模型行为，直接用存储/服务层复现「更正落新行 → 遗忘新行 → 旧值行幸存」：
+
+```js
+// 空库；严格 scope 不影响本现象，默认配置即可
+const store = createStore(":memory:");
+const service = createService({ store, mirror: null, config: {} });
+// ① 原始陈述（模拟对话 A 的蒸馏产物：颜色 + 时间合流一行）
+const r1 = service.saveWithDedupe({ type: "preference", title: "纸模工具的收纳与整理",
+  content: "纸模工具放在雾蓝色收纳盒，每周三晚上八点整理一次", importance: 3 });
+// ② 更正（模拟对话 B：标题由蒸馏器另起 → 三元组不命中 → 新行）
+const r2 = service.saveWithDedupe({ type: "preference", title: "收纳盒颜色与整理时间的更正",
+  content: "收纳盒换成浅橙色，整理时间改为每周六上午九点", importance: 3 });
+// ③ 结构断言：两行同时活跃，二者之间没有任何失效链接
+const activeCount = () => store.db.prepare(
+  "SELECT COUNT(*) AS n FROM memories WHERE forgotten = 0 AND archived = 0"
+).get().n;
+assert.equal(activeCount(), 2);
+// ④ 「忘掉颜色」= 按行遗忘新值行（模型在 R1/R2 里看到的颜色载体）
+service.setForget(r2.memory.id, true);
+// ⑤ 现象复现：新值行退出注入/检索面后，旧值行仍是唯一幸存载体
+assert.equal(store.getById(r1.memory.id).forgotten, false, "旧行从未被任何机制波及");
+assert.match(store.getById(r1.memory.id).content, /每周三晚上八点/, "旧值仍在召回面");
+```
+
+完整可跑版本见 `test/forget-corrections.test.js`（本 PR 附），其中 ④⑤ 两条断言就是 #532 现象的存储层等价物——机制修复（§3 的 B/C）落地时，这条测试的 ⑤ 应当翻转：更正行写入后，旧行要么被记上失效关系、要么退出活跃面；遗忘新行不应让旧值重新成为「当前答案」。
+
+## 5. 本 PR 落地的零争议部分
+
+- **`memory_forget` 工具描述补行粒度警示**（`src/tools.js`）：「抑制的是**一行**——多个事实合流在同一行里时，它们会一起退出可见面；请求只针对其中一个事实时，先看行内容、用 `memory_update` 拆分或在回复里说清连带了什么」。这是 #532 对话 5 里模型误用工具的直接对策：请求的语义粒度（一个事实）与工具的能力粒度（一行）之间的落差，模型无从得知，除非描述告诉它。
+- **本文档**与 §4 的合成轨迹测试。

package/docs/KB.md

@@ -1,110 +1,110 @@
-# 知识库（Knowledge base，第二层）
-
-给 agent 一个「用户自己的参考资料」检索面：本地文件、网页、仓库地志页进来，分块后用 BM25 检索。
-与记忆库（第一层）**物理隔离**——它不是记忆，不参与注入、不参与巩固、不参与质量过滤。
-
-## 职责边界
-
-**它是**：一个只读给模型的语料检索面（三个只读工具）+ 一组面板可管理的集合/文档（写路由）。
-**它不是**：文件的真源、向量库、记忆库的旁支。
-
-- 真源在 SQLite 的 `kb_*` 三张表里，**不在磁盘上**。用户随时可能把原文件挪走或删掉，
-  检索面不能跟着消失——所以 `readDoc` 从库里拼回正文，读侧零 IO（`src/kb/index.js` 顶部有同样的话）。
-- 与 chorography 的区别：地志以盘上的 MD 为真源（重扫即重建），知识库收的是外来原文的副本。
-- **绝不写 `memories`**，也绝不进 `saveWithDedupe` / `dream` / 质量过滤的任何行池。
-  这条与 wiki 行同源，是 §3.3 的红线；`test/kb-collections.test.js` 第一条用例钉它。
-
-## 对外接口
-
-### 程序面（`src/kb/index.js`）
-
-```js
-const kb = createKb({ store, embedder = null, cfg = {} });
-```
-
-| 方法 | 形状 |
-|---|---|
-| `listCollections()` | `[{key,title,description,docs,chunks,updatedAt}]` |
-| `upsertCollection({key,title,description})` | `{key,title,description}`；同 key 再调 = 改名，`created_at` 不动 |
-| `deleteCollection(key)` | `boolean`；连带删它的文档与分块（一个事务，不留孤儿行） |
-| `listDocs({collection})` | `[{relKey,kind,title,bytes,indexedAt,status,error}]` |
-| `ingest({collection,kind,source,title?})` | `{docId,chunks,skipped,error?}` |
-| `search({query,collection?,limit?})` | `{hits:[{collection,relKey,title,heading,line,excerpt,score}],unreadable:[]}` |
-| `readDoc({collection,relKey})` | `{title,content,kind,relKey,status,error}` 或 `null` |
-| `dispose()` | 清索引缓存；可重复调用，不丢数据 |
-
-`kind` 三选一：`file` / `url` / `choro_page`。`url` 走 `fetch`；`choro_page` 的 `source`
-就是该地志页 MD 的**绝对路径**，读取路径与 `file` 完全一致——不为它去跨域读 `choro_*` 表，
-那会把两条线的写作用域搅在一起。
-
-### HTTP 面（`src/kb/routes.js`，契约 §3.6）
-
-| 方法 | 路径 | policy |
-|---|---|---|
-| GET | `/api/dsh-mneme/kb/collections` | `token-write`（与 POST/DELETE 同路径，取更严的） |
-| POST | `/api/dsh-mneme/kb/collections` `{key,title,description}` | 同上 |
-| DELETE | `/api/dsh-mneme/kb/collections?key=<key>` | 同上 |
-| GET | `/api/dsh-mneme/kb/docs?collection=<key>` | `token` |
-| GET | `/api/dsh-mneme/kb/doc?collection=<key>&relKey=<rel>` | `token` |
-| POST | `/api/dsh-mneme/kb/ingest` `{collection,kind,source,title?}` | `token-write` |
-| POST | `/api/dsh-mneme/kb/search` `{query,collection?,limit?}` | `token-write` |
-
-`/kb/collections` 一条路径上读和写混着，只能声明一个 policy，取更严的 `token-write`
-（与 `/profile` 同款）。`register` 对同一 `kind+path` 重复登记直接抛错，所以不能拆两条。
-
-**状态码语义**（面板据此渲染，改之前先想清楚空态）：
-
-- `409 {error:"disabled",reason:"kb-not-enabled"}` — 开关没开。判定在 `src/api.js` 的 `kbGate`，
-  本模块**不自己判** `cfg.kbEnabled`（一处判定，不两处分叉）。
-- `503 {error:"unavailable"}` — 开了开关但 kb 没装配（headless / 测试）。#497 先例：503 = 环境缺件，409 = 用户没开。
-- `404 {error:"collection-not-found"}` — 入库目标集合不存在。**不静默建集合**：拼错的 key
-  会把资料塞进一个凭空出现的集合，用户永远找不到。
-- `404 {error:"doc-not-found"}` — 读整篇查不到。
-- `400` — 缺必填字段 / `bad-kind` / `query-required`。
-- 入库**来源级**失败（`file-not-found` / `too-large` / `http-404` …）回 **200 + `ok:false` + `error`**，
-  不是 4xx。理由：`kb_docs` 里已经落了 `status='error'` 的留痕行，面板要能显示「这份为什么没进来」；
-  回 4xx 会让面板把它当成「请求本身错了」而丢掉那条记录。
-
-### 模型面（`src/kb/tools.js`）
-
-三个**只读**工具，返回 `defineTool()` 兼容的描述对象数组，由 `src/tools.js` 在
-`kbEnabled` 为真时展开进自己的数组（本文件不 import `defineTool`，装配顺序与开关归调用方）：
-
-- `kb_list_collections` — 集合清单 + 文档/分块数。
-- `kb_search` — BM25 检索，回 `collection/relKey/heading/line/excerpt`。
-- `kb_read_doc` — 按 `collection + relKey` 读整篇。
-
-写操作一个都不给模型：建集合、入库都是用户在面板上按的按钮。知识库收的是用户自己的资料，
-模型不该有权决定往里塞什么（与 chorography「生成只走 CLI」同一条红线）。
-
-## 内部文件
-
-- `src/kb/index.js` — `createKb`、切块（`chunkContent`）、检索（`search`）、读整篇。
-- `src/kb/routes.js` — `registerKbRoutes`，七个 handler 全在这里。
-- `src/kb/tools.js` — `kbToolDefinitions`，三个工具描述对象 + render。
-- `src/store.js` — `kb_collections` / `kb_docs` / `kb_chunks` 三张表与十个 `kb*` 方法
-  （`kbCollectionByKey` / `listKbCollections` / `upsertKbCollection` / `deleteKbCollection` /
-  `listKbDocs` / `kbDocByRelKey` / `kbChunksByDoc` / `replaceKbDoc` / `markKbDocError` /
-  `kbChunksForSearch`）。
-- `test/kb-collections.test.js` — 建表/集合/幂等/重切块/检索/readDoc/失败留痕/dispose。
-- `test/kb-routes.test.js` — 路由表形状/policy/状态码/工具描述对象。
-
-## 已知坑（都是踩过或刻意设计成这样的）
-
-1. **切块必须严格按行连续、一个空行都不剥**。这是 `readDoc` 能逐字节还原原文、以及
-   `search` 能回算准确行号（起始行 = 1 + 前面所有块的行数）的**共同前提**。破坏它两件事一起坏。
-   空行不产生 token，对 BM25 的 `len` 分母零成本，剥它纯赔。
-2. **幂等判据是正文 sha256，不是 mtime / size**。同 rel_key + 同 sha256 = 整件事 no-op
-   （回执 `skipped:true`，`chunks` 是库里现有块数）。否则编辑器保存一次（mtime 变、内容没变）
-   就要全量重切块，库和索引一起白忙。上一版 `status='error'` 的行不算命中——重来必须真跑。
-3. **`## ` 是唯一的节边界**。一级标题 `# ` 不切节，它属于文件头那一块。这就是为什么
-   `## 部署` 那块的起始行是标题自己的行号，而不是上一行。
-4. **不带 `return` 的 `readBody().then(...)` 会吞掉回执**。handler 里凡是异步的那几条
-   （collections 的 POST、ingest、search）都必须把 Promise 整条链 `return` 出去；不 return 的话
-   请求会在响应发出之前就「完成」，面板拿到空 body。choro/search 踩过同一个坑
-   （`src/api.js:2787-2788` 有注释）。
-5. **索引缓存按集合懒物化，写路径必须 `invalidate`**。`ingest` / `upsertCollection` /
-   `deleteCollection` 都会失效对应缓存（`markKbDocError` 走的是同一处）。漏一处 = 检索命中
-   已删除的段落。
-6. **Windows 上临时目录会被 Defender 短暂持锁**，`rmSync` 撞 `EPERM` 是抖动不是失败，
-   测试里用 `rmTempEventually` 重试（与 `test/wiki-store.test.js` 同源）。
+# 知识库（Knowledge base，第二层）
+
+给 agent 一个「用户自己的参考资料」检索面：本地文件、网页、仓库地志页进来，分块后用 BM25 检索。
+与记忆库（第一层）**物理隔离**——它不是记忆，不参与注入、不参与巩固、不参与质量过滤。
+
+## 职责边界
+
+**它是**：一个只读给模型的语料检索面（三个只读工具）+ 一组面板可管理的集合/文档（写路由）。
+**它不是**：文件的真源、向量库、记忆库的旁支。
+
+- 真源在 SQLite 的 `kb_*` 三张表里，**不在磁盘上**。用户随时可能把原文件挪走或删掉，
+  检索面不能跟着消失——所以 `readDoc` 从库里拼回正文，读侧零 IO（`src/kb/index.js` 顶部有同样的话）。
+- 与 chorography 的区别：地志以盘上的 MD 为真源（重扫即重建），知识库收的是外来原文的副本。
+- **绝不写 `memories`**，也绝不进 `saveWithDedupe` / `dream` / 质量过滤的任何行池。
+  这条与 wiki 行同源，是 §3.3 的红线；`test/kb-collections.test.js` 第一条用例钉它。
+
+## 对外接口
+
+### 程序面（`src/kb/index.js`）
+
+```js
+const kb = createKb({ store, embedder = null, cfg = {} });
+```
+
+| 方法 | 形状 |
+|---|---|
+| `listCollections()` | `[{key,title,description,docs,chunks,updatedAt}]` |
+| `upsertCollection({key,title,description})` | `{key,title,description}`；同 key 再调 = 改名，`created_at` 不动 |
+| `deleteCollection(key)` | `boolean`；连带删它的文档与分块（一个事务，不留孤儿行） |
+| `listDocs({collection})` | `[{relKey,kind,title,bytes,indexedAt,status,error}]` |
+| `ingest({collection,kind,source,title?})` | `{docId,chunks,skipped,error?}` |
+| `search({query,collection?,limit?})` | `{hits:[{collection,relKey,title,heading,line,excerpt,score}],unreadable:[]}` |
+| `readDoc({collection,relKey})` | `{title,content,kind,relKey,status,error}` 或 `null` |
+| `dispose()` | 清索引缓存；可重复调用，不丢数据 |
+
+`kind` 三选一：`file` / `url` / `choro_page`。`url` 走 `fetch`；`choro_page` 的 `source`
+就是该地志页 MD 的**绝对路径**，读取路径与 `file` 完全一致——不为它去跨域读 `choro_*` 表，
+那会把两条线的写作用域搅在一起。
+
+### HTTP 面（`src/kb/routes.js`，契约 §3.6）
+
+| 方法 | 路径 | policy |
+|---|---|---|
+| GET | `/api/dsh-mneme/kb/collections` | `token-write`（与 POST/DELETE 同路径，取更严的） |
+| POST | `/api/dsh-mneme/kb/collections` `{key,title,description}` | 同上 |
+| DELETE | `/api/dsh-mneme/kb/collections?key=<key>` | 同上 |
+| GET | `/api/dsh-mneme/kb/docs?collection=<key>` | `token` |
+| GET | `/api/dsh-mneme/kb/doc?collection=<key>&relKey=<rel>` | `token` |
+| POST | `/api/dsh-mneme/kb/ingest` `{collection,kind,source,title?}` | `token-write` |
+| POST | `/api/dsh-mneme/kb/search` `{query,collection?,limit?}` | `token-write` |
+
+`/kb/collections` 一条路径上读和写混着，只能声明一个 policy，取更严的 `token-write`
+（与 `/profile` 同款）。`register` 对同一 `kind+path` 重复登记直接抛错，所以不能拆两条。
+
+**状态码语义**（面板据此渲染，改之前先想清楚空态）：
+
+- `409 {error:"disabled",reason:"kb-not-enabled"}` — 开关没开。判定在 `src/api.js` 的 `kbGate`，
+  本模块**不自己判** `cfg.kbEnabled`（一处判定，不两处分叉）。
+- `503 {error:"unavailable"}` — 开了开关但 kb 没装配（headless / 测试）。#497 先例：503 = 环境缺件，409 = 用户没开。
+- `404 {error:"collection-not-found"}` — 入库目标集合不存在。**不静默建集合**：拼错的 key
+  会把资料塞进一个凭空出现的集合，用户永远找不到。
+- `404 {error:"doc-not-found"}` — 读整篇查不到。
+- `400` — 缺必填字段 / `bad-kind` / `query-required`。
+- 入库**来源级**失败（`file-not-found` / `too-large` / `http-404` …）回 **200 + `ok:false` + `error`**，
+  不是 4xx。理由：`kb_docs` 里已经落了 `status='error'` 的留痕行，面板要能显示「这份为什么没进来」；
+  回 4xx 会让面板把它当成「请求本身错了」而丢掉那条记录。
+
+### 模型面（`src/kb/tools.js`）
+
+三个**只读**工具，返回 `defineTool()` 兼容的描述对象数组，由 `src/tools.js` 在
+`kbEnabled` 为真时展开进自己的数组（本文件不 import `defineTool`，装配顺序与开关归调用方）：
+
+- `kb_list_collections` — 集合清单 + 文档/分块数。
+- `kb_search` — BM25 检索，回 `collection/relKey/heading/line/excerpt`。
+- `kb_read_doc` — 按 `collection + relKey` 读整篇。
+
+写操作一个都不给模型：建集合、入库都是用户在面板上按的按钮。知识库收的是用户自己的资料，
+模型不该有权决定往里塞什么（与 chorography「生成只走 CLI」同一条红线）。
+
+## 内部文件
+
+- `src/kb/index.js` — `createKb`、切块（`chunkContent`）、检索（`search`）、读整篇。
+- `src/kb/routes.js` — `registerKbRoutes`，七个 handler 全在这里。
+- `src/kb/tools.js` — `kbToolDefinitions`，三个工具描述对象 + render。
+- `src/store.js` — `kb_collections` / `kb_docs` / `kb_chunks` 三张表与十个 `kb*` 方法
+  （`kbCollectionByKey` / `listKbCollections` / `upsertKbCollection` / `deleteKbCollection` /
+  `listKbDocs` / `kbDocByRelKey` / `kbChunksByDoc` / `replaceKbDoc` / `markKbDocError` /
+  `kbChunksForSearch`）。
+- `test/kb-collections.test.js` — 建表/集合/幂等/重切块/检索/readDoc/失败留痕/dispose。
+- `test/kb-routes.test.js` — 路由表形状/policy/状态码/工具描述对象。
+
+## 已知坑（都是踩过或刻意设计成这样的）
+
+1. **切块必须严格按行连续、一个空行都不剥**。这是 `readDoc` 能逐字节还原原文、以及
+   `search` 能回算准确行号（起始行 = 1 + 前面所有块的行数）的**共同前提**。破坏它两件事一起坏。
+   空行不产生 token，对 BM25 的 `len` 分母零成本，剥它纯赔。
+2. **幂等判据是正文 sha256，不是 mtime / size**。同 rel_key + 同 sha256 = 整件事 no-op
+   （回执 `skipped:true`，`chunks` 是库里现有块数）。否则编辑器保存一次（mtime 变、内容没变）
+   就要全量重切块，库和索引一起白忙。上一版 `status='error'` 的行不算命中——重来必须真跑。
+3. **`## ` 是唯一的节边界**。一级标题 `# ` 不切节，它属于文件头那一块。这就是为什么
+   `## 部署` 那块的起始行是标题自己的行号，而不是上一行。
+4. **不带 `return` 的 `readBody().then(...)` 会吞掉回执**。handler 里凡是异步的那几条
+   （collections 的 POST、ingest、search）都必须把 Promise 整条链 `return` 出去；不 return 的话
+   请求会在响应发出之前就「完成」，面板拿到空 body。choro/search 踩过同一个坑
+   （`src/api.js:2787-2788` 有注释）。
+5. **索引缓存按集合懒物化，写路径必须 `invalidate`**。`ingest` / `upsertCollection` /
+   `deleteCollection` 都会失效对应缓存（`markKbDocError` 走的是同一处）。漏一处 = 检索命中
+   已删除的段落。
+6. **Windows 上临时目录会被 Defender 短暂持锁**，`rmSync` 撞 `EPERM` 是抖动不是失败，
+   测试里用 `rmTempEventually` 重试（与 `test/wiki-store.test.js` 同源）。