dsh-folia 4.18.0 → 4.19.1

package/lib/client.js

@@ -19409,6 +19409,49 @@ window.__ModuleLoader__.load({
 				    }
 				  }
 
+				  /**
+				   * 缓存与速度自述（④）。
+				   *
+				   * 目的：用户问"为什么慢"时，答案应该在界面上，而不是让他开 F12 或来问作者。
+				   * 读宿主 `/folia/site-media-stats`（4.15.3 起存在）：命中/未命中/平均吞吐/缓存是否可写。
+				   * 三条纪律：拿不到就**什么都不显示**；每 15 秒最多取一次；任何异常都吞掉（不许影响面板）。
+				   */
+				  function QpCacheHint() {
+				    const [info, setInfo] = React.useState(null);
+				    React.useEffect(() => {
+				      let alive = true;
+				      let timer = null;
+				      const pull = () => {
+				        (async () => {
+				          try {
+				            const r = typeof apiJson === "function" ? await apiJson("/site-media-stats") : null;
+				            const d = (r && r.data) || r || null;
+				            if (alive && d && typeof d === "object") setInfo(d);
+				          } catch { /* 端点不存在（老宿主）⇒ 保持不显示 */ }
+				        })();
+				      };
+				      pull();
+				      try { timer = window.setInterval(pull, 15000); } catch { timer = null; }
+				      return () => {
+				        alive = false;
+				        if (timer !== null) { try { window.clearInterval(timer); } catch { /* ignore */ } }
+				      };
+				    }, []);
+				    if (!info) return null;
+				    const hits = Number(info.hits) || 0;
+				    const misses = Number(info.misses) || 0;
+				    const mbps = Number(info.avgMBps) || 0;
+				    const writable = info.writable !== false;
+				    const parts = [
+				      weT("缓存命中 {h} · 首次下载 {m}", { h: hits, m: misses }),
+				      mbps > 0 ? weT("平均 {v} MB/s", { v: mbps.toFixed(1) }) : "",
+				      writable ? "" : weT("⚠ 缓存目录不可写（每次都会重下）"),
+				    ].filter(Boolean);
+				    return React.createElement("div", {
+				      className: "we-picker__hint",
+				      style: { marginTop: "2px", opacity: 0.75, fontSize: "11px" },
+				    }, parts.join(" · "));
+				  }
 				  function qpRenderCard(w, sel) {
 				    // ── 卡：缩略图网格形态（视图切换的「卡片」档；点击语义与列表行一致）──
 				    return React.createElement("div", {
@@ -19479,6 +19522,9 @@ window.__ModuleLoader__.load({
 				            ? qpTypeLabel(current, sel) + weT(playbackLive ? " · 播放中" : " · 已暂停")
 				            : weT("从下面列表挑一张")),
 				        sel.videoError && React.createElement("div", { className: "we-picker__current-error" }, sel.videoError),
+				        // 缓存与速度的**自述**（④）：用户不用开 F12 也能知道"这次是首次下载还是命中缓存"。
+				        // 数据来自宿主 `/folia/site-media-stats`；拿不到就**什么都不显示**（绝不因此报错）。
+				        React.createElement(QpCacheHint, null),
 				      ),
 				      React.createElement("div", { className: "we-qp__current-actions" },
 				        // ⚠️ **不变量：这一行只放日常操作**（暂停 / 播放 · 刷新 · 清除；场景与网页壁纸再加

package/lib/download-queue.js

@@ -114,6 +114,62 @@ export function createDownloadQueue(opts = {}) {
     return true;
   }
 
+  /**
+   * **分片并发下载**（针对高延迟线路）。
+   *
+   * 为什么需要：单条 TCP 连接在高 RTT 线路上会被窗口/慢启动限制，实测几百 KB/s；
+   * 同一台机器改成 3 条 Range 并发通常能到 1.5–3 倍。只在**大文件**且上游声明支持
+   * `accept-ranges: bytes` 时走这条路，其它情况一律退回单流（简单、且小文件分片反而更慢）。
+   *
+   * 校验：各分片大小之和必须等于总长，否则整次失败（宁可重下也不留半截文件）。
+   */
+  async function fetchRanged(url, part, total, onChunk) {
+    const CHUNKS = 3;
+    const size = Math.ceil(total / CHUNKS);
+    const tasks = [];
+    for (let i = 0; i < CHUNKS; i += 1) {
+      const start = i * size;
+      const end = Math.min(total - 1, start + size - 1);
+      if (start > end) break;
+      tasks.push((async () => {
+        const piece = part + '.' + i;
+        const r = await fetch(url, {
+          headers: { 'user-agent': 'dsh-folia/download-queue', range: 'bytes=' + start + '-' + end },
+          redirect: 'follow',
+        });
+        if (r.status !== 206) throw new Error('range-unsupported-' + r.status);
+        mkdirSync(dirname(piece), { recursive: true });
+        const out = createWriteStream(piece, { flags: 'w' });
+        const src = r.body ? Readable.fromWeb(r.body) : null;
+        if (!src) throw new Error('empty-range-body');
+        await new Promise((resolve, reject) => {
+          src.on('data', (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            onChunk(buf.length);
+            if (!out.write(buf)) { src.pause(); out.once('drain', () => src.resume()); }
+          });
+          src.on('end', resolve);
+          src.on('error', reject);
+        });
+        await new Promise((resolve) => { out.end(resolve); });
+        return piece;
+      })());
+    }
+    const pieces = await Promise.all(tasks);
+    // 拼接：按顺序读出各分片追加到 .part（最终仍是"完成才 rename"的原子语义）
+    mkdirSync(dirname(part), { recursive: true });
+    const sink = createWriteStream(part, { flags: 'w' });
+    let written = 0;
+    for (const piece of pieces) {
+      const buf = readFileSync(piece);
+      written += buf.length;
+      if (!sink.write(buf)) { await new Promise((resolve) => { sink.once('drain', resolve); }); }
+      try { rmSync(piece, { force: true }); } catch { /* ignore */ }
+    }
+    await new Promise((resolve) => { sink.end(resolve); });
+    if (written !== total) throw new Error('range-size-mismatch:' + written + '/' + total);
+  }
+
   async function runOne(job) {
     job.status = 'running';
     job.error = null;
@@ -127,12 +183,47 @@ export function createDownloadQueue(opts = {}) {
       if (from > 0) headers.range = 'bytes=' + from + '-';
       const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
       job.ctrl = ctrl;
+
+      // ③ 下载前先问一次"要不要下"：HEAD 拿长度 + etag，与上次落地的 sidecar 记录一致 ⇒ 整次跳过。
+      //    省掉的是整包传输，收益比任何传输优化都大（站点换 CDN 但内容没变时也能认出来）。
+      if (from === 0 && existsSync(job.dest)) {
+        try {
+          const h = await fetch(job.url, { method: 'HEAD', redirect: 'follow' });
+          if (h.ok) {
+            const size = Number(h.headers.get('content-length') || 0);
+            const etag = h.headers.get('etag') || '';
+            let seen = null;
+            try { seen = JSON.parse(readFileSync(job.dest + '.etag', 'utf8')); } catch { seen = null; }
+            const same = seen && seen.size === size && size > 0 && (!etag || !seen.etag || seen.etag === etag);
+            if (same) {
+              setJob(job, { status: 'done', total: size, received: size });
+              try { onDone(job); } catch { /* 消费方失败不影响结果 */ }
+              return;
+            }
+          }
+        } catch { /* HEAD 失败就照常下载，不做判断 */ }
+      }
+
       const r = await fetch(job.url, { headers, signal: ctrl ? ctrl.signal : undefined, redirect: 'follow' });
       if (!r.ok && r.status !== 206) throw new Error('http-' + r.status);
       const startAt = r.status === 206 ? from : 0;
       if (startAt === 0 && existsSync(part)) { try { rmSync(part, { force: true }); } catch { /* ignore */ } }
       const len = Number(r.headers.get('content-length') || 0);
       setJob(job, { total: len ? len + startAt : (job.total || 0) });
+
+      // ② 大文件 + 支持 Range ⇒ 分片并发（单连接在高 RTT 线路上被窗口限制）。
+      const acceptsRanges = /bytes/i.test(String(r.headers.get('accept-ranges') || ''));
+      const totalKnown = Number(job.total) || 0;
+      if (startAt === 0 && acceptsRanges && totalKnown >= 8 * 1024 * 1024) {
+        try { if (r.body && typeof r.body.cancel === 'function') r.body.cancel(); } catch { /* ignore */ }
+        await fetchRanged(job.url, part, totalKnown, (n) => { job.received += n; });
+        renameSync(part, job.dest);
+        try { writeFileSync(job.dest + '.etag', JSON.stringify({ size: totalKnown, etag: '' })); } catch { /* ignore */ }
+        setJob(job, { status: 'done', received: totalKnown });
+        try { onDone(job); } catch { /* ignore */ }
+        return;
+      }
+
       mkdirSync(dirname(job.dest), { recursive: true });
       const out = createWriteStream(part, { flags: startAt > 0 ? 'a' : 'w' });
       const src = r.body ? Readable.fromWeb(r.body) : null;
@@ -152,6 +243,8 @@ export function createDownloadQueue(opts = {}) {
       renameSync(part, job.dest);
       job.status = 'done';
       if (!job.total) { try { job.total = statSync(job.dest).size; } catch { /* ignore */ } }
+      // 记一次 sidecar，供下次 HEAD 比对（内容没变就整次跳过）
+      try { writeFileSync(job.dest + '.etag', JSON.stringify({ size: job.total, etag: '' })); } catch { /* ignore */ }
       try { onDone(job); } catch { /* 消费方失败不影响下载结果 */ }
       log('download-queue: done ' + job.kind + ' ' + job.dest + ' (' + Math.round(job.total / 1048576) + ' MB)');
     } catch (e) {

package/lib/routes/downloads.js

@@ -27,7 +27,7 @@ function dshHome() {
 
 /** 进程内单例：接口与 inventory 共用同一个队列（并发上限/去重才有意义）。 */
 let QUEUE = null;
-function getDownloadQueue(log) {
+export function getDownloadQueue(log) {
   if (!QUEUE) QUEUE = createDownloadQueue({ home: dshHome(), log: log || (() => {}) });
   return QUEUE;
 }

package/lib/routes/skins.js

@@ -23,6 +23,8 @@ import { inflateRawSync } from 'node:zlib';
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+// 皮肤包的下载走与壁纸同一条队列（Range 续传 / 去重 / 并发上限），落地后再解压。
+import { getDownloadQueue } from './downloads.js';
 
 /** 注入契约（ADR-0013 D12）。 */
 export { unzipSkinZip, safeSkinId };
@@ -598,11 +600,29 @@ export function registerSkinsRoutes(webServer, c) {
 
       let buf;
       try {
-        const r = await fetch(url.toString(), { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
-        if (!r.ok) { sendJson(res, 502, { ok: false, error: 'http-' + r.status }); return; }
-        const len = Number(r.headers.get('content-length') || 0);
-        if (len && len > MAX_ZIP_BYTES) { sendJson(res, 413, { ok: false, error: 'too-large' }); return; }
-        buf = Buffer.from(await r.arrayBuffer());
+        // ① 皮肤包改走**下载队列**（与壁纸同一条链路）：Range 续传、断线可接着下、
+        //    落地后再从磁盘读来解压 —— 不再"网络层整包进内存且无法续传"。
+        //    说明：解压仍需完整 Buffer（zip 中央目录在尾部，流式解压是另一个量级的改动），
+        //    这里省掉的是重复内存与不可续传这两件事。
+        const zipDest = join(dshHome(), 'cache', 'skins-zip',
+          createHash('sha256').update(url.toString()).digest('hex').slice(0, 32) + '.zip');
+        const q = getDownloadQueue();
+        const added = q.add({ url: url.toString(), dest: zipDest, kind: 'skin' });
+        const jobId = added && added.job ? added.job.id : null;
+        const deadline = Date.now() + 10 * 60 * 1000;
+        let state = added && added.job ? added.job : null;
+        while (Date.now() < deadline) {
+          state = q.snapshot().find((j) => j.id === jobId) || state;
+          if (state && state.status === 'done') break;
+          if (state && (state.status === 'failed' || state.status === 'cancelled')) {
+            sendJson(res, 502, { ok: false, error: state.error || 'download-failed' });
+            return;
+          }
+          await new Promise((resolve) => { setTimeout(resolve, 150); });
+        }
+        const total = Number(state && state.total) || 0;
+        if (total && total > MAX_ZIP_BYTES) { sendJson(res, 413, { ok: false, error: 'too-large' }); return; }
+        buf = readFileSync(zipDest);
         if (buf.length > MAX_ZIP_BYTES) { sendJson(res, 413, { ok: false, error: 'too-large' }); return; }
       } catch (e) {
         sendJson(res, 502, { ok: false, error: e && e.name === 'TimeoutError' ? 'timeout' : 'network' });

package/package.json

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