dsh-shared-kb 0.0.0-stage → 1.0.1

package/lib/core/paths.js

@@ -0,0 +1,129 @@
+/**
+ * 路径与命名规则。
+ *
+ * 铁律：库名只允许字母数字汉字与 - _ .，不许出现路径分隔符或 ..，
+ * 因为库名直接当目录名用。文档 id 由相对键的哈希派生，天然安全。
+ */
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { badRequest } from "./errors.js";
+
+/** 展开 ~ 与 ~/xxx。 */
+export function expandUser(input) {
+  const text = String(input ?? "");
+  if (text === "~") return homedir();
+  if (text.startsWith("~/") || text.startsWith("~\\")) return join(homedir(), text.slice(2));
+  return text;
+}
+
+/** 把用户给的物理地址解析成绝对路径；相对路径按 cwd 解析。 */
+export function resolveRoot(input, cwd = process.cwd()) {
+  const expanded = expandUser(String(input ?? "").trim());
+  if (expanded === "") throw badRequest("kbRoot 不能为空");
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+}
+
+const KB_NAME_SAFE = /^[\p{L}\p{N}][\p{L}\p{N}._-]{0,63}$/u;
+
+/** 库名规范化：去空白、禁止路径分隔符与保留名。 */
+export function sanitizeKbName(input) {
+  const raw = String(input ?? "").trim();
+  if (raw === "") throw badRequest("库名不能为空");
+  const name = raw.normalize("NFC");
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+    throw badRequest(`库名不允许包含路径分隔符或 ".."：${raw}`);
+  }
+  if (name.startsWith(".")) throw badRequest(`库名不允许以 . 开头（保留给 .hub/.index 等内部目录）：${raw}`);
+  if (!KB_NAME_SAFE.test(name)) {
+    throw badRequest(`库名只能包含字母、数字、汉字、- _ .，且不超过 64 字符：${raw}`);
+  }
+  return name;
+}
+
+export function hubDir(root) {
+  return join(root, ".hub");
+}
+export function kbRootDir(root, name) {
+  return join(root, name);
+}
+export function kbMetaPath(dir) {
+  return join(dir, "kb.json");
+}
+export function sourcesDir(dir) {
+  return join(dir, "sources");
+}
+export function markdownDir(dir) {
+  return join(dir, "markdown");
+}
+export function docDir(dir, docId) {
+  return join(markdownDir(dir), docId);
+}
+export function docMetaPath(dir, docId) {
+  return join(docDir(dir, docId), "meta.json");
+}
+export function docMergedPath(dir, docId) {
+  return join(docDir(dir, docId), `${docId}.md`);
+}
+export function notesDir(dir) {
+  return join(dir, "notes");
+}
+export function exportsDir(dir) {
+  return join(dir, "exports");
+}
+export function snapshotsDir(dir) {
+  return join(dir, "snapshots");
+}
+export function locksDir(dir) {
+  return join(dir, ".locks");
+}
+export function localIndexDir(dir) {
+  return join(dir, ".index");
+}
+
+/** 文档 id：相对键（导入时的路径或标题）的短哈希，同键必然同 id。 */
+export function docIdFor(relKey) {
+  return createHash("sha256").update(String(relKey), "utf8").digest("hex").slice(0, 16);
+}
+
+/** 笔记 id：标题派生，同标题必然同 id（重复写=更新而不是新建）。 */
+export function noteIdFor(title) {
+  return "n" + createHash("sha256").update(String(title).trim(), "utf8").digest("hex").slice(0, 15);
+}
+
+/** 把源文件名整理成可安全落盘的形式（保留可读性，去掉非法字符）。 */
+export function safeFileName(input, fallback = "file") {
+  const raw = basename(String(input ?? "").trim()) || fallback;
+  const cleaned = raw
+    .replace(/[\u0000-\u001f<>:"/\\|?*]/g, "_")
+    .replace(/\s+/g, " ")
+    .trim();
+  const limited = cleaned.length > 120 ? cleaned.slice(0, 120) : cleaned;
+  return limited === "" || limited === "." || limited === ".." ? fallback : limited;
+}
+
+/** 判定路径是否落在某个根之内（防目录穿越）。 */
+export function isInside(root, target) {
+  const a = resolve(root);
+  const b = resolve(target);
+  if (a === b) return true;
+  return b.startsWith(a.endsWith(sep) ? a : a + sep);
+}
+
+const TEXTUAL_EXTS = new Set([".txt", ".md", ".markdown", ".json", ".csv", ".log", ".yml", ".yaml"]);
+
+export function extOf(path) {
+  return extname(String(path ?? "")).toLowerCase();
+}
+
+export function isTextualExt(ext) {
+  return TEXTUAL_EXTS.has(ext);
+}
+
+/** 把相对键统一成 / 分隔，跨平台一致（用于 docId 与展示）。 */
+export function normalizeRelKey(input) {
+  return String(input ?? "")
+    .split(/[\\/]+/)
+    .filter((part) => part !== "" && part !== ".")
+    .join("/");
+}

package/lib/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M4 5.5A2.5 2.5 0 0 1 6.5 3H19a1 1 0 0 1 1 1v13.5"/>
+  <path d="M4 5.5V19a2 2 0 0 0 2 2h12.5"/>
+  <path d="M6 17h13"/>
+  <circle cx="15.5" cy="9.5" r="2.5"/>
+  <path d="M15.5 12v4.5"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,202 @@
+/**
+ * 插件入口（Host 半）。
+ *
+ * 生命周期：
+ *   apply(ctx, config)
+ *     → 解析物理根目录（kbRoot），确保 .hub 标记
+ *     → 创建 hub 门面（懒按需，不在这里就连库连索引）
+ *     → 注册 kb_* 工具
+ *     → 注册 /shared-kb 工作台路由（宿主有 webServer 才做）
+ *     → 注册一条 systemPrompt 说明（告诉模型这个库怎么用）
+ *     → 返回 dispose：关闭所有 sqlite 句柄
+ *
+ * 硬约束：
+ *   - 不在 apply 里做耗时工作（导入/建索引），否则拖慢宿主启动；
+ *   - 任何失败都不能让宿主起不来：包一层 try/catch，失败降级为「不可用」
+ *     并在日志里写清楚，而不是 throw 出去。
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createHub } from "./service/hub.js";
+import { registerTools } from "./tools/index.js";
+import { registerWeb } from "./web/server.js";
+import { resolveRoot } from "./core/paths.js";
+
+const name = "shared-kb";
+const inject = ["tools", "systemPrompt"];
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** 读 package.json 版本（发版核对时日志里要有版本号）。 */
+function pluginVersion() {
+  try {
+    return JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export const Config = z.object({
+  kbRoot: z
+    .string()
+    .default("~/.dsh/shared-kb")
+    .description("知识库物理根目录。每个库在它下面建一个独立子文件夹；可以指向共享盘（UNC 路径或已挂载的盘符）。"),
+  defaultKb: z.string().default("default").description("未指定 kb 时使用的默认库名。"),
+  semanticProvider: z
+    .string()
+    .default("auto")
+    .description("语义检索 provider：auto（优先 onnx，缺失回退 builtin）/ onnx / remote / builtin。"),
+  semanticModelDir: z
+    .string()
+    .default("")
+    .description("ONNX 模型目录（需含 model.onnx / tokenizer.json / tokenizer_config.json）。留空则 onnx 不可用。"),
+  remoteBaseUrl: z.string().default("").description("remote provider：OpenAI 兼容 base URL（如 https://api.openai.com/v1）。"),
+  remoteApiKey: z.string().default("").description("remote provider：API Key。"),
+  remoteModel: z.string().default("").description("remote provider：embedding 模型名。"),
+  remoteDim: z.number().default(1024).description("remote provider 的向量维度（需与模型实际一致）。"),
+  builtinDim: z.number().default(512).description("builtin provider 的向量维度。"),
+  partChars: z.number().default(1200).description("每块字符数上限。"),
+  overlapChars: z.number().default(150).description("相邻块的重叠字符数。"),
+  indexCacheRoot: z
+    .string()
+    .default("")
+    .description("本机索引缓存根目录。留空用 ~/.dsh/shared-kb/indexes/<根目录哈希>。索引不放进共享盘（SQLite 在 SMB 上不可靠）。"),
+  historyKeep: z.number().default(10).description("每篇文档保留多少个历史正文版本。"),
+  maxImportBytes: z.number().default(536870912).description("单文件导入上限（字节，默认 512 MiB）。"),
+  autoIndex: z.boolean().default(true).description("导入后与检索前自动增量同步索引。"),
+  webEnabled: z.boolean().default(true).description("是否挂载 /shared-kb 工作台。"),
+});
+
+export { name, inject };
+
+export function apply(ctx, config = {}) {
+  const version = pluginVersion();
+  const log = (message) => {
+    try {
+      ctx.logger?.info?.(`[shared-kb] ${message}`);
+    } catch {
+      /* 日志不可用不应影响功能 */
+    }
+  };
+  const warn = (message) => {
+    try {
+      ctx.logger?.warn?.(`[shared-kb] ${message}`);
+    } catch {
+      /* ignore */
+    }
+  };
+
+  let hub = null;
+  let hubPromise = null;
+  const disposers = [];
+
+  /** 懒创建 hub：第一次真正用到时才连库。 */
+  const getHub = () => {
+    if (hub) return Promise.resolve(hub);
+    if (!hubPromise) {
+      const root = resolveRoot(config.kbRoot ?? "~/.dsh/shared-kb");
+      hubPromise = createHub({
+        root,
+        kbRoot: root,
+        defaultKb: config.defaultKb ?? "default",
+        semanticProvider: config.semanticProvider ?? "auto",
+        semanticModelDir: config.semanticModelDir ?? "",
+        remoteBaseUrl: config.remoteBaseUrl ?? "",
+        remoteApiKey: config.remoteApiKey ?? "",
+        remoteModel: config.remoteModel ?? "",
+        remoteDim: Number(config.remoteDim) || 1024,
+        builtinDim: Number(config.builtinDim) || 512,
+        partChars: Number(config.partChars) || 1200,
+        overlapChars: Number(config.overlapChars) ?? 150,
+        indexCacheRoot: config.indexCacheRoot ? resolveRoot(config.indexCacheRoot) : "",
+        historyKeep: Number(config.historyKeep) || 10,
+        maxImportBytes: Number(config.maxImportBytes) || 512 * 1024 * 1024,
+        autoIndex: config.autoIndex !== false,
+        logger: { warn },
+      })
+        .then((instance) => {
+          hub = instance;
+          log(`已就绪 v${version}，根目录 ${instance.root}，索引 ${instance.indexCacheRoot}`);
+          return instance;
+        })
+        .catch((error) => {
+          hubPromise = null;
+          warn(`初始化失败：${String(error?.message ?? error)}`);
+          throw error;
+        });
+    }
+    return hubPromise;
+  };
+
+  // 工具注册需要一个同步的 hub 句柄：这里给一个代理对象，
+  // 每个方法调用时才 await getHub()，这样工具注册本身不阻塞启动。
+  const lazyHub = new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (prop === "root") return resolveRoot(config.kbRoot ?? "~/.dsh/shared-kb");
+        if (prop === "then") return undefined;
+        return async (...args) => {
+          const instance = await getHub();
+          const fn = instance[prop];
+          if (typeof fn !== "function") throw new Error(`hub 没有方法 ${String(prop)}`);
+          return fn.apply(instance, args);
+        };
+      },
+    }
+  );
+  // 有几个同步属性（providerInfo / indexCacheRoot）在工具里当值用，单独兜住
+  lazyHub.providerInfo = () => (hub ? hub.providerInfo() : { name: "未初始化", dim: 0, kind: "unknown" });
+
+  try {
+    const { count } = registerTools(ctx, { hub: lazyHub, defineTool, config });
+    log(`注册 ${count} 个工具`);
+  } catch (error) {
+    warn(`工具注册失败：${String(error?.message ?? error)}`);
+  }
+
+  // 工作台：宿主提供 webServer 才挂，desktop/headless 不受影响
+  if (config.webEnabled !== false) {
+    try {
+      const dispose = registerWeb(ctx, { hub: lazyHub, getHub, config, version });
+      if (typeof dispose === "function") disposers.push(dispose);
+    } catch (error) {
+      warn(`工作台挂载失败：${String(error?.message ?? error)}`);
+    }
+  }
+
+  // 系统提示：只描述能力边界与使用顺序，不塞长文
+  try {
+    const prompt = [
+      "知识库（dsh-shared-kb）：",
+      `- 物理根目录 ${resolveRoot(config.kbRoot ?? "~/.dsh/shared-kb")}，每个库一个独立子文件夹。`,
+      "- 需要库内资料时：先 skb_query 检索（中文短语直接写；标准号写 GB/T 或 GBT 都行），命中后用 skb_read 精读对应块。",
+      "- 导入资料用 skb_import（支持 pdf/docx/xlsx/pptx/epub/md/txt/csv/html；目录可批量）。内容相同会自动跳过。",
+      "- 沉淀结论用 skb_note（同一标题再次写入=更新，不要另起「续」）。",
+      "- 索引在本机、资料在共享盘：多人多机同时用同一库时，写入靠 rev 号做并发保护；遇到 REV_CONFLICT 表示别人先改了，重新读取后再提交，不要盲目重试。",
+    ].join("\n");
+    ctx.systemPrompt?.section?.({ name: "shared-kb", text: prompt, order: 60 });
+  } catch (error) {
+    // 老版本宿主没有 systemPrompt.section 时静默跳过
+  }
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose();
+      } catch {
+        /* ignore */
+      }
+    }
+    try {
+      hub?.close?.();
+    } catch {
+      /* ignore */
+    }
+  };
+}
+
+export default { name, inject, Config, apply };

