pi-web-ui 0.90.1 → 0.92.0

package/dist/server/model-enrich.js

@@ -0,0 +1,478 @@
+const t = (lang, zh, en) => (lang === "zh" ? zh : en);
+/** 反代路由档位后缀（只在精确匹配失败后剥离；-pro/-flash/-lite 等真实
+ *  家族区分绝不在此列）。 */
+const TIER_SUFFIXES = ["-thinking", "-high", "-low", "-max", "-preview", "-latest", "-exp"];
+/** 小写 + 下划线转横线 + 去 provider 前缀（a/b → b）。 */
+export function normalizeModelId(id) {
+    let s = id.trim().toLowerCase().replace(/_/g, "-");
+    const slash = s.lastIndexOf("/");
+    if (slash >= 0)
+        s = s.slice(slash + 1);
+    return s;
+}
+/** 剥离路由档位与日期后缀（-0813 / -20250929），精确匹配失败后的回退用。 */
+export function stripTierSuffix(id) {
+    let s = normalizeModelId(id);
+    for (let i = 0; i < 3; i++) {
+        let next = s.replace(/-((0[1-9]|1[0-2])\d{2}|\d{6,8})$/, "");
+        for (const suf of TIER_SUFFIXES) {
+            if (next.endsWith(suf) && next.length > suf.length + 2) {
+                next = next.slice(0, -suf.length);
+                break;
+            }
+        }
+        if (next === s)
+            return s;
+        s = next;
+    }
+    return s;
+}
+export function buildIndex(models) {
+    const byId = new Map();
+    const byName = new Map();
+    for (const m of models) {
+        const idKey = normalizeModelId(m.id);
+        if (idKey) {
+            const arr = byId.get(idKey) ?? [];
+            arr.push(m);
+            byId.set(idKey, arr);
+        }
+        const nameKey = m.name.trim().toLowerCase();
+        if (nameKey && nameKey !== idKey) {
+            const arr = byName.get(nameKey) ?? [];
+            arr.push(m);
+            byName.set(nameKey, arr);
+        }
+    }
+    return { byId, byName, all: models };
+}
+/** OpenRouter /api/v1/models → CatalogModel[]（缺字段即缺席，不编造）。 */
+export function parseOpenRouterCatalog(json) {
+    const data = json?.data;
+    if (!Array.isArray(data))
+        return [];
+    const out = [];
+    for (const item of data) {
+        const r = (item ?? {});
+        if (typeof r.id !== "string" || !r.id.trim())
+            continue;
+        const norm = normalizeModelId(r.id);
+        const slash = norm.lastIndexOf("/");
+        // OpenRouter id 形如 anthropic/claude-sonnet-4-5（normalize 已去前缀，
+        // provider 从原始 id 取）。
+        const raw = r.id.trim();
+        const rawSlash = raw.lastIndexOf("/");
+        const provider = rawSlash >= 0 ? raw.slice(0, rawSlash).toLowerCase() : "";
+        const tail = slash >= 0 ? norm.slice(slash + 1) : norm;
+        const arch = (r.architecture ?? {});
+        const inputs = Array.isArray(arch.input_modalities)
+            ? arch.input_modalities.filter((x) => typeof x === "string")
+            : [];
+        const top = (r.top_provider ?? {});
+        const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
+        const params = Array.isArray(r.supported_parameters)
+            ? r.supported_parameters.filter((x) => typeof x === "string")
+            : [];
+        out.push({
+            id: tail,
+            provider,
+            rawId: raw,
+            name: typeof r.name === "string" ? r.name : tail,
+            contextWindow: num(top.context_length) ?? num(r.context_length),
+            maxTokens: num(top.max_completion_tokens),
+            vision: inputs.includes("image") ? true : undefined,
+            reasoning: params.includes("reasoning") || params.includes("include_reasoning") ? true : undefined,
+        });
+    }
+    return out;
+}
+/** models.dev /api.json → CatalogModel[]（{ provider: { models: {...} } }）。 */
+export function parseModelsDevCatalog(json) {
+    const root = (json ?? {});
+    const out = [];
+    const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
+    for (const [providerKey, entry] of Object.entries(root)) {
+        const models = entry?.models;
+        if (!models || typeof models !== "object")
+            continue;
+        for (const [key, item] of Object.entries(models)) {
+            const r = (item ?? {});
+            const rawId = typeof r.id === "string" && r.id.trim() ? r.id.trim() : key;
+            const norm = normalizeModelId(rawId);
+            const slash = norm.lastIndexOf("/");
+            const tail = slash >= 0 ? norm.slice(slash + 1) : norm;
+            if (!tail)
+                continue;
+            const limit = (r.limit ?? {});
+            const modalities = (r.modalities ?? {});
+            const inputs = Array.isArray(modalities.input)
+                ? modalities.input.filter((x) => typeof x === "string")
+                : [];
+            out.push({
+                id: tail,
+                provider: (slash >= 0 ? norm.slice(0, slash) : providerKey).toLowerCase(),
+                rawId,
+                name: typeof r.name === "string" && r.name.trim() ? r.name.trim() : tail,
+                family: typeof r.family === "string" ? r.family.toLowerCase() : undefined,
+                contextWindow: num(limit.context),
+                maxTokens: num(limit.output),
+                vision: inputs.includes("image") ? true : undefined,
+                reasoning: r.reasoning === true ? true : undefined,
+            });
+        }
+    }
+    return out;
+}
+async function fetchJson(fetchFn, url, maxBytes, timeoutMs, signal) {
+    if (signal?.aborted)
+        throw new Error("aborted");
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const onAbort = () => ac.abort();
+    if (signal)
+        signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        const res = await fetchFn(url, {
+            signal: ac.signal,
+            headers: { "user-agent": "pi-web-ui model-enrich" },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const text = await res.text();
+        if (text.length > maxBytes)
+            throw new Error("response too large");
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (signal?.aborted)
+            throw new Error("aborted");
+        if (err.name === "AbortError")
+            throw new Error("timeout");
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        if (signal)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+/** 目录抓取缓存（24h TTL，进程内；首跑后无感）。 */
+const catalogCache = new Map();
+const CATALOG_TTL_MS = 24 * 3600 * 1000;
+export function clearEnrichCache() {
+    catalogCache.clear();
+}
+export async function getOpenRouterCatalog(fetchFn = fetch, signal) {
+    const hit = catalogCache.get("openrouter");
+    if (hit && Date.now() - hit.at < CATALOG_TTL_MS)
+        return hit.data;
+    const data = parseOpenRouterCatalog(await fetchJson(fetchFn, "https://openrouter.ai/api/v1/models", 5_000_000, 25000, signal));
+    catalogCache.set("openrouter", { at: Date.now(), data });
+    return data;
+}
+export async function getModelsDevCatalog(fetchFn = fetch, signal) {
+    const hit = catalogCache.get("modelsdev");
+    if (hit && Date.now() - hit.at < CATALOG_TTL_MS)
+        return hit.data;
+    const data = parseModelsDevCatalog(await fetchJson(fetchFn, "https://models.dev/api.json", 25_000_000, 30000, signal));
+    catalogCache.set("modelsdev", { at: Date.now(), data });
+    return data;
+}
+/** 从网页正文提取参数（hint URL 兜底；只认上下文/输出上限/识图，不认推理）。 */
+export function extractParamsFromHtml(html) {
+    const text = html
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s+/g, " ")
+        .slice(0, 200_000);
+    const toNum = (n, unit) => {
+        const base = Number(n.replace(/[,，]/g, ""));
+        if (!Number.isFinite(base) || base <= 0)
+            return undefined;
+        const mult = unit?.toLowerCase() === "m" ? 1_000_000 : unit?.toLowerCase() === "k" ? 1000 : 1;
+        const v = Math.round(base * mult);
+        return v >= 1000 && v <= 100_000_000 ? v : undefined;
+    };
+    const out = {};
+    const ctx = text.match(/(\d[\d,.]*)\s*([kKmM])\s*(?:token\s*)?context/i) ??
+        text.match(/(\d[\d,.]*)\s*tokens?\s+context/i) ??
+        text.match(/context(?:\s+window)?[^.\n]{0,50}?(\d[\d,.]*)\s*([kKmM])?\s*tokens?/i);
+    if (ctx) {
+        const v = toNum(ctx[1], ctx[2]);
+        if (v !== undefined)
+            out.contextWindow = v;
+    }
+    const max = text.match(/(\d[\d,.]*)\s*([kKmM])\s*(?:max(?:imum)?\s+)?output/i) ??
+        text.match(/(\d[\d,.]*)\s*tokens?\s+(?:max(?:imum)?\s+)?output/i) ??
+        text.match(/(?:max(?:imum)?\s+output|output\s+limit)[^.]{0,50}?(\d[\d,.]*)\s*([kKmM])?\s*tokens?/i);
+    if (max) {
+        const v = toNum(max[1], max[2]);
+        if (v !== undefined)
+            out.maxTokens = v;
+    }
+    if (/image\s*(input|understanding|support)/i.test(text))
+        out.vision = true;
+    return out;
+}
+async function fetchPageText(fetchFn, url, signal) {
+    if (signal?.aborted)
+        throw new Error("aborted");
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 15000);
+    const onAbort = () => ac.abort();
+    if (signal)
+        signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        const res = await fetchFn(url, {
+            signal: ac.signal,
+            headers: { "user-agent": "pi-web-ui model-enrich" },
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const text = await res.text();
+        if (text.length > 2_000_000)
+            throw new Error("response too large");
+        return text;
+    }
+    catch (err) {
+        if (signal?.aborted)
+            throw new Error("aborted");
+        if (err.name === "AbortError")
+            throw new Error("timeout");
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        if (signal)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+/** 单个 id 在给定索引里的精确/别名命中（exact → normalized）。 */
+function lookupIndex(norm, index) {
+    const exact = index.byId.get(norm);
+    if (exact?.length)
+        return { model: exact[0], matchType: "exact" };
+    const stripped = stripTierSuffix(norm);
+    if (stripped !== norm) {
+        const hit = index.byId.get(stripped);
+        if (hit?.length)
+            return { model: hit[0], matchType: "normalized" };
+    }
+    const nameHit = index.byName.get(norm);
+    if (nameHit?.length)
+        return { model: nameHit[0], matchType: "exact" };
+    return null;
+}
+/** 家族候选（只做建议，不自动填）：family 字符串与 id 互含。 */
+function familySuggestions(norm, indexes, cap = 6) {
+    const seen = new Set();
+    const out = [];
+    for (const index of indexes) {
+        for (const m of index.all) {
+            if (!m.family || out.length >= cap)
+                break;
+            if (norm.includes(m.family) || m.family.includes(norm)) {
+                if (!seen.has(m.rawId)) {
+                    seen.add(m.rawId);
+                    out.push(m.rawId);
+                }
+            }
+        }
+        if (out.length >= cap)
+            break;
+    }
+    return out;
+}
+function toResult(lang, id, model, source, matchType) {
+    return {
+        id,
+        status: "matched",
+        ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
+        ...(model.maxTokens ? { maxTokens: model.maxTokens } : {}),
+        ...(model.vision ? { input: ["text", "image"] } : {}),
+        ...(model.reasoning ? { reasoning: true } : {}),
+        ...(model.name && model.name.toLowerCase() !== id.toLowerCase() ? { name: model.name } : {}),
+        source: `${source}${matchType === "exact" || matchType === "hint" ? "" : t(lang, "（别名）", " (alias)")}`,
+        matchType,
+    };
+}
+function isUrl(s) {
+    return /^https?:\/\//i.test(s.trim());
+}
+/** 批量补参数：hint（目录 id / URL）优先，否则 OpenRouter → models.dev 自动匹配。 */
+export async function enrichBatch(ids, hints, opts = {}) {
+    const lang = opts.lang ?? "en";
+    const fetchFn = opts.fetchFn ?? fetch;
+    const uniq = [...new Set(ids.map((s) => (s ?? "").trim()).filter(Boolean))].slice(0, 100);
+    const results = [];
+    const throwAbort = () => {
+        const err = new Error("aborted");
+        err.partialResults = results;
+        throw err;
+    };
+    if (opts.signal?.aborted)
+        throwAbort();
+    let orModels = null;
+    let mdModels = null;
+    let orIndex = null;
+    let mdIndex = null;
+    if (opts.catalogs) {
+        orModels = opts.catalogs.openrouter;
+        mdModels = opts.catalogs.modelsdev;
+        orIndex = buildIndex(orModels);
+        mdIndex = buildIndex(mdModels);
+    }
+    else {
+        opts.onProgress?.({
+            phase: "catalog",
+            message: t(lang, "正在获取 OpenRouter 模型目录…", "Fetching OpenRouter catalog…"),
+        });
+        try {
+            orModels = await getOpenRouterCatalog(fetchFn, opts.signal);
+        }
+        catch (err) {
+            if (opts.signal?.aborted || err.message === "aborted")
+                throwAbort();
+            orModels = [];
+        }
+        orIndex = buildIndex(orModels);
+    }
+    const ensureMd = async () => {
+        if (opts.signal?.aborted)
+            throwAbort();
+        if (!mdIndex) {
+            if (!opts.catalogs) {
+                opts.onProgress?.({
+                    phase: "catalog",
+                    message: t(lang, "正在拉取 models.dev 目录（约 25MB）…", "Fetching models.dev catalog (~25MB)…"),
+                });
+            }
+            try {
+                mdModels = opts.catalogs ? opts.catalogs.modelsdev : await getModelsDevCatalog(fetchFn, opts.signal);
+            }
+            catch (err) {
+                if (opts.signal?.aborted || err.message === "aborted")
+                    throwAbort();
+                mdModels = [];
+            }
+            mdIndex = buildIndex(mdModels ?? []);
+        }
+        return mdIndex;
+    };
+    const indexes = () => (mdIndex ? [orIndex, mdIndex] : [orIndex]);
+    if (!opts.catalogs && orModels.length === 0) {
+        // 主源不可达时仍试一次辅源；都空才报错。
+        await ensureMd();
+        if ((mdModels ?? []).length === 0) {
+            throw new Error(t(lang, "参考源不可达（OpenRouter / models.dev），请检查网络后重试", "Reference catalogs unreachable (OpenRouter / models.dev); check your network and retry"));
+        }
+    }
+    const total = uniq.length;
+    for (let i = 0; i < total; i++) {
+        if (opts.signal?.aborted)
+            throwAbort();
+        const id = uniq[i];
+        opts.onProgress?.({
+            phase: "matching",
+            current: i + 1,
+            total,
+            message: t(lang, `正在匹配参数 (${i + 1}/${total})：${id}`, `Matching params (${i + 1}/${total}): ${id}`),
+        });
+        const norm = normalizeModelId(id);
+        const hint = (hints[id] ?? hints[norm] ?? "").trim();
+        // -- 依据分支 ---------------------------------------------------------
+        if (hint) {
+            if (isUrl(hint)) {
+                opts.onProgress?.({
+                    phase: "page",
+                    current: i + 1,
+                    total,
+                    message: t(lang, `正在抓取依据网页 (${i + 1}/${total})：${hint}`, `Fetching evidence page (${i + 1}/${total}): ${hint}`),
+                });
+                try {
+                    const html = opts.pageFetch ? await opts.pageFetch(hint) : await fetchPageText(fetchFn, hint, opts.signal);
+                    const ext = extractParamsFromHtml(html);
+                    if (ext.contextWindow === undefined && ext.maxTokens === undefined && ext.vision === undefined) {
+                        results.push({
+                            id,
+                            status: "unmatched",
+                            note: t(lang, "网页未提取到可用参数", "No usable params extracted from the page"),
+                        });
+                        continue;
+                    }
+                    results.push({
+                        id,
+                        status: "matched",
+                        ...(ext.contextWindow ? { contextWindow: ext.contextWindow } : {}),
+                        ...(ext.maxTokens ? { maxTokens: ext.maxTokens } : {}),
+                        ...(ext.vision ? { input: ["text", "image"] } : {}),
+                        source: t(lang, "网页", "Web page"),
+                        matchType: "hint-url",
+                    });
+                }
+                catch (err) {
+                    if (opts.signal?.aborted || err.message === "aborted")
+                        throwAbort();
+                    results.push({
+                        id,
+                        status: "unmatched",
+                        note: t(lang, "依据网页抓取失败", "Failed to fetch the evidence page"),
+                    });
+                }
+                continue;
+            }
+            const hNorm = normalizeModelId(hint);
+            const hStripped = stripTierSuffix(hNorm);
+            const hit = orIndex.byId.get(hNorm)?.[0] ??
+                orIndex.byId.get(hStripped)?.[0] ??
+                orIndex.byName.get(hNorm)?.[0];
+            if (hit) {
+                results.push(toResult(lang, id, hit, t(lang, "依据", "Evidence"), "hint"));
+                continue;
+            }
+            const md = await ensureMd();
+            const mdHit = md.byId.get(hNorm)?.[0] ?? md.byId.get(hStripped)?.[0] ?? md.byName.get(hNorm)?.[0];
+            if (mdHit) {
+                results.push(toResult(lang, id, mdHit, t(lang, "依据", "Evidence"), "hint"));
+                continue;
+            }
+            results.push({
+                id,
+                status: "unmatched",
+                note: t(lang, `依据「${hint}」在目录中未命中`, `Evidence "${hint}" not found in catalogs`),
+            });
+            continue;
+        }
+        // -- 自动匹配分支 -----------------------------------------------------
+        const orHit = lookupIndex(norm, orIndex);
+        if (orHit) {
+            const r = toResult(lang, id, orHit.model, "OpenRouter", orHit.matchType);
+            // OpenRouter 的推理信号弱；models.dev 有明确布尔值时补上。
+            if (!orHit.model.reasoning) {
+                const md = await ensureMd();
+                const mdHit = md.byId.get(normalizeModelId(orHit.model.id))?.[0];
+                if (mdHit?.reasoning)
+                    r.reasoning = true;
+            }
+            results.push(r);
+            continue;
+        }
+        const md = await ensureMd();
+        const mdHit = lookupIndex(norm, md);
+        if (mdHit) {
+            results.push(toResult(lang, id, mdHit.model, "models.dev", mdHit.matchType));
+            continue;
+        }
+        const suggestions = familySuggestions(norm, indexes());
+        results.push({
+            id,
+            status: suggestions.length ? "suggested" : "unmatched",
+            ...(suggestions.length ? { suggestions, matchType: "family" } : {}),
+            note: suggestions.length
+                ? t(lang, "家族相近，可用其 id 作依据重试", "Close family match — retry with its id as evidence")
+                : t(lang, "目录无此模型，可填官方文档 URL 作依据重试", "Not in catalogs — retry with an official docs URL as evidence"),
+        });
+    }
+    return results;
+}

package/dist/server/plugin-catalog.js

@@ -16,6 +16,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { normalizeIconSvg } from "./icon-svg.js";
 import { pick } from "./i18n.js";
 /** 合法插件 id（与 server/plugins.ts 的 ID_RE 一致，防路径穿越）。 */
 const ID_RE = /^[A-Za-z0-9_-]+$/;
@@ -77,6 +78,7 @@ function toEntry(raw, builtin) {
     const description = typeof raw.description === "string" && raw.description.trim() ? raw.description.trim() : undefined;
     const descriptionEn = typeof raw.descriptionEn === "string" && raw.descriptionEn.trim() ? raw.descriptionEn.trim() : undefined;
     const icon = typeof raw.icon === "string" && raw.icon.trim() ? raw.icon.trim() : undefined;
+    const iconSvg = normalizeIconSvg(raw.iconSvg);
     const homepage = typeof raw.homepage === "string" && raw.homepage.trim() ? raw.homepage.trim() : undefined;
     return {
         id,
@@ -86,6 +88,7 @@ function toEntry(raw, builtin) {
         ...(description ? { description } : {}),
         ...(descriptionEn ? { descriptionEn } : {}),
         ...(icon ? { icon } : {}),
+        ...(iconSvg ? { iconSvg } : {}),
         ...(homepage ? { homepage } : {}),
     };
 }
@@ -146,6 +149,7 @@ lang) {
             ? { description: input.description.trim() }
             : {}),
         ...(typeof input?.icon === "string" && input.icon.trim() ? { icon: input.icon.trim() } : {}),
+        ...(normalizeIconSvg(input?.iconSvg) ? { iconSvg: normalizeIconSvg(input?.iconSvg) } : {}),
     });
     atomicWrite(customPath, { entries: next });
     return toEntry(next[next.length - 1], false);
@@ -223,6 +227,7 @@ export function writeCustomCatalog(customPath, incoming, replace) {
         ...(e.description ? { description: e.description } : {}),
         ...(e.descriptionEn ? { descriptionEn: e.descriptionEn } : {}),
         ...(e.icon ? { icon: e.icon } : {}),
+        ...(e.iconSvg ? { iconSvg: e.iconSvg } : {}),
         ...(e.homepage ? { homepage: e.homepage } : {}),
     }));
     atomicWrite(customPath, { entries });

