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

package/lib/kb/index.js

@@ -0,0 +1,309 @@
+// dsh-mneme/src/kb/index.js
+// 知识库第二层（§3.3/§3.4）：集合 + 文档入库（本地文件 / 网页 / 仓库地志页）+
+// 分块 + BM25 检索。真源在 kb_* 三张表里（不像 chorography 那样以磁盘 MD 为真源
+// ——知识库收的就是「外来原文的副本」，用户随时可能把原文件挪走/删掉，检索面不能
+// 跟着消失），所以读侧零 IO。
+//
+// 物理隔离：本模块只碰 kb_* 三张表，绝不写 memories，也不进巩固/质量过滤任何池子
+// （与 wiki 行同一条纪律，也是 §3.3 的红线）。
+import { readFileSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { createHash } from "node:crypto";
+import { createBM25Index } from "../search/bm25.js";
+
+// 单文档上限：知识库是检索面不是文件仓，几十兆的语料进来只会把 BM25 全量重算
+// 变成卡顿源。超限给明确 error 回执（面板要能显示「这份为什么不进来」），不静默截断。
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+// 单块目标长度：BM25 的 length normalization 对超长块惩罚很重，而太碎的块丢上下文。
+// 1200 字符约等于中文 600 字，是「一段完整论述」的常见尺度。
+const CHUNK_TARGET_CHARS = 1200;
+
+const KINDS = new Set(["file", "url", "choro_page"]);
+
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/**
+ * 按行切块，**严格连续、不跳行**——这是 readDoc 能逐字节还原原文、以及检索命中
+ * 能给出准确行号（起始行 = 1 + 前面所有块的行数）的前提。破坏它这两件事同时坏。
+ * `## ` 标题开启新节并重置 target（一节尽量整块进来，除非它自己就超长）；
+ * 超长单行单独成块不拆（行号与原文还原都靠这个假设）。
+ */
+function chunkContent(content) {
+  const lines = String(content ?? "").replace(/\r\n/g, "\n").split("\n");
+  const chunks = [];
+  let heading = "";
+  let buf = [];
+  let bufChars = 0;
+
+  const flush = () => {
+    if (!buf.length) return;
+    // 一个空行都不剥：块间用 \n 直接拼接就是原文（readDoc 靠这条），而且空白行
+    // 不产生 token，对 BM25 的 len 分母零成本——剥它反而是纯损。
+    chunks.push({ heading, text: buf.join("\n") });
+    buf = [];
+    bufChars = 0;
+  };
+
+  for (const line of lines) {
+    const isH2 = /^##\s+/.test(line);
+    const startsSection = isH2 && buf.length > 0;
+    if (startsSection) flush();
+    if (isH2) heading = line.replace(/^##\s+/, "").trim();
+    buf.push(line);
+    bufChars += line.length + 1;
+    if (bufChars >= CHUNK_TARGET_CHARS) flush();
+  }
+  flush();
+  return chunks;
+}
+
+function makeExcerpt(text, max = 200) {
+  return String(text ?? "").replace(/\s+/g, " ").trim().slice(0, max);
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.store  createStore() 的返回值（用到 kb* 那组方法）
+ * @param {object} [deps.embedder]  v1 不接向量（BM25 打底）；保留位，配了也不影响
+ *                                 检索结果，接向量是下一档的事
+ * @param {object} [deps.cfg]
+ */
+export function createKb({ store, embedder = null, cfg = {} } = {}) {
+  if (!store || !store.db) throw new TypeError("createKb: store is required");
+  const maxBytes = Number(cfg?.kbMaxBytes) > 0 ? Number(cfg.kbMaxBytes) : DEFAULT_MAX_BYTES;
+  // 检索索引按集合懒物化：kb 是 opt-in 子系统，一次 ingest 之后反复检索的收益远大于
+  // 「每次重建一遍 corpus」。写路径（ingest / delete / upsert）令其失效。
+  const indexCache = new Map();
+
+  function resolveCollection(key) {
+    return store.kbCollectionByKey(String(key ?? "").trim());
+  }
+
+  function invalidate(collectionKey) {
+    if (collectionKey == null) indexCache.clear();
+    else indexCache.delete(String(collectionKey));
+  }
+
+  function listCollections() {
+    return store.listKbCollections().map((r) => ({
+      key: r.key,
+      title: r.title,
+      description: r.description ?? "",
+      docs: Number(r.doc_count ?? 0),
+      chunks: Number(r.chunk_count ?? 0),
+      updatedAt: r.updated_at,
+    }));
+  }
+
+  function upsertCollection({ key, title, description = "" } = {}) {
+    const k = String(key ?? "").trim();
+    if (k === "") throw new TypeError("upsertCollection: key is required");
+    const row = store.upsertKbCollection({
+      key: k,
+      title: String(title ?? "").trim() || k,
+      description: String(description ?? ""),
+      at: new Date().toISOString(),
+    });
+    invalidate(k);
+    return { key: row.key, title: row.title, description: row.description ?? "" };
+  }
+
+  function deleteCollection(key) {
+    const k = String(key ?? "").trim();
+    if (k === "") return false;
+    const gone = store.deleteKbCollection(k);
+    invalidate(k);
+    return gone;
+  }
+
+  function listDocs({ collection } = {}) {
+    const col = resolveCollection(collection);
+    if (!col) return [];
+    return store.listKbDocs(col.id).map((d) => ({
+      relKey: d.rel_key,
+      kind: d.kind,
+      title: d.title,
+      bytes: Number(d.bytes ?? 0),
+      indexedAt: d.indexed_at,
+      status: d.status,
+      error: d.error ?? null,
+    }));
+  }
+
+  /** 读来源正文。三种 kind 各自的最短路径，出错一律抛，由 ingest 收成 error 回执。 */
+  async function readSource({ kind, source }) {
+    const src = String(source ?? "").trim();
+    if (src === "") throw new Error("empty-source");
+    if (kind === "url") {
+      if (typeof fetch !== "function") throw new Error("fetch-unavailable");
+      const res = await fetch(src, { redirect: "follow" });
+      if (!res.ok) throw new Error(`http-${res.status}`);
+      const raw = await res.text();
+      return { text: raw, relKey: src, title: src };
+    }
+    // file / choro_page：choro_page 的 source 就是该地志页 MD 的绝对路径（面板从
+    // 地志页「导入」时拿到的正是它）。kind 只作分类与展示，读取路径与普通文件一致
+    // ——不为它去跨域读 choro_* 表，那会把两条线的写作用域搅在一起。
+    let size = 0;
+    try {
+      size = statSync(src).size;
+    } catch (cause) {
+      throw new Error(cause.code === "ENOENT" ? "file-not-found" : "file-unreadable");
+    }
+    if (size > maxBytes) throw new Error("too-large");
+    const text = readFileSync(src, "utf8");
+    return { text, relKey: src, title: basename(src) };
+  }
+
+  /**
+   * 入库。同 rel_key + 同 sha256 是 no-op（回执 skipped=true，chunks 是库里现有的
+   * 块数不是重新切出来的块数）——这条是整个幂等契约的落点，编辑器保存一次不能
+   * 触发全量重切块。
+   */
+  async function ingest({ collection, kind, source, title } = {}) {
+    const colKey = String(collection ?? "").trim();
+    const k = String(kind ?? "").trim();
+    const now = new Date().toISOString();
+    if (!KINDS.has(k)) {
+      return { docId: null, chunks: 0, skipped: false, error: "bad-kind" };
+    }
+    const col = resolveCollection(colKey);
+    if (!col) {
+      // 不静默建集合：拼错 key 的入库会把资料塞进一个凭空出现的集合里，用户永远
+      // 找不到。面板的流程是先建集合再入库，工具侧也是先 list 再 ingest。
+      return { docId: null, chunks: 0, skipped: false, error: "collection-not-found" };
+    }
+
+    let body;
+    try {
+      body = await readSource({ kind: k, source });
+    } catch (cause) {
+      const message = String(cause?.message ?? cause);
+      const docId = store.markKbDocError({
+        collectionId: col.id,
+        relKey: String(source ?? "").trim() || "(empty)",
+        kind: k,
+        sourcePath: String(source ?? "").trim() || null,
+        title: String(title ?? "").trim() || String(source ?? ""),
+        error: message,
+        at: now,
+      });
+      invalidate(colKey);
+      return { docId, chunks: 0, skipped: false, error: message };
+    }
+
+    const chunks = chunkContent(body.text);
+    const result = store.replaceKbDoc({
+      collectionId: col.id,
+      relKey: body.relKey,
+      kind: k,
+      sourcePath: body.relKey,
+      title: String(title ?? "").trim() || body.title,
+      bytes: Buffer.byteLength(body.text, "utf8"),
+      sha256: sha256(body.text),
+      at: now,
+      chunks: chunks.map((c, i) => ({ ordinal: i, heading: c.heading, text: c.text })),
+    });
+    invalidate(colKey);
+    return { docId: result.docId, chunks: result.chunks, skipped: result.skipped };
+  }
+
+  /** 集合级语料的 BM25 索引（懒物化，写路径失效）。 */
+  function indexFor(col) {
+    const cacheKey = col ? String(col.key) : "*";
+    const cached = indexCache.get(cacheKey);
+    if (cached) return cached;
+    const rows = store.kbChunksForSearch(col ? col.id : null);
+    const docs = rows.map((r) => ({
+      id: r.id,
+      // 标题与本节标题都进索引文本：用户搜「安装」时，命中「## 安装」比命中正文里
+      // 偶然出现的「安装」更该排前面，而 BM25 只看词频，标题必须显式入语料。
+      title: `${r.title} ${r.heading ?? ""}`.trim(),
+      content: r.text ?? "",
+      row: r,
+    }));
+    const built = { index: createBM25Index(docs), byId: new Map(docs.map((d) => [d.id, d])) };
+    indexCache.set(cacheKey, built);
+    return built;
+  }
+
+  function search({ query, collection = null, limit = 20 } = {}) {
+    const q = String(query ?? "").trim();
+    if (q === "") return { hits: [], unreadable: [] };
+    let col = null;
+    if (collection != null && String(collection).trim() !== "") {
+      col = resolveCollection(collection);
+      if (!col) return { hits: [], unreadable: [] };
+    }
+    const cap = Math.max(1, Math.min(100, Number(limit) || 20));
+    const { index, byId } = indexFor(col);
+    const ranked = index.search(q, { limit: cap });
+    // 行号：块是**严格连续按行切**的，所以某块起始行 = 1 + 它前面所有块的行数。
+    // 这里按需回算（只算命中的那一篇），避免给 kb_chunks 加一列只为省这点算术。
+    const lineCache = new Map();
+    const lineOf = (row) => {
+      if (!lineCache.has(row.doc_id)) {
+        const all = store.kbChunksByDoc(row.doc_id);
+        let cursor = 1;
+        const map = new Map();
+        for (const c of all) {
+          map.set(c.id, cursor);
+          // 块间用 \n 拼接，所以上一块的行数就是游标增量（不 +1）。
+          cursor += String(c.text ?? "").split("\n").length;
+        }
+        lineCache.set(row.doc_id, map);
+      }
+      return lineCache.get(row.doc_id).get(row.id) ?? 1;
+    };
+    const hits = ranked.map((hit) => {
+      const row = byId.get(hit.id).row;
+      return {
+        collection: row.collection_key,
+        relKey: row.rel_key,
+        title: row.title,
+        heading: row.heading ?? "",
+        line: lineOf(row),
+        excerpt: makeExcerpt(row.text),
+        score: hit.score,
+      };
+    });
+    return { hits, unreadable: [] };
+  }
+
+  /** 读整篇：块按行连续切，用 \n 拼回即是原文（见 chunkContent 的注释）。 */
+  function readDoc({ collection, relKey } = {}) {
+    const col = resolveCollection(collection);
+    if (!col) return null;
+    const doc = store.kbDocByRelKey(col.id, String(relKey ?? ""));
+    if (!doc) return null;
+    const chunks = store.kbChunksByDoc(doc.id);
+    return {
+      title: doc.title,
+      content: chunks.map((c) => c.text).join("\n"),
+      kind: doc.kind,
+      relKey: doc.rel_key,
+      status: doc.status,
+      error: doc.error ?? null,
+    };
+  }
+
+  function dispose() {
+    indexCache.clear();
+    try {
+      embedder?.dispose?.();
+    } catch { /* 释放期的失败不该盖住调用方的正常退出 */ }
+  }
+
+  return {
+    listCollections,
+    upsertCollection,
+    deleteCollection,
+    listDocs,
+    ingest,
+    search,
+    readDoc,
+    dispose,
+  };
+}

package/lib/kb/routes.js

@@ -0,0 +1,220 @@
+// dsh-mneme/src/kb/routes.js
+// 知识库第二层的 HTTP 面（契约 §3.6 的路径表）。**这张表是 C 线面板的合同**：
+// 路径、方法、请求体字段、回执形状都照表写死，两边不许各自发挥。
+//
+// 本文件不判 cfg.kbEnabled——那是 A 线 api.js 里 kbGate 的职责（一处判定，不两处
+// 分叉）。这里只吃传进来的 gate；万一没传（单测直接装路由），退化成「kb 未装配 →
+// 503」这一条最小围栏，语义与 #497 先例一致：503 = 环境缺件、409 = 用户没开。
+//
+// kb 允许为 null（未装配），此时一律 503 而不是抛：面板要靠状态码渲染空态。
+function defaultGate(kb, sendJson, res) {
+  if (!kb) {
+    sendJson(res, 503, { error: "unavailable", reason: "kb-unavailable" });
+    return false;
+  }
+  return true;
+}
+
+function queryOf(req) {
+  return new URL(req.url, "http://localhost").searchParams;
+}
+
+/**
+ * @param {(route: object) => void} register createRouteRegistrar 的注册函数
+ * @param {object} deps
+ * @param {object|null} deps.kb      createKb() 的返回值，未装配时 null
+ * @param {object} deps.cfg
+ * @param {(res, status, body) => void} deps.sendJson
+ * @param {(req, res) => Promise<string|null>} deps.readBody  超限时自己回过 413 并返回 null
+ * @param {(text: string) => object} deps.parseBody           坏 JSON 回 {}
+ * @param {(req, res) => boolean} [deps.gate]                 关 409 / 缺件 503，false = 已回执
+ */
+export function registerKbRoutes(register, { kb = null, cfg = {}, sendJson, readBody, parseBody, gate } = {}) {
+  if (typeof register !== "function") throw new TypeError("registerKbRoutes: register is required");
+  if (typeof sendJson !== "function") throw new TypeError("registerKbRoutes: sendJson is required");
+
+  const allowed = (req, res) => (typeof gate === "function" ? gate(req, res) : defaultGate(kb, sendJson, res));
+
+  // 读 JSON body 的唯一入口（三条写路由共用）。返回 null = readBody 已经回过 413，
+  // 调用点**必须**直接 return：否则会拿着空对象继续往 store 写，413 之后又落一次库。
+  // 坏 JSON 退化成 {}，由各 handler 的必填校验收成 400。
+  const readJson = async (req, res) => {
+    const text = await readBody(req, res);
+    if (text === null) return null;
+    if (typeof parseBody === "function") return parseBody(text);
+    try {
+      return JSON.parse(text);
+    } catch {
+      return {};
+    }
+  };
+
+  // --- 集合 ---------------------------------------------------------------
+  // 一条路径上读（GET）与写（POST/DELETE）混在一起，只能声明一个 policy，取更严的
+  // `token-write`——与 /profile 同款处理（src/api.js:495-514）。registrar 对同一
+  // kind+path 重复登记直接抛错，所以不能拆成两条。
+  //
+  // 失败闭环：kb.collections 里出现过的文档之外一切都不动。不存在「删了一半」——
+  // deleteCollection 是整个事务（store.deleteKbCollection 里有注释）。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/kb/collections",
+    policy: "token-write",
+    handler(req, res) {
+      if (!allowed(req, res)) return;
+      if (req.method === "GET") {
+        sendJson(res, 200, { collections: kb.listCollections() });
+        return;
+      }
+      if (req.method === "DELETE") {
+        // key 走 query：集合 key 允许含斜杠，塞进路径会把 router 的 exact 匹配搅坏。
+        const key = String(queryOf(req).get("key") ?? "").trim();
+        if (key === "") {
+          sendJson(res, 400, { error: "key-required" });
+          return;
+        }
+        sendJson(res, 200, { ok: true, deleted: kb.deleteCollection(key) === true });
+        return;
+      }
+      if (req.method !== "POST") {
+        sendJson(res, 405, { error: "method-not-allowed" });
+        return;
+      }
+      // 必须 return：handler 是 async 时吞掉 Promise，调用点（测试里的 await、
+      // 宿主里的 invoke）就看不到回执已经发出——与 choro/search 踩过的坑同源。
+      return readJson(req, res).then((body) => {
+        if (body === null) return;
+        const key = String(body?.key ?? "").trim();
+        if (key === "") {
+          sendJson(res, 400, { error: "key-required" });
+          return;
+        }
+        const saved = kb.upsertCollection({
+          key,
+          title: body?.title,
+          description: body?.description
+        });
+        sendJson(res, 200, { ok: true, key: saved.key });
+      });
+    }
+  });
+
+  // --- 文档列表 -----------------------------------------------------------
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/kb/docs",
+    policy: "token",
+    handler(req, res) {
+      if (!allowed(req, res)) return;
+      const collection = String(queryOf(req).get("collection") ?? "").trim();
+      if (collection === "") {
+        sendJson(res, 400, { error: "collection-required" });
+        return;
+      }
+      sendJson(res, 200, { docs: kb.listDocs({ collection }) });
+    }
+  });
+
+  // --- 读整篇 -------------------------------------------------------------
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/kb/doc",
+    policy: "token",
+    handler(req, res) {
+      if (!allowed(req, res)) return;
+      const url = queryOf(req);
+      const collection = String(url.get("collection") ?? "").trim();
+      const relKey = String(url.get("relKey") ?? "");
+      if (collection === "" || relKey === "") {
+        sendJson(res, 400, { error: "collection-and-relKey-required" });
+        return;
+      }
+      const doc = kb.readDoc({ collection, relKey });
+      if (!doc) {
+        sendJson(res, 404, { error: "doc-not-found", collection, relKey });
+        return;
+      }
+      sendJson(res, 200, {
+        title: doc.title,
+        content: doc.content,
+        kind: doc.kind,
+        relKey: doc.relKey,
+        status: doc.status
+      });
+    }
+  });
+
+  // --- 入库 ---------------------------------------------------------------
+  // 入库是异步的（url 要 fetch），handler 必须把整条 Promise 链 return 出去——
+  // 不 return 会在响应发出之前就返回，body 恒空（choro/search 那条踩过同一个坑）。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/kb/ingest",
+    policy: "token-write",
+    handler(req, res) {
+      if (!allowed(req, res)) return;
+      if (req.method !== "POST") {
+        sendJson(res, 405, { error: "method-not-allowed" });
+        return;
+      }
+      return readJson(req, res).then(async (body) => {
+        if (body === null) return;
+        const collection = String(body?.collection ?? "").trim();
+        const kind = String(body?.kind ?? "").trim();
+        const source = String(body?.source ?? "").trim();
+        if (collection === "" || kind === "" || source === "") {
+          sendJson(res, 400, { error: "collection-kind-source-required" });
+          return;
+        }
+        const r = await kb.ingest({ collection, kind, source, title: body?.title });
+        if (r.error === "bad-kind") {
+          sendJson(res, 400, { ok: false, error: r.error });
+          return;
+        }
+        if (r.error === "collection-not-found") {
+          // 拼错的集合 key 是调用方的错，不是文档的错——不能悄悄建集合（见 index.js）。
+          sendJson(res, 404, { ok: false, error: r.error, collection });
+          return;
+        }
+        // 来源级失败（找不到文件 / 太大 / http-404）回 200 + ok:false：kb_docs 里已经
+        // 落了 status='error' 的行，面板要能显示「这份为什么没进来」，而 HTTP 4xx
+        // 会让面板把它当成「请求本身错了」丢掉那条记录。
+        sendJson(res, 200, {
+          ok: !r.error,
+          docId: r.docId,
+          chunks: r.chunks,
+          skipped: r.skipped,
+          ...(r.error ? { error: r.error } : {})
+        });
+      });
+    }
+  });
+
+  // --- 检索 ---------------------------------------------------------------
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/kb/search",
+    policy: "token-write",
+    handler(req, res) {
+      if (!allowed(req, res)) return;
+      if (req.method !== "POST") {
+        sendJson(res, 405, { error: "method-not-allowed" });
+        return;
+      }
+      return readJson(req, res).then((body) => {
+        if (body === null) return;
+        const query = String(body?.query ?? "").trim();
+        if (query === "") {
+          sendJson(res, 400, { error: "query-required" });
+          return;
+        }
+        const r = kb.search({
+          query,
+          collection: body?.collection ?? null,
+          limit: body?.limit
+        });
+        sendJson(res, 200, { hits: r.hits, unreadable: r.unreadable ?? [] });
+      });
+    }
+  });
+}

