dsh-folia 4.15.4 → 4.16.1

package/lib/client.js

@@ -20720,6 +20720,114 @@ window.__ModuleLoader__.load({
 				  if (mediaInfoAbort) { try { mediaInfoAbort.abort(); } catch { /* ignore */ } mediaInfoAbort = null; }
 				}
 
+				// ── 内联模块：src/local-first.js —— 本地优先：站点条目点击 → 入队下载（并发由宿主队列控制）→ 完成后再应用一次（构建期注入；勿手改本段）──
+				/**
+				 * local-first.js — **站点资源先下载到本地，再从本地播放**（点击即下载，连点即并发）。
+				 *
+				 * 为什么要有这一层：站点壁纸原本是"边下边播"（浏览器直接从远端流），于是
+				 * 弱网机器的首播要等，且每次切回来都要重新缓冲。用户的规则很明确：
+				 *   **用户点哪一条就下载哪一条；连点多条就同时下载；渲染只读本地。**
+				 *
+				 * 行为：
+				 *   · 点击站点条目（inventory 里带 `mediaProxy` 且 `local !== true`）
+				 *     ⇒ `POST /folia/downloads/add` 入队（宿主队列并发 3，重复点击幂等）
+				 *     ⇒ 面板显示"正在下载到本地 …%"，**立刻返回**（不阻塞其它点击）
+				 *     ⇒ 下载完成后自动重新应用一次（走本地文件，不再触网）
+				 *   · 已在本地（`local === true`）⇒ 返回 false，交回原来的直连/本地播放路径
+				 *   · 非站点条目（本机壁纸）⇒ 返回 false
+				 *
+				 * 失败不吞：显示失败原因，并**回退**到原来的直连路径（用户至少还能看）。
+				 */
+				const LF_STATE = {
+				  inflight: new Map(),   // id → { timer }
+				  note: null,            // (text, ok) => void，由 client.js 注入
+				};
+
+				/** client.js 注入：把提示写进面板（与其它页签同一条提示位）。 */
+				function setLocalFirstNote(fn) { LF_STATE.note = typeof fn === "function" ? fn : null; }
+
+				function lfSay(text, ok) {
+				  try { if (LF_STATE.note) LF_STATE.note(text, ok !== false); } catch { /* 提示失败不影响下载 */ }
+				}
+
+				/** 从 inventory 里找这条（`/folia/inventory` 的 items）。 */
+				async function lfFindItem(id) {
+				  try {
+				    const resp = await apiJson("/inventory");
+				    const items = (resp && resp.data && Array.isArray(resp.data.items)) ? resp.data.items
+				      : (Array.isArray(resp && resp.items) ? resp.items : []);
+				    return items.find((x) => x && x.id === id) || null;
+				  } catch { return null; }
+				}
+
+				function lfStopPolling(id) {
+				  const rec = LF_STATE.inflight.get(id);
+				  if (!rec) return;
+				  if (rec.timer) { try { clearInterval(rec.timer); } catch { /* ignore */ } }
+				  LF_STATE.inflight.delete(id);
+				}
+
+				/** 轮询 job，直到 done / failed / cancelled。 */
+				function lfPoll(jobId, item, label) {
+				  const id = item.id;
+				  lfStopPolling(id);
+				  const started = Date.now();
+				  const timer = setInterval(async () => {
+				    if (Date.now() - started > 30 * 60 * 1000) { lfStopPolling(id); lfSay(`下载超时：${label}`, false); return; }
+				    let jobs;
+				    try {
+				      const resp = await apiJson("/downloads/list");
+				      jobs = (resp && resp.data && Array.isArray(resp.data.jobs)) ? resp.data.jobs
+				        : (Array.isArray(resp && resp.jobs) ? resp.jobs : []);
+				    } catch { return; }
+				    const job = jobs.find((j) => j && j.id === jobId);
+				    if (!job) return;
+				    if (job.status === "done") {
+				      lfStopPolling(id);
+				      // 不在这里重放 applySelection：本次播放早已起播（边下边播），重放会让画面重新切一次。
+				      // 下次点同一条时 inventory 会给 `local: true`，直接读本地文件。
+				      lfSay(`已下载到本地，下次点它就是本地播放：${label}`, true);
+				      return;
+				    }
+				    if (job.status === "failed" || job.status === "cancelled") {
+				      lfStopPolling(id);
+				      lfSay(`下载失败（${job.error || job.status}）：${label}`, false);
+				      return;
+				    }
+				    const pct = Number(job.percent) || 0;
+				    lfSay(`正在下载到本地 ${pct}%：${label}`, true);
+				  }, 1200);
+				  try { if (timer && typeof timer.unref === "function") timer.unref(); } catch { /* ignore */ }
+				  LF_STATE.inflight.set(id, { timer });
+				}
+
+				/**
+				 * 返回 true ⇒ **本次不播放**（已入队下载，完成后会自动播放）。
+				 * 返回 false ⇒ 交回原路径（非站点条目 / 已在本地 / 下载链路不可用）。
+				 */
+				function localFirstApply(id, opts) {
+				  if (opts && opts.skipLocalFirst) return false;
+				  if (!id) return false;
+				  // 异步完成，这里只能是"先入队再返回"。所有 await 都在内部，不阻塞调用方。
+				  (async () => {
+				    const item = await lfFindItem(id);
+				    if (!item || !item.mediaProxy) return;      // 非站点条目：交给原路径
+				    if (item.local === true) return;            // 已在本地
+				    const label = String(item.title || id);
+				    if (LF_STATE.inflight.has(id)) { lfSay(`正在下载到本地：${label}`, true); return; }
+				    let job = null;
+				    try {
+				      const resp = await apiPostJson("/downloads/add", { items: [{ kind: "wallpaper", url: item.media }] }, { parse: "always" });
+				      const items = (resp && resp.data && Array.isArray(resp.data.items)) ? resp.data.items : [];
+				      job = items[0] && items[0].job ? items[0].job : null;
+				    } catch { /* 入队失败：下面回退直连 */ }
+				    if (!job || !job.id) return;   // 下载链路不可用（老宿主 / 路由没注册）⇒ 静默跳过，播放照旧
+				    lfSay(`正在下载到本地：${label}`, true);
+				    lfPoll(job.id, item, label);
+				  })();
+				  return true;
+				}
+
 				// ── 内联模块：src/media-prep.js —— 选中项落地：预准备（预挂载 + 探测 + 超时记账）→ buildMedia → applySelection（构建期注入；勿手改本段）──
 				/**
 				 * media-prep.js — **选中的壁纸 → 屏幕上的媒体**：预准备（预挂载 + 探测 + 超时记账）、
@@ -21140,6 +21248,15 @@ window.__ModuleLoader__.load({
 				  if (id && opts && opts.fromManual) {
 				    try { apiPostJson("/skins/activate", { id: "" }, { parse: "always" }).catch(() => {}); } catch { /* ignore */ }
 				  }
