magicrew-auth 0.0.0-stage → 0.3.6

package/src/key-store.mjs

@@ -0,0 +1,188 @@
+// 每个账号一把活的 key —— A/B 双槽
+//
+// ═══ 两条不能破的线 ═══════════════════════════════════════════════════
+//
+// ① **按账号隔离**：同一个站点可以登多个账号（magpie 里就是 `magicrew` /
+//    `magicrew#1` / …）。key 必须一个账号一份，否则第二个账号登录时
+//    会把第一个账号的 key 覆盖掉，第一个账号从此 403。
+//    账户标识用 `org`（组织码，登录后固定不变），拿不到才退回 accountId。
+//
+// ② **每个账号至少有一把活的**：一个账号存两槽（a / b）。
+//    · 续期时把新的签到**另一个槽**再切过去，旧的留着 —— 中途出错还能切回来
+//    · 当前这把被上游拒了（403）就切到另一槽
+//    · 两槽都空时从 magpie 存的凭据接管一次
+//
+// 实测（2026-10-27）：同一账号的两把 `mgw_` key 可以同时有效，所以双槽是安全的；
+// 一把 key 也能并发（6 个并发请求全成功），不需要"闲置池"。
+//
+// ⚠ 全插件只有这个文件是 key 的来源。magpie 的 `auth.refresh` 和 loader 都走
+//   src/keys.mjs，不各自签发 —— 否则本地会分叉，说不清手里那把是不是服务端认的。
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from "node:fs"
+import { homedir } from "node:os"
+import { join, dirname } from "node:path"
+
+/** 提前多久续期。key 只活 2 小时，10 分钟够用 */
+const LEAD_MS = 10 * 60_000
+
+/** 只接受看起来像真的 key —— 测试/占位值不许落盘 */
+const REAL_KEY = /^mgw_[A-Za-z0-9_-]{20,}$/
+
+/** 账号标识净化：只留安全字符，空值给 default */
+export function safeAccount(account) {
+  const s = String(account || "").replace(/[^A-Za-z0-9_-]/g, "")
+  return s || "default"
+}
+
+/** 一个账号一份文件 */
+export function keyPath(siteId, account) {
+  return join(homedir(), ".cache", "magpie", `magicrew-key-${siteId}__${safeAccount(account)}.json`)
+}
+
+function blank() {
+  return { current: "a", refreshToken: "", keys: { a: null, b: null }, at: "" }
+}
+
+function normalize(v) {
+  // 旧格式（单槽）：{ apiKey, refreshToken, expiresAt, at } → 迁移到 a 槽
+  if (v && typeof v === "object" && typeof v.apiKey === "string" && !v.keys) {
+    return {
+      current: "a",
+      refreshToken: String(v.refreshToken || ""),
+      keys: {
+        a: REAL_KEY.test(v.apiKey) ? { apiKey: v.apiKey, expiresAt: Number(v.expiresAt) || 0 } : null,
+        b: null,
+      },
+      at: String(v.at || ""),
+    }
+  }
+  const s = v && typeof v === "object" ? v : {}
+  const keys = s.keys && typeof s.keys === "object" ? s.keys : {}
+  const clean = (k) =>
+    k && typeof k.apiKey === "string" && REAL_KEY.test(k.apiKey)
+      ? { apiKey: k.apiKey, expiresAt: Number(k.expiresAt) || 0 }
+      : null
+  return {
+    current: s.current === "b" ? "b" : "a",
+    refreshToken: String(s.refreshToken || ""),
+    keys: { a: clean(keys.a), b: clean(keys.b) },
+    at: String(s.at || ""),
+  }
+}
+
+export function readStore(siteId, account) {
+  try {
+    return normalize(JSON.parse(readFileSync(keyPath(siteId, account), "utf8")))
+  } catch {
+    return blank()
+  }
+}
+
+export function writeStore(siteId, account, st) {
+  const next = normalize(st)
+  next.at = new Date().toISOString()
+  try {
+    const f = keyPath(siteId, account)
+    mkdirSync(dirname(f), { recursive: true })
+    writeFileSync(f, JSON.stringify(next))
+  } catch {}
+  return next
+}
+
+/** 这个站点下所有账号的 key 文件（排障用） */
+export function listAccounts(siteId) {
+  try {
+    const dir = join(homedir(), ".cache", "magpie")
+    const pfx = `magicrew-key-${siteId}__`
+    return readdirSync(dir)
+      .filter((f) => f.startsWith(pfx) && f.endsWith(".json"))
+      .map((f) => f.slice(pfx.length, -5))
+  } catch {
+    return []
+  }
+}
+
+/** 清掉某个账号的 key（重新登录时用） */
+export function dropStore(siteId, account) {
+  try {
+    unlinkSync(keyPath(siteId, account))
+  } catch {}
+}
+
+export const otherSlot = (slot) => (slot === "a" ? "b" : "a")
+
+/** 这一把还能用吗：没有到期信息时按「能用」处理，由服务端说了算 */
+export function isFresh(k, leadMs = LEAD_MS) {
+  if (!k?.apiKey) return false
+  if (!k.expiresAt) return true
+  return Date.now() + leadMs < k.expiresAt
+}
+
+export function currentKey(st) {
+  return st?.keys?.[st.current] ?? null
+}
+
+/** 两槽里还有活的吗 */
+export function hasLiveKey(st, leadMs = 0) {
+  return ["a", "b"].some((s) => isFresh(st?.keys?.[s], leadMs))
+}
+
+/**
+ * 把服务端给的到期时间标准化成毫秒时间戳。
+ * 实测两种样子：`"2026-10-27 18:36:26"`（本地时间）和毫秒数字。
+ */
+export function toEpochMs(v) {
+  if (typeof v === "number" && v > 1e12) return v
+  if (typeof v === "string" && v.trim()) {
+    const s = v.trim()
+    const m = s.match(/^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/)
+    if (m) {
+      const [, y, mo, d, h, mi, se] = m.map(Number)
+      return new Date(y, mo - 1, d, h, mi, se).getTime()
+    }
+    const t = Date.parse(s)
+    if (!Number.isNaN(t)) return t
+  }
+  return 0
+}
+
+/**
+ * 当前这把被上游拒了 → 切到另一槽。被拒的那把标失效，免得下次又用它。
+ * @returns 另一槽那把 key，没有可用的就 null
+ */
+export function switchSlot(siteId, account, badApiKey) {
+  const st = readStore(siteId, account)
+  const keys = { ...st.keys }
+  for (const slot of ["a", "b"]) {
+    if (keys[slot]?.apiKey === badApiKey) keys[slot] = { ...keys[slot], expiresAt: 0 }
+  }
+  const alt = otherSlot(st.current)
+  const target = keys[alt]?.apiKey ? alt : keys[st.current]?.apiKey ? st.current : null
+  if (!target) return null
+  writeStore(siteId, account, { ...st, current: target, keys })
+  return keys[target]
+}
+
+// ── 续期串行化 ────────────────────────────────────────────────────────
+//
+// refresh_token 一次性。多个请求同时发现 key 不新鲜会一起续，除第一个外全失败。
+// 按「站点 + 账号」把续期合成一次。
+
+const inflight = new Map()
+
+export function renewOnce(siteId, account, doRenew) {
+  const k = `${siteId}__${safeAccount(account)}`
+  const running = inflight.get(k)
+  if (running) return running
+  const p = (async () => {
+    try {
+      return await doRenew()
+    } catch {
+      return null
+    } finally {
+      inflight.delete(k)
+    }
+  })()
+  inflight.set(k, p)
+  return p
+}

package/src/keys.mjs

@@ -0,0 +1,109 @@
+// key 的唯一出口 —— 按账号隔离的 A/B 双槽
+//
+//   登录成功  → issueAndStore()  签一把放进「另一个槽」，切过去
+//   loader    → ensureKey()      快过期就把新的签到另一个槽，切过去；旧的留着当回退
+//   refresh   → ensureKey()      同上，magpie 拿到的也是同一把
+//
+// **每个账号一套槽，互不干扰** —— 同站点登两个账号时，第二个人登录不会碰第一个人的 key。
+// 账号标识用 `org`（组织码），拿不到才退回 accountId。
+
+import { issueGatewayKey, refreshGatewayKey } from "./api.mjs"
+import {
+  readStore,
+  writeStore,
+  isFresh,
+  toEpochMs,
+  renewOnce,
+  otherSlot,
+  currentKey,
+  safeAccount,
+} from "./key-store.mjs"
+
+/**
+ * 从 auth 里取账号标识。org 是组织码，登录后固定不变，最稳。
+ */
+export function accountOf(auth) {
+  return safeAccount(auth?.org || auth?.accountId || auth?.uid || "default")
+}
+
+/**
+ * 拿到这个账号一把能用的 key。**永不抛** —— 续不上就交出手里那把（哪怕不新鲜），
+ * 让请求自己去撞上游的错误，比在这里抛更能说明问题。
+ *
+ * @param {object} c         站点上下文
+ * @param {Function} getAuth magpie 的取账号函数，或直接给 auth 对象
+ * @param {{leadMs?:number}} opts 提前多久算「不新鲜」，默认 10 分钟
+ */
+export async function ensureKey(c, getAuth, { leadMs } = {}) {
+  let auth = null
+  try {
+    auth = typeof getAuth === "function" ? await getAuth() : getAuth
+  } catch {}
+  const account = accountOf(auth)
+
+  const st = readStore(c.id, account)
+  const cur = currentKey(st)
+  if (isFresh(cur, leadMs)) return cur
+
+  const renewed = await renewOnce(c.id, account, async () => {
+    const again = readStore(c.id, account)
+    const againCur = currentKey(again)
+    // 可能别的请求刚续过 —— 别再签一次（refresh_token 一次性）
+    if (isFresh(againCur, leadMs)) return againCur
+
+    let refreshToken = again.refreshToken
+
+    // ── 该账号第一次跑：从 magpie 存的凭据接管一次 ────────────────────
+    if (!againCur && !refreshToken && auth?.access) {
+      const rec = { apiKey: auth.access, expiresAt: Number(auth.expires) || 0 }
+      const seeded = {
+        current: again.current,
+        refreshToken: auth.refresh || "",
+        keys: { ...again.keys, [again.current]: rec },
+        at: again.at,
+      }
+      writeStore(c.id, account, seeded)
+      if (isFresh(rec, leadMs)) return rec
+      refreshToken = seeded.refreshToken
+    }
+
+    if (!refreshToken) return againCur ?? null
+
+    // ── 续期：签到**另一个**槽再切过去；旧的留在原槽当回退 ────────────
+    const k = await refreshGatewayKey(refreshToken, c.host)
+    const rec = { apiKey: k.apiKey, expiresAt: toEpochMs(k.apiKeyExpiresAt) }
+    const slot = otherSlot(again.current)
+    writeStore(c.id, account, {
+      current: slot,
+      refreshToken: k.refreshToken || refreshToken,
+      keys: { ...again.keys, [slot]: rec },
+      at: again.at,
+    })
+    return rec
+  })
+  if (renewed) return renewed
+
+  // 续不上：交出手里那把（可能是死的，但比"没有"更清楚）
+  if (cur) return cur
+  if (auth?.access) return { apiKey: auth.access, expiresAt: 0 }
+  return null
+}
+
+/**
+ * 登录成功后签一把并落盘：写进「另一个槽」再切过去，原来那把留着当回退。
+ * @returns {Promise<{apiKey,expiresAt,refreshToken}>}
+ */
+export async function issueAndStore(c, jwt, org, account) {
+  const acc = safeAccount(account || org)
+  const st = readStore(c.id, acc)
+  const k = await issueGatewayKey(jwt, org, c.host)
+  const rec = { apiKey: k.apiKey, expiresAt: toEpochMs(k.apiKeyExpiresAt) }
+  const slot = otherSlot(st.current)
+  writeStore(c.id, acc, {
+    current: slot,
+    refreshToken: k.refreshToken || st.refreshToken,
+    keys: { ...st.keys, [slot]: rec },
+    at: st.at,
+  })
+  return { ...rec, refreshToken: k.refreshToken || st.refreshToken, account: acc }
+}

package/src/model-context.mjs

@@ -0,0 +1,100 @@
+// 模型上下文窗口 —— 向 magpie 自己的模型库查
+//
+// ═══ 为什么不能自己填一个值 ═══════════════════════════════════════════
+//
+// magicrew 的两个模型接口**都不返回上下文窗口**：
+//   GET /api/v1/flows/models  → value / label / vision / tags / configs
+//   GET /v1/models            → id / object / created_at / owner_by
+//
+// 早前这里一律填 256_000 当保守值，后果是反的：
+// `pi-ai detected context overflow for model "magicrew/deepseek-v4.1-flash"`
+// —— agent 拿 256K 判断"放不下了"，而实际窗口是 1M，白砍掉四分之三。
+//
+// magpie 自己有一份模型库（`~/.cache/magpie/models.json`，按厂商分组，
+// 每条带 `limit.context`），它本来就随 magpie 更新。**向它查，不要自己编。**
+//
+// 查不到才退回保守值 —— 宁可保守，不要给出超过真实窗口的数（那会让 agent
+// 以为还有余量，请求超了上游才报错）。
+
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/**
+ * 查不到时的兜底：**1M**。
+ *
+ * 优先级从高到低：
+ *   ① 用户在 magpie GUI 里手选的（「上下文窗口」那一行）—— magpie 直接用它，插件的值只是默认
+ *   ② 本文件从 magpie 模型库查到的真实值（models.dev 数据）
+ *   ③ 这个兜底
+ *
+ * ⚠ 兜底故意给大的：给 1M 而实际只有 128K 时，上游会在超限时报错，用户看得到；
+ *   给 256K 而实际有 1M 时，agent 会主动拒绝一段本可以处理的对话 —— 那是静默的能力损失，
+ *   比报错更难查（`pi-ai detected context overflow` 就是这么来的）。
+ */
+const FALLBACK_CONTEXT = 1_048_576
+
+let cache = null
+let cacheAt = 0
+
+/** models.json 5-6MB，读一次缓存住；10 分钟内不重复读 */
+const CACHE_MS = 10 * 60_000
+
+function loadLibrary() {
+  if (cache && Date.now() - cacheAt < CACHE_MS) return cache
+  const idx = new Map()
+  try {
+    const raw = readFileSync(join(homedir(), ".cache", "magpie", "models.json"), "utf8")
+    const walk = (o) => {
+      if (Array.isArray(o)) {
+        for (const v of o) walk(v)
+        return
+      }
+      if (!o || typeof o !== "object") return
+      const id = typeof o.id === "string" ? o.id : ""
+      const ctx = o.limit?.context ?? o.context_length ?? o.context_window
+      if (id && Number(ctx) > 0) {
+        idx.set(id.toLowerCase(), Number(ctx))
+        // 同一个模型可能挂在多个厂商下（deepseek-ai/x、Pro/deepseek-ai/x …），
+        // 只保留最大值 —— 那才是它真能收的
+        const tail = id.toLowerCase().split("/").pop()
+        if (tail) {
+          const prev = idx.get(`~${tail}`) || 0
+          if (Number(ctx) > prev) idx.set(`~${tail}`, Number(ctx))
+        }
+      }
+      for (const v of Object.values(o)) walk(v)
+    }
+    walk(JSON.parse(raw))
+  } catch {}
+  cache = idx
+  cacheAt = Date.now()
+  return idx
+}
+
+/**
+ * 这个模型的上下文窗口。
+ * @param {string} modelId  插件侧的模型 id，如 `deepseek-v4.1-flash`
+ * @returns {number} 字节按 token 计；查不到给保守值
+ */
+export function contextOf(modelId) {
+  const id = String(modelId || "").toLowerCase()
+  if (!id) return FALLBACK_CONTEXT
+  const idx = loadLibrary()
+
+  // ① 全名命中（插件 id 恰好等于库里的 id）
+  if (idx.has(id)) return idx.get(id)
+
+  // ② 尾段命中：库里的 `deepseek-ai/deepseek-v4.1-flash` ↔ 我们的 `deepseek-v4.1-flash`
+  if (idx.has(`~${id}`)) return idx.get(`~${id}`)
+
+  // ③ 同一个模型挂在不同厂商前缀下，取最大的那个（真能收的容量）
+  let best = 0
+  for (const [k, v] of idx) {
+    if (k.startsWith("~")) continue
+    if (k.endsWith(`/${id}`) && v > best) best = v
+  }
+  return best || FALLBACK_CONTEXT
+}
+
+export const _internal = { FALLBACK_CONTEXT, loadLibrary }

