@modusensus/dsh-mneme 0.12.0 → 0.13.0

package/test/kb-collections.test.js

@@ -0,0 +1,272 @@
+// 知识库第二层（src/kb/**）的回归锁。锁五件事：
+// 1) 三张 kb_* 表在空库上打开即建（幂等迁移面），且 memories 表不受影响；
+// 2) 集合建/改名/删除的正确语义（删集合连带删文档与分块，不留孤儿行）；
+// 3) 同一 rel_key + 同 sha256 重入库是 no-op —— 这条是幂等契约本身，回归了就是
+//    「编辑器保存一次 → 全量重切块」的性能事故；
+// 4) 内容变了要真替换：旧块不能残留（残留会让检索命中已删除的段落）；
+// 5) 检索能命中、readDoc 能把原文逐字节还原（切块必须严格连续按行）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createStore } from "../src/store.js";
+import { createKb } from "../src/kb/index.js";
+
+// Windows 上 %TEMP% 里刚写完的文件会被 Defender 短暂持锁，rmSync 撞 EPERM 是
+// 瞬时抖动不是用例失败（与 test/wiki-store.test.js 同一处踩坑）。
+async function rmTempEventually(dir) {
+  for (let i = 0; i < 10; i++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      await sleep(200);
+    }
+  }
+}
+
+function makeTempDir() {
+  return mkdtempSync(join(tmpdir(), "kb-test-"));
+}
+
+function writeDoc(dir, name, content) {
+  const abs = join(dir, name);
+  writeFileSync(abs, content, "utf8");
+  return abs;
+}
+
+function newKb() {
+  const store = createStore(":memory:");
+  return { store, kb: createKb({ store, cfg: {} }) };
+}
+
+test("新库打开即建三张 kb_* 表，且不碰 memories 表", () => {
+  const { store } = newKb();
+  for (const name of ["kb_collections", "kb_docs", "kb_chunks"]) {
+    const row = store.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
+    assert.ok(row, `缺表 ${name}`);
+  }
+  // 物理隔离的另一半：知识库的表不得出现在记忆行池的查询里。这里锁的是「memories
+  // 仍只有它自己那一份」，防止有人日后把 kb 行灌进 memories 图省事。
+  const memCount = store.db.prepare("SELECT COUNT(*) AS c FROM memories").get().c;
+  assert.equal(memCount, 0);
+  store.close();
+});
+
+test("createKb 建/改名/列集合，计数随文档与分块变化", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "manual", title: "手册", description: "内部手册" });
+    let list = kb.listCollections();
+    assert.equal(list.length, 1);
+    assert.deepEqual(
+      { key: list[0].key, title: list[0].title, description: list[0].description, docs: list[0].docs, chunks: list[0].chunks },
+      { key: "manual", title: "手册", description: "内部手册", docs: 0, chunks: 0 }
+    );
+
+    // 同名 key 再 upsert 是「改名」不是「新建」：created_at 不动、行数不增。
+    kb.upsertCollection({ key: "manual", title: "手册v2", description: "" });
+    list = kb.listCollections();
+    assert.equal(list.length, 1);
+    assert.equal(list[0].title, "手册v2");
+
+    const src = writeDoc(dir, "a.md", "# 标题\n\n## 安装\n跑 npm install 就行。\n");
+    const r = await kb.ingest({ collection: "manual", kind: "file", source: src });
+    assert.equal(r.error, undefined);
+    assert.equal(r.skipped, false);
+    assert.ok(r.chunks >= 1);
+
+    list = kb.listCollections();
+    assert.equal(list[0].docs, 1);
+    assert.equal(list[0].chunks, r.chunks);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("同 sha256 重入库 no-op；内容变了才重切块并清掉旧块", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "c", title: "c" });
+    const src = writeDoc(dir, "doc.md", "## 甲\n第一版正文 alpha\n");
+
+    const first = await kb.ingest({ collection: "c", kind: "file", source: src });
+    assert.equal(first.skipped, false);
+
+    // 同一份内容（哪怕 mtime 变了）不许重切块 —— 幂等契约。
+    await sleep(10);
+    writeFileSync(src, "## 甲\n第一版正文 alpha\n", "utf8");
+    const again = await kb.ingest({ collection: "c", kind: "file", source: src });
+    assert.equal(again.skipped, true, "同 sha256 必须 skipped");
+    assert.equal(again.docId, first.docId, "skipped 时 docId 应指向既有文档");
+    assert.equal(again.chunks, first.chunks, "skipped 时 chunks 应是库里现有块数");
+    assert.equal(store.kbChunksByDoc(first.docId).length, first.chunks);
+
+    // 内容变了：替换，旧块不能残留（否则检索会命中已删除的段落）。
+    writeFileSync(src, "## 乙\n第二版正文 beta only\n", "utf8");
+    const changed = await kb.ingest({ collection: "c", kind: "file", source: src });
+    assert.equal(changed.skipped, false);
+    assert.equal(changed.docId, first.docId, "同一 rel_key 复用文档行");
+    const texts = store.kbChunksByDoc(changed.docId).map((c) => c.text).join("\n");
+    assert.ok(texts.includes("beta"), "新内容要进来");
+    assert.ok(!texts.includes("alpha"), "旧分块必须被清掉");
+    assert.equal(kb.search({ query: "alpha", collection: "c" }).hits.length, 0);
+    assert.equal(kb.search({ query: "beta", collection: "c" }).hits.length, 1);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("检索命中带集合/相对键/节标题/行号/摘录；集合过滤生效", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "a", title: "A" });
+    kb.upsertCollection({ key: "b", title: "B" });
+    const f1 = writeDoc(dir, "one.md", "# 一\n\n## 部署\n部署用 docker compose 起服务。\n\n## 回滚\n回滚走 git revert。\n");
+    const f2 = writeDoc(dir, "two.md", "## 数据库\n数据库是 SQLite，用 WAL 模式。\n");
+    await kb.ingest({ collection: "a", kind: "file", source: f1 });
+    await kb.ingest({ collection: "b", kind: "file", source: f2 });
+
+    const hit = kb.search({ query: "docker" });
+    assert.equal(hit.hits.length, 1);
+    assert.equal(hit.hits[0].collection, "a");
+    assert.equal(hit.hits[0].relKey, f1);
+    assert.equal(hit.hits[0].heading, "部署");
+    // 块从它自己那节的 `## 部署` 行起算（第 3 行）——第一节是 "# 一" + 空行。
+    assert.equal(hit.hits[0].line, 3, "命中块起始行按行连续切回算");
+    assert.ok(hit.hits[0].excerpt.includes("docker"));
+    assert.deepEqual(hit.unreadable, []);
+
+    // 单集合过滤：查 B 才有的词，限定 a 应无命中。
+    assert.equal(kb.search({ query: "SQLite", collection: "a" }).hits.length, 0);
+    assert.equal(kb.search({ query: "SQLite", collection: "b" }).hits.length, 1);
+
+    // 中文查询也能命中（tokenize 的 CJK bigram 路径）。
+    const zh = kb.search({ query: "回滚" });
+    assert.equal(zh.hits.length, 1);
+    assert.equal(zh.hits[0].heading, "回滚");
+
+    // 空 query 不报错也不返回全库。
+    assert.deepEqual(kb.search({ query: "   " }), { hits: [], unreadable: [] });
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("readDoc 逐字节还原原文（切块必须严格连续、不剥空行）", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "c", title: "c" });
+    const original = [
+      "# 大标题",
+      "",
+      "引言段落，含**markdown**。",
+      "",
+      "## 第一节",
+      "",
+      "第一段。",
+      "",
+      "第二段。",
+      "",
+    ].join("\n");
+    const src = writeDoc(dir, "big.md", original);
+    await kb.ingest({ collection: "c", kind: "file", source: src });
+
+    const doc = kb.readDoc({ collection: "c", relKey: src });
+    assert.ok(doc, "readDoc 应命中");
+    assert.equal(doc.content, original);
+    assert.equal(doc.title, "big.md");
+    assert.equal(doc.status, "ok");
+
+    // 查不到的组合返回 null（面板据此走空态），不抛。
+    assert.equal(kb.readDoc({ collection: "c", relKey: "/nope.md" }), null);
+    assert.equal(kb.readDoc({ collection: "nope", relKey: src }), null);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("listDocs 给出面板要的文档列表；删集合连带清文档与分块", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "c", title: "c" });
+    const src = writeDoc(dir, "x.md", "## 节\n内容 content\n");
+    const r = await kb.ingest({ collection: "c", kind: "file", source: src });
+
+    const docs = kb.listDocs({ collection: "c" });
+    assert.equal(docs.length, 1);
+    assert.deepEqual(Object.keys(docs[0]).sort(), ["bytes", "error", "indexedAt", "kind", "relKey", "status", "title"]);
+    assert.equal(docs[0].relKey, src);
+    assert.equal(docs[0].kind, "file");
+    assert.equal(docs[0].status, "ok");
+    assert.equal(docs[0].error, null);
+    assert.ok(docs[0].bytes > 0);
+
+    assert.equal(kb.deleteCollection("c"), true);
+    assert.equal(kb.deleteCollection("c"), false, "再删一次是 false 不是抛错");
+    assert.equal(kb.listCollections().length, 0);
+    assert.equal(kb.listDocs({ collection: "c" }).length, 0);
+    // 孤儿行是隐性占空间：文档行与分块行都要真没了。
+    assert.equal(store.db.prepare("SELECT COUNT(*) AS c FROM kb_docs").get().c, 0);
+    assert.equal(store.db.prepare("SELECT COUNT(*) AS c FROM kb_chunks").get().c, 0);
+    assert.equal(store.db.prepare("SELECT COUNT(*) AS c FROM kb_docs WHERE id = ?").get(r.docId).c, 0);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("入库失败留痕不静默：来源不存在 / 集合不存在 / kind 非法都回 error", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "c", title: "c" });
+
+    const missing = await kb.ingest({ collection: "c", kind: "file", source: join(dir, "nope.md") });
+    assert.equal(missing.error, "file-not-found");
+    // 失败要能出现在面板上（否则用户看到的是「点了没反应」）。
+    const docs = kb.listDocs({ collection: "c" });
+    assert.equal(docs.length, 1);
+    assert.equal(docs[0].status, "error");
+    assert.equal(docs[0].error, "file-not-found");
+
+    const noCol = await kb.ingest({ collection: "ghost", kind: "file", source: join(dir, "nope.md") });
+    assert.equal(noCol.error, "collection-not-found");
+    assert.equal(kb.listCollections().length, 1, "拼错的 key 不许凭空建集合");
+
+    const badKind = await kb.ingest({ collection: "c", kind: "pdf", source: join(dir, "nope.md") });
+    assert.equal(badKind.error, "bad-kind");
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("dispose 之后不再持有索引缓存（可安全重复调用）", async () => {
+  const { store, kb } = newKb();
+  const dir = makeTempDir();
+  try {
+    kb.upsertCollection({ key: "c", title: "c" });
+    const src = writeDoc(dir, "d.md", "## 节\n缓存测试 cache\n");
+    await kb.ingest({ collection: "c", kind: "file", source: src });
+    assert.equal(kb.search({ query: "cache" }).hits.length, 1);
+    kb.dispose();
+    kb.dispose();
+    // 释放索引不等于丢数据：再查一次仍然命中（懒物化重建）。
+    assert.equal(kb.search({ query: "cache" }).hits.length, 1);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});

package/test/kb-routes.test.js

@@ -0,0 +1,379 @@
+// 知识库 HTTP 面的形状锁（契约 §3.6 的路径表）。这些用例防的是三类回归：
+// 1) 路径/方法/请求体字段与 C 线面板对不上（两边各自发挥 → 面板「点了没反应」）；
+// 2) 漏声明 policy 或同一 kind+path 重复登记（src/api.js 的 registrar 会直接抛，
+//    插件起不来——所以这里用真的 registrar 语义手搓一个会抛的假 register）；
+// 3) 应答把错误吞掉（来源找不到却回 200 + ok:true，面板就会显示「已入库」）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Readable } from "node:stream";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createStore } from "../src/store.js";
+import { createKb } from "../src/kb/index.js";
+import { registerKbRoutes } from "../src/kb/routes.js";
+import { kbToolDefinitions } from "../src/kb/tools.js";
+
+const POLICIES = ["open", "token", "token-write"];
+
+async function rmTempEventually(dir) {
+  for (let i = 0; i < 10; i++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      await sleep(200);
+    }
+  }
+}
+
+/** 手搓一个与 createRouteRegistrar 同语义的假 register（校验 policy + 拒重复）。 */
+function makeRegistrar() {
+  const seen = new Map();
+  const routes = [];
+  const register = (route) => {
+    assert.ok(POLICIES.includes(route.policy), `路由 ${route.path} 漏了 policy`);
+    const key = `${route.kind}:${route.path}`;
+    assert.ok(!seen.has(key), `路由 ${key} 被重复登记`);
+    seen.set(key, route);
+    routes.push(route);
+  };
+  return { register, routes };
+}
+
+function makeReq({ method = "GET", url = "/", body = null } = {}) {
+  const req = Readable.from(body === null ? [] : [Buffer.from(body, "utf8")]);
+  req.method = method;
+  req.url = url;
+  return req;
+}
+
+function makeRes() {
+  const res = { statusCode: null, body: null, headersSent: false };
+  res.setHeader = () => {};
+  res.writeHead = (code) => { res.statusCode = code; res.headersSent = true; return res; };
+  res.end = (payload) => { if (payload) res.body = JSON.parse(String(payload)); };
+  return res;
+}
+
+const sendJson = (res, status, payload) => {
+  res.writeHead(status);
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(payload));
+};
+
+/**
+ * 装好路由并直接调 handler。install 的 readBody/parseBody 与 src/api.js 的同名
+ * 函数同语义（超限回 null、坏 JSON 回 {}），这样测的是真分支而不是理想化输入。
+ */
+function install({ kb, gate, cfg = {} } = {}) {
+  const { register, routes } = makeRegistrar();
+  registerKbRoutes(register, {
+    kb,
+    cfg,
+    sendJson,
+    gate,
+    readBody: async (req) => {
+      const chunks = [];
+      for await (const c of req) chunks.push(c);
+      return Buffer.concat(chunks).toString("utf8");
+    },
+    parseBody: (text) => {
+      try { return JSON.parse(text || "{}"); } catch { return {}; }
+    }
+  });
+  const byPath = (path) => {
+    const found = routes.filter((r) => r.path === path);
+    assert.equal(found.length, 1, `路径 ${path} 应有且仅有一条`);
+    return found[0];
+  };
+  const call = async (path, opts) => {
+    // 注册表按无 query 的路径索引；调用点传的是「路径 + query」的完整 URL。
+    const route = byPath(path.split("?")[0]);
+    const req = makeReq({ url: path, ...opts });
+    const res = makeRes();
+    await route.handler(req, res);
+    return res;
+  };
+  return { routes, call, byPath };
+}
+
+function newKb() {
+  const store = createStore(":memory:");
+  return { store, kb: createKb({ store, cfg: {} }) };
+}
+
+test("六条路由全在场，路径与 policy 严格照 §3.6 的表", () => {
+  const { store, kb } = newKb();
+  try {
+    const { routes } = install({ kb });
+    const table = routes.map((r) => `${r.kind}:${r.path}:${r.policy}`).sort();
+    assert.deepEqual(table, [
+      "exact:/api/dsh-mneme/kb/collections:token-write",
+      "exact:/api/dsh-mneme/kb/doc:token",
+      "exact:/api/dsh-mneme/kb/docs:token",
+      "exact:/api/dsh-mneme/kb/ingest:token-write",
+      "exact:/api/dsh-mneme/kb/search:token-write"
+    ].sort());
+  } finally {
+    store.close();
+  }
+});
+
+test("kb 未装配时全部 503，不抛也不静默 200", async () => {
+  const { call } = install({ kb: null });
+  for (const [path, opts] of [
+    ["/api/dsh-mneme/kb/collections", { method: "GET" }],
+    ["/api/dsh-mneme/kb/docs", { method: "GET", url: "/api/dsh-mneme/kb/docs?collection=c" }],
+    ["/api/dsh-mneme/kb/doc", { method: "GET", url: "/api/dsh-mneme/kb/doc?collection=c&relKey=x" }],
+    ["/api/dsh-mneme/kb/ingest", { method: "POST", body: "{}" }],
+    ["/api/dsh-mneme/kb/search", { method: "POST", body: "{}" }]
+  ]) {
+    const res = await call(path, opts);
+    assert.equal(res.statusCode, 503, `${path} 应 503`);
+    assert.equal(res.body.error, "unavailable");
+  }
+});
+
+test("传入的 gate 原样生效（关着时 409 由 gate 回，路由自己不再判）", async () => {
+  const { store, kb } = newKb();
+  try {
+    let gateCalls = 0;
+    const { call } = install({
+      kb,
+      gate: (_req, res) => {
+        gateCalls += 1;
+        sendJson(res, 409, { error: "disabled", reason: "kb-not-enabled" });
+        return false;
+      }
+    });
+    const res = await call("/api/dsh-mneme/kb/collections", { method: "GET" });
+    assert.equal(res.statusCode, 409);
+    assert.equal(res.body.reason, "kb-not-enabled");
+    assert.equal(gateCalls, 1, "每个请求过且只过一次 gate");
+  } finally {
+    store.close();
+  }
+});
+
+test("集合：POST 建 → GET 列出 → DELETE 按 query key 删，重复删 deleted:false", async () => {
+  const { store, kb } = newKb();
+  try {
+    const { call } = install({ kb });
+
+    let res = await call("/api/dsh-mneme/kb/collections", {
+      method: "POST",
+      body: JSON.stringify({ key: "manual", title: "手册", description: "内部" })
+    });
+    assert.equal(res.statusCode, 200);
+    assert.deepEqual(res.body, { ok: true, key: "manual" });
+
+    res = await call("/api/dsh-mneme/kb/collections", { method: "GET" });
+    assert.equal(res.body.collections.length, 1);
+    assert.equal(res.body.collections[0].key, "manual");
+    assert.equal(res.body.collections[0].docs, 0);
+
+    // 缺 key 是 400，不是默默建一个空 key 的集合。
+    res = await call("/api/dsh-mneme/kb/collections", { method: "POST", body: "{}" });
+    assert.equal(res.statusCode, 400);
+    assert.equal(res.body.error, "key-required");
+
+    res = await call("/api/dsh-mneme/kb/collections?key=manual", { method: "DELETE" });
+    assert.deepEqual(res.body, { ok: true, deleted: true });
+
+    res = await call("/api/dsh-mneme/kb/collections?key=manual", { method: "DELETE" });
+    assert.deepEqual(res.body, { ok: true, deleted: false }, "重复删是 false 不是 500");
+  } finally {
+    store.close();
+  }
+});
+
+test("ingest：成功回 ok:true + skipped 语义透出；坏 body / 缺字段 / 拼错集合各走各的码", async () => {
+  const { store, kb } = newKb();
+  const dir = mkdtempSync(join(tmpdir(), "kb-routes-"));
+  try {
+    const { call } = install({ kb });
+    await call("/api/dsh-mneme/kb/collections", {
+      method: "POST",
+      body: JSON.stringify({ key: "c", title: "C" })
+    });
+    const src = join(dir, "a.md");
+    writeFileSync(src, "## 节\n路由测试内容 router\n", "utf8");
+
+    let res = await call("/api/dsh-mneme/kb/ingest", {
+      method: "POST",
+      body: JSON.stringify({ collection: "c", kind: "file", source: src })
+    });
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.skipped, false);
+    assert.ok(res.body.chunks >= 1);
+    assert.ok(res.body.docId > 0);
+
+    // 再入库：skipped 必须透传到 HTTP 面（面板据此不显示「重新索引了」）。
+    res = await call("/api/dsh-mneme/kb/ingest", {
+      method: "POST",
+      body: JSON.stringify({ collection: "c", kind: "file", source: src })
+    });
+    assert.equal(res.body.skipped, true);
+
+    // 缺字段 → 400。
+    res = await call("/api/dsh-mneme/kb/ingest", { method: "POST", body: "{}" });
+    assert.equal(res.statusCode, 400);
+    assert.equal(res.body.error, "collection-kind-source-required");
+
+    // 坏 JSON 不崩：parseBody 回 {} → 同样落到缺字段 400。
+    res = await call("/api/dsh-mneme/kb/ingest", { method: "POST", body: "{not json" });
+    assert.equal(res.statusCode, 400);
+
+    // 拼错集合 → 404（且不凭空建集合）。
+    res = await call("/api/dsh-mneme/kb/ingest", {
+      method: "POST",
+      body: JSON.stringify({ collection: "ghost", kind: "file", source: src })
+    });
+    assert.equal(res.statusCode, 404);
+    assert.equal(res.body.error, "collection-not-found");
+    assert.equal(kb.listCollections().length, 1);
+
+    // kind 非法 → 400。
+    res = await call("/api/dsh-mneme/kb/ingest", {
+      method: "POST",
+      body: JSON.stringify({ collection: "c", kind: "pdf", source: src })
+    });
+    assert.equal(res.statusCode, 400);
+    assert.equal(res.body.error, "bad-kind");
+
+    // 来源不存在 → **200 + ok:false**：kb_docs 已留 error 行，面板要能显示原因；
+    // 回 4xx 会让面板当成「请求错了」把那条记录丢掉。
+    res = await call("/api/dsh-mneme/kb/ingest", {
+      method: "POST",
+      body: JSON.stringify({ collection: "c", kind: "file", source: join(dir, "nope.md") })
+    });
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.ok, false);
+    assert.equal(res.body.error, "file-not-found");
+
+    const docs = await call("/api/dsh-mneme/kb/docs?collection=c", { method: "GET" });
+    assert.equal(docs.body.docs.length, 2);
+    assert.equal(docs.body.docs.filter((d) => d.status === "error").length, 1);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("search / doc：命中形状与 readDoc 走 query 参数；查不到回 404", async () => {
+  const { store, kb } = newKb();
+  const dir = mkdtempSync(join(tmpdir(), "kb-routes-"));
+  try {
+    const { call } = install({ kb });
+    await call("/api/dsh-mneme/kb/collections", {
+      method: "POST",
+      body: JSON.stringify({ key: "c", title: "C" })
+    });
+    const src = join(dir, "s.md");
+    const original = "# 题\n\n## 检索\n这里有 needle 这个词。\n";
+    writeFileSync(src, original, "utf8");
+    await call("/api/dsh-mneme/kb/ingest", {
+      method: "POST",
+      body: JSON.stringify({ collection: "c", kind: "file", source: src })
+    });
+
+    let res = await call("/api/dsh-mneme/kb/search", {
+      method: "POST",
+      body: JSON.stringify({ query: "needle" })
+    });
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.hits.length, 1);
+    assert.deepEqual(res.body.unreadable, []);
+    assert.equal(res.body.hits[0].collection, "c");
+    assert.equal(res.body.hits[0].relKey, src);
+    assert.equal(res.body.hits[0].heading, "检索");
+
+    // 空 query 是 400：回 200 + 空 hits 会让模型以为「库里没这个」。
+    res = await call("/api/dsh-mneme/kb/search", { method: "POST", body: JSON.stringify({ query: "  " }) });
+    assert.equal(res.statusCode, 400);
+    assert.equal(res.body.error, "query-required");
+
+    // GET 打 search 是 405（不是静默 200）。
+    res = await call("/api/dsh-mneme/kb/search", { method: "GET" });
+    assert.equal(res.statusCode, 405);
+
+    res = await call(
+      `/api/dsh-mneme/kb/doc?collection=c&relKey=${encodeURIComponent(src)}`,
+      { method: "GET" }
+    );
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.content, original);
+    assert.equal(res.body.title, "s.md");
+
+    res = await call("/api/dsh-mneme/kb/doc?collection=c&relKey=nope", { method: "GET" });
+    assert.equal(res.statusCode, 404);
+    assert.equal(res.body.error, "doc-not-found");
+
+    res = await call("/api/dsh-mneme/kb/doc?collection=c", { method: "GET" });
+    assert.equal(res.statusCode, 400);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});
+
+test("三个工具的形状：名字/只读性/execute 在 kb 缺席时给人话", async () => {
+  const { store, kb } = newKb();
+  const dir = mkdtempSync(join(tmpdir(), "kb-tools-"));
+  try {
+    const defs = kbToolDefinitions({ kb, cfg: {} });
+    assert.deepEqual(defs.map((d) => d.name).sort(), ["kb_list_collections", "kb_read_doc", "kb_search"]);
+    for (const d of defs) {
+      assert.equal(typeof d.description, "string");
+      assert.ok(d.description.length > 20, `${d.name} 的描述要能指导模型`);
+      assert.equal(typeof d.parameters, "object");
+      assert.equal(typeof d.output?.schema, "object");
+      assert.equal(typeof d.output?.render, "function");
+      assert.equal(typeof d.execute, "function");
+      // 只读红线：参数里不许出现任何「写」味的东西（工具侧只有读口）。
+      assert.ok(!/ingest|upsert|delete|write/i.test(d.name));
+    }
+
+    await kb.upsertCollection({ key: "c", title: "C" });
+    const src = join(dir, "t.md");
+    writeFileSync(src, "## 节\ntool content\n", "utf8");
+    await kb.ingest({ collection: "c", kind: "file", source: src });
+
+    const [list, search, read] = [
+      defs.find((d) => d.name === "kb_list_collections"),
+      defs.find((d) => d.name === "kb_search"),
+      defs.find((d) => d.name === "kb_read_doc")
+    ];
+
+    const listed = await list.execute({});
+    assert.equal(listed.collections.length, 1);
+    assert.equal(listed.collections[0].key, "c");
+
+    const hit = await search.execute({ query: "tool" });
+    assert.equal(hit.hits.length, 1);
+    assert.deepEqual(hit.unreadable, []);
+
+    const doc = await read.execute({ collection: "c", relKey: src });
+    assert.equal(doc.content, "## 节\ntool content\n");
+    assert.equal(doc.title, "t.md");
+
+    // 查不到要抛（模型看到的是「不存在」而不是空串——空串会被当成空文档继续编）。
+    await assert.rejects(() => read.execute({ collection: "c", relKey: "/nope" }), /was not found/);
+    await assert.rejects(() => search.execute({ query: "  " }), /query is required/);
+    await assert.rejects(() => read.execute({ collection: "c" }), /both required/);
+
+    // render 不能因为空结果就炸（回执里 hits/collections 可能是空数组）。
+    assert.ok(list.output.render({}, { collections: [] })[0].text.includes("0 collections"));
+    assert.ok(search.output.render({}, { hits: [] })[0].text.includes("0 hits"));
+
+    // 未装配：不返回 undefined.name，而是明确抛一句人话。
+    const orphan = kbToolDefinitions({ kb: null })[0];
+    await assert.rejects(() => orphan.execute({}), /not available/);
+  } finally {
+    await rmTempEventually(dir);
+    store.close();
+  }
+});

