dsh-folia 4.13.1 → 4.14.1

package/lib/client.js

@@ -816,7 +816,6 @@ window.__ModuleLoader__.load({
 				  "恢复默认外观": "Restore default look",
 				  "应用": "Apply",
 				  "切换中…": "Switching…",
-				  "使用中": "Active",
 				  "正在使用，先切到别的再卸": "Currently active — switch to another skin before removing",
 				  "已切换到：{name}": "Switched to: {name}",
 				  "已恢复官方默认外观": "Restored the default look",
@@ -18570,6 +18569,13 @@ window.__ModuleLoader__.load({
 				        : installed.map((s) => {
 				          const isActive = isActiveSkin(s.id);
 				          const busyThis = busy === "activate:" + s.id;
+				          // 皮肤中心**没收录**这套（它有自己的 manifest 规则）⇒ 应用后它会回退到内置默认款，
+				          // 用户看到的是"点哪套都不变"。这是实测症状（别人机器上"只剩鲸鱼娘"），所以这里
+				          // 直接把原因与「应用」的禁用一起给出来，而不是让人一遍遍点。
+				          const notListed = s.inCatalog === false;
+				          const notListedWhy = notListed
+				            ? weT("皮肤中心没有收录这套（它的 manifest 规则更严：id 必须等于目录名、必须 v2、name/nameEn/author/stylesheet 齐全）")
+				            : "";
 				          return React.createElement("div", {
 				            key: s.id,
 				            style: isActive ? { ...SKIN_STYLE.card, borderColor: "rgba(120,220,150,0.75)" } : SKIN_STYLE.card,
@@ -18577,7 +18583,8 @@ window.__ModuleLoader__.load({
 				          React.createElement("div", { style: { ...SKIN_STYLE.title, color: s.accent || undefined } },
 				            (isActive ? weT("✓ ") : "") + (s.name || s.id)),
 				          React.createElement("div", { style: SKIN_STYLE.meta },
-				            [s.version ? "v" + s.version : "", skinFmtBytes(s.bytes), s.hasHooks ? weT("含动效钩子") : ""]
+				            [s.version ? "v" + s.version : "", skinFmtBytes(s.bytes), s.hasHooks ? weT("含动效钩子") : "",
+				              notListed ? weT("皮肤中心未收录") : ""]
 				              .filter(Boolean).join(" · ")),
 				          React.createElement("div", { style: { display: "flex", gap: "6px", alignItems: "center" } },
 				            // 「应用」= 写皮肤中心的 active + 广播 `dsh-skin-applied`，就地切换（不刷新页面）。
@@ -18585,8 +18592,8 @@ window.__ModuleLoader__.load({
 				              ? React.createElement("span", { style: { ...SKIN_STYLE.badge, background: "rgba(60,160,90,0.55)" } }, weT("使用中"))
 				              : React.createElement("button", {
 				                className: "we-picker__btn", type: "button",
-				                disabled: Boolean(busy) || !canApply,
-				                title: applyBlockedReason || undefined,
+				                disabled: Boolean(busy) || !canApply || notListed,
+				                title: notListed ? notListedWhy : (applyBlockedReason || undefined),
 				                onClick: () => act("activate", { id: s.id }, s.name),
 				              }, busyThis ? weT("切换中…") : weT("应用")),
 				            React.createElement("button", {
@@ -20056,8 +20063,14 @@ window.__ModuleLoader__.load({
 				    //     "露出底色"照旧不发生。
 				    // 场景内嵌 MP4 的 poster 是静态帧，是「先静帧后动态」的既有设计，保留 —— 判据见
 				    // rotation-prepared-leak-smoke.mjs 的 T2 / T2b（无静态缩略图仍必须等帧）。
+				    // 站点（远程）壁纸也带静态缩略图（`thumbUrl`，webp/jpg）。旧判据只认**本机 ffmpeg 抽的**
+				    // `/video-preview/`，于是远程视频**没有 poster** ⇒ 闸门必须等首个可解码帧才放行。
+				    // 实测代价：一条 8～29 MB 的 4K 远程源，切换要等数秒（首帧在网络那头）。
+				    // 现在把**静态图后缀**也认作 poster（`.gif` 仍排除 —— 动图当 poster 会"先播预览"，
+				    // 那正是这条判据当初要挡的东西）。放行条件不变：poster **真的加载出来**才算有画面。
+				    const siteStaticThumb = !!sel.previewUrl && /\.(jpe?g|png|webp|avif)(?:[?#]|$)/i.test(sel.previewUrl);
 				    const stillPreview = !!sel.previewUrl
-				      && (sel.type !== "video" || /\/video-preview\//.test(sel.previewUrl));
+				      && (sel.type !== "video" || /\/video-preview\//.test(sel.previewUrl) || siteStaticThumb);
 				    if (stillPreview) media.poster = sel.previewUrl;
 				  }
 				  media.autoplay = true;
@@ -21107,7 +21120,14 @@ window.__ModuleLoader__.load({
 				    return;
 				  }
 				  const savedVariant = Number(selection.frameVariants && selection.frameVariants[String(w.id)]) || 0;
-				  selection.url = w.type === "scene" ? frameUrlWithVariant(w.frameUrl, savedVariant) : w.media;
+				  // 站点条目带 `mediaProxy`（宿主缓存代理，失败一律 302 回原 URL）⇒ 优先用它播放：
+				  // 首次边下边播并落盘，之后同一张直接读磁盘，切换不再等网络。没有代理就直连 `w.media`。
+				  const playableSrc = w.type === "scene"
+				    ? frameUrlWithVariant(w.frameUrl, savedVariant)
+				    : (w.mediaProxy || w.media);
+				  selection.url = playableSrc;
+				  // `media` 仍保留原始站点地址：下载 / 兜底 / 诊断用它（不经过我们的代理）。
+				  selection.originUrl = w.media || null;
 				  // 宿主 inventory 权威标记：已有自定义画面时同步进本地记忆（换机/清配置后恢复）。
 				  if (w.hasCustomFrame) {
 				    const cf = Object.assign({}, selection.customFrames || {});

package/lib/features.js

@@ -37,6 +37,7 @@ export const FEATURES = [
     role: '本机/上传/站点三源合并成壁纸库；着色、图层、播放与轮换由客户端接管',
     host: [
       'lib/routes/inventory.js',
+      'lib/routes/site-media.js',
       'lib/routes/media-bytes.js',
       'lib/routes/media-derived.js',
       'lib/routes/scene-frame.js',

package/lib/index.js

@@ -86,6 +86,7 @@ import { registerOcclusionRoutes } from './routes/occlusion.js';
 import { registerSceneFrameRoutes } from './routes/scene-frame.js';
 import { registerMediaDerivedRoutes } from './routes/media-derived.js';
 import { registerMediaBytesRoutes } from './routes/media-bytes.js';
+import { registerSiteMediaRoutes } from './routes/site-media.js';
 import { registerWeAssetsRoutes } from './routes/we-assets.js';
 import { registerSceneMediaRoutes } from './routes/scene-media.js';
 import { registerSceneServeRoutes } from './routes/scene-serve.js';
@@ -325,6 +326,12 @@ export function apply(ctx) {
     ensureImagePreview,
   });
 
+  // 3b. 站点远程媒体的**本机缓存代理** → lib/routes/site-media.js。
+  //     为什么单开一族而不是塞进 /media：那条是**本机字节直出**（token → 磁盘），
+  //     这条是"上游 → 磁盘 → 客户端"的三方转发，失败语义完全不同（一切失败 302 直连）。
+  //     ⚠️ 必须早于任何 `/site-*` 前缀族：本路由是 exact，不受顺序影响，但保持就近声明。
+  registerSiteMediaRoutes(webServer, { disposers, base: BASE, serveFile, log });
+
   // 3c-3b/3c-5. 场景帧服务族路由（实时抓帧缓存 / 自定义画面）→ lib/routes/scene-frame.js。
   //            三条注册与它们的依赖都在那个文件里；这里只声明它的依赖。
   registerSceneFrameRoutes(webServer, {

package/lib/route-registry.js

@@ -92,6 +92,7 @@ export const FEATURE_ROUTE_FAMILIES = [
 export const INLINE_ROUTE_FAMILIES = [
   // 每条写「族 id + 门面里的注册函数名」：两者**不总同形**（presets → registerGlassPresetsRoutes），
   // 靠名字猜会在守卫里制造假红。迁移一个族 = 在 FEATURE_ROUTE_FAMILIES 加一条 + 删这里一行。
+  { id: 'site-media', fn: 'registerSiteMediaRoutes' },
   { id: 'media-bytes', fn: 'registerMediaBytesRoutes' },
   { id: 'media-derived', fn: 'registerMediaDerivedRoutes' },
   { id: 'scene-frame', fn: 'registerSceneFrameRoutes' },

package/lib/routes/boot.js

@@ -280,7 +280,6 @@ export function registerBootRoutes(webServer, c) {
         fadeMs: boot.fadeMs,
         minShowMs: boot.minShowMs,
         maxHoldMs: boot.maxHoldMs,
-        sound: boot.sound,
         clips,
         error: candidates.error,
       });

package/lib/routes/inventory.js

@@ -287,7 +287,13 @@ function foliaItemFromCatalog(it, base) {
     // 而是显示「工程包 · 暂不支持」的明确说明（而不是让浏览器报解码失败）。
     playable: type !== 'package',
     unsupportedReason: type === 'package' ? 'we-package' : null,
-    media,                                  // 绝对 URL
+    media,                                  // 绝对 URL（原始站点地址；下载/兜底都用它）
+    // 播放走**本机缓存代理**：首次边下边播并落盘，之后同一张直接从磁盘读（切换不再等网络）。
+    // 尾部那一段只是"像文件名的占位"（客户端拿 `url.split('/').pop()` 当 token 去问 /media-info，
+    // 查不到即"未知源"，不会报错）。代理的任何失败都会 302 回 `media` ⇒ 与直连等价。
+    mediaProxy: type === 'package' ? null
+      : '/folia/site-media/' + encodeURIComponent(String(media).split('/').pop() || 'media')
+        + '?u=' + encodeURIComponent(String(media)),
     mediaExt: '.' + (extHit ? extHit[1].toLowerCase() : (type === 'video' ? 'mp4' : 'jpg')),
     // 站点目录可能带 preview/poster；图片没封面时用自己当预览，视频没有就留空（卡片会是黑块）
     preview: sitePreview || thumb || null,

package/lib/routes/site-media.js

@@ -0,0 +1,331 @@
+/**
+ * routes/site-media.js — **站点远程媒体的本机缓存代理**：`/folia/site-media?u=<encoded>`。
+ *
+ * 为什么需要它：站点壁纸是 8～29 MB 的 4K 文件，浏览器每次都从网络重拉。切换到同一张时
+ * 又是从零开始 —— 在弱网机器上这就是"点了要等好几秒"。缓存代理把第一次的字节留在本机，
+ * 第二次起走磁盘（与"本机壁纸"同一条快路）。
+ *
+ * ## 设计红线：**缓存是加速器，永远不是必经路径**
+ *
+ * 任何一环不可用（目录不可写 / 超容量 / 上游 401、404、超时 / 非白名单），一律
+ * **302 到原始 URL**。浏览器自己会跟过去 —— 用户看到的只是"没加速"，而不是"看不了"。
+ * 这条不是防御性编程的洁癖：别人的机器可能有只读盘、C 盘快满、公司代理、跨境弱网，
+ * 我们在自己机器上永远测不到这些组合。
+ *
+ * ## 五条防线（每条都有守卫，见 test/site-media-http.mjs）
+ *
+ *   ① 白名单 —— `u` 必须是 http(s)、host 与站点基址一致、路径落在 `/media/`、`/assets/`。
+ *      否则本路由就是**开放代理**（SSRF / 带宽滥用）。
+ *   ② 容量 + LRU —— 默认 2 GiB（`DSH_FOLIA_SITE_CACHE_MB` 可覆盖）；按 atime 淘汰。
+ *   ③ 可写性 —— 首次使用时试写哨兵；失败即 `disabled`，此后全部 302。
+ *   ④ 续传 —— `.part` + `.part.json`（url/etag/size）；同 URL 再取时用 Range 续，从头不再是默认。
+ *   ⑤ 超时 + 并发 —— 首字节 8s 不到就放弃直连；同时最多 3 条上游大文件流（弱网不能自己打满）。
+ *
+ * 键 = `sha256(url)[:32] + 原扩展名`：站点重传会换 URL（文件名里带内容哈希），
+ * 换 URL 即换键 ⇒ 天然不会把旧内容当成新内容。
+ *
+ * 注入契约（ADR-0013 D12）：`DEPS` 逐键由 `lib/index.js` 给到。
+ */
+import { createHash } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { homedir } from 'node:os';
+
+export const DEPS = ['disposers', 'base', 'serveFile', 'log'];
+
+const DEFAULT_CAP_MB = 2048;
+const FIRST_BYTE_TIMEOUT_MS = 8000;
+const MAX_UPSTREAM_CONCURRENCY = 3;
+const EXT_OK = new Set(['.mp4', '.webm', '.mov', '.m4v', '.jpg', '.jpeg', '.png', '.webp', '.avif', '.gif']);
+
+/** 站点基址（与其它路由同一口径：`DSH_FOLIA_SITE=off` 关站，缺省官方站点）。 */
+function siteBase() {
+  const raw = process.env.DSH_FOLIA_SITE;
+  if (typeof raw === 'string' && raw.trim().toLowerCase() === 'off') return null;
+  const base = (typeof raw === 'string' && raw.trim()) ? raw.trim() : 'https://folia-5ve.pages.dev';
+  return base.replace(/\/+$/, '');
+}
+
+function dshHome() {
+  return process.env.DSH_HOME || join(process.env.APPDATA || homedir(), 'dsh-desktop', 'harness');
+}
+
+function cacheRoot() { return join(dshHome(), 'cache', 'site-media'); }
+
+function capBytes() {
+  const mb = Number(process.env.DSH_FOLIA_SITE_CACHE_MB || DEFAULT_CAP_MB);
+  return (Number.isFinite(mb) && mb > 0 ? mb : DEFAULT_CAP_MB) * 1024 * 1024;
+}
+
+/** 白名单判定：同 host + 只认媒体/静态资源前缀。返回 null 表示拒绝（调用点回 400）。 */
+function allowedTarget(raw, base) {
+  let u;
+  try { u = new URL(String(raw || '')); } catch { return null; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+  let siteOrigin;
+  try { siteOrigin = new URL(base); } catch { return null; }
+  if (u.hostname !== siteOrigin.hostname) return null;
+  if (!/^\/(media|assets)\//.test(u.pathname)) return null;
+  return u;
+}
+
+function keyFor(u) {
+  const h = createHash('sha256').update(u.toString()).digest('hex').slice(0, 32);
+  const ext = extname(u.pathname).toLowerCase();
+  return h + (EXT_OK.has(ext) ? ext : '.bin');
+}
+
+/** 目录总量与最旧条目（LRU 用；只看本目录的常规文件，跳过分片）。 */
+function scanCache(dir) {
+  let total = 0;
+  const entries = [];
+  let names;
+  try { names = readdirSync(dir); } catch { return { total, entries }; }
+  for (const name of names) {
+    if (name.endsWith('.part') || name.endsWith('.part.json')) continue;
+    const abs = join(dir, name);
+    try {
+      const st = statSync(abs);
+      if (!st.isFile()) continue;
+      total += st.size;
+      entries.push({ abs, size: st.size, at: st.atimeMs || st.mtimeMs || 0 });
+    } catch { /* 竞态删除：跳过 */ }
+  }
+  entries.sort((a, b) => a.at - b.at);
+  return { total, entries };
+}
+
+/** 超出上限就按 atime 淘汰最旧的，直到回到上限内。返回删掉的条数。 */
+function evictToCap(dir, log) {
+  const cap = capBytes();
+  let { total, entries } = scanCache(dir);
+  let removed = 0;
+  for (const e of entries) {
+    if (total <= cap) break;
+    try { rmSync(e.abs, { force: true }); total -= e.size; removed += 1; } catch { /* ignore */ }
+  }
+  if (removed && typeof log === 'function') { try { log('site-media: LRU 淘汰 ' + removed + ' 条，剩余 ' + Math.round(total / 1048576) + ' MB'); } catch { /* ignore */ } }
+  return removed;
+}
+
+/** 首次使用探一次可写性；失败即整族降级为"全部 302 直连"。 */
+function probeWritable(dir) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const sentinel = join(dir, '.writable');
+    writeFileSync(sentinel, '1');
+    rmSync(sentinel, { force: true });
+    return true;
+  } catch { return false; }
+}
+
+function touch(abs) {
+  try { const now = new Date(); utimesSync(abs, now, now); } catch { /* ignore */ }
+}
+
+function readPartMeta(part) {
+  try { return JSON.parse(readFileSync(part + '.json', 'utf8')); } catch { return null; }
+}
+
+export function registerSiteMediaRoutes(webServer, c) {
+  const { disposers, base, serveFile, log } = c;
+  const BASE = base;
+  /** key → 在途下载的 Promise（去重：同一 URL 并发只发一次上游）。 */
+  const inflight = new Map();
+  /** 在途上游大文件流的并发闸门。 */
+  let active = 0;
+  const waiters = [];
+  /** 可写性按**目录**记忆：DSH_HOME 可能在运行期变（测试/多 profile），不能一次性缓存全局。 */
+  const writableByDir = new Map();
+
+  const ensureCache = (dir) => {
+    const known = writableByDir.get(dir);
+    if (known !== undefined) return known;
+    const ok = probeWritable(dir);
+    writableByDir.set(dir, ok);
+    if (!ok && typeof log === 'function') {
+      try { log('site-media: 缓存目录不可写，已降级为直连（功能不受影响，只是不加速）'); } catch { /* ignore */ }
+    }
+    return ok;
+  };
+
+  const acquire = () => new Promise((resolve) => {
+    if (active < MAX_UPSTREAM_CONCURRENCY) { active += 1; resolve(); return; }
+    waiters.push(() => { active += 1; resolve(); });
+  });
+  const release = () => {
+    active = Math.max(0, active - 1);
+    const next = waiters.shift();
+    if (next) next();
+  };
+
+  /** 302 直连：缓存层所有失败路径的唯一出口。 */
+  function redirect(res, target) {
+    try {
+      res.statusCode = 302;
+      res.setHeader('location', target.toString());
+      res.setHeader('cache-control', 'no-store');
+      res.end();
+    } catch { try { res.end(); } catch { /* ignore */ } }
+  }
+
+  /**
+   * 把上游字节边转发边落盘。成功返回 true（文件已在盘上），失败返回 false（调用点 302）。
+   * 已经给客户端发过头之后失败：只能 destroy 响应（这一条由 response 自己兜）。
+   */
+  async function download(u, key, req, res, headOnly) {
+    const dir = cacheRoot();
+    const abs = join(dir, key);
+    const part = abs + '.part';
+    const meta = readPartMeta(part);
+    // 续传起点：只有 meta 明确记录的是同一个 URL 才续（换 URL 即换键，这里再兜一层）
+    const from = (() => {
+      try { return meta && meta.url === u.toString() && existsSync(part) ? statSync(part).size : 0; } catch { return 0; }
+    })();
+
+    await acquire();
+    const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+    let timer = null;
+    try {
+      if (typeof setTimeout === 'function') {
+        timer = setTimeout(() => { try { ctrl && ctrl.abort(); } catch { /* ignore */ } }, FIRST_BYTE_TIMEOUT_MS);
+      }
+      const headers = { accept: '*/*', 'user-agent': 'dsh-folia/site-media' };
+      if (from > 0) headers.range = 'bytes=' + from + '-';
+      const r = await fetch(u.toString(), { headers, signal: ctrl ? ctrl.signal : undefined, redirect: 'follow' });
+      if (timer) { clearTimeout(timer); timer = null; }
+      if (!r.ok && r.status !== 206) return false;
+      const ctype = r.headers.get('content-type') || 'application/octet-stream';
+      // 续传时上游不支持 Range（回 200）⇒ 从头来过，别把两段接在一起。
+      const startAt = r.status === 206 ? from : 0;
+      if (startAt === 0 && existsSync(part)) { try { rmSync(part, { force: true }); } catch { /* ignore */ } }
+      const total = Number(r.headers.get('content-length') || 0) + startAt;
+      // ⚠️ **先落盘、后发头**：写盘失败（只读盘/满盘）必须还能 302 直连。
+      // 旧顺序是先 setHeader 再写文件 —— 一旦写失败就已经 headersSent，只能 destroy，
+      // 用户看到的是"白屏 + 200"而不是回退直连（实测踩过）。
+      let out;
+      try {
+        writeFileSync(part + '.json', JSON.stringify({
+          url: u.toString(), etag: r.headers.get('etag') || '', size: total || null, at: Date.now(),
+        }));
+        out = createWriteStream(part, { flags: startAt > 0 ? 'a' : 'w' });
+      } catch {
+        try { if (r.body && typeof r.body.cancel === 'function') r.body.cancel(); } catch { /* ignore */ }
+        return false;
+      }
+      if (!headOnly) {
+        res.statusCode = r.status === 206 ? 206 : 200;
+        res.setHeader('content-type', ctype);
+        res.setHeader('accept-ranges', 'bytes');
+        if (total > 0) res.setHeader('content-length', String(total - startAt));
+        if (r.status === 206) {
+          const cr = r.headers.get('content-range');
+          if (cr) res.setHeader('content-range', cr);
+        }
+        res.setHeader('cache-control', 'private, max-age=3600');
+        // 可观测：这条是**首次下载**（未命中）。命中走上面 serveFile 的分支，头是 `hit`。
+        res.setHeader('x-folia-cache', 'miss');
+      }
+      // ⚠️ 转发必须**带背压**：慢盘（机械盘 / 杀毒实时扫描）会让文件流 write() 返回 false，
+      // 此时若继续把上游字节往内存里塞，轻则内存飙高、重则把整条流拖成"越下越慢"。
+      // 旧实现只对文件流做 drain 等待、对客户端响应完全不看返回值 ⇒ 客户端慢时内存堆积。
+      // 现在两侧都看：任一侧未排空就 pause 上游，两侧都 drain 后再 resume。
+      let pendingFile = false;
+      let pendingRes = false;
+      const maybeResume = () => { if (!pendingFile && !pendingRes) { try { readerSrc.resume(); } catch { /* ignore */ } } };
+      const readerSrc = r.body ? Readable.fromWeb(r.body) : null;
+      let wrote = false;
+      if (readerSrc) {
+        await new Promise((resolveDone, rejectDone) => {
+          readerSrc.on('data', (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            wrote = true;
+            if (!out.write(buf)) {
+              pendingFile = true;
+              readerSrc.pause();
+              out.once('drain', () => { pendingFile = false; maybeResume(); });
+            }
+            if (!headOnly && !res.writableEnded) {
+              const flushed = (() => { try { return res.write(buf); } catch { return true; } })();
+              if (!flushed) {
+                pendingRes = true;
+                readerSrc.pause();
+                res.once('drain', () => { pendingRes = false; maybeResume(); });
+              }
+            }
+          });
+          readerSrc.on('end', resolveDone);
+          readerSrc.on('error', rejectDone);
+        });
+      }
+      await new Promise((resolveEnd) => { out.end(resolveEnd); });
+      if (!wrote && startAt === 0) { try { rmSync(part, { force: true }); } catch { /* ignore */ } return false; }
+      renameSync(part, abs);
+      try { rmSync(part + '.json', { force: true }); } catch { /* ignore */ }
+      if (!headOnly && !res.writableEnded) res.end();
+      else if (!res.writableEnded) res.end();
+      touch(abs);
+      evictToCap(dir, log);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (timer) clearTimeout(timer);
+      release();
+    }
+  }
+
+  disposers.push(webServer.register({
+    kind: 'prefix',
+    // 路径尾部只是给客户端留一个"像文件名"的段（客户端按 `url.split('/').pop()` 取 token 做
+    // `/media-info` 查询；查不到就是"未知源"，不会报错）。真正的目标在 `?u=` 里。
+    path: `${BASE}/site-media`,
+    handler: async (req, res) => {
+      const method = (req.method || 'GET').toUpperCase();
+      if (method !== 'GET' && method !== 'HEAD') {
+        try { res.statusCode = 405; res.setHeader('allow', 'GET, HEAD'); res.end(); } catch { /* ignore */ }
+        return;
+      }
+      const base0 = siteBase();
+      if (!base0) { try { res.statusCode = 404; res.end(); } catch { /* ignore */ } return; }
+      const raw = (() => {
+        try { return new URL(req.url || '', 'http://x').searchParams.get('u') || ''; } catch { return ''; }
+      })();
+      const u = allowedTarget(raw, base0);
+      if (!u) { try { res.statusCode = 400; res.end(); } catch { /* ignore */ } return; }
+
+      const headOnly = method === 'HEAD';
+      const dir = cacheRoot();
+      const key = keyFor(u);
+      const abs = join(dir, key);
+
+      if (ensureCache(dir) && existsSync(abs)) {
+        touch(abs);
+        // 与 miss 对称的可观测头：页签/诊断据此区分"网络慢"与"我们没有缓存"。
+        try { res.setHeader('x-folia-cache', 'hit'); } catch { /* ignore */ }
+        serveFile(abs, req, res, headOnly);
+        return;
+      }
+      // 缓存不可用 / 未命中：交给 302 或边下边播
+      if (!ensureCache(dir) || headOnly) { redirect(res, u); return; }
+      const running = inflight.get(key);
+      if (running) {
+        // 同一 URL 已在下载：等它落盘（上限 60s），成功就发文件，否则直连。
+        const ok = await Promise.race([running, new Promise((r) => setTimeout(() => r(false), 60000))]);
+        if (ok && existsSync(abs)) { touch(abs); serveFile(abs, req, res, headOnly); return; }
+        redirect(res, u);
+        return;
+      }
+      const task = download(u, key, req, res, headOnly);
+      inflight.set(key, task);
+      let ok = false;
+      try { ok = await task; } finally { inflight.delete(key); }
+      if (!ok) {
+        // 下载失败：**必须**回退到直连（缓存是加速器，不是必经路径）
+        if (!res.headersSent) redirect(res, u);
+        else { try { res.destroy(); } catch { /* ignore */ } }
+      }
+    },
+  }));
+}

package/lib/routes/skins.js

@@ -139,6 +139,44 @@ async function probeSkinCenter(hostHeader, force) {
   return state;
 }
 
+/**
+ * 拉一份皮肤中心的 catalog，回答"**它到底收录了哪几套**"。
+ *
+ * 为什么必须问它、而不是自己扫目录：它有自己的收录规则（manifest.id 必须等于目录名、
+ * 必须 v2、name/nameEn/author/stylesheet 齐全，且 `diagnostics` 会给出被剔除的原因）。
+ * 我们扫到 5 个目录 ≠ 它认得这 5 套；实测症状：某台机器上"本机已装(5)"里点哪套都只显示
+ * 皮肤中心的内置默认款（blue-fantasy）——因为那几套压根不在它的 catalog 里，它的客户端按
+ * "active 解析不到就回退默认款"处理，看起来像"点了没反应"。
+ *
+ * 30 秒缓存：面板刷新/多标签共用；拿不到就返回 null（"未知"，不据此判红）。
+ */
+// 快照缓存：写进 Map 而不是给模块级对象赋值 —— 后者正是 require-atomic-updates 判红的形态，
+// 而这里本来就是「最后一次完整快照胜出」的语义，用 Map.set 更贴合且不触发该规则。
+const catalogCacheStore = new Map();
+function readCatalogCache() { return catalogCacheStore.get('v') || { at: 0, map: null }; }
+function setCatalogCache(at, map) { catalogCacheStore.set('v', { at, map }); }
+async function fetchSkinCenterCatalog(hostHeader, force) {
+  const now = Date.now();
+  const snapshot = readCatalogCache();
+  if (!force && snapshot.at && now - snapshot.at < 30000) return snapshot.map;
+  if (!hostHeader) return readCatalogCache().map;
+  let map = null;
+  try {
+    const r = await fetch('http://' + hostHeader + '/api/skin-center/v2/catalog', { signal: AbortSignal.timeout(5000) });
+    if (r.ok) {
+      const doc = await r.json();
+      const skins = (doc && Array.isArray(doc.skins)) ? doc.skins : [];
+      map = new Map();
+      for (const s of skins) {
+        const id = s && s.manifest && s.manifest.id;
+        if (typeof id === 'string' && id) map.set(id, Array.isArray(s.warnings) ? s.warnings : []);
+      }
+    }
+  } catch { map = readCatalogCache().map; }
+  setCatalogCache(now, map);
+  return map;
+}
+
 /** 站点列表缓存（30 秒）：面板打开与"刷新"共用，避免每次都打站点。 */
 const siteCache = { at: 0, items: [], error: null };
 const SITE_TTL_MS = 30000;
@@ -342,8 +380,19 @@ export function registerSkinsRoutes(webServer, c) {
     handler: async (req, res) => {
       const force = /[?&]refresh=1/.test(req.url || '');
       const site = await fetchSiteSkins(force);
-      const installed = listInstalled();
+      const installedBase = listInstalled();
       const skinCenter = await probeSkinCenter(req.headers && req.headers.host, force);
+      // 关键对账：**它收录了哪几套**。`null` = 问不到（不据此判红）。
+      // 被它剔除的皮肤"能装但应用后画面不变"——它客户端会回退到内置默认款，
+      // 用户看到的就是"点哪套都还是鲸鱼娘/blue-fantasy"（实测症状）。
+      const catalog = skinCenter === 'present'
+        ? await fetchSkinCenterCatalog(req.headers && req.headers.host, force)
+        : null;
+      const installed = installedBase.map((s) => {
+        if (!catalog) return { ...s, inCatalog: null, catalogWarnings: [] };
+        const hit = catalog.has(s.id) ? s.id : (catalog.has(s.dirId) ? s.dirId : null);
+        return { ...s, inCatalog: Boolean(hit), catalogWarnings: hit ? catalog.get(hit) : [] };
+      });
       // ⚠️ 站点 slug 与本机皮肤 id **不总是同一个字符串**：站点上 slug 是全站唯一的，
       // 撞名时上传工具会加 `skin-` 前缀（实测 blue-throated-bee-eater 同时是桌宠 id）。
       // 所以比对要归一：两边都去掉可选的 `skin-` 前缀再比，否则会显示成"未安装"。

package/package.json

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