dsh-shared-kb 0.0.0-stage → 1.0.0

package/lib/service/hub.js

@@ -0,0 +1,791 @@
+/**
+ * 服务层：把解析、存储、索引、检索串成一条可被工具与 HTTP 调用的链。
+ *
+ * 多人协作的核心约束都在这里落地：
+ *
+ *  1. 索引**只在本机**建。任何一台机器都能直接读共享盘上的资料并重建自己的
+ *     索引，彼此不干扰；索引坏了删掉重建，不影响别人。
+ *
+ *  2. 索引刷新是**增量**的，判据是 manifest 里每篇文档的 version。
+ *     别人在另一台机器上导了 3 篇，我这边第一次检索时只补这 3 篇，
+ *     不会重建全库（重建 900 篇要几十秒，增量只要几百毫秒）。
+ *
+ *  3. 写操作走 withManifest 的 CAS。两个人在同一秒改同一个库时，
+ *     后提交的那个会收到 REV_CONFLICT 而不是静默覆盖。
+ *
+ *  4. provider 身份（名字 + 维度）写进索引 meta。换模型后索引自动整体重建，
+ *     绝不把两套不同模型的向量混在一个索引里。
+ */
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { HubError, badRequest, notFound } from "../core/errors.js";
+import { ensureHub, heartbeat, listMachines, localIndexCacheRoot, readHub } from "../core/hubconfig.js";
+import {
+  docDir,
+  docIdFor,
+  kbRootDir,
+  normalizeRelKey,
+  safeFileName,
+  sanitizeKbName,
+  sourcesDir,
+} from "../core/paths.js";
+import { packBlocks, outlineOf } from "../parse/chunk.js";
+import { parseFile, renderPdfPage, SUPPORTED_EXTS } from "../parse/parser.js";
+import { createBuiltinProvider, resolveProvider } from "../indexer/embedder.js";
+import { indexFileInfo, indexPathFor, openIndex } from "../indexer/sqlite-index.js";
+import { groupByDoc, search as runSearch } from "../search/search.js";
+import {
+  createKb,
+  createSnapshot,
+  keepSourceCopy,
+  listKbs,
+  listNotes,
+  listPartFiles,
+  listSnapshots,
+  purgeDoc,
+  readDocMerged,
+  readNote,
+  readPartFromDisk,
+  refreshCatalog,
+  removeKb,
+  renameKb,
+  requireKb,
+  restoreDeletedDoc,
+  restoreDocVersion,
+  listDocHistory,
+  softDeleteDoc,
+  updateDocMeta,
+  updateKbMeta,
+  writeDoc,
+  writeNote,
+} from "../store/docs.js";
+import { appendEvent, readEvents, readManifest, withManifest } from "../store/manifest.js";
+import { inspectLeases, pruneStaleLeases } from "../store/lease.js";
+
+export const DEFAULT_CONFIG = Object.freeze({
+  kbRoot: "~/.dsh/shared-kb",
+  defaultKb: "default",
+  semanticProvider: "auto",
+  semanticModelDir: "",
+  remoteBaseUrl: "",
+  remoteApiKey: "",
+  remoteModel: "",
+  remoteDim: 1024,
+  builtinDim: 512,
+  partChars: 1200,
+  overlapChars: 150,
+  indexCacheRoot: "",
+  historyKeep: 10,
+  maxImportBytes: 512 * 1024 * 1024,
+  autoIndex: true,
+  logger: null,
+});
+
+/**
+ * Hub 门面：一个实例对应一个 kbRoot。
+ * 用工厂函数而不是 class，方便测试注入。
+ */
+export async function createHub(options = {}) {
+  const config = { ...DEFAULT_CONFIG, ...options };
+  const root = config.root ?? config.kbRoot;
+  if (!root) throw badRequest("createHub 需要 root（知识库物理地址）");
+  const ensured = await ensureHub(root);
+  const indexCacheRoot = config.indexCacheRoot || localIndexCacheRoot(join(homeOf(), ".dsh", "shared-kb"), root);
+  await mkdir(indexCacheRoot, { recursive: true });
+
+  let providerPromise = null;
+  let providerInfo = { name: "builtin-hash-v1", dim: config.builtinDim, kind: "builtin", notes: [] };
+
+  /** 解析 embedding provider（懒加载 + 缓存探针结果）。 */
+  async function getProvider() {
+    if (!providerPromise) {
+      providerPromise = resolveProvider({
+        semanticProvider: config.semanticProvider,
+        semanticModelDir: config.semanticModelDir,
+        remoteBaseUrl: config.remoteBaseUrl,
+        remoteApiKey: config.remoteApiKey,
+        remoteModel: config.remoteModel,
+        remoteDim: config.remoteDim,
+        builtinDim: config.builtinDim,
+        logger: config.logger,
+      })
+        .then((resolved) => {
+          providerInfo = {
+            name: resolved.provider.name,
+            dim: resolved.probe?.dim || resolved.provider.dim || config.builtinDim,
+            kind: resolved.provider.kind,
+            notes: resolved.notes ?? [],
+          };
+          return resolved.provider;
+        })
+        .catch((error) => {
+          // 任何意外都退回 builtin：语义检索可以降级，检索本身不能没有
+          providerInfo = {
+            name: "builtin-hash-v1",
+            dim: config.builtinDim,
+            kind: "builtin",
+            notes: [`provider 初始化失败：${String(error?.message ?? error)}`],
+          };
+          return createBuiltinProvider({ dim: config.builtinDim });
+        });
+    }
+    return providerPromise;
+  }
+
+  const indexHandles = new Map();
+  async function getIndex(kb) {
+    if (indexHandles.has(kb)) return indexHandles.get(kb);
+    const provider = await getProvider();
+    const path = indexPathFor(indexCacheRoot, kb);
+    const handle = await openIndex(path, { provider: provider.name, dim: providerInfo.dim });
+    indexHandles.set(kb, handle);
+    return handle;
+  }
+
+  function closeIndexes() {
+    for (const handle of indexHandles.values()) handle.close();
+    indexHandles.clear();
+  }
+
+  // -------------------------------------------------------------------------
+  // 索引同步
+  // -------------------------------------------------------------------------
+
+  /**
+   * 把索引与本机视角下的 manifest 对齐（增量）。
+   * @returns {Promise<{added: number, removed: number, total: number, rev: number, rebuilt: boolean}>}
+   */
+  async function syncIndex(kb, { force = false } = {}) {
+    const { dir } = await requireKb(root, kb);
+    const manifest = await readManifest(dir, kb);
+    const index = await getIndex(kb);
+    const live = (manifest.docs ?? []).filter((doc) => !doc.deletedAt && doc.status === "ready");
+    const indexed = index.indexedVersions();
+
+    const toWrite = [];
+    const toRemove = [];
+    for (const doc of live) {
+      const known = indexed.get(doc.id);
+      if (force || known === undefined || Number(known) !== Number(doc.version)) toWrite.push(doc);
+    }
+    for (const docId of indexed.keys()) {
+      if (!live.some((doc) => doc.id === docId)) toRemove.push(docId);
+    }
+
+    let rebuilt = false;
+    if (toWrite.length === 0 && toRemove.length === 0) {
+      return { added: 0, removed: 0, total: index.partCount(), rev: manifest.rev, rebuilt, unchanged: true };
+    }
+
+    const provider = await getProvider();
+    const payloads = [];
+    for (const doc of toWrite) {
+      const parts = await loadPartsForIndex(dir, doc);
+      if (parts.length === 0) continue;
+      let vectors = [];
+      try {
+        vectors = await provider.embed(parts.map((part) => `${doc.title}\n${part.heading}\n${part.text}`));
+      } catch (error) {
+        // 向量失败不能阻断全文索引：语义是增强，不是前提
+        vectors = [];
+        config.logger?.warn?.(`[shared-kb] ${kb}/${doc.id} 向量化失败，仅建全文索引：${String(error?.message ?? error)}`);
+      }
+      payloads.push({
+        docId: doc.id,
+        version: doc.version,
+        title: doc.title,
+        updatedAt: doc.updatedAt ?? "",
+        chars: doc.chars ?? 0,
+        parts,
+        vectors,
+      });
+    }
+
+    if (toRemove.length > 0) index.removeDocs(toRemove);
+    if (payloads.length > 0) index.upsertDocs(payloads, { manifestRev: manifest.rev, builtAt: new Date().toISOString() });
+    else index.upsertDocs([], { manifestRev: manifest.rev });
+
+    return {
+      added: payloads.length,
+      removed: toRemove.length,
+      total: index.partCount(),
+      rev: manifest.rev,
+      rebuilt,
+      skipped: toWrite.length - payloads.length,
+    };
+  }
+
+  /** 从磁盘重新解析一篇文档的所有分块（索引不存原文来源，只存分块）。 */
+  async function loadPartsForIndex(dir, doc) {
+    const merged = await readDocMerged(dir, doc.id);
+    if (merged === null) return [];
+    const indices = await listPartFiles(dir, doc.id);
+    if (indices.length > 0) {
+      const parts = [];
+      for (const index of indices) {
+        const text = await readPartFromDisk(dir, doc.id, index);
+        if (text === null || text === "") continue;
+        parts.push({ index, text, heading: "", page: null, chars: text.length });
+      }
+      if (parts.length > 0) {
+        // heading / page 从 meta 的 outline 补齐（拿不到就留空，不影响检索）
+        const outline = Array.isArray(doc.outline) ? doc.outline : [];
+        for (const part of parts) {
+          const nearest = [...outline].reverse().find((item) => item.part != null && item.part <= part.index);
+          if (nearest) part.heading = nearest.title ?? "";
+        }
+        return parts;
+      }
+    }
+    // 没有分块文件（老数据 / 手工放入的资料）：现场切一遍
+    const blocks = merged.split(/\n{2,}/).map((text) => ({ text, heading: "", level: 0 }));
+    return packBlocks(blocks, { partChars: config.partChars, overlapChars: config.overlapChars });
+  }
+
+  // -------------------------------------------------------------------------
+  // 建库 / 列库
+  // -------------------------------------------------------------------------
+
+  async function ensureDefaultKb() {
+    const name = sanitizeKbName(config.defaultKb ?? "default");
+    const result = await createKb(root, name, { existOk: true, description: "默认知识库" });
+    return result;
+  }
+
+  async function list(options = {}) {
+    await ensureDefaultKb();
+    const kbs = await listKbs(root);
+    if (!options.withMachines) return kbs;
+    return { kbs, machines: await listMachines(root) };
+  }
+
+  async function status() {
+    await heartbeat(root, { kbCount: (await listKbs(root)).length });
+    const hub = await readHub(root);
+    const machines = await listMachines(root);
+    const provider = await getProvider();
+    const kbs = await listKbs(root);
+    const indexes = [];
+    for (const kb of kbs) {
+      if (kb.broken) {
+        indexes.push({ kb: kb.name, broken: true });
+        continue;
+      }
+      const path = indexPathFor(indexCacheRoot, kb.name);
+      const info = await indexFileInfo(path);
+      let indexedDocs = null;
+      let indexedParts = null;
+      try {
+        const handle = await getIndex(kb.name);
+        indexedDocs = handle.docCount();
+        indexedParts = handle.partCount();
+      } catch (error) {
+        indexes.push({ kb: kb.name, ...info, error: String(error?.message ?? error) });
+        continue;
+      }
+      indexes.push({
+        kb: kb.name,
+        ...info,
+        indexedDocs,
+        indexedParts,
+        manifestDocs: kb.docs,
+        manifestRev: kb.rev,
+        stale: indexedDocs !== kb.docs,
+      });
+    }
+    return {
+      root,
+      indexCacheRoot,
+      indexLocation: "local",
+      hub,
+      provider: { ...providerInfo, instance: provider.name },
+      machines,
+      kbs,
+      indexes,
+      leases: await inspectLeases(await kbDirForLeases(kbs, root)),
+    };
+  }
+
+  async function kbDirForLeases(kbs, base) {
+    const first = kbs.find((kb) => !kb.broken);
+    return first ? kbRootDir(base, first.name) : base;
+  }
+
+  // -------------------------------------------------------------------------
+  // 导入
+  // -------------------------------------------------------------------------
+
+  /**
+   * 导入一个文件或目录。
+   *
+   * @param {object} params
+   * @param {string} params.path 源文件或目录
+   * @param {string} [params.kb] 库名（默认 defaultKb）
+   * @param {boolean} [params.recursive] 目录是否递归（默认 true）
+   * @param {object} [params.meta] 额外的元数据（title/tags/trust...），单文件时生效
+   * @param {number} [params.expectedRev] 并发保护
+   */
+  async function importPath(params) {
+    const kbName = sanitizeKbName(params.kb ?? config.defaultKb ?? "default");
+    await createKb(root, kbName, { existOk: true });
+    const { dir } = await requireKb(root, kbName);
+    const target = String(params.path ?? "").trim();
+    if (target === "") throw badRequest("path 不能为空");
+
+    const info = await stat(target).catch(() => null);
+    if (!info) throw notFound(`路径 ${target}`);
+    const files = [];
+    if (info.isFile()) {
+      files.push({ path: target, relKey: safeFileName(target) });
+    } else if (info.isDirectory()) {
+      const recursive = params.recursive !== false;
+      const collected = await collectFiles(target, { recursive });
+      for (const filePath of collected) {
+        const rel = normalizeRelKey(filePath.slice(target.length));
+        files.push({ path: filePath, relKey: rel || safeFileName(filePath) });
+      }
+    } else {
+      throw badRequest("path 既不是文件也不是目录");
+    }
+
+    if (files.length === 0) {
+      return { kb: kbName, imported: 0, skipped: 0, failed: 0, results: [], note: "目录下没有受支持的文件" };
+    }
+
+    const results = [];
+    let imported = 0;
+    let skipped = 0;
+    let failed = 0;
+
+    for (const file of files) {
+      try {
+        const size = (await stat(file.path)).size;
+        if (size > config.maxImportBytes) {
+          results.push({ relKey: file.relKey, status: "skipped", reason: `文件超过上限 ${config.maxImportBytes} 字节` });
+          skipped += 1;
+          continue;
+        }
+        const parsed = await parseFile(file.path);
+        const parts = packBlocks(
+          parsed.blocks.map((block) => ({
+            ...block,
+            page: block.page ?? null,
+          })),
+          { partChars: config.partChars, overlapChars: config.overlapChars }
+        );
+        if (parts.length === 0) {
+          results.push({ relKey: file.relKey, status: "skipped", reason: "没有解析出任何正文（可能是空白或纯图片文档）" });
+          skipped += 1;
+          continue;
+        }
+        const title = params.meta?.title && files.length === 1 ? params.meta.title : defaultTitle(file.relKey);
+        // 原始文件留一份：库要能整包搬走，不能依赖导入时那台机器的路径
+        await keepSourceCopy(dir, file.path, file.relKey);
+        const written = await writeDoc({
+          dir,
+          kb: kbName,
+          relKey: file.relKey,
+          parsed: { ...parsed, outline: outlineOf(parts) },
+          parts,
+          meta: { ...(files.length === 1 ? params.meta ?? {} : {}), title },
+          expectedRev: params.expectedRev,
+          sourcePath: file.path,
+          historyKeep: config.historyKeep,
+        });
+        if (written.status === "unchanged") skipped += 1;
+        else imported += 1;
+        results.push({ relKey: file.relKey, ...written, warnings: parsed.warnings });
+      } catch (error) {
+        failed += 1;
+        results.push({
+          relKey: file.relKey,
+          status: "failed",
+          reason: String(error?.message ?? error),
+          code: error?.code ?? "INTERNAL",
+        });
+      }
+    }
+
+    await refreshCatalog(dir, kbName);
+    let index = null;
+    if (config.autoIndex && imported > 0) {
+      index = await syncIndex(kbName).catch((error) => ({ error: String(error?.message ?? error) }));
+    }
+    return { kb: kbName, imported, skipped, failed, total: files.length, results, index };
+  }
+
+  async function collectFiles(dir, { recursive, out = [] } = {}) {
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return out;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive) await collectFiles(full, { recursive, out });
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = entry.name.slice(entry.name.lastIndexOf(".")).toLowerCase();
+      if (!SUPPORTED_EXTS.includes(ext)) continue;
+      out.push(full);
+    }
+    out.sort();
+    return out;
+  }
+
+  // -------------------------------------------------------------------------
+  // 检索
+  // -------------------------------------------------------------------------
+
+  async function query(params) {
+    const kbName = sanitizeKbName(params.kb ?? config.defaultKb ?? "default");
+    // 检索绝不隐式建库：库名打错时应该立刻报 NOT_FOUND，
+    // 而不是悄悄建一个空库然后返回「没有命中」，让人以为资料丢了。
+    await requireKb(root, kbName);
+    const text = String(params.query ?? "").trim();
+    if (text === "") throw badRequest("query 不能为空");
+
+    // 检索前自动增量同步：别人在别的机器上加的资料，这里第一次问就能看到
+    let sync = null;
+    if (config.autoIndex) {
+      sync = await syncIndex(kbName).catch((error) => ({ error: String(error?.message ?? error) }));
+    }
+    const provider = await getProvider();
+    const index = await getIndex(kbName);
+    const { hits, diagnostics } = await runSearch({
+      index,
+      query: text,
+      embedder: provider,
+      options: {
+        mode: params.mode,
+        limit: params.limit,
+        minVectorScore: params.minVectorScore,
+      },
+    });
+
+    const { dir } = await requireKb(root, kbName);
+    const manifest = await readManifest(dir, kbName);
+    const byId = new Map((manifest.docs ?? []).map((doc) => [doc.id, doc]));
+    // 过滤器：被软删的文档、以及清单里已经不存在的文档，都不能出现在检索结果里。
+    // 索引是异步增量刷的，删除后到下一次 sync 之间会有窗口期 —— 靠这一层兜住，
+    // 而不是要求调用方「删完记得重建索引」。
+    const enriched = hits
+      .filter((hit) => {
+        const doc = byId.get(hit.docId);
+        if (!doc) return false; // 清单里没有 = 已彻底删除
+        return !doc.deletedAt && doc.status === "ready";
+      })
+      .map((hit) => {
+        const doc = byId.get(hit.docId);
+        return {
+          ...hit,
+          title: doc.title,
+          standardNo: doc.standardNo ?? "",
+          trust: doc.trust ?? "unknown",
+          tags: doc.tags ?? [],
+          type: doc.type ?? "",
+          status: "ready",
+        };
+      });
+    const grouped = params.groupByDoc === false ? [] : groupByDoc(enriched).map((group) => {
+      const doc = byId.get(group.docId);
+      return { ...group, title: doc?.title ?? group.title, standardNo: doc?.standardNo ?? "" };
+    });
+
+    return {
+      kb: kbName,
+      query: text,
+      total: enriched.length,
+      hits: enriched,
+      docs: grouped,
+      diagnostics: { ...diagnostics, sync, provider: providerInfo },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // 精读
+  // -------------------------------------------------------------------------
+
+  async function readDocContent(params) {
+    const kbName = sanitizeKbName(params.kb ?? config.defaultKb ?? "default");
+    const { dir } = await requireKb(root, kbName);
+    const manifest = await readManifest(dir, kbName);
+    const doc = resolveDocRef(manifest, params.doc);
+    if (!doc) throw notFound(`文档 ${params.doc}`);
+
+    if (params.note) {
+      const content = await readNote(dir, doc.id);
+      if (content === null) throw notFound(`笔记 ${doc.id}`);
+      return { kb: kbName, docId: doc.id, title: doc.title, kind: "note", content, chars: content.length };
+    }
+
+    if (params.part === "all") {
+      const merged = (await readDocMerged(dir, doc.id)) ?? "";
+      const limit = Math.max(500, Number(params.maxChars) || 20000);
+      return {
+        kb: kbName,
+        docId: doc.id,
+        title: doc.title,
+        part: "all",
+        content: merged.slice(0, limit),
+        chars: merged.length,
+        truncated: merged.length > limit,
+        outline: doc.outline ?? [],
+      };
+    }
+
+    if (params.part === "outline") {
+      return {
+        kb: kbName,
+        docId: doc.id,
+        title: doc.title,
+        part: "outline",
+        outline: doc.outline ?? [],
+        parts: doc.parts ?? (await listPartFiles(dir, doc.id)).length,
+        pages: doc.pages ?? null,
+        warnings: doc.warnings ?? [],
+      };
+    }
+
+    const index = Math.max(1, Math.round(Number(params.part) || 1));
+    const fromDisk = await readPartFromDisk(dir, doc.id, index);
+    if (fromDisk === null) {
+      throw notFound(`文档 ${doc.title} 的第 ${index} 块（共 ${doc.parts ?? "?"} 块）`);
+    }
+    return {
+      kb: kbName,
+      docId: doc.id,
+      title: doc.title,
+      part: index,
+      total: doc.parts ?? (await listPartFiles(dir, doc.id)).length,
+      content: fromDisk,
+      chars: fromDisk.length,
+      warnings: doc.warnings ?? [],
+    };
+  }
+
+  function resolveDocRef(manifest, ref) {
+    const key = String(ref ?? "").trim();
+    if (key === "") return null;
+    const docs = manifest.docs ?? [];
+    const byId = docs.find((doc) => doc.id === key);
+    if (byId) return byId;
+    const lowered = key.toLowerCase();
+    const exact = docs.find((doc) => String(doc.title ?? "").toLowerCase() === lowered);
+    if (exact) return exact;
+    const partial = docs.filter((doc) => String(doc.title ?? "").toLowerCase().includes(lowered));
+    if (partial.length === 1) return partial[0];
+    if (partial.length > 1) {
+      throw new HubError("DOC_AMBIGUOUS", `标题 "${key}" 匹配到 ${partial.length} 篇文档，请用更精确的标题或 docId`, {
+        status: 409,
+        details: { candidates: partial.slice(0, 10).map((doc) => ({ id: doc.id, title: doc.title })) },
+      });
+    }
+    return null;
+  }
+
+  // -------------------------------------------------------------------------
+  // 维护
+  // -------------------------------------------------------------------------
+
+  async function rebuildIndex(kb) {
+    const kbName = sanitizeKbName(kb ?? config.defaultKb);
+    await requireKb(root, kbName);
+    const handle = indexHandles.get(kbName);
+    if (handle) {
+      handle.close();
+      indexHandles.delete(kbName);
+    }
+    const result = await syncIndex(kbName, { force: true });
+    return { kb: kbName, ...result };
+  }
+
+  /** 列出与检索相关的诊断信息（给 skb_status / 工作台用）。 */
+  async function inspect(kb) {
+    const kbName = sanitizeKbName(kb ?? config.defaultKb);
+    const { dir, meta } = await requireKb(root, kbName);
+    const manifest = await readManifest(dir, kbName);
+    const paths = {
+      root,
+      kbDir: dir,
+      sources: sourcesDir(dir),
+      markdown: join(dir, "markdown"),
+      notes: join(dir, "notes"),
+      manifest: join(dir, "manifest.json"),
+      events: join(dir, "events.jsonl"),
+      schema: join(dir, "schema.md"),
+      index: indexPathFor(indexCacheRoot, kbName),
+    };
+    return {
+      kb: kbName,
+      meta,
+      rev: manifest.rev,
+      docs: manifest.stats,
+      paths,
+      leases: await inspectLeases(dir),
+      history: await listDocHistory(dir, (manifest.docs ?? [])[0]?.id ?? "").catch(() => []),
+    };
+  }
+
+  return {
+    config,
+    root,
+    indexCacheRoot,
+    // 库
+    list,
+    status,
+    createKb: (name, opts) => createKb(root, name, opts),
+    removeKb: (name, opts) => removeKb(root, name, opts),
+    renameKb: (name, next) => renameKb(root, name, next),
+    updateKbMeta: (name, patch) => updateKbMeta(root, name, patch),
+    // 导入
+    importPath,
+    // 检索
+    query,
+    readDoc: readDocContent,
+    // 写
+    writeNote: async (params) => {
+      const kbName = sanitizeKbName(params.kb ?? config.defaultKb);
+      await createKb(root, kbName, { existOk: true });
+      const { dir } = await requireKb(root, kbName);
+      const result = await writeNote(dir, kbName, params);
+      await refreshCatalog(dir, kbName);
+      return result;
+    },
+    listNotes: async (kb) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      return listNotes(dir);
+    },
+    updateDocMeta: (kb, docId, patch, opts) => updateDocMeta(root, kb, docId, patch, opts),
+    // 删除/恢复都顺手同步索引：查询侧虽然有过滤器兜底，但索引里留着
+    // 已删文档的向量会让每次检索多扫无用的行，也让 status 报的数字对不上。
+    softDelete: async (kb, docId, opts) => {
+      const result = await softDeleteDoc(root, kb, docId, opts);
+      await syncIndex(sanitizeKbName(kb)).catch(() => {});
+      return result;
+    },
+    undelete: async (kb, docId, opts) => {
+      const result = await restoreDeletedDoc(root, kb, docId, opts);
+      await syncIndex(sanitizeKbName(kb)).catch(() => {});
+      return result;
+    },
+    purge: async (kb, docId, opts) => {
+      const result = await purgeDoc(root, kb, docId, opts);
+      await syncIndex(sanitizeKbName(kb)).catch(() => {});
+      return result;
+    },
+    docHistory: async (kb, docId) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      return listDocHistory(dir, docId);
+    },
+    restoreVersion: async (kb, docId, historyName) => {
+      const kbName = sanitizeKbName(kb ?? config.defaultKb);
+      const { dir } = await requireKb(root, kbName);
+      const result = await restoreDocVersion(dir, kbName, docId, historyName);
+      await syncIndex(kbName, { force: true }).catch(() => {});
+      return result;
+    },
+    // 清单/文档查询
+    docs: async (kb, options = {}) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      const manifest = await readManifest(dir, sanitizeKbName(kb ?? config.defaultKb));
+      let docs = manifest.docs ?? [];
+      if (!options.includeDeleted) docs = docs.filter((doc) => !doc.deletedAt && doc.status !== "deleted");
+      if (options.status) docs = docs.filter((doc) => doc.status === options.status);
+      if (options.kind) {
+        docs = options.kind === "note" ? docs.filter((doc) => doc.type === "note") : docs.filter((doc) => doc.type !== "note");
+      }
+      if (options.query) {
+        const q = String(options.query).toLowerCase();
+        docs = docs.filter((doc) => String(doc.title ?? "").toLowerCase().includes(q));
+      }
+      if (options.trust) docs = docs.filter((doc) => (doc.trust ?? "unknown") === options.trust);
+      docs = [...docs].sort((a, b) => String(a.title).localeCompare(String(b.title), "zh-Hans-CN"));
+      const offset = Math.max(0, Number(options.offset) || 0);
+      const limit = Math.max(1, Math.min(500, Number(options.limit) || 50));
+      return {
+        kb: sanitizeKbName(kb ?? config.defaultKb),
+        rev: manifest.rev,
+        total: docs.length,
+        offset,
+        limit,
+        hasMore: offset + limit < docs.length,
+        docs: docs.slice(offset, offset + limit),
+      };
+    },
+    // 索引
+    syncIndex,
+    rebuildIndex,
+    inspect,
+    // 快照
+    snapshot: async (kb, opts) => {
+      const kbName = sanitizeKbName(kb ?? config.defaultKb);
+      const { dir } = await requireKb(root, kbName);
+      return createSnapshot(dir, kbName, opts);
+    },
+    snapshots: async (kb) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      return listSnapshots(dir);
+    },
+    // 审计
+    events: async (kb, opts) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      return readEvents(dir, opts);
+    },
+    catalog: async (kb) => {
+      const kbName = sanitizeKbName(kb ?? config.defaultKb);
+      const { dir } = await requireKb(root, kbName);
+      return refreshCatalog(dir, kbName);
+    },
+    // 锁
+    leases: async (kb) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      return inspectLeases(dir);
+    },
+    pruneLeases: async (kb) => {
+      const { dir } = await requireKb(root, sanitizeKbName(kb ?? config.defaultKb));
+      return pruneStaleLeases(dir);
+    },
+    // 原件
+    renderPage: async (kb, docRef, pageNo, opts) => {
+      const kbName = sanitizeKbName(kb ?? config.defaultKb);
+      const { dir } = await requireKb(root, kbName);
+      const manifest = await readManifest(dir, kbName);
+      const doc = resolveDocRef(manifest, docRef);
+      if (!doc) throw notFound(`文档 ${docRef}`);
+      if ((doc.type ?? "") !== "pdf") throw badRequest(`只有 PDF 支持按页渲染（当前类型 ${doc.type}）`);
+      const sourcePath = join(sourcesDir(dir), doc.relKey ?? "");
+      await stat(sourcePath).catch(() => {
+        throw notFound(`原始文件不在库内：${doc.relKey}（可能导入时未保留副本）`);
+      });
+      return renderPdfPage(sourcePath, pageNo, opts);
+    },
+    provider: getProvider,
+    providerInfo: () => providerInfo,
+    heartbeat: () => heartbeat(root),
+    machines: () => listMachines(root),
+    close: closeIndexes,
+    appendEvent: (event) => appendEvent(kbRootDir(root, event.kb ?? config.defaultKb), event),
+    withManifest,
+  };
+}
+
+function homeOf() {
+  try {
+    return process.env.USERPROFILE || process.env.HOME || process.cwd();
+  } catch {
+    return process.cwd();
+  }
+}
+
+/** 从 relKey 推标题：去扩展名 + 把下划线换空格。 */
+export function defaultTitle(relKey) {
+  const base = String(relKey ?? "").split("/").pop() ?? "";
+  const dot = base.lastIndexOf(".");
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  return stem.replace(/[_]+/g, " ").trim() || "未命名文档";
+}