package/dist/server/plugin-facilities.js

@@ -16,7 +16,7 @@
  *     不能防同一用户账号下的完整进程妥协——本地个人工具的合理折衷。
  */
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { readFile as fspReadFile, readdir as fspReaddir, rm as fspRm, mkdir as fspMkdir, writeFile as fspWriteFile, appendFile as fspAppendFile, stat as fspStat, } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { createRequire } from "node:module";
@@ -31,24 +31,52 @@ function atomicWrite(file, data) {
 // ---------------------------------------------------------------------------
 // storage
 // ---------------------------------------------------------------------------
-/** 每插件的 JSON 文件 KV。所有方法同步（数据量小，避免并发写乱序）。 */
+/** 每插件的 JSON 文件 KV。所有方法同步（数据量小，避免并发写乱序）。
+ *
+ * 缓存按文件 mtimeMs 失效（而非「首次读入后永不失效」）：storage.json 有两个
+ * 写入者 —— 本类，以及宿主 settings 面板的 saveSettingsValues（直写磁盘的
+ * settings 键，不经过本缓存）。插件长轮询里每隔几秒就 store.set("cursor", …)
+ * 一次，若缓存永不失效，set() 会把整份旧快照回写，把面板刚保存的 settings
+ * 抹掉 —— 表现为「设置重启即丢」。mtime 失效让下一次 load() 重读，两个写入者
+ * 各自保留自己的键。 */
 export class PluginStorage {
     file;
     cache;
+    /** 缓存对应的文件 mtimeMs（undefined = 文件尚不存在或不可 stat）。 */
+    cacheMtimeMs;
     constructor(file) {
         this.file = file;
     }
-    load() {
-        if (this.cache)
-            return this.cache;
+    mtime() {
         try {
-            const parsed = JSON.parse(readFileSync(this.file, "utf8"));
-            this.cache = parsed && typeof parsed === "object" ? parsed : {};
+            return statSync(this.file).mtimeMs;
         }
         catch {
-            this.cache = {}; // 不存在/损坏 = 空表（损坏不致命，重新积累）
+            return undefined; // 不存在 / 不可 stat
         }
-        return this.cache;
+    }
+    /** 从磁盘重读（不存在 / 损坏 = 空表）并同步缓存与 mtime。 */
+    readFromDisk(mtimeMs = this.mtime()) {
+        let parsed = {};
+        if (mtimeMs !== undefined) {
+            try {
+                const raw = JSON.parse(readFileSync(this.file, "utf8"));
+                if (raw && typeof raw === "object")
+                    parsed = raw;
+            }
+            catch {
+                parsed = {}; // 损坏 = 空表（不致命，重新积累）
+            }
+        }
+        this.cache = parsed;
+        this.cacheMtimeMs = mtimeMs;
+        return parsed;
+    }
+    load() {
+        const mtimeMs = this.mtime();
+        if (this.cache && this.cacheMtimeMs === mtimeMs)
+            return this.cache;
+        return this.readFromDisk(mtimeMs);
     }
     get(key, fallback) {
         const v = this.load()[key];
@@ -60,7 +88,10 @@ export class PluginStorage {
     set(key, value) {
         if (!key)
             throw new Error("storage.set: key 不能为空");
-        const store = this.load();
+        // 写前必重读磁盘：宿主 settings 面板的 saveSettingsValues 直写同一文件的
+        // settings 键（不经过本缓存），拿旧快照整份回写会把它抹掉。写是低频路径，
+        // 重读的代价可忽略；mtime 粒度即使同毫秒也抹不掉（这里是无条件重读）。
+        const store = this.readFromDisk();
         store[key] = value;
         try {
             atomicWrite(this.file, JSON.stringify(store));
@@ -70,7 +101,7 @@ export class PluginStorage {
         }
     }
     delete(key) {
-        const store = this.load();
+        const store = this.readFromDisk(); // 同 set：写前重读，不拿旧快照回写
         if (!(key in store))
             return;
         delete store[key];

package/dist/server/plugin-schedule.js

@@ -136,7 +136,15 @@ export function parseCronSpec(spec) {
 function isFull(values, min, max) {
     return values.length === max - min + 1;
 }
-/** 下一次触发毫秒时间戳（从 fromMs 的下一分钟开始扫，上限约一年）。纯函数，单测覆盖。 */
+/**
+ * 下一次触发毫秒时间戳（从 fromMs 的下一分钟开始扫，上限约一年）；**一年内没有下一次回 null**
+ * （例如 `0 0 31 2 *` 这种永远不存在的日子）。
+ *
+ * 为什么不是回一个「一年后的哨兵值」：调用方 `armCron` 拿它做 `setTimeout(next - now)`，
+ * 而 Node 的 setTimeout 延迟超过 2^31-1ms（≈24.8 天）会**溢出成 1ms** —— 哨兵值配上溢出
+ * 就是「1ms 后触发 → 再排下一次」的死循环（每次触发还伴随插件回调与写盘）。回 null 之后，
+ * 调用方能明确区分「还有很久」与「永远不会发生」。纯函数，单测覆盖。
+ */
 export function nextCronFire(parts, fromMs) {
     const minuteSet = new Set(parts.minute);
     const hourSet = new Set(parts.hour);
@@ -163,7 +171,24 @@ export function nextCronFire(parts, fromMs) {
             continue;
         return t;
     }
-    return limit;
+    return null;
+}
+/**
+ * setTimeout 的安全延迟上限（毫秒）：Node 与浏览器都按 32 位有符号整数存延迟，
+ * 超过 2^31-1 会被截断（Node 会**静默变成 1ms** 并打一条 TimeoutOverflowWarning）。
+ */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * 把「距离下次触发的毫秒数」切成一段安全的 setTimeout 延迟（纯函数，单测覆盖）。
+ *
+ * 超过上限就只等一个分片（默认 6 小时）再重新计算 —— 重新计算这一步是关键：
+ * 过期声明、时钟回拨、系统休眠回来都能自然纠正，比一次性排一个超长定时器稳。
+ */
+export function armDelay(nextAtMs, nowMs, maxChunkMs = 6 * 60 * 60 * 1000) {
+    const raw = Math.max(0, Number(nextAtMs) - Number(nowMs));
+    if (!Number.isFinite(raw))
+        return 0;
+    return Math.min(raw, Math.max(1, Math.min(maxChunkMs, MAX_TIMEOUT_MS)));
 }
 export function scheduleFile(pluginDir) {
     return join(pluginDir, "schedules.json");