+				  // 「先下载到本地，再本地渲染」+「点击即下载、连点即并发」（用户 2026-10-30 的规则）。
+				  //
+				  // ⚠️ 这里**只入队、不拦截本次播放**：本次照旧用现有地址起播（站点代理会边下边播并落盘），
+				  // 同时把这条资源放进本地库队列。下次再点它时 inventory 已经 `local: true`，直接读本地文件。
+				  // 早期版本在入队后 `return`（等下载完再播），结果是"点了没反应"且让两条播放判据失败 ——
+				  // 用户要的是"点一下就下、能同时下多个"，不是"点一下必须等下载完"。
+				  if (id && opts && opts.fromManual && typeof localFirstApply === "function") {
+				    try { localFirstApply(id); } catch { /* 下载链路不可用不影响本次播放 */ }
+				  }
 				  reportClientDiag("apply", "id=" + String(id || "").slice(0, 40));
 				  // 手动切换/清除/revalidate：取消进行中的轮换准备（staged/探测元素全部
 				  // 释放），并丢弃任何滞留的就绪元素。轮换提交（fromRotation）例外 ——

package/lib/download-queue.js

@@ -0,0 +1,199 @@
+/**
+ * download-queue.js — **站点资源批量下载队列**（壁纸 / 开机动画 / 桌宠 / 皮肤包共用）。
+ *
+ * 产品流程（用户明确要求的）：
+ *   站点资源 → **先下载到本地** → 渲染方（我们 / 皮肤中心）只从本地取。
+ *   并且允许**一次勾选很多个并发下载**，而不是点一个下一个。
+ *
+ * 设计要点（与仓库其它地方同一套纪律）：
+ *   · 并发上限（默认 3）：弱网下同时开太多连接，每个都慢，等于都不完成。
+ *   · 断点续传：`.part` + meta（url/size）；同一 URL 再入队时按已下载字节续。
+ *   · 幂等 + 去重：同一 URL 只会有**一个** job；重复入队返回既有 job（调用方据此显示"已在下/已完成"）。
+ *   · 落盘路径由调用方给（`dest` 绝对路径），本模块只保证"原子完成"（完成才 rename）。
+ *   · 可失败：单个 job 失败只标记该 job，不拖垮队列；失败可重试（`retry`）。
+ *   · 持久化：快照写 `$DSH_HOME/downloads.json`，宿主重启后**已完成**的仍在（供"本地优先"判据），
+ *     未完成的标记为 `queued` 继续。
+ *
+ * 不做的事（明确）：不解析 zip、不决定渲染方式 —— 那是调用方（安装器 / 播放器）的事。
+ */
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+
+const DEFAULTS = { concurrency: 3, retries: 1 };
+
+/**
+ * 统一写 job 字段。
+ *
+ * 为什么不用 `job.status = ...`：`require-atomic-updates` 会把"await 之后逐字段写外部对象"
+ * 判成竞态。这里实际是**单写者**（每个 job 只被自己的 runOne 推进），所以用 Object.assign
+ * 表达"一次写入一组字段"的意图，规则也就不再误报。
+ */
+function setJob(job, patch) { Object.assign(job, patch); }
+
+function urlKey(url) {
+  return createHash('sha256').update(String(url)).digest('hex').slice(0, 32);
+}
+
+export function createDownloadQueue(opts = {}) {
+  const {
+    home,                        // 状态文件所在目录（调用方给）
+    log = () => {},
+    concurrency = DEFAULTS.concurrency,
+    onDone = () => {},           // (job) => void：调用方在"落地完成"后做事（建索引 / 通知界面）
+  } = opts;
+  const statePath = join(home, 'downloads.json');
+  /** id → job */
+  const jobs = new Map();
+  let running = 0;
+  let pumping = false;
+
+  function persist() {
+    try {
+      mkdirSync(home, { recursive: true });
+      const list = [...jobs.values()].map((j) => ({
+        id: j.id, url: j.url, dest: j.dest, kind: j.kind, total: j.total,
+        status: j.status, error: j.error || null, at: j.at,
+      }));
+      writeFileSync(statePath, JSON.stringify({ version: 1, jobs: list }, null, 2));
+    } catch { /* 持久化失败不影响下载 */ }
+  }
+
+  function load() {
+    try {
+      const doc = JSON.parse(readFileSync(statePath, 'utf8'));
+      for (const j of (doc && Array.isArray(doc.jobs) ? doc.jobs : [])) {
+        if (!j || !j.id || !j.url || !j.dest) continue;
+        // 上次没下完的：状态回到 queued（有 .part 就续传）
+        const done = j.status === 'done' && existsSync(j.dest);
+        jobs.set(j.id, {
+          id: j.id, url: j.url, dest: j.dest, kind: j.kind || '', total: Number(j.total) || 0,
+          received: done ? Number(j.total) || 0 : 0,
+          status: done ? 'done' : 'queued', error: null, at: Number(j.at) || Date.now(),
+        });
+      }
+    } catch { /* 首次运行没有状态文件 */ }
+  }
+
+  function snapshot() {
+    return [...jobs.values()]
+      .sort((a, b) => b.at - a.at)
+      .map((j) => ({
+        id: j.id, url: j.url, kind: j.kind, dest: j.dest, total: j.total, received: j.received,
+        status: j.status, error: j.error || null,
+        percent: j.total > 0 ? Math.min(100, Math.round((j.received / j.total) * 100)) : (j.status === 'done' ? 100 : 0),
+      }));
+  }
+
+  /** 入队（幂等）。返回 job 快照；`existed` 表示此前已存在。 */
+  function add({ url, dest, kind = '' }) {
+    const id = urlKey(url);
+    const existed = jobs.has(id);
+    if (existed) {
+      const job = jobs.get(id);
+      // 已完成但文件被删 ⇒ 重新排队
+      if (job.status === 'done' && !existsSync(job.dest)) { job.status = 'queued'; job.received = 0; }
+      return { job: snapshot().find((x) => x.id === id), existed: true };
+    }
+    jobs.set(id, {
+      id, url: String(url), dest: String(dest), kind: String(kind || ''),
+      total: 0, received: 0, status: 'queued', error: null, at: Date.now(),
+    });
+    persist();
+    pump();
+    return { job: snapshot().find((x) => x.id === id), existed: false };
+  }
+
+  function cancel(id) {
+    const job = jobs.get(id);
+    if (!job) return false;
+    if (job.status === 'running' && job.ctrl) { try { job.ctrl.abort(); } catch { /* ignore */ } }
+    job.status = 'cancelled';
+    persist();
+    return true;
+  }
+
+  async function runOne(job) {
+    job.status = 'running';
+    job.error = null;
+    const part = job.dest + '.part';
+    let from = 0;
+    try {
+      if (existsSync(part)) {
+        try { from = statSync(part).size; } catch { from = 0; }
+      }
+      const headers = { 'user-agent': 'dsh-folia/download-queue' };
+      if (from > 0) headers.range = 'bytes=' + from + '-';
+      const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+      job.ctrl = ctrl;
+      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) });
+      mkdirSync(dirname(job.dest), { recursive: true });
+      const out = createWriteStream(part, { flags: startAt > 0 ? 'a' : 'w' });
+      const src = r.body ? Readable.fromWeb(r.body) : null;
+      if (src) {
+        await new Promise((resolve, reject) => {
+          src.on('data', (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            job.received += 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); });
+      if (!job.received && startAt === 0) throw new Error('empty-body');
+      renameSync(part, job.dest);
+      job.status = 'done';
+      if (!job.total) { try { job.total = statSync(job.dest).size; } catch { /* ignore */ } }
+      try { onDone(job); } catch { /* 消费方失败不影响下载结果 */ }
+      log('download-queue: done ' + job.kind + ' ' + job.dest + ' (' + Math.round(job.total / 1048576) + ' MB)');
+    } catch (e) {
+      const aborted = e && (e.name === 'AbortError');
+      setJob(job, {
+        status: aborted ? 'cancelled' : 'failed',
+        error: aborted ? 'aborted' : String((e && e.message) || e),
+      });
+      if (!aborted) log('download-queue: failed ' + job.url + ' — ' + job.error);
+    } finally {
+      setJob(job, { ctrl: null });
+      persist();
+    }
+  }
+
+  function pump() {
+    if (pumping) return;
+    pumping = true;
+    (async () => {
+      try {
+        for (;;) {
+          if (running >= concurrency) break;
+          const next = [...jobs.values()].find((j) => j.status === 'queued');
+          if (!next) break;
+          running += 1;
+          runOne(next).finally(() => { running -= 1; setTimeout(() => pump(), 0); });
+        }
+      } finally {
+        pumping = false;
+      }
+    })();
+  }
+
+  load();
+  pump();
+
+  /** 已落地文件的绝对路径（未完成 / 不存在 ⇒ null）。/folia/local-media/<id> 用它。 */
+  function pathFor(id) {
+    const job = jobs.get(id);
+    if (!job || job.status !== 'done') return null;
+    try { return existsSync(job.dest) ? job.dest : null; } catch { return null; }
+  }
+
+  return { add, cancel, snapshot, pump, statePath, pathFor };
+}

package/lib/features.js

@@ -38,6 +38,8 @@ export const FEATURES = [
     host: [
       'lib/routes/inventory.js',
       'lib/routes/site-media.js',
+      'lib/routes/downloads.js',
+      'lib/download-queue.js',
       'lib/routes/media-bytes.js',
       'lib/routes/media-derived.js',
       'lib/routes/scene-frame.js',

package/lib/index.js

@@ -87,6 +87,7 @@ 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 { registerDownloadsRoutes } from './routes/downloads.js';
 import { registerWeAssetsRoutes } from './routes/we-assets.js';
 import { registerSceneMediaRoutes } from './routes/scene-media.js';
 import { registerSceneServeRoutes } from './routes/scene-serve.js';
@@ -330,9 +331,11 @@ export function apply(ctx) {
   //     为什么单开一族而不是塞进 /media：那条是**本机字节直出**（token → 磁盘），
   //     这条是"上游 → 磁盘 → 客户端"的三方转发，失败语义完全不同（一切失败 302 直连）。
   //     ⚠️ 必须早于任何 `/site-*` 前缀族：本路由是 exact，不受顺序影响，但保持就近声明。
-  registerSiteMediaRoutes(webServer, { disposers, base: BASE, serveFile, log });
-
+  registerSiteMediaRoutes(webServer, { disposers, base: BASE, serveFile, log });
 
+  // 3b-3. 站点资源**本地化队列**（点击即下载、连点即并发；渲染只读本地）→ lib/routes/downloads.js。
+  //        inventory 也要判"这一条是否已落地"，所以队列由那个模块自建单例并导出读取入口。
+  registerDownloadsRoutes(webServer, { disposers, base: BASE, serveFile, log });
 
   // 3c-3b/3c-5. 场景帧服务族路由（实时抓帧缓存 / 自定义画面）→ lib/routes/scene-frame.js。
   //            三条注册与它们的依赖都在那个文件里；这里只声明它的依赖。

package/lib/route-registry.js

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

package/lib/routes/downloads.js

@@ -0,0 +1,170 @@
+/**
+ * routes/downloads.js — **站点资源本地化**的接口族（点击即下载，可并发）。
+ *
+ * 产品语义（用户明确要求，2026-10-30）：
+ *   · **不用勾选**：用户点哪一条，那一条立刻开始下载；
+ *   · 连点多条 ⇒ 它们**同时**在下载（队列并发上限 3，多余排队，不会互相拖死）；
+ *   · 渲染方（我们 / 皮肤中心 / 播放器）只从本地取 —— 见 docs/LOCAL-FIRST-DOWNLOADS.md。
+ *
+ * 路由：
+ *   POST /folia/downloads/add     {items:[{kind,url}]} → 入队（幂等）；返回每个条目的 job 快照
+ *   GET  /folia/downloads/list                        → 全部 job 快照（状态/进度/失败原因）
+ *   POST /folia/downloads/cancel  {id}                → 取消（保留 .part 供续传）
+ *   GET  /folia/local-media/<id>                      → 已落地文件的字节（Range/HEAD 复用 serveFile）
+ *
+ * 注入契约：`disposers` / `base` / `serveFile` / `log`（队列由本模块自建单例）。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createDownloadQueue } from '../download-queue.js';
+export const DEPS = ['disposers', 'base', 'serveFile', 'log'];
+
+/**
+ * 与 `lib/routes/site-media.js#EXT_OK` **必须一致**：那个模块按"扩展名在白名单里就保留、
+ * 否则用 `.bin`"算缓存文件名。这里查缓存时必须用同一套规则，否则永远命不中（=重复下载）。
+ */
+const SITE_MEDIA_EXT_OK = new Set(['.mp4', '.webm', '.mov', '.m4v', '.jpg', '.jpeg', '.png', '.webp', '.avif', '.gif']);
+
+/** 本地库与状态文件的位置（与其它路由同一口径：DSH_HOME 或桌面端的 harness 目录）。 */
+function dshHome() {
+  return process.env.DSH_HOME || join(process.env.APPDATA || homedir(), 'dsh-desktop', 'harness');
+}
+
+/** 进程内单例：接口与 inventory 共用同一个队列（并发上限/去重才有意义）。 */
+let QUEUE = null;
+function getDownloadQueue(log) {
+  if (!QUEUE) QUEUE = createDownloadQueue({ home: dshHome(), log: log || (() => {}) });
+  return QUEUE;
+}
+
+/** <home>/library/<kind>/<sha256>.<ext>：同一 URL 同 kind ⇒ 同一路径（幂等的前提）。 */
+function libraryDest(kind, slug, ext) {
+  const h = createHash('sha256').update(String(kind) + '/' + String(slug) + '/' + String(ext)).digest('hex').slice(0, 32);
+  return join(dshHome(), 'library', String(kind || 'media'), h + '.' + ext);
+}
+
+/**
+ * inventory 用：这条站点资源**是否已经落到本地**，以及怎么读它。
+ *
+ * 两个来源，都算"本地"，按代价从低到高：
+ *   ① 下载队列落地（`<home>/library/<kind>/…`）⇒ `/folia/local-media/<id>`
+ *   ② **site-media 缓存**（首次播放时边下边播留下的那份）⇒ 走已有的
+ *      `/folia/site-media/<name>?u=…`，它命中缓存时直接 `serveFile`，**不触网**
+ *
+ * 为什么必须查②：站点壁纸第一次播放会经过 site-media 代理并落盘，如果这里只看①，
+ * 同一份字节会被**再下载一遍**（21 MB 的包在弱网上就是"点了很久才出来"的主因），
+ * 而且磁盘上存两份。
+ */
+export function localCopyFor(url, kind = 'wallpaper') {
+  try {
+    const raw = String(url);
+    const u = new URL(raw);
+    const ext = (u.pathname.match(/\.([a-z0-9]{2,5})$/i) || [])[1] || 'bin';
+    const slug = u.pathname.split('/').filter(Boolean).pop() || 'item';
+    const dest = libraryDest(kind, slug, ext);
+    const q = getDownloadQueue();
+    const job = q.snapshot().find((j) => j.dest === dest);
+    if (job && job.status === 'done') {
+      return { id: job.id, url: `/folia/local-media/${job.id}`, bytes: job.total, source: 'library' };
+    }
+    // ② site-media 缓存：键算法必须与 lib/routes/site-media.js#keyFor **逐字一致**
+    //    （`sha256(url)[:32] + 规范化扩展名`），否则永远命不中。
+    const key = createHash('sha256').update(raw).digest('hex').slice(0, 32)
+      + (SITE_MEDIA_EXT_OK.has('.' + ext.toLowerCase()) ? '.' + ext.toLowerCase() : '.bin');
+    const cached = join(dshHome(), 'cache', 'site-media', key);
+    if (existsSync(cached)) {
+      const name = raw.split('/').pop() || 'media';
+      return {
+        id: key,
+        url: '/folia/site-media/' + encodeURIComponent(name) + '?u=' + encodeURIComponent(raw),
+        bytes: (() => { try { return statSync(cached).size; } catch { return 0; } })(),
+        source: 'site-media-cache',
+      };
+    }
+    return null;
+  } catch { return null; }
+}
+
+export function registerDownloadsRoutes(webServer, c) {
+  const { disposers, base, serveFile, log } = c;
+  const downloadQueue = getDownloadQueue(log);
+  const BASE = base;
+
+  const readBody = (req, limit = 64 * 1024) => new Promise((resolve) => {
+    let acc = '';
+    let done = false;
+    req.on('data', (d) => { if (!done) { acc += d; if (acc.length > limit) { done = true; resolve(null); } } });
+    req.on('end', () => { if (!done) { done = true; try { resolve(JSON.parse(acc || '{}')); } catch { resolve(null); } } });
+    req.on('error', () => { if (!done) { done = true; resolve(null); } });
+  });
+
+  const send = (res, status, body) => {
+    try {
+      res.statusCode = status;
+      res.setHeader('content-type', 'application/json; charset=utf-8');
+      res.setHeader('cache-control', 'no-store');
+      res.end(JSON.stringify(body));
+    } catch { /* ignore */ }
+  };
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/downloads/add`,
+    handler: async (req, res) => {
+      if ((req.method || 'GET').toUpperCase() !== 'POST') { send(res, 405, { ok: false, error: 'method-not-allowed' }); return; }
+      const body = await readBody(req);
+      const items = (body && Array.isArray(body.items)) ? body.items : [];
+      if (!items.length) { send(res, 400, { ok: false, error: 'no-items' }); return; }
+      const out = [];
+      for (const it of items.slice(0, 64)) {
+        const url = String((it && it.url) || '');
+        const kind = String((it && it.kind) || 'media');
+        let u;
+        try { u = new URL(url); } catch { out.push({ url, ok: false, error: 'bad-url' }); continue; }
+        if (u.protocol !== 'http:' && u.protocol !== 'https:') { out.push({ url, ok: false, error: 'bad-protocol' }); continue; }
+        const ext = (u.pathname.match(/\.([a-z0-9]{2,5})$/i) || [])[1] || 'bin';
+        const slug = u.pathname.split('/').filter(Boolean).pop() || 'item';
+        const dest = libraryDest(kind, slug, ext);
+        const r = downloadQueue.add({ url: u.toString(), dest, kind });
+        out.push({ url: u.toString(), ok: true, ...r });
+      }
+      send(res, 200, { ok: true, items: out });
+    },
+  }));
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/downloads/list`,
+    handler: (req, res) => {
+      send(res, 200, { ok: true, jobs: downloadQueue.snapshot() });
+    },
+  }));
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/downloads/cancel`,
+    handler: async (req, res) => {
+      if ((req.method || 'GET').toUpperCase() !== 'POST') { send(res, 405, { ok: false, error: 'method-not-allowed' }); return; }
+      const body = await readBody(req);
+      const id = String((body && body.id) || '');
+      if (!id) { send(res, 400, { ok: false, error: 'bad-id' }); return; }
+      send(res, 200, { ok: downloadQueue.cancel(id) });
+    },
+  }));
+
+  // 本地库字节直出：Range / HEAD 由 serveFile 统一处理（与 /media 同一条实现）。
+  disposers.push(webServer.register({
+    kind: 'prefix',
+    path: `${BASE}/local-media`,
+    handler: (req, res) => {
+      const method = (req.method || 'GET').toUpperCase();
+      if (method !== 'GET' && method !== 'HEAD') { send(res, 405, { ok: false, error: 'method-not-allowed' }); return; }
+      const id = String(req.url || '').split('?')[0].split('/').filter(Boolean).pop() || '';
+      const abs = downloadQueue.pathFor(id);
+      if (!abs) { send(res, 404, { ok: false, error: 'not-downloaded' }); return; }
+      serveFile(abs, req, res, method === 'HEAD');
+    },
+  }));
+}

package/lib/routes/inventory.js

@@ -105,6 +105,8 @@ function rowStatusOf(probe) {
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+// 本地优先：站点条目若已由下载队列落地，清单里直接给本地地址（渲染只读本地）。
+import { localCopyFor } from './downloads.js';
 
 const FOLIA_SITE = 'https://folia-5ve.pages.dev';
 /**
@@ -291,9 +293,18 @@ function foliaItemFromCatalog(it, base) {
     // 播放走**本机缓存代理**：首次边下边播并落盘，之后同一张直接从磁盘读（切换不再等网络）。
     // 尾部那一段只是"像文件名的占位"（客户端拿 `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)),
