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

package/test/kb-api-wiring.test.js

@@ -0,0 +1,128 @@
+// 知识库第二层的接线回归锁（契约 §3.4 / §3.6）。
+//
+// A 线只负责「把已经写好的 kb 子系统接上闸与两条出口」——所以这里锁的是**闸的
+// 分叉形状**，不是 kb 内部功能（那在 kb 自己的测试里）。两条闸必须可区分：
+// 503 = 这个宿主没装配 kb；409 = 用户没开开关。两者混成一个状态码，面板就没法
+// 分辨「去设置里打开」和「这台宿主不支持」。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { Context } from "@deepseek-ai/cordis";
+import SystemPrompt from "@deepseek-ai/dsh-system-prompt";
+import ToolRuntime from "@deepseek-ai/dsh-tools";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createApi } from "../src/api.js";
+import { createSettings } from "../src/settings.js";
+import { createKb } from "../src/kb/index.js";
+import { createTools } from "../src/tools.js";
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+function req(path, method = "GET") {
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = method;
+  r.headers = {};
+  return r;
+}
+
+// 注意实参顺序：kb 是第 12 参，必须显式补到位置（facts 用 undefined 占位）。
+function setup({ config = null, kb = null } = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const routes = [];
+  const ctx = { webServer: { register(route) { routes.push(route); return () => {}; } } };
+  createApi(ctx, service, settings, { add: () => {}, remove: () => false, list: () => [] },
+    null, undefined, "", config, null, null, null, undefined, kb);
+  return { routes, store };
+}
+
+async function invoke(route, path) {
+  const res = new FakeRes();
+  await route.handler(req(path), res);
+  return { status: res.statusCode, body: JSON.parse(res.body || "{}") };
+}
+
+test("kb 未装配 → 503 unavailable；装了但开关没开 → 409 disabled（两条闸不许混）", async () => {
+  const missing = setup({ config: { kbEnabled: true } });
+  const off = setup({ config: { kbEnabled: false }, kb: createKb({ store: missing.store }) });
+  try {
+    const a = await invoke(missing.routes.find((r) => r.path === "/api/dsh-mneme/kb/collections"), "/api/dsh-mneme/kb/collections");
+    assert.equal(a.status, 503);
+    assert.equal(a.body.error, "unavailable");
+
+    const b = await invoke(off.routes.find((r) => r.path === "/api/dsh-mneme/kb/collections"), "/api/dsh-mneme/kb/collections");
+    assert.equal(b.status, 409);
+    assert.equal(b.body.error, "disabled");
+    assert.equal(b.body.reason, "kb-not-enabled");
+  } finally {
+    missing.store.close();
+    off.store.close();
+  }
+});
+
+test("开关开 + 已装配 → kb 六条路由全在册且 200 通", async () => {
+  const s = setup({ config: { kbEnabled: true }, kb: createKb({ store: createStore(":memory:") }) });
+  try {
+    const paths = [
+      "/api/dsh-mneme/kb/collections",
+      "/api/dsh-mneme/kb/docs",
+      "/api/dsh-mneme/kb/doc",
+      "/api/dsh-mneme/kb/ingest",
+      "/api/dsh-mneme/kb/search"
+    ];
+    for (const p of paths) assert.ok(s.routes.find((r) => r.path === p), `${p} 在册`);
+
+    // 同一路径上混了 GET/POST，policy 只能声明一个，取更严的 token-write。
+    // 这条锁防的是「为了省事把集合路径拆成两条」——registrar 会直接抛重复路径。
+    const collections = s.routes.find((r) => r.path === "/api/dsh-mneme/kb/collections");
+    assert.equal(collections.policy, "token-write");
+
+    const list = await invoke(collections, "/api/dsh-mneme/kb/collections");
+    assert.equal(list.status, 200);
+    assert.ok(Array.isArray(list.body.collections), "空知识库也要回空数组，面板靠它渲染空态而不是报错");
+  } finally {
+    s.store.close();
+  }
+});
+
+// 用 tools.get(name) 逐个探存在性：宿主注册表没有 list()，而 wiki-tools 里 choro
+// 三工具也是这么断言的（同一套探法，避免两处对「怎么算注册了」有两种理解）。
+async function toolPresence(config, kb, names) {
+  const ctx = new Context();
+  const prompt = await ctx.plugin(SystemPrompt);
+  const runtime = await ctx.plugin(ToolRuntime);
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const registry = ctx.get("tools");
+  createTools({ tools: registry }, service, config, null, null, null, kb);
+  const present = Object.fromEntries(names.map((n) => [n, Boolean(registry.get(n))]));
+  runtime.dispose(); prompt.dispose(); store.close();
+  return present;
+}
+
+test("kb 三工具：默认不注册，开关打开且装配到位才可见", async () => {
+  const KB_TOOLS = ["kb_list_collections", "kb_search", "kb_read_doc"];
+  const store = createStore(":memory:");
+  const kb = createKb({ store });
+
+  // 默认（kbEnabled 缺省 false）：模型看不到就不会调——与 choro 三工具同款反向语义。
+  const off = await toolPresence({}, kb, KB_TOOLS);
+  for (const name of KB_TOOLS) assert.equal(off[name], false, `${name} 默认不该注册`);
+
+  // 开了但装配缺件：同样不可见。可区分性归路由层（503 / 409），模型侧不需要
+  // 看见一个调了必抛的半个知识库。
+  const noKb = await toolPresence({ kbEnabled: true }, null, KB_TOOLS);
+  for (const name of KB_TOOLS) assert.equal(noKb[name], false, `${name} 装配缺件时不该注册`);
+
+  const on = await toolPresence({ kbEnabled: true }, kb, KB_TOOLS);
+  for (const name of KB_TOOLS) assert.equal(on[name], true, `${name} 开关开 + 装配到位时必须注册`);
+
+  store.close();
+});

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();
+  }
+});