package/src/self-register.mjs

@@ -0,0 +1,234 @@
+// 自注册：把本插件写进 magpie 的市场缓存
+//
+// ═══════════════════════════════════════════════════════════════════
+// 问题
+// ═══════════════════════════════════════════════════════════════════
+//
+// magpie 的插件卡片上，「源码」按钮和卡片标题来自
+// ~/.cache/magpie/plugin-market.json —— magpie 的社区插件列表缓存。
+//
+// 包不在那个列表里 ⇒ 卡片标题退回包名，没有源码按钮。
+//
+// ═══════════════════════════════════════════════════════════════════
+// 做法：攒一批，合并去重，写一次
+// ═══════════════════════════════════════════════════════════════════
+//
+// magpie 把**所有插件加载进同一个 Bun 进程**（它自己的文档写
+// "one Bun process, the plugin host"）。所以插件之间可以通过
+// globalThis 共享一个队列。
+//
+//   插件 A 加载 → 入队
+//   插件 B 加载 → 入队
+//   ...          ↓ 100ms 窗口
+//              合并去重 → 一次写入
+//
+// 实测：10 个插件同时启动，**只写盘 1 次**，全部存活，官方条目不动。
+//
+// ═══════════════════════════════════════════════════════════════════
+// 只写一次，绝不轮询
+// ═══════════════════════════════════════════════════════════════════
+//
+// 实测（2026-10-25）：
+//
+//   手工往缓存里加一条 → 等 10 秒 → 没被覆盖
+//   再跑 plugin update → 也没被覆盖
+//   连续观察 3 分钟     → mtime 零变化
+//
+// magpie 只在启动时重写这个文件，静默运行期间完全不碰。
+//
+// ⚠⚠ 绝对不要用 fs.watch 或 setInterval 去「补」。
+//    我试过：我们写文件（rename）会触发自己的 watch，watch 又写，
+//    每秒 3-4 次，永不停止（实测 60 秒内 mtime 变化 19 次）。
+//    删掉后 60 秒变化 0 次。
+//
+// ═══════════════════════════════════════════════════════════════════
+
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+
+/** 官方 registry 的地址（缓存丢了时的兜底）*/
+const OFFICIAL_REGISTRY =
+  "https://raw.githubusercontent.com/magpie-community/plugins/main/registry.json"
+
+/** 队列的共享键（Symbol.for 保证同一进程内所有插件拿到同一个）*/
+const QUEUE_KEY = Symbol.for("magpie.plugin-template.registry-queue")
+
+/** 攒批窗口。够短（卡片不卡），够长（同期插件都能进来）*/
+const FLUSH_MS = 100
+
+/**
+ * 从 magpie 的配置目录推出它的缓存目录。
+ *
+ * 插件的 directory 是 magpie 的 config folder（~/.config/magpie）。
+ * XDG 规则下 cache 和 config 平级。
+ */
+export function cacheDirOf(configDir) {
+  if (configDir && typeof configDir === "string") {
+    const cfg = path.resolve(configDir)
+    const guess = path.join(path.dirname(path.dirname(cfg)), ".cache", "magpie")
+    if (fs.existsSync(guess)) return guess
+    if (process.platform === "darwin") {
+      const mac = path.join(os.homedir(), "Library", "Caches", "magpie")
+      if (fs.existsSync(mac)) return mac
+    }
+    const xdg = process.env.XDG_CACHE_HOME
+    if (xdg) return path.join(xdg, "magpie")
+    return guess
+  }
+  const xdg = process.env.XDG_CACHE_HOME
+  if (xdg) return path.join(xdg, "magpie")
+  return path.join(os.homedir(), ".cache", "magpie")
+}
+
+/** 取（或创建）共享队列 */
+function queue(configDir) {
+  if (!globalThis[QUEUE_KEY]) {
+    globalThis[QUEUE_KEY] = {
+      /** package → entry，按包名天然去重 */
+      entries: new Map(),
+      timer: null,
+      configDir,
+      log: () => {},
+      writes: 0,
+    }
+  }
+  const q = globalThis[QUEUE_KEY]
+  if (configDir) q.configDir = configDir
+  return q
+}
+
+/**
+ * 把一个条目加入队列。
+ *
+ * 同一个包名重复入队只保留最后一次 —— 这就是去重。
+ *
+ * @param {object} entry { package, name, providers?, community?, summary }
+ * @param {{configDir?: string, log?: Function, timeoutMs?: number}} [opts]
+ */
+export function registerSelf(entry, opts = {}) {
+  if (!entry || typeof entry.package !== "string" || entry.package.length === 0) {
+    return Promise.resolve({ ok: false, reason: "entry.package 缺失" })
+  }
+
+  const q = queue(opts.configDir)
+  if (typeof opts.log === "function") q.log = opts.log
+
+  q.entries.set(entry.package, entry)
+
+  if (q.timer) return Promise.resolve({ ok: true, queued: true })
+
+  return new Promise((resolve) => {
+    q.timer = setTimeout(() => {
+      q.timer = null
+      const r = flush(q, opts.timeoutMs)
+      resolve(r)
+    }, FLUSH_MS)
+    if (typeof q.timer.unref === "function") q.timer.unref()
+  })
+}
+
+/**
+ * 一次读、一次合并、一次写。
+ *
+ * 队列里的所有条目（可能来自多个插件）在这个函数里一起进缓存，
+ * 所以并发插件之间不存在「你覆盖我」的窗口。
+ */
+function flush(q, timeoutMs = 15_000) {
+  const log = q.log
+  if (q.entries.size === 0) return { ok: true, changed: false }
+
+  const cacheDir = cacheDirOf(q.configDir)
+  const marketPath = path.join(cacheDir, "plugin-market.json")
+
+  try {
+    let current = null
+    if (fs.existsSync(marketPath)) {
+      try {
+        current = JSON.parse(fs.readFileSync(marketPath, "utf8"))
+      } catch {
+        current = null
+      }
+    }
+
+    if (!current || !Array.isArray(current.plugins)) {
+      // 缓存不可用就跳过（不阻塞插件加载）。下次启动还会再试。
+      const names = [...q.entries.keys()].join(", ")
+      log(`市场缓存不可用，跳过注册：${names}`)
+      q.entries.clear()
+      return { ok: false, reason: "市场缓存不可用" }
+    }
+
+    const snapshot = JSON.stringify(current, null, 2)
+    const added = []
+    const updated = []
+
+    // 按包名合并：有就原地更新，没有才追加
+    for (const [pkg, entry] of q.entries) {
+      const idx = current.plugins.findIndex((x) => x?.package === pkg)
+      if (idx >= 0) {
+        current.plugins[idx] = entry
+        updated.push(pkg)
+      } else {
+        current.plugins.push(entry)
+        added.push(pkg)
+      }
+    }
+    q.entries.clear()
+
+    const next = JSON.stringify(current, null, 2)
+    if (snapshot === next) {
+      return { ok: true, changed: false, total: current.plugins.length }
+    }
+
+    fs.mkdirSync(cacheDir, { recursive: true })
+    const tmp = `${marketPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 6)}`
+    fs.writeFileSync(tmp, next, "utf8")
+    fs.renameSync(tmp, marketPath)
+    q.writes++
+
+    const parts = []
+    if (added.length) parts.push(`新增 ${added.length}`)
+    if (updated.length) parts.push(`更新 ${updated.length}`)
+    log(`已注册 ${parts.join("，")}（共 ${current.plugins.length} 条，这是第 ${q.writes} 次写入）`)
+
+    return {
+      ok: true,
+      changed: true,
+      total: current.plugins.length,
+      added,
+      updated,
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    log(`自注册失败：${msg}`)
+    q.entries.clear()
+    return { ok: false, reason: msg }
+  }
+}
+
+/**
+ * 启动自注册。
+ *
+ * 一次调用只入队一次。同期的其它插件会在同一个窗口里被合并，
+ * 一起写进缓存 —— 不管有多少个插件，写入次数都接近 1。
+ *
+ * @param {object} entry
+ * @param {{configDir?: string, log?: Function}} [opts]
+ */
+export function startSelfRegister(entry, opts = {}) {
+  registerSelf(entry, opts).catch(() => {})
+}
+
+/** 供测试：立刻清空队列（不影响真实使用）*/
+export function _flushNow() {
+  const q = globalThis[QUEUE_KEY]
+  if (!q) return { ok: true, changed: false }
+  if (q.timer) {
+    clearTimeout(q.timer)
+    q.timer = null
+  }
+  return flush(q)
+}
+
+export const _internal = { cacheDirOf, OFFICIAL_REGISTRY, QUEUE_KEY, FLUSH_MS }