dsh-folia 4.0.0 → 4.0.2

package/lib/boot/index.js

@@ -8,6 +8,7 @@
  *     内联 JSON，启动时连一次请求都不发。
  *  3. **任何异常都必须放行**。注入的脚本顶层 try/catch，超时自毁，绝不把用户挡在门外。
  */
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { extname, join } from 'node:path';
@@ -67,12 +68,33 @@ export function writeBoot(patch) {
   return readBoot();
 }
 
-/** 允许的 id：目录名安全字符，防止拿它拼路径时被穿越。 */
-const ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+/**
+ * id → **磁盘文件名**：ASCII 化 + 短哈希。
+ *
+ * 为什么不再拿 id 直接当文件名：站点上的 slug 允许中文（实测有一条叫「痘印」），
+ * 而严格的正则把它判成非法 ⇒ 用户点下载永远是 `bad-id`。id 可以任意宽容，
+ * **文件名必须安全** —— 这两件事不该绑在一起。
+ *
+ * 规则：非 `[a-zA-Z0-9._-]` 一律折成 `-`，再拼 8 位 sha1 前缀，保证
+ *   · 永远不会出现路径分隔符 / `..` / 控制字符；
+ *   · 不同 id 即使折成同一个 ASCII 名也不会互相覆盖；
+ *   · 原始 id 存在同名 `.json` 里，列表读回来还是原来那个。
+ */
+function clipStem(id) {
+  const raw = String(id || '');
+  const ascii = raw.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 40) || 'clip';
+  const hash = createHash('sha1').update(raw).digest('hex').slice(0, 8);
+  return ascii + '-' + hash;
+}
+/** 片段文件。id 可以是任意字符串（含中文），只有磁盘名会被 ASCII 化。 */
 export function clipFile(id) {
-  if (!ID_RE.test(String(id || ''))) return null;
-  const p = join(bootDir(), String(id) + '.mp4');
-  return p;
+  if (!String(id || '')) return null;
+  return join(bootDir(), clipStem(id) + '.mp4');
+}
+/** 片段元数据文件（存原始 id / 标题 / 时长）。 */
+export function clipMetaFile(id) {
+  if (!String(id || '')) return null;
+  return join(bootDir(), clipStem(id) + '.json');
 }
 export function clipExists(id) {
   const p = clipFile(id);
@@ -85,14 +107,21 @@ export function listLocalClips() {
   const out = [];
   let names = [];
   try { names = readdirSync(dir); } catch { return out; }
+  // 以 `.json` 为主：里面有**原始 id**（可能是中文），文件名只是它的 ASCII 代理。
+  const stems = new Set();
   for (const n of names) {
-    if (extname(n).toLowerCase() !== '.mp4') continue;
-    const id = n.slice(0, -4);
-    const abs = join(dir, n);
+    if (extname(n).toLowerCase() === '.json') stems.add(n.slice(0, -5));
+    if (extname(n).toLowerCase() === '.mp4') stems.add(n.slice(0, -4));
+  }
+  for (const stem of stems) {
+    const abs = join(dir, stem + '.mp4');
+    if (!existsSync(abs)) continue;
     let bytes = 0;
     try { bytes = statSync(abs).size; } catch { continue; }
+    if (bytes <= 0) continue;
     let meta = {};
-    try { meta = JSON.parse(readFileSync(join(dir, id + '.json'), 'utf8')) || {}; } catch { /* 没 meta 也能用 */ }
+    try { meta = JSON.parse(readFileSync(join(dir, stem + '.json'), 'utf8')) || {}; } catch { /* 没 meta 也能用 */ }
+    const id = String(meta.id || stem);
     out.push({ id, bytes, title: meta.title || id, durationSec: meta.durationSec || null });
   }
   return out;
@@ -102,7 +131,7 @@ export function removeClip(id) {
   const p = clipFile(id);
   if (!p) return false;
   try { if (existsSync(p)) rmSync(p); } catch { return false; }
-  try { const m = join(bootDir(), String(id) + '.json'); if (existsSync(m)) rmSync(m); } catch { /* ignore */ }
+  try { const m = clipMetaFile(id); if (m && existsSync(m)) rmSync(m); } catch { /* ignore */ }
   return true;
 }
 

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

@@ -14,7 +14,7 @@ import { join } from 'node:path';
 import { sendJson } from '../json-response.js';
 import { bodyReader } from '../http-body.js';
 import { resolveModules } from './modules.js';
-import { bootDir, clipExists, clipFile, listLocalClips, readBoot, removeClip, writeBoot } from '../boot/index.js';
+import { clipExists, clipFile, clipMetaFile, listLocalClips, readBoot, removeClip, writeBoot } from '../boot/index.js';
 
 /**
  * 站点基址。开机动画的候选**从站点分类取**（`?category=boot-animation`），
@@ -118,7 +118,12 @@ async function readIdBody(req) {
     const text = await readBodyText(req, 64 * 1024);
     const doc = JSON.parse(text || '{}');
     const id = String((doc && doc.id) || '').trim();
-    return /^[a-z0-9][a-z0-9._-]*$/i.test(id) ? id : null;
+    // id 来自站点 slug，**可以是中文**（实测有「痘印」）。这里只挡真正的危险输入：
+    // 路径分隔符、控制字符、`..`、超长 —— 其余一律放行，文件名由宿主安全化。
+    if (!id || id.length > 200) return null;
+    if (/[\u0000-\u001f\u007f/\\]/.test(id)) return null;
+    if (id === '.' || id === '..' || id.includes('..')) return null;
+    return id;
   } catch {
     return null;
   }
@@ -128,7 +133,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 +218,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) => {
@@ -259,7 +278,8 @@ export function registerBootRoutes(webServer, c) {
         if (buf.length > CLIP_MAX_BYTES) { sendJson(res, 413, { ok: false, error: 'too-large' }); return; }
         writeFileSync(dest, buf);
         try {
-          writeFileSync(join(bootDir(), id + '.json'), JSON.stringify({
+          writeFileSync(clipMetaFile(id), JSON.stringify({
+            id,
             title: item.title, durationSec: item.durationSec, bytes: buf.length, sha256: item.sha256 || null,
           }, null, 2) + '\n');
         } catch { /* meta 只是锦上添花 */ }

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.2",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {