dsh-folia 4.13.0 → 4.14.0

package/cordis.patch.yml

@@ -1,23 +1,24 @@
 # dsh-plugin-folia bundle patch.
 #
-# ⚠️ 这里**只有一条** row。皮肤中心由桌面端/市场自己那条 row 负责，我们不再插第二条（见下）。
+# 两条 row：我们自己的 `folia` + 随身携带的皮肤中心 `skin-center`。
 #
-# ── 为什么不再声明 skin-center 的 row 与依赖（2026-10-30 实测）─────────────────
-# 我们一厢情愿地"随身携带"皮肤中心（`dependencies` + 第二条 insert row），结果与桌面端自己
-# 管理的同一条 row 撞了：`.dsh-market/log.ndjson` 每次启动都会写
+# ── 皮肤中心为什么"带过一次、去掉、又带回来"（两次都是实测结论）──────────────
+# 1) 4.12.x：带着它（dependencies + row）→ 0.4.12 的 engines 要求 `dsh >= 0.2.1-rc.3`，
+#    而当时桌面端是 0.2.1-rc.2 ⇒ 市场把这条行**保持为 off**：
+#       ".dsh-market/log.ndjson": "plugin kept off: @linxin666/dsh-client-ui-skin-center"
+#    `/api/skin-center/v2/*` 整族变成路由 miss（带会话实测 404），页签点「应用」必失败。
+#    当时把依赖钉到 0.4.8 只在一两次启动里有效，桌面端会把 0.4.12 投影回来 ⇒ 又 off。
+# 2) 现在：桌面端基线升到 0.2.1-rc.3+（本机实测 dsh=0.2.1-rc.3），engines 满足 ⇒ 可以正常携带。
+#    携带的意义：用户装 dsh-folia 就同时得到"皮肤渲染方"，不必再自己去市场找。
 #
-#     "@linxin666/dsh-client-ui-skin-center -> off: fiber=true"
-#     "plugin kept off: @linxin666/dsh-client-ui-skin-center"
-#
-# 也就是**它被关掉了**，于是 `/api/skin-center/v2/*` 整族变成路由 miss（带会话实测：404），
-# 「助手皮肤」页签里点「应用」必然失败。把依赖钉到 0.4.8 只在那一次启动里生效，桌面端重启后
-# 会把 0.4.12 投影回来（engines 要求 `dsh >= 0.2.1-rc.3`，而当前桌面端是 rc.2）→ 又被关掉。
-# 直接改 profile 的 package.json / overrides 会让桌面端"Profile 恢复未完成"进安全模式 —— 那条路
-# 我们已经走过一次并回滚，不再重复。
-#
-# 结论：**不由我们替用户装这个插件**。它该由用户在自己的插件市场/桌面端里装（那里管版本与引擎
-# 匹配），我们的页签只做两件事：把站点 zip 解到 `$DSH_HOME/skins`，以及在它确实在跑时写选择。
-# 判据见 test/verify-skin-center-bundle.mjs：**只允许一条 row**，且不得再声明为依赖。
+# ── 仍然保留的纪律 ─────────────────────────────────────────────────────────
+# · 重复挂载是安全的（实测）：宿主侧 apply 走 `mountOnce`，客户端 slots.register 包 try/catch
+#   ⇒ 用户市场里再装一份也不会打起来（第二次是空操作）。
+# · 若某台机器 dsh 低于 0.4.12 的要求：市场会 keep off，我们的页签会如实显示
+#   "皮肤中心未运行"，壁纸/桌宠/开机动画/玻璃**完全不受影响**（探测四态 + 应用禁用）。
+# · row id 不得以 `folia-` 开头：`lib/subpackage-boot.js#subpackageSpecifiers` 会把
+#   「id 以 folia- 开头的行」当成我们自己的子包去仓库解析（解析不到就抛）。
+# · 依赖版本**精确**（不带 ^）：0.4.9+ 的 engines 会随上游再抬，我们不能让用户被动中招。
 #
 # A patch replaces the targeted row's whole `config`, so only additive `insert`
 # rows appear here (we never override an existing shipped row).
@@ -25,3 +26,5 @@
 - insert:
     - id: folia
       name: 'dsh-folia'
+    - id: skin-center
+      name: '@linxin666/dsh-client-ui-skin-center'

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",
@@ -18340,7 +18339,12 @@ window.__ModuleLoader__.load({
 				        }
 				        setState(doc);
 				        if (doc.siteError && doc.siteError !== "site-off") {
-				          setNote({ ok: false, text: weT("站点清单读不到：{msg}", { msg: String(doc.siteError) }) });
+				          // `site-locked` = 站点整站上锁（登录页 + {"code":"site_locked"}），不是网络/插件问题。
+				          // 给它一句能照做的说明，而不是甩一个 http-401（实测：这个错误码让人误判成插件坏了）。
+				          const msg = doc.siteError === "site-locked"
+				            ? weT("站点已锁定：只对已登录的管理员开放（需站点侧放行 GET /api/public/wallpapers）")
+				            : String(doc.siteError);
+				          setNote({ ok: false, text: weT("站点清单读不到：{msg}", { msg }) });
 				        }
 				      } else {
 				        setNote({ ok: false, text: weT("读取失败：{msg}", { msg: (doc && doc.error) || "unknown" }) });
@@ -18468,11 +18472,19 @@ window.__ModuleLoader__.load({
 				  //   不在 → 明说它是个**独立插件**（不在 dsh-web-all 里），给一条可复制的安装命令
 				  //   unknown（探测失败）→ 保守地按"在"讲，不吓唬用户
 				  const skinCenter = (state && state.skinCenter) || "unknown";
+				  // 用户在插件市场里手动禁用了它 —— 这是最准确的原因，优先于所有 http 状态码推测。
+				  const marketDisabled = Boolean(state && state.skinCenterDisabled);
 				  // `present` 是**唯一**允许点「应用」的状态：只有真的拿到 catalog JSON 才算它在跑。
 				  // `absent`=路由不存在（插件没装/未启用）；`auth-gated`=鉴权在路由前面挡住（无法判定）；
 				  // `unknown`=探测失败。后三种都如实告诉用户"现在点应用不会成功"，而不是让他点了看 404。
 				  const canApply = skinCenter === "present";
-				  if (skinCenter === "absent") {
+				  if (marketDisabled) {
+				    children.push(React.createElement("div", {
+				      key: "hint-disabled",
+				      className: "we-picker__hint",
+				      style: { margin: "6px 0 4px", color: "#ffd08a", lineHeight: "1.6" },
+				    }, weT("皮肤中心被**你在插件市场里禁用了**（市场记录里它在 disabled 列表里）。皮肤的实际渲染方就是它，禁用它 ⇒ 这里只能装/卸皮肤包，不能应用。到插件市场把它重新启用即可（dsh-folia 已把它作为依赖随身携带，不需要另装）。")));
+				  } else if (skinCenter === "absent") {
 				    children.push(React.createElement("div", {
 				      key: "hint-absent",
 				      className: "we-picker__hint",
@@ -20043,8 +20055,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;
@@ -21094,7 +21112,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,305 @@
+/**
+ * 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 { 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);
+    let from = 0;
+    try { from = meta && meta.url === u.toString() && existsSync(part) ? statSync(part).size : 0; } catch { from = 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');
+      }
+      const reader = r.body && typeof r.body.getReader === 'function' ? r.body.getReader() : null;
+      let received = startAt;
+      let wrote = false;
+      if (reader) {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const buf = Buffer.from(value);
+          received += buf.length;
+          if (!out.write(buf)) await new Promise((resolveDrain) => { out.once('drain', resolveDrain); });
+          if (!headOnly && !res.writableEnded) { try { res.write(buf); } catch { /* 客户端走了，继续落盘 */ } }
+          wrote = true;
+        }
+      }
+      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; }
+      let raw = '';
+      try { raw = new URL(req.url || '', 'http://x').searchParams.get('u') || ''; } catch { raw = ''; }
+      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);
+        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

@@ -83,6 +83,23 @@ function siteBase() {
  * 判据用**它自己的 catalog 路由**：该路由不需要鉴权（实测 200），404 就是没装。
  */
 const skinCenterProbe = { at: 0, state: 'unknown', detail: '' };
+
+/**
+ * 皮肤中心是不是被**用户自己在插件市场里禁用了**。
+ *
+ * 为什么要单独读：它被禁用时 DSH 的鉴权中间件先于路由回答 401，和"需要会话"长得一模一样，
+ * 于是页签只能写出"浏览器侧也被鉴权挡住"这种既对又没用的话（实测被用户当成插件故障）。
+ * 市场的 `.dsh-market/state.json` 里有 `disabled` 数组 —— 读它是**只读事实**，比猜准得多。
+ */
+function readMarketDisabled() {
+  try {
+    const p = join(dshHome(), 'profiles', 'web', '.dsh-market', 'state.json');
+    const j = JSON.parse(readFileSync(p, 'utf8'));
+    const list = Array.isArray(j && j.disabled) ? j.disabled : [];
+    return { known: true, skinCenterDisabled: list.includes('@linxin666/dsh-client-ui-skin-center') };
+  } catch { return { known: false, skinCenterDisabled: false }; }
+}
+
 async function probeSkinCenter(hostHeader, force) {
   const now = Date.now();
   if (!force && skinCenterProbe.at && now - skinCenterProbe.at < 30000) return skinCenterProbe.state;
@@ -144,11 +161,26 @@ async function fetchSiteSkins(force) {
       mime: String(it.mime || ''),
       url: String(it.url || ''),
       thumbUrl: it.thumbUrl ? String(it.thumbUrl) : '',
-      tags: (() => { try { return JSON.parse(it.tags || '[]'); } catch { return []; } })(),
+      // 站点现在把 tags 直接给**数组**（旧版给的是字符串化 JSON）。两种都收：
+      // 只认字符串会让「动态」这类标记静默丢失（实测：线上返回 ["皮肤","catppuccin",…]）。
+      tags: (() => {
+        const raw = it.tags;
+        if (Array.isArray(raw)) return raw.map((t) => String(t));
+        try { const parsed = JSON.parse(raw || '[]'); return Array.isArray(parsed) ? parsed.map((t) => String(t)) : []; } catch { return []; }
+      })(),
     }));
     siteCache.error = null;
   } catch (e) {
-    siteCache.error = (e && e.message) || 'fetch-failed';
+    // 把站点的**真实原因**带出来：站点整站上锁时只回 401 + `{"error":{"code":"site_locked"}}`，
+    // 只显示 "http-401" 会让人以为是插件/网络问题（实测就栽在这条上）。
+    const msg = (e && e.message) || 'fetch-failed';
+    const status = /^http-(\d+)$/.exec(msg);
+    if (status) {
+      const code = Number(status[1]);
+      siteCache.error = (code === 401 || code === 403) ? 'site-locked' : msg;
+    } else {
+      siteCache.error = msg;
+    }
     siteCache.items = siteCache.items || [];
   }
   siteCache.at = now;
@@ -320,16 +352,19 @@ export function registerSkinsRoutes(webServer, c) {
         installedKeys.add(normSkinId(s.id));
         installedKeys.add(normSkinId(s.dirId));
       }
+      const market = readMarketDisabled();
       sendJson(res, 200, {
         ok: true,
         skinCenter,
+        // 用户在插件市场里**手动禁用**它 ⇒ 这是我们能给出的最准确的原因（比 401 含糊其辞好）
+        skinCenterDisabled: market.skinCenterDisabled,
+        skinCenterMarketKnown: market.known,
         skinCenterDetail: skinCenterProbe.detail || '',
-        // 皮肤中心被"保持为 off"时（peer 版本不匹配等），用户需要知道去改什么。
-        // 这里不动它，只把"它为什么可能不在"说清楚：我们钉的是 0.4.8（peer dsh >= 0.2.1-rc.2），
-        // 0.4.9+ 要求 rc.3，装了更高版本就会被市场关掉。
+        // 版本线索：我们随身携带的是 0.4.12（engines 要求 dsh >= 0.2.1-rc.3）。
+        // 低于该内核的机器会被市场 keep off —— 页签据此告诉用户"要么升级桌面端、要么别指望它"。
         skinCenterHint: skinCenter === 'present'
           ? ''
-          : 'skin-center-0.4.8',
+          : 'skin-center-0.4.12',
         siteBase: siteBase(),
         siteError: site.error,
         installed,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-folia",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
   "type": "module",
   "engines": {
@@ -193,6 +193,7 @@
     }
   },
   "dependencies": {
+    "@linxin666/dsh-client-ui-skin-center": "0.4.12",
     "webwallgl": "^3.0.0",
     "x11": "^4.3.1"
   },