package/lib/kb/tools.js

@@ -0,0 +1,148 @@
+// dsh-mneme/src/kb/tools.js
+// 知识库的模型侧出口：三个**只读**工具（kb_list_collections / kb_search /
+// kb_read_doc）。写操作一个都不给模型——建集合、入库都是用户在面板上按的按钮
+// （与 chorography「生成只走 CLI」同一条红线：知识库收的是用户自己的资料，模型
+// 不该有权决定往里塞什么）。
+//
+// 返回 defineTool() 兼容的描述对象数组，由 src/tools.js 在 kbEnabled 时展开进
+// 它自己的数组——本文件不 import defineTool，装配顺序与两个开关（kbEnabled 与
+// kb 是否装配到位）由调用方掌握，一处判定不两处分叉。
+const TEXT_OUTPUT = (text) => [{ type: "text", text }];
+
+/**
+ * @param {object} deps
+ * @param {object|null} deps.kb  createKb() 的返回值；null = 未装配，仍返回数组但
+ *                               execute 会明确抛错（调用方本不该在此情形注册它们，
+ *                               真注册了也要给人话而不是 undefined 崩）
+ * @param {object} [deps.cfg]
+ */
+export function kbToolDefinitions({ kb = null, cfg = {} } = {}) {
+  const limitCap = Number(cfg?.kbSearchHitCap) > 0 ? Number(cfg.kbSearchHitCap) : 20;
+
+  const requireKb = () => {
+    if (!kb) throw new Error("Knowledge base is not available in this session (kb-unavailable).");
+    return kb;
+  };
+
+  return [
+    {
+      name: "kb_list_collections",
+      description: "List knowledge-base collections with document and chunk counts. The knowledge base holds the user's own reference material (local files, web pages, chorography pages) and is separate from memory. Use kb_search to search inside them. Read-only.",
+      parameters: {},
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            collections: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  key: { type: "string", required: true },
+                  title: { type: "string", required: true },
+                  description: { type: "string" },
+                  docs: { type: "integer", required: true },
+                  chunks: { type: "integer", required: true },
+                  updatedAt: { type: "string" }
+                }
+              }
+            }
+          }
+        },
+        render: (_args, value) => {
+          const list = value.collections ?? [];
+          if (list.length === 0) {
+            return TEXT_OUTPUT("0 collections. The user can add one from the mneme panel (Knowledge base → new collection).");
+          }
+          const lines = list.map((c) => `- ${c.key} — ${c.title}（${c.docs} docs, ${c.chunks} chunks）${c.description ? ` · ${c.description}` : ""}`);
+          return TEXT_OUTPUT(`${list.length} collections:\n${lines.join("\n")}`);
+        }
+      },
+      async execute() {
+        return { collections: requireKb().listCollections() };
+      }
+    },
+
+    {
+      name: "kb_search",
+      description: "Keyword (BM25) search over the knowledge base. Returns matching chunks with collection key, document relative key, section heading, line number and excerpt. Read-only — the knowledge base is not memory and nothing here is written back to it.",
+      parameters: {
+        query: { type: "string", description: "Search text (CJK and ASCII both work)" },
+        collection: { type: "string", description: "Restrict to one collection key; omit to search all collections" },
+        limit: { type: "integer", description: `Max hits (default 20, cap ${limitCap})` }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            hits: { type: "array", required: true, items: { type: "object", additionalProperties: true } },
+            unreadable: { type: "array", items: { type: "string" }, description: "Documents that could not be read during the search" }
+          }
+        },
+        render: (_args, value) => {
+          const hits = value.hits ?? [];
+          if (hits.length === 0) return TEXT_OUTPUT("0 hits.");
+          const lines = hits.map(
+            (h) => `${h.collection}/${h.relKey} · ${h.heading || "(no section)"} · L${h.line}: ${h.excerpt}`
+          );
+          return TEXT_OUTPUT(`${hits.length} hits:\n${lines.join("\n")}`);
+        }
+      },
+      async execute(args) {
+        const instance = requireKb();
+        const query = String(args?.query ?? "").trim();
+        if (query === "") throw new Error("kb_search: query is required.");
+        const limit = Math.max(1, Math.min(limitCap, Number(args?.limit) || 20));
+        const r = instance.search({ query, collection: args?.collection ?? null, limit });
+        return { hits: r.hits, unreadable: r.unreadable ?? [] };
+      }
+    },
+
+    {
+      name: "kb_read_doc",
+      description: "Read one knowledge-base document in full by collection key and relative key (as returned by kb_search). Read-only.",
+      parameters: {
+        collection: { type: "string", description: "Collection key" },
+        relKey: { type: "string", description: "Document relative key, e.g. the absolute source path shown in kb_search hits" }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            collection: { type: "string", required: true },
+            relKey: { type: "string", required: true },
+            title: { type: "string", required: true },
+            content: { type: "string", required: true }
+          }
+        },
+        render: (_args, value) => TEXT_OUTPUT(value.content)
+      },
+      async execute(args) {
+        const instance = requireKb();
+        const collection = String(args?.collection ?? "").trim();
+        const relKey = String(args?.relKey ?? "");
+        if (collection === "" || relKey === "") {
+          throw new Error("kb_read_doc: collection and relKey are both required.");
+        }
+        const doc = instance.readDoc({ collection, relKey });
+        if (!doc) {
+          // 明确说「查不到」而不是回空串：空串会被模型当成「文件是空的」继续瞎编。
+          throw new Error(
+            `Knowledge-base document ${JSON.stringify(relKey)} was not found in collection ${JSON.stringify(collection)}. Use kb_list_collections / kb_search to find the right key.`
+          );
+        }
+        if (doc.status === "error") {
+          throw new Error(
+            `Document ${JSON.stringify(relKey)} was not indexed successfully (last error: ${doc.error ?? "unknown"}). The user can re-ingest it from the mneme panel.`
+          );
+        }
+        return { collection, relKey, title: doc.title, content: doc.content };
+      }
+    }
+  ];
+}