package/test/mint-source.test.js

@@ -260,6 +260,32 @@ test("issue#512: only creation is recorded — edits to existing rows stay in re
   store.close();
 });
 
+// #619 / Ephor 第七轮 ③：原地刷新不是出生。同一个 pattern 跑两轮，第一轮真铸了、
+// 第二轮只是把同一行重写；memory_mints 的语义是「这条记忆出生自哪一轮」，第二行
+// 就是「同一条记忆出生过两次」——面板上会显示两条出生记录（mintsFor 由
+// provenance-http.js 读）。live 库当时还没显形，因为同题刷新刚上线。
+test("issue#619r: a refreshed pattern does not record a second birth", () => {
+  const { store, service } = setup();
+  const decision = [{ action: "create", type: "pattern", title: "同题规律", content: "第一轮", importance: 3 }];
+  const first = applyDecisions(decision, service, null, null, { mintSource: "sleep", runId: "run-a" });
+  assert.equal(first.applied, 1, "第一轮真铸了");
+  const row = service.all().find((m) => m.type === "pattern");
+  assert.equal(store.mintsFor(row.id).length, 1);
+
+  const second = applyDecisions(
+    [{ action: "create", type: "pattern", title: "同题规律", content: "第二轮", importance: 3 }],
+    service,
+    null,
+    null,
+    { mintSource: "sleep", runId: "run-b" }
+  );
+  assert.equal(second.applied, 0, "第二轮没有新铸");
+  assert.equal(second.merged, 1, "它刷新了一条");
+  assert.equal(second.committed[0].action, "create_merged");
+  assert.equal(store.mintsFor(row.id).length, 1, "刷新不算再一次出生");
+  store.close();
+});
+
 // 端到端：sleep 真的跑一轮，铸造出来的行要指回那一轮的 runId（不是随便一个 id）。
 test("issue#512: sleep mints point back at the run that produced them", async () => {
   const { store, service } = setup();