dsh-folia 4.0.0 → 4.0.1

package/lib/index.js

@@ -77,8 +77,8 @@ import { assertSubpackagesResolvable, assertSubpackagesResolvableInHost, httpVie
 // `extOf` 反向传给会话段（清单载荷的容器后缀判据 ⇒ 见该文件头）。
 import { createHostSession } from './kernel/host-session.js';
 export { extOf };
-import { registerInventoryRoutes } from './routes/inventory.js';
-import { registerModulesRoutes } from './routes/modules.js';
+import { registerInventoryRoutes, warmInventorySiteCache } from './routes/inventory.js';
+import { registerModulesRoutes, warmModulesCache } from './routes/modules.js';
 import { registerBootRoutes } from './routes/boot.js';
 import { registerSiteThumbRoutes } from './routes/site-thumb.js';
 import { installBootInjection } from './boot/index.js';
@@ -307,6 +307,10 @@ export function apply(ctx) {
 
   // 站点图片缩略图代理 → lib/routes/site-thumb.js。卡片用 320px 小图，不再每张下 500 KB 原图。
   registerSiteThumbRoutes(webServer, { disposers, base: BASE, ensureImagePreview, log });
+
+  // 启动预热（有意不阻塞）：站点清单与模块索引各拉一次，让第一次打开面板不冷。
+  warmInventorySiteCache();
+  warmModulesCache();
   installBootInjection(ctx, (m) => { try { log(m); } catch { /* ignore */ } });
 
   // 3./3a. 派生媒体族路由（源元信息 / 抽帧转码 + 进度 / 视频缩略图）→ lib/routes/media-derived.js。

package/lib/routes/boot.js

@@ -128,7 +128,21 @@ async function readIdBody(req) {
  * 候选清单：模块索引里的 `boot` 模块 → 拉它的 manifest → `{ clips: [...] }`。
  * 失败一律返回空数组（面板显示"没有候选"），绝不抛。
  */
-async function fetchCandidates() {
+/** 候选缓存：30 秒。页签每次打开要跳两跳（模块索引 + 站点分类），没必要每次都跳。 */
+const CANDIDATE_TTL_MS = 30000;
+let candidateCache = { at: 0, value: null };
+
+async function fetchCandidates(force = false) {
+  if (!force && candidateCache.value && Date.now() - candidateCache.at < CANDIDATE_TTL_MS) {
+    return candidateCache.value;
+  }
+  const fresh = await fetchCandidatesUncached();
+  // 有结果才缓存（空结果多半是站点恰好不可达，别把它固化 30 秒）。
+  if (fresh && fresh.clips && fresh.clips.length) candidateCache = { at: Date.now(), value: fresh };
+  return fresh;
+}
+
+async function fetchCandidatesUncached() {
   // ① 站点分类接口（与壁纸同一个接口，只是 category 不同）
   const site = siteBase();
   if (site) {
@@ -199,7 +213,7 @@ export function registerBootRoutes(webServer, c) {
       let force = false;
       try { force = new URL(req.url || '/', 'http://x').searchParams.get('refresh') === '1'; } catch { /* ignore */ }
       if (force) await resolveModules(true);
-      const [boot, candidates] = await Promise.all([Promise.resolve(readBoot()), fetchCandidates()]);
+      const [boot, candidates] = await Promise.all([Promise.resolve(readBoot()), fetchCandidates(force)]);
       const local = listLocalClips();
       const localById = new Map(local.map((x) => [x.id, x]));
       const clips = candidates.clips.map((c) => {

package/lib/routes/inventory.js

@@ -102,6 +102,10 @@ function rowStatusOf(probe) {
  * 站点格式（`<site>/manifest.json`）：`{ images: [{ file, title, url, preview, kind?, animated? }] }`
  * —— 与 `folia-wallpaper-site` 产物一致；`url`/`preview` 可以是相对路径（相对站点基址）。
  */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
 const FOLIA_SITE = 'https://folia-5ve.pages.dev';
 /**
  * 站点数据源的两个可能形态，按顺序尝试：
@@ -143,7 +147,46 @@ const FOLIA_TIMEOUT_MAX_MS = 15000;
  * 说清"为什么没有云端壁纸"，而不是静默空库 —— 之前就是静默失败，排查时无从下手。
  * @type {{ at: number, items: any[], status: { url: string, ok: boolean, count: number, ms: number, error: string|null } | null }}
  */
-let foliaCache = { at: 0, items: [], status: null };
+/**
+ * 站点清单的磁盘缓存：`~/.dsh-folia/cache/site-items.json`。
+ *
+ * 为什么落盘：内存缓存只活一个进程。没有它，**每次重启后第一次打开面板**都要等一次
+ * 完整的跨境往返（实测 ~800ms），这段时间界面是空的。有了它，冷启动也能立刻出内容。
+ *
+ * 纪律：读失败一律当"没有缓存"（坏缓存只该慢一次，不该出错）；只缓存**成功**的结果，
+ * 失败不落盘 —— 否则一次断网会把空列表固化下来，之后每次启动都显示没壁纸。
+ */
+function foliaDiskCachePath() {
+  const home = process.env.DSH_FOLIA_HOME || join(homedir(), '.dsh-folia');
+  return join(home, 'cache', 'site-items.json');
+}
+
+function readFoliaDiskCache() {
+  try {
+    const doc = JSON.parse(readFileSync(foliaDiskCachePath(), 'utf8'));
+    if (!doc || !Array.isArray(doc.items) || !doc.items.length) return null;
+    return { at: Number(doc.at) || 0, items: doc.items, status: doc.status || null };
+  } catch {
+    return null;
+  }
+}
+
+function writeFoliaDiskCache(entry) {
+  try {
+    const p = foliaDiskCachePath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify({ at: entry.at, items: entry.items, status: entry.status }));
+  } catch { /* 只读盘 / 配额：写不进去只影响下次速度，不影响正确性 */ }
+}
+
+/** 内存缓存；**用磁盘缓存打底** —— 冷启动第一次请求就能立刻返回旧列表。 */
+let foliaCache = (() => {
+  const disk = readFoliaDiskCache();
+  return disk ? { at: disk.at, items: disk.items, status: disk.status } : { at: 0, items: [], status: null };
+})();
+
+/** 后台刷新是否在途（避免多个请求同时触发同一次刷新）。 */
+let foliaRefreshInflight = false;
 
 /** 超时从 env 读，越界收敛到 [1s, 15s]。`DSH_FOLIA_SITE_TIMEOUT_MS=8000` 可放宽弱网。 */
 function foliaTimeoutMs() {
@@ -291,12 +334,32 @@ function foliaTypeOf(it) {
  *   `disabled` 通道被 `DSH_FOLIA_SITE=off` 关掉 · `timeout` 超时 · `tls` 证书问题
  *   `http-<code>` 状态码非 2xx · `json` 清单不是合法 JSON · `network` 其它网络错误
  */
+/**
+ * 对外入口：**先给已有结果，再后台刷新**（stale-while-revalidate）。
+ *
+ * 这是面板"打开就能看到东西"的关键：清单过期 ≠ 让用户等。有缓存就立刻返回，
+ * 同时后台拉一次新的（下次打开就是新的）。只有**一条缓存都没有**时才会阻塞等待。
+ */
 async function foliaRemote(force = false) {
   const base = foliaSiteBase();
   if (!base) return { items: [], status: null };
-  if (!force && Date.now() - foliaCache.at < FOLIA_TTL_MS) {
+
+  const fresh = Date.now() - foliaCache.at < FOLIA_TTL_MS;
+  if (!force && foliaCache.items.length) {
+    if (!fresh && !foliaRefreshInflight) {
+      foliaRefreshInflight = true;
+      // 有意不 await：这次先把旧列表发出去，刷新结果留给下一次请求。
+      foliaRefresh().catch(() => {}).finally(() => { foliaRefreshInflight = false; });
+    }
     return { items: foliaCache.items, status: foliaCache.status };
   }
+  return foliaRefresh();
+}
+
+/** 真正去站点抓一次（缓存为空、或调用方要求强制刷新时走这里）。 */
+async function foliaRefresh(force = false) {
+  const base = foliaSiteBase();
+  if (!base) return { items: [], status: null };
 
   const startedAt = Date.now();
   /** @type {any[]} */
@@ -391,11 +454,19 @@ async function foliaRemote(force = false) {
     error,
     at: Date.now(),
   };
-  // 失败也写缓存：否则每次 /inventory 都要再等一次超时。
+  // 失败也写内存缓存：否则每次 /inventory 都要再等一次超时。
   foliaCache = { at: Date.now(), items, status };
+  // **成功**才落盘（失败了别把空列表固化到磁盘上）。
+  if (!error && items.length) writeFoliaDiskCache(foliaCache);
   return { items, status };
 }
 
+// 启动预热：插件一装好就在后台抓一次站点清单，这样**重启后的第一次打开面板**也不冷。
+// 有意不 await、失败静默 —— 预热只是优化，绝不能影响启动。
+export function warmInventorySiteCache() {
+  try { foliaRemote(true).catch(() => {}); } catch { /* ignore */ }
+}
+
 export function registerInventoryRoutes(webServer, c) {
   const { disposers, base: BASE, mediaOriginApi, buildInventory, componentsProbe } = c;
 

package/lib/routes/modules.js

@@ -168,6 +168,12 @@ export async function resolveModules(force = false) {
   return payload;
 }
 
+// 启动预热：模块索引很小（~1.6KB），但第一跳要走站点代理；提前拉一次，
+// 开机动画页签第一次打开就不用等这一跳。
+export function warmModulesCache() {
+  try { resolveModules(true).catch(() => {}); } catch { /* ignore */ }
+}
+
 export function registerModulesRoutes(webServer, c) {
   const { disposers, base: BASE } = c;
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-folia",
-    "version":  "4.0.0",
+    "version":  "4.0.1",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {