@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.2

package/lib/vector-index.js

@@ -1,180 +1,180 @@
-// Thin vector-index layer over the store's embedding column. Keeps the
-// current model fingerprint + stats in a dedicated `vector_meta` table so the
-// index can detect drift (embeddings generated by a different model) and the
-// Web panel can report index health. The heavy lifting (cosine search) lives
-// in store.searchVector; this module owns the index lifecycle.
-
-const META_SCHEMA = `
-CREATE TABLE IF NOT EXISTS vector_meta (
-  key        TEXT PRIMARY KEY,
-  value      TEXT NOT NULL
-);
-`;
-
-export function createVectorIndex({ store, logger }) {
-  const db = store.db;
-  db.exec(META_SCHEMA);
-
-  function getMeta(key) {
-    const row = db.prepare("SELECT value FROM vector_meta WHERE key = ?").get(key);
-    return row?.value ?? undefined;
-  }
-
-  function setMeta(key, value) {
-    db.prepare(
-      `INSERT INTO vector_meta (key, value) VALUES (?, ?)
-       ON CONFLICT(key) DO UPDATE SET value = excluded.value`
-    ).run(key, String(value));
-  }
-
-  return {
-    /** Record the model that generated the current vectors. */
-    markModel(modelHash, dimension) {
-      setMeta("model_hash", modelHash);
-      setMeta("dimension", String(dimension ?? ""));
-      setMeta("updated_at", new Date().toISOString());
-    },
-
-    modelHash() {
-      return getMeta("model_hash");
-    },
-
-    dimension() {
-      const raw = getMeta("dimension");
-      return raw && Number.isInteger(Number(raw)) ? Number(raw) : undefined;
-    },
-
-    /** Store (or clear with null vector) one memory's embedding. */
-    saveEmbedding(id, vector) {
-      store.setEmbedding(id, vector);
-    },
-
-    /** Drop one memory's embedding. */
-    deleteEmbedding(id) {
-      store.setEmbedding(id, null);
-    },
-
-    /** Read one memory's cached vector; undefined when none/parse failure. */
-    getEmbedding(id) {
-      // Issue #202：走 store 的解析缓存（与 searchVector/getEmbeddings 同源）。
-      return store.getParsedEmbedding(id);
-    },
-
-    /** Cosine search over embedded rows; results carry a 0..1 score. */
-    search(queryVector, { limit = 20, threshold = 0.65 } = {}) {
-      return store.searchVector(queryVector, { limit, threshold });
-    },
-
-    /**
-     * Re-embed every row whose vector is missing OR came from another model.
-     *
-     * Returns { indexed, failed, skipped, remaining, error? } — three distinct
-     * outcomes instead of one `skipped` bucket that meant "failed", "threw" and
-     * "did not fit in the limit" all at once. #604.
-     */
-    async rebuildIndex(embedder, { limit = 1000 } = {}) {
-      // The loop needs a single-text embedder. Native embedSingle is preferred;
-      // embed-only OpenAI-compatible clients (issue #10) are accepted too via
-      // their `embed` single-text interface, so /vector-reindex no longer
-      // silently returns 0 for them. An embedder exposing neither is ignored.
-      // #604: prefer the detailed entry point when the embedder has one. The
-      // legacy OpenAI-compatible client drops the failure reason on its normal
-      // path (embedText returns only the vector), so a provider outage and an
-      // unembeddable row both surfaced here as a bare null. The reason is what
-      // tells them apart, and the operator needs it to know whether pressing
-      // the button again is worth anything.
-      let embedOne = null;
-      let embedOneDetailed = null;
-      if (embedder && typeof embedder.embedSingleDetailed === "function") {
-        embedOneDetailed = (text) => embedder.embedSingleDetailed(text);
-      }
-      if (embedder && typeof embedder.embedSingle === "function") {
-        embedOne = (text) => embedder.embedSingle(text);
-      } else if (embedder && typeof embedder.embed === "function") {
-        embedOne = (text) => Promise.resolve(embedder.embed(text));
-      }
-      if (!embedOne && !embedOneDetailed) {
-        return { indexed: 0, failed: 0, skipped: 0, remaining: 0, error: "no-embedder" };
-      }
-      const model = embedder?.modelHash ?? null;
-      // #604: this used to call needsEmbedding(), which only matches empty
-      // vectors. After a model switch every row already has a vector — from the
-      // previous model — so "reindex" selected nothing, embedded nothing, and
-      // reported {indexed: 0, skipped: 0} as if the index were already current.
-      // The boot sweep has always used the model-aware selector; using the same
-      // one here is what makes the button mean what it says.
-      const rows = model && typeof store.needsEmbeddingFor === "function"
-        ? store.needsEmbeddingFor(model, limit)
-        : store.needsEmbedding(limit);
-      let indexed = 0;
-      let failed = 0;
-      const failureReasons = {};
-      const noteFailure = (reason) => {
-        failureReasons[reason] = (failureReasons[reason] ?? 0) + 1;
-      };
-      for (const row of rows) {
-        try {
-          const text = [row.title, row.content].filter(Boolean).join("\n");
-          let vector;
-          if (embedOneDetailed) {
-            const detailed = await embedOneDetailed(text);
-            vector = detailed ? detailed.vector : null;
-            if (!vector && detailed?.reason) noteFailure(`error:${detailed.reason}`);
-          } else {
-            vector = await embedOne(text);
-          }
-          if (vector && vector.length) {
-            // #604: the model fingerprint was omitted here, so every rebuilt
-            // row kept embedding_model NULL. needsEmbeddingFor() then treated
-            // it as stale forever: the boot sweep re-embedded it on each start,
-            // the panel counted it as unsearchable, and pressing reindex again
-            // found nothing (the vector was no longer empty). Passing the
-            // fingerprint closes the loop between the write and the selector.
-            store.setEmbedding(row.id, vector, model ?? undefined);
-            indexed++;
-          } else {
-            failed++;
-            // A detailed adapter already recorded why; the plain path has no
-            // reason to record, so name the only thing it can mean.
-            if (!embedOneDetailed) noteFailure("empty-vector");
-            logger?.warn?.(`[dsh-mneme] rebuild produced no vector for ${row.id}`);
-          }
-        } catch (error) {
-          failed++;
-          noteFailure(`error:${String(error)}`);
-          logger?.warn?.(`[dsh-mneme] rebuild embed failed for ${row.id}: ${String(error)}`);
-        }
-      }
-      if (indexed > 0 && embedder.modelHash) this.markModel(embedder.modelHash, embedder.dimension);
-      // remaining = still selected by the same predicate after this run. Rows
-      // that failed stay in it (they were never written), which is exactly the
-      // number the caller needs to decide whether to run again.
-      const remaining = typeof store.countNeedsEmbeddingFor === "function"
-        ? store.countNeedsEmbeddingFor(model)
-        : null;
-      // `skipped` is 0 by definition here, not as a placeholder: every row the
-      // selector returned is attempted in the loop above, so nothing is left
-      // untouched. Rows that produced no vector are `failed`. The remaining
-      // bucket is the selector's own count, which is why a row can be both
-      // failed and remaining — it was tried and it is still stale.
-      //
-      // `failureReasons` mirrors the boot sweep's bucket names so the two paths
-      // read the same: `empty-vector` means this row will never embed, while an
-      // `error:` bucket means the provider or the store failed and the same
-      // press may well succeed next time. A run that only ever reports
-      // empty-vector is not a retry candidate.
-      return { indexed, failed, skipped: 0, remaining, failureReasons };
-    },
-
-    /** Index stats for the Web panel / debugging. */
-    getStats() {
-      return {
-        modelHash: getMeta("model_hash"),
-        dimension: this.dimension(),
-        updatedAt: getMeta("updated_at"),
-        embeddedCount: store.embeddedCount(),
-        totalCount: store.count()
-      };
-    }
-  };
-}
+// Thin vector-index layer over the store's embedding column. Keeps the
+// current model fingerprint + stats in a dedicated `vector_meta` table so the
+// index can detect drift (embeddings generated by a different model) and the
+// Web panel can report index health. The heavy lifting (cosine search) lives
+// in store.searchVector; this module owns the index lifecycle.
+
+const META_SCHEMA = `
+CREATE TABLE IF NOT EXISTS vector_meta (
+  key        TEXT PRIMARY KEY,
+  value      TEXT NOT NULL
+);
+`;
+
+export function createVectorIndex({ store, logger }) {
+  const db = store.db;
+  db.exec(META_SCHEMA);
+
+  function getMeta(key) {
+    const row = db.prepare("SELECT value FROM vector_meta WHERE key = ?").get(key);
+    return row?.value ?? undefined;
+  }
+
+  function setMeta(key, value) {
+    db.prepare(
+      `INSERT INTO vector_meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+    ).run(key, String(value));
+  }
+
+  return {
+    /** Record the model that generated the current vectors. */
+    markModel(modelHash, dimension) {
+      setMeta("model_hash", modelHash);
+      setMeta("dimension", String(dimension ?? ""));
+      setMeta("updated_at", new Date().toISOString());
+    },
+
+    modelHash() {
+      return getMeta("model_hash");
+    },
+
+    dimension() {
+      const raw = getMeta("dimension");
+      return raw && Number.isInteger(Number(raw)) ? Number(raw) : undefined;
+    },
+
+    /** Store (or clear with null vector) one memory's embedding. */
+    saveEmbedding(id, vector) {
+      store.setEmbedding(id, vector);
+    },
+
+    /** Drop one memory's embedding. */
+    deleteEmbedding(id) {
+      store.setEmbedding(id, null);
+    },
+
+    /** Read one memory's cached vector; undefined when none/parse failure. */
+    getEmbedding(id) {
+      // Issue #202：走 store 的解析缓存（与 searchVector/getEmbeddings 同源）。
+      return store.getParsedEmbedding(id);
+    },
+
+    /** Cosine search over embedded rows; results carry a 0..1 score. */
+    search(queryVector, { limit = 20, threshold = 0.65 } = {}) {
+      return store.searchVector(queryVector, { limit, threshold });
+    },
+
+    /**
+     * Re-embed every row whose vector is missing OR came from another model.
+     *
+     * Returns { indexed, failed, skipped, remaining, error? } — three distinct
+     * outcomes instead of one `skipped` bucket that meant "failed", "threw" and
+     * "did not fit in the limit" all at once. #604.
+     */
+    async rebuildIndex(embedder, { limit = 1000 } = {}) {
+      // The loop needs a single-text embedder. Native embedSingle is preferred;
+      // embed-only OpenAI-compatible clients (issue #10) are accepted too via
+      // their `embed` single-text interface, so /vector-reindex no longer
+      // silently returns 0 for them. An embedder exposing neither is ignored.
+      // #604: prefer the detailed entry point when the embedder has one. The
+      // legacy OpenAI-compatible client drops the failure reason on its normal
+      // path (embedText returns only the vector), so a provider outage and an
+      // unembeddable row both surfaced here as a bare null. The reason is what
+      // tells them apart, and the operator needs it to know whether pressing
+      // the button again is worth anything.
+      let embedOne = null;
+      let embedOneDetailed = null;
+      if (embedder && typeof embedder.embedSingleDetailed === "function") {
+        embedOneDetailed = (text) => embedder.embedSingleDetailed(text);
+      }
+      if (embedder && typeof embedder.embedSingle === "function") {
+        embedOne = (text) => embedder.embedSingle(text);
+      } else if (embedder && typeof embedder.embed === "function") {
+        embedOne = (text) => Promise.resolve(embedder.embed(text));
+      }
+      if (!embedOne && !embedOneDetailed) {
+        return { indexed: 0, failed: 0, skipped: 0, remaining: 0, error: "no-embedder" };
+      }
+      const model = embedder?.modelHash ?? null;
+      // #604: this used to call needsEmbedding(), which only matches empty
+      // vectors. After a model switch every row already has a vector — from the
+      // previous model — so "reindex" selected nothing, embedded nothing, and
+      // reported {indexed: 0, skipped: 0} as if the index were already current.
+      // The boot sweep has always used the model-aware selector; using the same
+      // one here is what makes the button mean what it says.
+      const rows = model && typeof store.needsEmbeddingFor === "function"
+        ? store.needsEmbeddingFor(model, limit)
+        : store.needsEmbedding(limit);
+      let indexed = 0;
+      let failed = 0;
+      const failureReasons = {};
+      const noteFailure = (reason) => {
+        failureReasons[reason] = (failureReasons[reason] ?? 0) + 1;
+      };
+      for (const row of rows) {
+        try {
+          const text = [row.title, row.content].filter(Boolean).join("\n");
+          let vector;
+          if (embedOneDetailed) {
+            const detailed = await embedOneDetailed(text);
+            vector = detailed ? detailed.vector : null;
+            if (!vector && detailed?.reason) noteFailure(`error:${detailed.reason}`);
+          } else {
+            vector = await embedOne(text);
+          }
+          if (vector && vector.length) {
+            // #604: the model fingerprint was omitted here, so every rebuilt
+            // row kept embedding_model NULL. needsEmbeddingFor() then treated
+            // it as stale forever: the boot sweep re-embedded it on each start,
+            // the panel counted it as unsearchable, and pressing reindex again
+            // found nothing (the vector was no longer empty). Passing the
+            // fingerprint closes the loop between the write and the selector.
+            store.setEmbedding(row.id, vector, model ?? undefined);
+            indexed++;
+          } else {
+            failed++;
+            // A detailed adapter already recorded why; the plain path has no
+            // reason to record, so name the only thing it can mean.
+            if (!embedOneDetailed) noteFailure("empty-vector");
+            logger?.warn?.(`[dsh-mneme] rebuild produced no vector for ${row.id}`);
+          }
+        } catch (error) {
+          failed++;
+          noteFailure(`error:${String(error)}`);
+          logger?.warn?.(`[dsh-mneme] rebuild embed failed for ${row.id}: ${String(error)}`);
+        }
+      }
+      if (indexed > 0 && embedder.modelHash) this.markModel(embedder.modelHash, embedder.dimension);
+      // remaining = still selected by the same predicate after this run. Rows
+      // that failed stay in it (they were never written), which is exactly the
+      // number the caller needs to decide whether to run again.
+      const remaining = typeof store.countNeedsEmbeddingFor === "function"
+        ? store.countNeedsEmbeddingFor(model)
+        : null;
+      // `skipped` is 0 by definition here, not as a placeholder: every row the
+      // selector returned is attempted in the loop above, so nothing is left
+      // untouched. Rows that produced no vector are `failed`. The remaining
+      // bucket is the selector's own count, which is why a row can be both
+      // failed and remaining — it was tried and it is still stale.
+      //
+      // `failureReasons` mirrors the boot sweep's bucket names so the two paths
+      // read the same: `empty-vector` means this row will never embed, while an
+      // `error:` bucket means the provider or the store failed and the same
+      // press may well succeed next time. A run that only ever reports
+      // empty-vector is not a retry candidate.
+      return { indexed, failed, skipped: 0, remaining, failureReasons };
+    },
+
+    /** Index stats for the Web panel / debugging. */
+    getStats() {
+      return {
+        modelHash: getMeta("model_hash"),
+        dimension: this.dimension(),
+        updatedAt: getMeta("updated_at"),
+        embeddedCount: store.embeddedCount(),
+        totalCount: store.count()
+      };
+    }
+  };
+}

package/lib/version-check.js

@@ -1,122 +1,122 @@
-// 版本自检（issue #174 后续，2026-09-15 拍板）：独立插件不把「用户在用哪个
-// 版本」托付给插件市场——市场收录有 ~26h 年龄闸门 + 30min 缓存，且安装时
-// 精确指定过版本的 profile 会被 pnpm 钉子挡住（update 尊重既有 semver 范围，
-// 永不跨 minor/major，#174 的报障者正是这样用着 0.7.32 的行为模型来报 bug）。
-//
-// 本模块只做三件事：
-//   1. 向 npm registry 查 @modusensus/dsh-mneme 的 latest dist-tag（带 TTL
-//      缓存 + 超时 + 全失败静默——离线/被墙/registry 异常都返回 null，调用方
-//      据 null 渲染「未知」，前端不打扰）；
-//   2. 与运行版本做纯函数比对（classify）；
-//   3. 对外暴露 registry URL 白名单校验（validateRegistryUrl）——发请求前
-//      强制 https + 精确 host，构造上排除本机与内网地址。
-import { readFileSync } from "node:fs";
-
-// 运行版本：src/ 与 lib/ 都在插件根下一层，相对 import.meta.url 解析一致；
-// 读取失败（打包/受限环境）降级 "unknown"，横幅随之静默。
-const PACKAGE_VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-})();
-
-// registry 查询地址是模块常量而非用户输入；validateRegistryUrl 仍作为发请求
-// 前的强制闸（构造上即排除非 https 与非白名单 host，双保险且可单测）。
-const REGISTRY_URL = "https://registry.npmjs.org/@modusensus%2Fdsh-mneme/latest";
-const REGISTRY_HOST = "registry.npmjs.org";
-// 市场收录本身有 ~1 天年龄闸门，1h 的 registry 缓存远低于该粒度，足够新鲜。
-const CACHE_TTL_MS = 60 * 60 * 1000;
-const FETCH_TIMEOUT_MS = 5000;
-
-// 精确 host 白名单：协议必须 https，且 host 逐字等于 registry.npmjs.org。
-// 这一条即构造性排除本机回环、私有网段与保留地址——不做任何
-// 「看起来像公网」的宽松判断，将来换源必须显式改这里的常量。
-export function validateRegistryUrl(candidate) {
-  let url;
-  try {
-    url = new URL(candidate);
-  } catch {
-    return false;
-  }
-  return url.protocol === "https:" && url.hostname === REGISTRY_HOST;
-}
-
-/** 解析 `x.y.z` / `x.y.z-后缀` 为可比较结构；解析失败返回 null。 */
-function parseVersion(text) {
-  if (typeof text !== "string") return null;
-  const match = text.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-  if (!match) return null;
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    // 有 prerelease 后缀的同号版本视为更旧（0.9.0-rc.1 < 0.9.0）。
-    prerelease: match[4] !== undefined
-  };
-}
-
-/**
- * 三元组语义化比较：a<b → -1，a>b → 1，无法比较 → null（调用方归入 unknown）。
- * 仅比较数字部分；数字相等时，带 prerelease 的一方更旧（0.9.0-rc.1 < 0.9.0），
- * 两侧都带则视为同版——横幅只关心「是否落后于 latest」，不追求完整 semver 序。
- */
-export function compareVersions(a, b) {
-  const va = parseVersion(a);
-  const vb = parseVersion(b);
-  if (!va || !vb) return null;
-  for (const key of ["major", "minor", "patch"]) {
-    if (va[key] !== vb[key]) return va[key] < vb[key] ? -1 : 1;
-  }
-  if (va.prerelease !== vb.prerelease) return va.prerelease ? -1 : 1;
-  return 0;
-}
-
-/**
- * 运行版本 vs registry latest 的展示归类。latest 为 null（查询失败/离线）
- * 或任一侧解析失败时归 unknown——前端对 unknown 完全静默。
- */
-export function classify(version, latest) {
-  const cmp = compareVersions(version, latest);
-  if (cmp === null) return "unknown";
-  if (cmp < 0) return "outdated";
-  if (cmp > 0) return "ahead";
-  return "up-to-date";
-}
-
-// 模块级缓存：面板可能多处/多次拉取，TTL 内一律复用，不重复打 registry。
-// at 用 -Infinity 作「从未拉取」哨兵：任何时钟下 now-at 都是正无穷，首轮
-// 必然真实请求（测试的假时钟从 0 起也不会被误判成新鲜缓存）。
-let cache = { at: -Infinity, latest: null };
-
-/**
- * 查询 registry latest。TTL 内直接命中缓存；任何失败（网络/超时/非 2xx/
- * 响应形状不对/URL 校验不过）都静默返回 null——版本提示是锦上添花，绝不
- * 让它成为新的故障面。失败不写缓存：TTL 起点保持旧值，下次调用立刻重试。
- */
-export async function fetchLatestVersion({ fetchImpl = typeof fetch === "function" ? fetch : () => Promise.reject(new Error("no fetch")), now = Date.now } = {}) {
-  if (now() - cache.at < CACHE_TTL_MS) return cache.latest;
-  if (!validateRegistryUrl(REGISTRY_URL)) return null;
-  let manifest;
-  try {
-    const response = await fetchImpl(REGISTRY_URL, {
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-      headers: { accept: "application/json" }
-    });
-    if (!response.ok) return null;
-    manifest = await response.json();
-  } catch {
-    return null;
-  }
-  const latest = typeof manifest?.version === "string" && manifest.version ? manifest.version : null;
-  cache = { at: now(), latest };
-  return latest;
-}
-
-/** 仅供测试：清空模块级缓存与时间戳。 */
-export function resetCacheForTest() {
-  cache = { at: -Infinity, latest: null };
-}
-
-export { PACKAGE_VERSION, REGISTRY_URL, CACHE_TTL_MS };
+// 版本自检（issue #174 后续，2026-09-15 拍板）：独立插件不把「用户在用哪个
+// 版本」托付给插件市场——市场收录有 ~26h 年龄闸门 + 30min 缓存，且安装时
+// 精确指定过版本的 profile 会被 pnpm 钉子挡住（update 尊重既有 semver 范围，
+// 永不跨 minor/major，#174 的报障者正是这样用着 0.7.32 的行为模型来报 bug）。
+//
+// 本模块只做三件事：
+//   1. 向 npm registry 查 @modusensus/dsh-mneme 的 latest dist-tag（带 TTL
+//      缓存 + 超时 + 全失败静默——离线/被墙/registry 异常都返回 null，调用方
+//      据 null 渲染「未知」，前端不打扰）；
+//   2. 与运行版本做纯函数比对（classify）；
+//   3. 对外暴露 registry URL 白名单校验（validateRegistryUrl）——发请求前
+//      强制 https + 精确 host，构造上排除本机与内网地址。
+import { readFileSync } from "node:fs";
+
+// 运行版本：src/ 与 lib/ 都在插件根下一层，相对 import.meta.url 解析一致；
+// 读取失败（打包/受限环境）降级 "unknown"，横幅随之静默。
+const PACKAGE_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+})();
+
+// registry 查询地址是模块常量而非用户输入；validateRegistryUrl 仍作为发请求
+// 前的强制闸（构造上即排除非 https 与非白名单 host，双保险且可单测）。
+const REGISTRY_URL = "https://registry.npmjs.org/@modusensus%2Fdsh-mneme/latest";
+const REGISTRY_HOST = "registry.npmjs.org";
+// 市场收录本身有 ~1 天年龄闸门，1h 的 registry 缓存远低于该粒度，足够新鲜。
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+
+// 精确 host 白名单：协议必须 https，且 host 逐字等于 registry.npmjs.org。
+// 这一条即构造性排除本机回环、私有网段与保留地址——不做任何
+// 「看起来像公网」的宽松判断，将来换源必须显式改这里的常量。
+export function validateRegistryUrl(candidate) {
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    return false;
+  }
+  return url.protocol === "https:" && url.hostname === REGISTRY_HOST;
+}
+
+/** 解析 `x.y.z` / `x.y.z-后缀` 为可比较结构；解析失败返回 null。 */
+function parseVersion(text) {
+  if (typeof text !== "string") return null;
+  const match = text.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    // 有 prerelease 后缀的同号版本视为更旧（0.9.0-rc.1 < 0.9.0）。
+    prerelease: match[4] !== undefined
+  };
+}
+
+/**
+ * 三元组语义化比较：a<b → -1，a>b → 1，无法比较 → null（调用方归入 unknown）。
+ * 仅比较数字部分；数字相等时，带 prerelease 的一方更旧（0.9.0-rc.1 < 0.9.0），
+ * 两侧都带则视为同版——横幅只关心「是否落后于 latest」，不追求完整 semver 序。
+ */
+export function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) return null;
+  for (const key of ["major", "minor", "patch"]) {
+    if (va[key] !== vb[key]) return va[key] < vb[key] ? -1 : 1;
+  }
+  if (va.prerelease !== vb.prerelease) return va.prerelease ? -1 : 1;
+  return 0;
+}
+
+/**
+ * 运行版本 vs registry latest 的展示归类。latest 为 null（查询失败/离线）
+ * 或任一侧解析失败时归 unknown——前端对 unknown 完全静默。
+ */
+export function classify(version, latest) {
+  const cmp = compareVersions(version, latest);
+  if (cmp === null) return "unknown";
+  if (cmp < 0) return "outdated";
+  if (cmp > 0) return "ahead";
+  return "up-to-date";
+}
+
+// 模块级缓存：面板可能多处/多次拉取，TTL 内一律复用，不重复打 registry。
+// at 用 -Infinity 作「从未拉取」哨兵：任何时钟下 now-at 都是正无穷，首轮
+// 必然真实请求（测试的假时钟从 0 起也不会被误判成新鲜缓存）。
+let cache = { at: -Infinity, latest: null };
+
+/**
+ * 查询 registry latest。TTL 内直接命中缓存；任何失败（网络/超时/非 2xx/
+ * 响应形状不对/URL 校验不过）都静默返回 null——版本提示是锦上添花，绝不
+ * 让它成为新的故障面。失败不写缓存：TTL 起点保持旧值，下次调用立刻重试。
+ */
+export async function fetchLatestVersion({ fetchImpl = typeof fetch === "function" ? fetch : () => Promise.reject(new Error("no fetch")), now = Date.now } = {}) {
+  if (now() - cache.at < CACHE_TTL_MS) return cache.latest;
+  if (!validateRegistryUrl(REGISTRY_URL)) return null;
+  let manifest;
+  try {
+    const response = await fetchImpl(REGISTRY_URL, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: "application/json" }
+    });
+    if (!response.ok) return null;
+    manifest = await response.json();
+  } catch {
+    return null;
+  }
+  const latest = typeof manifest?.version === "string" && manifest.version ? manifest.version : null;
+  cache = { at: now(), latest };
+  return latest;
+}
+
+/** 仅供测试：清空模块级缓存与时间戳。 */
+export function resetCacheForTest() {
+  cache = { at: -Infinity, latest: null };
+}
+
+export { PACKAGE_VERSION, REGISTRY_URL, CACHE_TTL_MS };