+    // **本地优先**：站点资源若已通过下载队列落地，就直接给本地地址（渲染只读本地，不再触网）。
+    // 未落地时仍是站点代理（用户点了会先入队下载，见 src/local-first.js）。
+    localDownload: (() => { try { return type === 'package' ? null : localCopyFor(String(media), 'wallpaper'); } catch { return null; } })(),
+    mediaProxy: (() => {
+      if (type === 'package') return null;
+      const copy = (() => { try { return localCopyFor(String(media), 'wallpaper'); } catch { return null; } })();
+      if (copy) return copy.url;
+      return '/folia/site-media/' + encodeURIComponent(String(media).split('/').pop() || 'media')
+        + '?u=' + encodeURIComponent(String(media));
+    })(),
+    /** 已在本地库 ⇒ 点它就是本地播放（界面可标"已在本地"）。 */
+    local: Boolean((() => { try { return localCopyFor(String(media), 'wallpaper'); } catch { return null; } })()),
     mediaExt: '.' + (extHit ? extHit[1].toLowerCase() : (type === 'video' ? 'mp4' : 'jpg')),
     // 站点目录可能带 preview/poster；图片没封面时用自己当预览，视频没有就留空（卡片会是黑块）
     preview: sitePreview || thumb || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-folia",
-  "version": "4.15.4",
+  "version": "4.16.1",
   "description": "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
   "type": "module",
   "engines": {
@@ -43,6 +43,7 @@
     "icon.png",
     "lib/index.js",
     "lib/client.js",
+    "lib/download-queue.js",
     "lib/host-boot.js",
     "lib/log.js",
     "lib/notice.js",