package/lib/indexer/embedder.js

@@ -0,0 +1,325 @@
+/**
+ * Embedding provider 抽象。
+ *
+ * 三种实现，按「能自动降级」的顺序尝试：
+ *
+ *  1. builtin  —— 零依赖的本地哈希嵌入（character n-gram + 线性投影）。
+ *                 不是真正语义模型，但对「同一份资料里的相近表述」有稳定的
+ *                 向量表示，可在无任何模型文件时让语义检索链路保持可用，
+ *                 也让索引格式在切换模型后仍然兼容（维度写进 meta）。
+ *  2. onnx     —— onnxruntime-node + @huggingface/tokenizers 加载
+ *                 BGE 类中文模型（可选 peer，未装则跳过）。
+ *  3. remote   —— 走 OpenAI 兼容 /v1/embeddings 接口（用户自备 key）。
+ *
+ * 关键约定：
+ *  - 每个向量都带 provider 名与维度；索引 meta 记录它们，切换 provider 时
+ *    维度或名字变了就整体重建，绝不混用不同模型的向量（混用后相似度没有意义）。
+ *  - 所有向量 L2 归一化后再存，检索用点积即余弦，省一次除法。
+ */
+
+import { createHash } from "node:crypto";
+
+export const BUILTIN_DIM = 512;
+export const BUILTIN_PROVIDER = "builtin-hash-v1";
+
+/** L2 归一化（原地不修改入参）。 */
+export function normalizeVector(vector) {
+  const out = new Float32Array(vector.length);
+  let sum = 0;
+  for (let i = 0; i < vector.length; i += 1) sum += vector[i] * vector[i];
+  const norm = Math.sqrt(sum);
+  if (norm === 0) return out;
+  for (let i = 0; i < vector.length; i += 1) out[i] = vector[i] / norm;
+  return out;
+}
+
+export function dot(a, b) {
+  const n = Math.min(a.length, b.length);
+  let sum = 0;
+  for (let i = 0; i < n; i += 1) sum += a[i] * b[i];
+  return sum;
+}
+
+/**
+ * builtin 嵌入：hash trick + 字符 n-gram。
+ *
+ * 做法：对文本的汉字二元组/英文词做 feature hashing 落到 DIM 维，
+ * 每个特征带符号（正负哈希，抵消碰撞偏置），再按 TF 加权。
+ * 这是经典的 hashing vectorizer，检索里常被用作「零依赖兜底」。
+ */
+export function builtinEmbed(text, { dim = BUILTIN_DIM } = {}) {
+  const vector = new Float32Array(dim);
+  const source = String(text ?? "").normalize("NFKC").toLowerCase();
+  if (source.trim() === "") return vector;
+
+  const bump = (feature, weight) => {
+    const hash = createHash("sha1").update(feature, "utf8").digest();
+    const idx = (hash[0] | (hash[1] << 8) | (hash[2] << 16)) % dim;
+    const sign = (hash[3] & 1) === 0 ? 1 : -1;
+    vector[idx] += sign * weight;
+  };
+
+  // 汉字 2-gram / 3-gram
+  const cjkRuns = source.match(/[\u3400-\u4dbf\u4e00-\u9fff]+/g) ?? [];
+  for (const run of cjkRuns) {
+    for (let i = 0; i + 1 < run.length; i += 1) bump(run.slice(i, i + 2), 1);
+    for (let i = 0; i + 2 < run.length; i += 2) bump(run.slice(i, i + 3), 0.6);
+    if (run.length === 1) bump(run, 1.2);
+  }
+  // 英文/数字词
+  for (const word of source.match(/[a-z][a-z0-9_-]{1,30}/g) ?? []) bump(`w:${word}`, 1);
+  for (const num of source.match(/\d+(?:\.\d+)*/g) ?? []) bump(`n:${num}`, 1.2);
+
+  return normalizeVector(vector);
+}
+
+/** provider 工厂：返回 { name, dim, embed(texts) } */
+export function createBuiltinProvider({ dim = BUILTIN_DIM } = {}) {
+  return {
+    name: `${BUILTIN_PROVIDER}`,
+    dim,
+    kind: "builtin",
+    async embed(texts) {
+      return (Array.isArray(texts) ? texts : [texts]).map((text) => builtinEmbed(text, { dim }));
+    },
+    async probe() {
+      return { ok: true, provider: BUILTIN_PROVIDER, dim };
+    },
+  };
+}
+
+export const DEFAULT_MODEL_DIR = "";
+export const ONNX_MODEL_NAME = "BAAI/bge-small-zh-v1.5";
+export const ONNX_DIM = 512;
+export const MAX_TOKENS = 512;
+/** 查询侧指令（BGE 系列要求；文档侧不加）。 */
+export const QUERY_PREFIX = "为这个句子生成表示以用于检索相关文章：";
+
+/**
+ * ONNX 运行时：懒加载，模型或依赖缺失就返回 { available:false, reason }。
+ * 与 dsh-knowledge-wiki 的做法一致（同源模型、同源池化），但独立实现，
+ * 因为它要能被单独测试（注入假 session），且不假设插件目录结构。
+ */
+export function createOnnxProvider({
+  modelDir = "",
+  loadModule = (spec) => import(spec),
+  readFileFn = null,
+  logger = null,
+  dim = ONNX_DIM,
+} = {}) {
+  let sessionPromise = null;
+  let tokenizerPromise = null;
+  let warned = false;
+
+  const warnOnce = (message) => {
+    if (warned) return;
+    warned = true;
+    try {
+      logger?.warn?.(message);
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const init = async () => {
+    if (!modelDir) throw new Error("未配置语义模型目录");
+    const fs = readFileFn ?? (await import("node:fs/promises")).readFile;
+    const { join } = await import("node:path");
+    const ort = await loadModule("onnxruntime-node");
+    const { Tokenizer } = await loadModule("@huggingface/tokenizers");
+    const modelPath = join(modelDir, "model.onnx");
+    const tokenizerPath = join(modelDir, "tokenizer.json");
+    const session = await ort.InferenceSession.create(modelPath, {
+      executionProviders: ["cpu"],
+      graphOptimizationLevel: "all",
+    });
+    const tokenizerJson = JSON.parse(await fs(tokenizerPath, "utf8"));
+    const tokenizer = new Tokenizer(tokenizerJson, JSON.parse(await fs(join(modelDir, "tokenizer_config.json"), "utf8").catch(() => "{}")));
+    return { ort, session, tokenizer };
+  };
+
+  const get = () => {
+    if (!sessionPromise) {
+      sessionPromise = init().catch((error) => {
+        sessionPromise = null;
+        throw error;
+      });
+    }
+    return sessionPromise;
+  };
+
+  const embedBatch = async (texts, withPrefix) => {
+    const { ort, session, tokenizer } = await get();
+    const list = (Array.isArray(texts) ? texts : [texts]).map((t) =>
+      withPrefix ? QUERY_PREFIX + String(t ?? "") : String(t ?? "")
+    );
+    const out = [];
+    const BATCH = 8;
+    for (let i = 0; i < list.length; i += BATCH) {
+      const slice = list.slice(i, i + BATCH);
+      const encoded = slice.map((text) => tokenizer.encode(text).getIds().slice(0, MAX_TOKENS));
+      const width = Math.max(...encoded.map((ids) => ids.length));
+      const ids = new BigInt64Array(slice.length * width);
+      const mask = new BigInt64Array(slice.length * width);
+      const types = new BigInt64Array(slice.length * width);
+      for (let r = 0; r < encoded.length; r += 1) {
+        for (let c = 0; c < width; c += 1) {
+          const value = encoded[r][c] ?? 0;
+          ids[r * width + c] = BigInt(value);
+          mask[r * width + c] = c < encoded[r].length ? 1n : 0n;
+          types[r * width + c] = 0n;
+        }
+      }
+      const feeds = {
+        input_ids: new ort.Tensor("int64", ids, [slice.length, width]),
+        attention_mask: new ort.Tensor("int64", mask, [slice.length, width]),
+        token_type_ids: new ort.Tensor("int64", types, [slice.length, width]),
+      };
+      const result = await session.run(feeds);
+      const hidden = result.last_hidden_state ?? Object.values(result)[0];
+      const [, seq, hiddenDim] = hidden.dims;
+      for (let r = 0; r < slice.length; r += 1) {
+        const vector = new Float32Array(hiddenDim);
+        // CLS 池化：第 0 个 token
+        for (let h = 0; h < hiddenDim; h += 1) vector[h] = hidden.data[r * seq * hiddenDim + h];
+        out.push(normalizeVector(vector));
+      }
+    }
+    return out;
+  };
+
+  return {
+    name: `onnx:${ONNX_MODEL_NAME}`,
+    kind: "onnx",
+    dim,
+    async embed(texts) {
+      return embedBatch(texts, false);
+    },
+    async embedQuery(text) {
+      return (await embedBatch([text], true))[0];
+    },
+    async probe() {
+      try {
+        const v = await embedBatch(["探针"], false);
+        return { ok: true, provider: `onnx:${ONNX_MODEL_NAME}`, dim: v[0]?.length ?? 0 };
+      } catch (error) {
+        warnOnce(`语义模型不可用，已降级：${String(error?.message ?? error)}`);
+        return { ok: false, reason: String(error?.message ?? error) };
+      }
+    },
+  };
+}
+
+/**
+ * 远端 provider：OpenAI 兼容 /v1/embeddings。
+ * 批量请求 + 失败不重试（重试交给上层，避免雪崩）。
+ */
+export function createRemoteProvider({
+  baseUrl,
+  apiKey,
+  model,
+  dim = 1024,
+  fetchImpl = globalThis.fetch,
+  batchSize = 32,
+  timeoutMs = 30_000,
+} = {}) {
+  if (!baseUrl) throw new Error("远端 embedding 需要 baseUrl");
+  if (!model) throw new Error("远端 embedding 需要 model");
+  const endpoint = String(baseUrl).replace(/\/+$/, "") + "/embeddings";
+
+  const call = async (input) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body: JSON.stringify({ model, input }),
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`embedding 接口返回 ${response.status}：${text.slice(0, 300)}`);
+      }
+      const payload = await response.json();
+      const rows = Array.isArray(payload?.data) ? payload.data : [];
+      if (rows.length !== input.length) {
+        throw new Error(`embedding 返回条数不匹配：期望 ${input.length}，实际 ${rows.length}`);
+      }
+      return rows
+        .sort((a, b) => Number(a.index) - Number(b.index))
+        .map((row) => normalizeVector(Float32Array.from(row.embedding ?? [])));
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  return {
+    name: `remote:${model}`,
+    kind: "remote",
+    dim,
+    async embed(texts) {
+      const list = (Array.isArray(texts) ? texts : [texts]).map((t) => String(t ?? ""));
+      const out = [];
+      for (let i = 0; i < list.length; i += batchSize) {
+        out.push(...(await call(list.slice(i, i + batchSize))));
+      }
+      return out;
+    },
+    async probe() {
+      try {
+        const v = await call(["探针"]);
+        return { ok: true, provider: `remote:${model}`, dim: v[0]?.length ?? 0 };
+      } catch (error) {
+        return { ok: false, reason: String(error?.message ?? error) };
+      }
+    },
+  };
+}
+
+/**
+ * 按配置选 provider，并在首选不可用时降级到 builtin。
+ * 降级必须写进返回值，让上层能如实报告「现在用的是兜底嵌入」。
+ */
+export async function resolveProvider(config = {}) {
+  const mode = String(config.semanticProvider ?? "auto").toLowerCase();
+  const notes = [];
+
+  const tryProvider = async (provider) => {
+    const probe = await provider.probe();
+    if (probe.ok) return { provider, probe, notes };
+    notes.push(`${provider.name}: ${probe.reason}`);
+    return null;
+  };
+
+  if (mode === "remote") {
+    const provider = createRemoteProvider({
+      baseUrl: config.remoteBaseUrl,
+      apiKey: config.remoteApiKey,
+      model: config.remoteModel,
+      dim: Number(config.remoteDim) || 1024,
+    });
+    const ok = await tryProvider(provider);
+    if (ok) return ok;
+  }
+
+  if (mode === "onnx" || mode === "auto") {
+    const provider = createOnnxProvider({
+      modelDir: config.semanticModelDir,
+      logger: config.logger,
+    });
+    const ok = await tryProvider(provider);
+    if (ok) return ok;
+    if (mode === "onnx") {
+      // 显式要求 onnx 但不可用：仍然降级，但把原因记清楚
+      notes.push("显式要求 onnx 但不可用，已降级为 builtin");
+    }
+  }
+
+  const builtin = createBuiltinProvider({ dim: Number(config.builtinDim) || BUILTIN_DIM });
+  const ok = await tryProvider(builtin);
+  return ok ?? { provider: builtin, probe: { ok: true, provider: builtin.name, dim: builtin.dim }, notes };
+}