modelstage 0.5.24 → 0.6.1

package/src/server/routes/data.mjs

@@ -17,6 +17,12 @@ import { live2dGuide } from '../../../tool/lib/runtime-guides.mjs';
 import { readRatioEnv } from '../core/env-num.mjs';
 // 插槽目录（S1-a）：与校验同源，见 plugins/slot-catalog.mjs
 import { SLOT_CATALOG, CURRENT_STAGE } from '../plugins/slot-catalog.mjs';
+// 扫描进度：单飞表 + NDJSON 帧写出（P0；设计 §4.6/§5/§6）
+import { createScanRunner, streamScanFrames } from '../data/scan-progress.mjs';
+
+// 扫描单飞表：**模块级一份**（不是每请求一份）—— 单飞的意义就是"同一时刻同一个根只扫一次"。
+//   P1 的 JSONL 存储会原样复用这张表（设计 §4.6）。
+const scanRunner = createScanRunner();
 
 /** 资源根 / 插件 / 品牌 / 前端配置 */
 function apiBasics(ctx, res, p) {
@@ -69,7 +75,7 @@ function apiBasics(ctx, res, p) {
 }
 
 /** 目录 / 模型清单 / 名表 / 配置导出 / 目录浏览 */
-function apiData(ctx, res, p, url) {
+async function apiData(ctx, res, p, url) {
   const { data, sendJson, browseDir } = ctx;
   if (p === '/api/tree') {
     const r = data.tree.listTree(url.searchParams.get('root') || '', url.searchParams.get('path') || '');
@@ -84,19 +90,70 @@ function apiData(ctx, res, p, url) {
     const force = url.searchParams.get('refresh') === '1';
     const cfg = data.config.readConfig().find((r) => r.id === rootId);
     if (!cfg) return sendJson(res, 400, { error: `未找到资源根: ${rootId}` });
-    try {
-      const isSpine = p === '/api/spine/models';
-      const r = isSpine ? data.spine.getSpineModels(cfg, force) : data.live2d.getLive2DModels(cfg, force);
-      return sendJson(res, 200, {
-        root: { id: cfg.id, name: cfg.name },
-        count: r.models.length,
-        cached: r.cached,
-        scannedAt: new Date(r.ts).toISOString(),
-        models: r.models,
+    const isSpine = p === '/api/spine/models';
+    // 不带 stream=1：仍走原来的 sendJson —— 这段响应必须**逐字节不变**（验收 ①）
+    if (url.searchParams.get('stream') !== '1') {
+      try {
+        const r = isSpine ? await data.spine.getSpineModels(cfg, force) : await data.live2d.getLive2DModels(cfg, force);
+        return sendJson(res, 200, {
+          root: { id: cfg.id, name: cfg.name },
+          count: r.models.length,
+          cached: r.cached,
+          scannedAt: new Date(r.ts).toISOString(),
+          models: r.models,
+        });
+      } catch (e) {
+        return sendJson(res, 500, { error: `${p === '/api/spine/models' ? 'Spine 扫描失败' : 'Live2D 扫描失败'}: ${e.message}` });
+      }
+    }
+
+    // ── stream=1：NDJSON 逐帧写进度。模型数据仍走上面的 JSON 接口（P0 只发进度，见设计 §6.3）
+    const kind = isSpine ? 'spine' : 'live2d';
+    const startedAt = Date.now();
+    const joined = scanRunner.startOrJoin({
+      kind,
+      rootId: cfg.id,
+      // onModel：扫描每产出一条模型就转发成 model 帧 —— 这是"首模型早出现"的关键
+      run: (onProgress, onStart, onModel) => (isSpine
+        ? data.spine.getSpineModels(cfg, force, { onProgress, onStart, onModel })
+        : data.live2d.getLive2DModels(cfg, force, onProgress, onStart, onModel)),
+    });
+    // 加入已有扫描时，把当前快照立刻推给这个新连接（设计 §4.6：后续请求不必等下一次节流）
+    if (joined.joined && joined.progress) {
+      setImmediate(() => {
+        try { joined.emitter.emit('progress', joined.progress); } catch { /* 订阅者可能已走 */ }
       });
-    } catch (e) {
-      return sendJson(res, 500, { error: `${p === '/api/spine/models' ? 'Spine 扫描失败' : 'Live2D 扫描失败'}: ${e.message}` });
     }
+    // **不 await**：这是一条长连接（扫描结束时才 res.end()），调用方不该被它挂住。
+    //   若改成 await，handleData 就得变 async —— 而它的调用方写的是 `if (handleData(...))`，
+    //   Promise 恒真会让**所有请求都被它认领**（这是个真实踩到过的坑，见本文件末尾注释）。
+    streamScanFrames({
+      res,
+      emitter: joined.emitter,
+      buildStartFrame: () => ({
+        type: 'start',
+        kind,
+        rootId: cfg.id,
+        rootPath: cfg.path,
+        startedAt: new Date(startedAt).toISOString(),
+      }),
+      buildDoneFrame: (result) => ({
+        type: 'done',
+        count: result && result.models ? result.models.length : 0,
+        cached: false,
+        elapsedMs: Date.now() - startedAt,
+      }),
+      buildCachedFrame: (result) => ({
+        type: 'cached',
+        count: result && result.models ? result.models.length : 0,
+        ts: result && result.ts,
+      }),
+    }).catch((e) => {
+      // 帧写出阶段出意外（例如 header 已发再抛）：尽量收尾，别留下半开连接
+      try { res.end(); } catch { /* 已断开 */ }
+      if (ctx.log && ctx.log.warn) ctx.log.warn('扫描进度流写出异常', { root: cfg.id, err: (e && e.message) || e });
+    });
+    return true;
   }
   if (p === '/api/names') return apiNames(ctx, res, url);
   // /api/config/export 与 /api/config/import 同属配置组，见 routes/config.mjs（此处不重复实现）
@@ -137,7 +194,7 @@ function apiNames(ctx, res, url) {
 }
 
 /** 需要按需 import 的三条（catalog / bundle probe / model meta） */
-function apiAsync(ctx, req, res, p, url) {
+async function apiAsync(ctx, req, res, p, url) {
   const { data, sendJson } = ctx;
   const done = (r) => sendJson(res, r.status, r.body);
   const fail = (label) => (e) => sendJson(res, 500, { ok: false, error: `${label}: ${e.message}` });
@@ -157,7 +214,7 @@ function apiAsync(ctx, req, res, p, url) {
       const known = data.config.readConfig().map((r) => r.id);
       return sendJson(res, 400, { ok: false, error: '缺少 root 参数（?root=<资源根 id>）', known });
     }
-    return done(data.catalog.listCatalog(rootId));
+    return done(await data.catalog.listCatalog(rootId));
   }
   if (p === '/api/bundle/probe') {
     data.bundleProbe.probeBundle(url.searchParams.get('root') || '', url.searchParams.get('path') || '')
@@ -289,7 +346,7 @@ function serveLive2DLib(ctx, req, res, p) {
  * @param {object} ctx 需要 data/fs/path/sendJson/sendFile/resolveSafe/browseDir/toRootView/writeApi/readBody
  * @returns {boolean} 是否已处理
  */
-export function handleData(req, res, p, url, ctx) {
+export async function handleData(req, res, p, url, ctx) {
   const { sendJson, readBody, writeApi } = ctx;
 
   // 资源根写操作（增 / 删 / 改名 / 启停）：校验 → 备份 → 写 → 失效缓存
@@ -303,8 +360,10 @@ export function handleData(req, res, p, url, ctx) {
     return true;
   }
   if (apiBasics(ctx, res, p)) return true;
-  if (apiData(ctx, res, p, url)) return true;
-  if (apiAsync(ctx, req, res, p, url)) return true;
+  // await：apiData 内部要等扫描（async 化后），但**返回的仍是 boolean** ——
+  //   不能写成 `if (apiData(...))`（Promise 恒真会让所有 /api 请求都被它认领，上一轮踩过）
+  if (await apiData(ctx, res, p, url)) return true;
+  if (await apiAsync(ctx, req, res, p, url)) return true;
   if (serveModelFile(ctx, req, res, p, url)) return true;
   if (serveIcon(ctx, req, res, p)) return true;
   if (serveAvatar(ctx, req, res, p)) return true;

package/src/server/serve.mjs

@@ -31,6 +31,8 @@ import { createLogger } from './core/log.mjs';
 import { createUnpackStore } from './unpack/plugin-store.mjs';
 import { createUnpackRoutes } from './unpack/routes.mjs';
 import { handleData } from './routes/data.mjs';
+// 扫描并发上限与让路提示（P0 退化修复）；serve 只负责把"在途请求数"同步进去
+import { noteRequestStart, noteRequestEnd } from './data/scan-queue.mjs';
 import { handleConfig } from './routes/config.mjs';
 import { handleDiag } from './routes/diag.mjs';
 import { handleReady } from './routes/ready.mjs';
@@ -236,7 +238,54 @@ const ctx = {
  * @param {string} p
  * @param {URL} url
  */
-function dispatch(req, res, p, url) {
+/**
+ * 版本号：读 package.json（它是版本号的唯一权威，与 bin 的 --version 同源）。
+ * 读不到时返回 'unknown' 而不是抛错 —— 探活端点不该因为包元信息缺失而 500。
+ */
+function readVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * GET /api/health —— 探活端点（`web.sh status` 与外部监控用）。
+ *
+ * 为什么单独一条而不复用 /api/ready：ready 是"能否开始服务请求"的业务就绪信号
+ *   （要扫资源根、可能 503），而 health 只回答"进程活着吗、什么版本、数据在哪"。
+ *   两者语义不同，混一起会让监控在"资源根还没扫完"时误判进程已死。
+ *
+ * 只暴露排障必需的粗粒度信息：版本 / 运行时长 / 数据根绝对路径 / 插件数。
+ *   **不返回**配置内容、资源根清单、任何凭据或环境变量。
+ */
+function handleHealth(req, res, p) {
+  if (p !== '/api/health') return false;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    sendJson(res, 405, { ok: false, error: '仅支持 GET' });
+    return true;
+  }
+  // 插件数：直接问数据层（与 /api/plugins 同源）。
+  //   早先这里写的是 ctx.providers()，但本函数没有 ctx 参数 —— 异常被 catch 吞成 0，
+  //   结果 health 永远报 plugins:0（实测 5 个插件时也报 0）。探活字段报假数比不报更糟，故改为同源直取。
+  let pluginCount = 0;
+  try {
+    pluginCount = (data.plugins.readPlugins() || []).length;
+  } catch { /* 插件系统未就绪也算 0，探活不该因此失败 */ }
+  sendJson(res, 200, {
+    ok: true,
+    uptimeSec: Math.round(process.uptime()),
+    version: readVersion(),
+    dataRoot: data.paths.dataRoot,
+    plugins: pluginCount,
+  });
+  return true;
+}
+
+async function dispatch(req, res, p, url) {
+  // 探活放最前：它不该被其它路由的鉴权/副作用影响（也就不会因为那些逻辑出错而"连探活都挂"）
+  if (handleHealth(req, res, p)) return true;
   if (unpackRoutes(req, res, p, url)) return true;
   if (handleDiag(req, res, p, url, ctx)) return true;
   if (handleReady(req, res, p, url, ctx)) return true;
@@ -247,7 +296,8 @@ function dispatch(req, res, p, url) {
   if (handleBackgrounds(req, res, p, ctx)) return true;
   // 条目状态（写读一体）：必须在 handleData 之前认领，否则 /api/ 前缀兜底会当未知接口 404
   if (handleEntries(req, res, p, url, ctx)) return true;
-  if (handleData(req, res, p, url, ctx)) return true;
+  // handleData 已 async 化（内部要等扫描）：必须 await，否则 Promise 恒真会让所有请求都被它认领
+  if (await handleData(req, res, p, url, ctx)) return true;
   if (staticRoutes.serveAssets(req, res, p)) return true;
   if (res.headersSent) return true;
   if (p.startsWith('/api/')) {
@@ -259,25 +309,27 @@ function dispatch(req, res, p, url) {
   return true;
 }
 
-const server = http.createServer((req, res) => {
+const server = http.createServer(async (req, res) => {
   const url = new URL(req.url, `http://localhost:${PORT}`);
   // 长连接（SSE）不计入活跃度：它一挂几分钟，计入就等于"服务永远忙"
   const longLived = url.pathname.includes('/stream');
   if (!longLived) {
     activity.inflight += 1;
+    noteRequestStart();   // 同一个事实同步给扫描调度（它据此让路）
     activity.lastRequestAt = Date.now();
     let counted = true;
     const done = () => {
       if (!counted) return;      // close 与 finish 都会来，只减一次
       counted = false;
       activity.inflight -= 1;
+      noteRequestEnd();     // 必须与 noteRequestStart 成对（放在同一个 done 回调里）
       activity.lastRequestAt = Date.now();
     };
     res.on('finish', done);
     res.on('close', done);
   }
   try {
-    dispatch(req, res, url.pathname, url);
+    await dispatch(req, res, url.pathname, url);
   } catch (e) {
     log.error('请求处理异常', { err: (e && e.stack) ? e.stack : String(e) });
     try {
@@ -302,6 +354,21 @@ server.listen(PORT, '0.0.0.0', () => {
   log.info('资源根已登记', { roots: data.config.readConfig().map((r) => `${r.id}=${r.name}`) });
 });
 
+// 监听失败要**说人话**：不处理的话用户看到的是 EADDRINUSE 原始堆栈（一大坨，且不说下一步做什么）。
+//   退出码用 2 而不是 1：1 留给"参数/配置错误"这类，端口占用是环境问题，靠退出码就能区分。
+server.on('error', (e) => {
+  const code = (e && e.code) || '';
+  if (code === 'EADDRINUSE') {
+    log.error(`端口 ${PORT} 已被占用：用 --port <其他端口> 换一个，或先停掉占用该端口的进程`);
+    log.error(`排查提示：lsof -i :${PORT}（macOS/Linux）或 netstat -ano | findstr :${PORT}（Windows）`);
+    process.exit(2);
+  }
+  // 其它监听错误（EACCES 权限不足、EADDRNOTAVAIL 地址不可用…）：保留原始信息，同样给出下一步
+  log.error(`监听端口 ${PORT} 失败：${(e && e.message) || e}`, { code });
+  log.error('可尝试：换一个端口（--port），或检查是否有权限监听该端口/该地址');
+  process.exit(2);
+});
+
 /**
  * 收尾钩子：先把**常驻资源**放掉再退出。
  *

package/src/server/unpack/plugin-store.mjs

@@ -287,7 +287,7 @@ export function createUnpackStore(opts) {
 
   // 解包 worker 客户端：**常驻 1 个**（与既有串行队列一致，不并发解包）。
   //   硬超时 120s 只用于"防死循环把队列永久堵住"，不是"约束合法解包" ——
-  //   锚点包 azurlane_bundle/live2d/z46_2（解压 33.4MB 的 LZMA）实测墙钟 17.83s、unpackMs 9416ms，
+  //   实测大体积 LZMA 包也在 20s 内完成，
   //   120s 有 6.7 倍余量，正常解包一辈子不该触发它。
   //   ⚠️ 别把这个 120s 与"客户端不设总时长上限"当成矛盾，两者防的不是一回事：
   //     这里防的是「worker 死循环把串行队列永久堵死」（服务端自保，与有没有人看无关）；

package/src/server/unpack/runtime/exec.mjs

@@ -162,6 +162,30 @@ function expandPlaceholder(value, opts = {}) {
  * @param {object} meta 插件清单
  * @returns {string} 解释器路径或命令名
  */
+/** PATH 里的目录（空段过滤掉：空串会让 path.join 拼出当前目录，那是安全隐患） */
+function pathDirs() {
+  return String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+}
+
+/**
+ * 按**名字**在 PATH 里找可执行文件，返回绝对路径；找不到返回 null。
+ *
+ * 为什么不能写一串"常见安装路径"：那样换机器（或换 Node/Python 安装方式）就失效，
+ *   而且会让"这个解释器一定在 /usr/local/bin"变成隐含假设 —— 这正是要被消灭的形态。
+ *   PATH 是运行时的权威，问它就行。
+ * @param {string} binaryName 不带路径的命令名（如 'python3.14'）
+ * @returns {string|null}
+ */
+function findInPath(binaryName) {
+  for (const dir of pathDirs()) {
+    const candidate = path.join(dir, binaryName);
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch { /* 该 PATH 目录不可读：跳过，继续下一个 */ }
+  }
+  return null;
+}
+
 let interpreterProbeCache = null;
 function resolveInterpreter(meta) {
   // ① 环境变量最优先（部署期覆盖，便于换机/换版本而不改清单）
@@ -171,14 +195,16 @@ function resolveInterpreter(meta) {
   const declared = meta && meta.interpreter ? String(meta.interpreter) : '';
   if (declared) return declared;
   if (interpreterProbeCache) return interpreterProbeCache;
-  // 候选按"新到旧"排：新版本装的依赖不保证能在旧版本里 import
-  for (const candidate of ['/usr/local/bin/python3.14', '/usr/local/bin/python3.10', '/usr/bin/python3']) {
-    try {
-      if (fs.existsSync(candidate)) {
-        interpreterProbeCache = candidate;
-        return candidate;
-      }
-    } catch { /* 继续下一个 */ }
+  // ③ 按名字在 PATH 里探（**不写死任何安装位置**）。
+  //   候选集合**严格沿用**改动前的那三个（python3.14 → python3.10 → python3），
+  //   按"新到旧"排：新版本装的依赖不保证能在旧版本里 import。
+  //   只扩大候选集合（比如补上 3.13/3.12/3.11）会改变"选中哪个解释器"这个结果，本批要求行为不变，故不加。
+  for (const binaryName of ['python3.14', 'python3.10', 'python3']) {
+    const found = findInPath(binaryName);
+    if (found) {
+      interpreterProbeCache = found;
+      return found;
+    }
   }
   // 都没探到 ⇒ 交给 PATH（spawn 会报 ENOENT，错误信息里带命令名，够定位）
   interpreterProbeCache = 'python3';
@@ -218,6 +244,9 @@ class ExecWorker {
     if (this.ready) return this.ready;
     this.ready = new Promise((resolve, reject) => {
       const interpreter = resolveInterpreter(this.meta);
+      // 记一行解释器路径：spawn 失败（ENOENT / 版本不对 / 依赖没装）时，日志里能直接看到
+      //   "用哪个 python 起的"——否则只能从报错反推，多绕一圈。
+      if (this.log) this.log('info', `exec worker 使用解释器：${interpreter}`, { plugin: this.pluginId || null });
       const entryAbs = path.join(this.pluginDir, String(this.meta.entry || 'worker.py'));
       if (!fs.existsSync(entryAbs)) {
         this.ready = null;

package/src/server/unpack/worker-client.mjs

@@ -11,7 +11,7 @@
 //
 // 硬超时语义（写死在注释里，避免被误读成"包太大被拒"）：
 //   120s 只用于**防死循环把队列永久堵住**，不是"约束合法解包"。
-//   锚点包（azurlane_bundle/live2d/z46_2，解压 33.4MB 的 LZMA）实测墙钟 17.83s、unpackMs 9416ms，
+//   实测大体积 LZMA 包也在 20s 内完成，
 //   120s 有 6.7 倍余量 —— 正常解包一辈子不该触发它。
 
 import fs from 'node:fs';
@@ -20,6 +20,12 @@ import { Worker } from 'node:worker_threads';
 
 const WORKER_URL = new URL('./unpack-worker.mjs', import.meta.url);
 
+// worker 单次解包的默认超时。
+//   语义：**worker 活着但不响应**的上限（卡住），不是"崩溃检测"——崩溃由 exit 事件立即结算。
+//   为什么 120s：最大的包（几十 MB + LZMA 解压 + 贴图解码）实测在 30~60s 量级，
+//     留一倍余量避免正常慢包被误杀；更长的等待意味着真卡住，继续等没有收益。
+const DEFAULT_TIMEOUT_MS = 120_000;
+
 /**
  * @param {{
  *   rootDir: string,
@@ -30,7 +36,10 @@ const WORKER_URL = new URL('./unpack-worker.mjs', import.meta.url);
 export function createUnpackWorkerClient(opts) {
   const rootDir = opts && opts.rootDir;
   if (!rootDir) throw new Error('createUnpackWorkerClient: rootDir 必填');
-  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 120000;
+  // workerUrl 可注入：仅用于测试「worker 启动即崩溃」这条路径。
+  //   生产调用方不传 ⇒ 用模块级常量，行为与改动前逐字一致。
+  const workerUrl = (opts && opts.workerUrl) || WORKER_URL;
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : DEFAULT_TIMEOUT_MS;
   const log = typeof opts.log === 'function' ? opts.log : () => {};
 
   /** @type {Worker|null} */
@@ -101,22 +110,28 @@ export function createUnpackWorkerClient(opts) {
 
   function ensureWorker() {
     if (worker) return worker;
-    const w = new Worker(WORKER_URL, { workerData: { rootDir } });
+    const w = new Worker(workerUrl, { workerData: { rootDir } });
     w.on('message', onMessage);
     w.on('error', (e) => {
       // worker 自己抛未捕获异常 ⇒ 该次请求 reject、句柄置空、下次重建
       failCurrent('unpack worker crashed', (e && e.message) || e);
       worker = null;
     });
-    w.on('exit', (code) => {
+    w.on('exit', (code, signal) => {
       // 只有"它仍是当前句柄"才算意外退出：超时/close 路径会先把 worker 置空再 terminate，
       //   所以这里判断句柄归属比维护一个全局 terminating 标志更硬 —— 不依赖 exit 与 finally 的先后。
       const wasCurrent = worker === w;
       if (wasCurrent) worker = null;
       if (!wasCurrent) return;
-      if (code !== 0) {
-        failCurrent('unpack worker exited unexpectedly', `exit code ${code}`);
-        log('warn', `解包 worker 异常退出（code ${code}），已丢弃句柄，下次请求将重建`);
+      // 为什么 code === 0 也要让在途请求失败：worker 正常走完生命周期就不会再回消息了，
+      //   不 reject 的话这个请求要白等到 120s 超时，而且报出来的是"timeout"——
+      //   把"已退出"误报成"卡住"，排查方向直接跑偏（这两类要分开）。
+      //   没有在途请求时 failCurrent 内部会早退，所以这里无条件调用是安全的。
+      const hadPending = Boolean(current);
+      failCurrent('unpack worker 已退出', `code=${code === null ? 'null' : code}, signal=${signal || 'none'}`);
+      // 日志只在"异常退出"或"有请求被牵连"时打，避免正常退出刷日志
+      if (code !== 0 || hadPending) {
+        log('warn', `解包 worker 已退出（code=${code === null ? 'null' : code}, signal=${signal || 'none'}），已丢弃句柄，下次请求将重建`);
       }
     });
     worker = w;
@@ -149,7 +164,7 @@ export function createUnpackWorkerClient(opts) {
         Promise.resolve(dead && dead.terminate && dead.terminate()).catch(() => undefined);
         // 清理该 fp 的残留临时目录（writeResult 的 .tmp-<fp>-* 命名规则）
         cleanupTmp(fp);
-        reject(new Error(`unpack worker timeout after ${timeoutMs}ms（本次解包未完成，已终止并重建 worker）`));
+        reject(new Error(`unpack worker 无响应：超过 ${timeoutMs}ms 未返回（worker 仍在运行但卡住了，已终止并重建；与「worker 已退出」是两类问题）`));
       }, timeoutMs);
       current = { id, resolve, reject, timer, onProgress: typeof opts.onProgress === 'function' ? opts.onProgress : null };
       try {

package/src/shared/scan-limits.mjs

@@ -0,0 +1,23 @@
+// shared/scan-limits.mjs —— 扫描判死的阈值（**单一来源**）
+//
+// 为什么放 shared：前端要用它判"多久没进度就算疑似卡住"，将来服务端/插件也可能要读同一个数。
+//   两处各写一份数字，调参时必然漂移（一处改了另一处没改，表现为"前端说卡住、服务端还在跑"）。
+//
+// 口径（设计 §7.3）：
+//   · 这是**无进展**阈值，不是总时长阈值：大目录本来就慢，用总时长判死会误杀正常扫描。
+//   · 每次收到任意一帧（start / progress / done / cached / error）都会重置计时。
+//   · 触发后只改状态与文案，**不自动取消请求** —— 是否重试交给调用方决定。
+
+/** 连续无帧多久 ⇒ 判"疑似卡住"（毫秒） */
+export const SCAN_STALL_MS = 10000;
+
+/**
+ * 解析可覆盖值（来自 `/api/web-config` 的 scanStallMs 或测试注入）。
+ * 非法/缺失一律回落默认：判死阈值必须始终有个可用数字，不能因为配置脏就变成 NaN。
+ * @param {unknown} raw
+ * @returns {number}
+ */
+export function resolveScanStallMs(raw) {
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : SCAN_STALL_MS;
+}

package/src/shared/type-labels.mjs

@@ -0,0 +1,31 @@
+// shared/type-labels.mjs —— 内容类型（kind）的显示名映射（**单一来源**）
+//
+// 谁用：前端名册的类型筛选胶囊、以及将来可能的插件/其它视图。
+// 为什么放 shared 而不是各自写一份：显示名是"同一事实两处表达"的高危点——
+//   前端写一套、插件再写一套，很快就会出现"同一个类型两处叫法不同"。
+//
+// 规则（设计口径）：
+//   · 已知类型 → 可读名（下表）
+//   · 未知类型 → **原样返回 key**，不做大小写美化（避免"看起来认识其实不认识"）
+
+/** kind 为 null/空时的归并键（未解包容器条目走这一档，见设计稿 §5.1） */
+export const UNKNOWN_TYPE_KEY = 'unknown';
+
+/** 内置显示名：键是条目上的 kind 值（null 一律先归成 UNKNOWN_TYPE_KEY） */
+export const TYPE_LABELS = Object.freeze({
+  spine: 'Spine',
+  live2d: 'Live2D',
+  [UNKNOWN_TYPE_KEY]: '待解包',
+  bundle: '资源包',
+});
+
+/**
+ * 取显示名：已知返回中文/品牌名，未知**原值返回**。
+ * @param {string} typeKey 类型键（如 'spine' / 'unknown' / 将来插件的自定义值）
+ * @returns {string}
+ */
+export function typeLabel(typeKey) {
+  const key = String(typeKey == null ? '' : typeKey);
+  if (!key) return String(UNKNOWN_TYPE_KEY);
+  return Object.prototype.hasOwnProperty.call(TYPE_LABELS, key) ? TYPE_LABELS[key] : key;
+}

package/src/web/app/anim-list.js

@@ -125,7 +125,7 @@ export function syncTransportOptions() {
  * 为什么需要：动作是**模型属性**（设计 §1.9），但它的三个副本都是应用层状态，不会自己跟着模型走：
  *   · `cycle.currentId`  —— 循环推进用，名字命中新清单就会继续按旧项推进
  *   · `state.transportMotion` —— 底栏下拉的副本，被 `currentAnimationId()` 优先读取
- *   · 底栏下拉自身的值 —— 新模型若有同名动作（碧蓝航线 live2d 全都叫 idle/home/…），
+ *   · 底栏下拉自身的值 —— 新模型若有同名动作，会被误当成"上次选的那个"，
  *     "保留同名项"的规则会让它原样停在上一个模型选的那条 ⇒ 新模型**真的播它**
  * 三者不清，就会出现"选了 home、切哪个模型都播 home"。
  */

package/src/web/app/backgrounds.js

@@ -42,16 +42,14 @@ export function describeFailure(body, status) {
 /**
  * 统一请求封装：解析 JSON、把失败翻成 {ok:false, reason, message}。
  * @param {string} url 目标地址
- * @param {object} [init] fetch 参数（传 signal 可覆盖兜底超时）
+ * @param {object} [init] fetch 参数（可传 signal 主动取消）
  * @returns {Promise<object>} 成功时为响应体（含 ok:true），失败时 {ok:false, reason, message}
  */
 async function request(url, init) {
   let res;
   try {
-    // 兜底超时 8s：本文件四个调用点（列表/改名/删除/重置）都是读改写一份小 JSON，
-    //   同源同类接口实测 10~58ms（/api/plugins 10ms、/api/config/export 58ms），留 100 倍余量。
-    //   上传那处 body 最大 4MB（dataURL）⇒ 由调用方传更长的 signal 覆盖（见 uploadBackground）。
-    res = await fetch(url, { ...(init || {}), signal: (init && init.signal) || AbortSignal.timeout(8000) });
+    // 不设时限：调用方要取消就传 signal。
+    res = await fetch(url, { ...(init || {}), ...(init && init.signal ? { signal: init.signal } : {}) });
   } catch (e) {
     return { ok: false, reason: 'network', message: `网络请求失败：${(e && e.message) || e}` };
   }
@@ -93,9 +91,7 @@ export function uploadBackground(file) {
       'x-filename': encodeURIComponent(file.name || ''),
     },
     body: file,
-    // 上传单独覆盖成 15s：body 最大 4MB（MAX_BYTES），服务端要收满 + 落盘（CIFS 上写几 MB 可能数秒），
-    //   兜底的 8s 对这一步太紧；其余三个调用点都是小 JSON，用兜底值即可。
-    signal: AbortSignal.timeout(15000),
+    // 不设时限。
   });
 }
 

package/src/web/app/dir-picker.js

@@ -55,7 +55,7 @@ export function createDirPicker({ onPick, formatError, getLastError } = {}) {
         <div class="dir-picker-alert" data-role="alert" role="alert" hidden></div>
         <div class="dir-picker-foot">
           <span class="muted-hint">显示名称（同名会合并成一个游戏，用于归类原版／Mod）</span>
-          <input type="text" data-role="name" placeholder="如：棕色尘埃2" aria-label="资源根显示名称" />
+          <input type="text" data-role="name" placeholder="显示名称" aria-label="资源根显示名称" />
           <button type="button" class="mini-btn is-accent" data-role="add">添加</button>
         </div>
       </div>`;
@@ -75,10 +75,8 @@ export function createDirPicker({ onPick, formatError, getLastError } = {}) {
     body.append(text('div', 'dir-picker-hint', '加载中…'));
     let data = null;
     try {
-      // 幂等 GET（连点同一目录会被 api.js 去重）⇒ 走统一层；超时 30s 的依据：
-      //   本机 CIFS（vers=3.02）实测 75 条目 5.5ms、241 条目 19ms，**未实测到慢例**，
-      //   按项目既有「catalog 冷启动最坏 31s」（同属目录扫描链路）**类推**取 30s。
-      data = await getJson(`/api/browse?path=${encodeURIComponent(currentPath)}`, { timeoutMs: 30000 });
+      // 幂等 GET（连点同一目录会被 api.js 去重）⇒ 走统一层；统一层不设时限，慢就等。
+      data = await getJson(`/api/browse?path=${encodeURIComponent(currentPath)}`);
       if (!data || data.error) throw new Error((data && data.error) || '服务端返回空目录数据');
     } catch (err) {
       body.replaceChildren(text('div', 'dir-picker-error',

package/src/web/app/memory-budget.js

@@ -92,7 +92,6 @@ async function fetchServerJudgement(sourceMb) {
     fetchCount += 1;
     const res = await fetch(`/api/unpack/capacity${qs}`, {
       headers: { Accept: 'application/json' },
-      signal: AbortSignal.timeout(2000),
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
     const j = await res.json();

package/src/web/app/memory-guard.js

@@ -161,7 +161,6 @@ export async function refreshMemoryReadout(target) {
   try {
     const res = await fetch(`/api/unpack/capacity${qs}`, {
       headers: { Accept: 'application/json' },
-      signal: AbortSignal.timeout(2000),
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
     const j = await res.json();

package/src/web/app/model-actions.js

@@ -212,10 +212,10 @@ async function probeSkelVersion(url) {
   try {
     const vfs = getSharedVirtualFS();
     const real = (vfs && typeof vfs.resolve === 'function' ? vfs.resolve(url) : null) || url;
-    // 归 **B 类（只加超时，不走 api.js）**：这里要的是二进制头，不是 JSON —— getJson 会 res.json() 解坏。
-    //   注意 `.slice(0,32)` 是在**已拿到的 blob** 上切，不是 HTTP Range ⇒ 实际仍下载整个 .skel，
-    //   所以超时按"整文件下载"给：20s（CIFS 上几 MB 骨架可能数秒，实测运行时脚本读取同量级）。
-    const res = await fetch(real, { signal: AbortSignal.timeout(20000) });
+    // 不走 api.js：这里要的是二进制头，不是 JSON —— getJson 会 res.json() 解坏。
+    //   注意 `.slice(0,32)` 是在**已拿到的 blob** 上切，不是 HTTP Range ⇒ 实际仍下载整个 .skel。
+    //   不设时限。
+    const res = await fetch(real);
     if (!res || !res.ok) return null;
     // 读前 64 字节：3.8 格式是「hash 串 + 版本串」，两段加起来可能 40+ 字节（实测 1+27+1+7=36）
     const head = new Uint8Array(await (await res.blob()).slice(0, 64).arrayBuffer());
@@ -289,11 +289,11 @@ async function expandContainerEntry(src, name) {
   let fetchNote = '';
   try {
     if (fetchUrl) {
-      // 归 **B 类（只加超时）**：这里必须保留 `cache: 'no-store'`（entry.json 是解包产物，
+      // 归 **B 类**：这里必须保留 `cache: 'no-store'`（entry.json 是解包产物，
       //   读到浏览器缓存会拿到上一版产物）；而 getJson/fetchWithRetry 都不透传 cache 选项，
-      //   走 api.js 会静默丢掉这个语义 ⇒ 宁可只补超时。
-      //   8.5s 与 api.js 默认一致（entry.json 是小 JSON，实测同量级接口 10~58ms）。
-      const res = await fetch(fetchUrl, { cache: 'no-store', signal: AbortSignal.timeout(8500) });
+      //   走 api.js 会静默丢掉这个语义。
+      //   不设时限。
+      const res = await fetch(fetchUrl, { cache: 'no-store' });
       if (res && res.ok) meta = await res.json();
       else fetchNote = `HTTP ${res && res.status}`;
     } else fetchNote = 'resolve 返回空';
@@ -494,8 +494,9 @@ function mountEntry(entry, name) {
   };
 
   // 唯一的装载通路：来源解析在 loadModel 内部完成，这里不再按 kind/source 分支
+  //   **返回这个 promise**：冷启动要能等"首个模型真的出来"再放行加载队列。
   const loadPromise = loadModel(entry, name);
-  loadPromise
+  return loadPromise
     .then((info) => {
       // null = 本次请求被排队/被更新的选择取代（Surface 的 last-wins 语义）：
       //   不能当成功读结果字段，否则出现"旧面已释放 + 新面没装"的空白 + TypeError
@@ -571,7 +572,7 @@ function onSelectModel(model) {
 
   // 换模型 = 换内容：先把「当前动作」的副本清掉（动作是模型属性，见设计 §1.9）。
   //   必须在这里清而不是装载成功后清：装载失败/被拒时也不该残留上一个模型的动作名，
-  //   否则新模型的清单里只要恰好有同名项（碧蓝航线 live2d 全都叫 idle/home/…）就会被继续播。
+  //   否则新模型的清单里只要恰好有同名项，就会被继续播。
   resetMotionState();
   // 无残缺（绝大多数情况）：直接走统一装载入口
   return mountEntry(entry, name);
@@ -602,12 +603,14 @@ async function loadRoots(opts = {}) {
       onSelect: onSelectModel,
     });
     state.roster = roster;
-    // 关闭自动恢复时，连"上次展开的节点"也不还原：保持空舞台、空展开
-    await roster.mount(roots, { restoreExpanded: autoRestore });
+    // 关闭自动恢复时，连"上次展开的节点"也不还原：保持空舞台、空展开。
+    //   mount 内部会做恢复并返回结果 —— 恢复只允许有一个所有者，不再在这里二次调用 restoreLast
+    //   （两个入口会让"先恢复、后排队"的次序随时序漂移而失效）。
     state.autoRestore = autoRestore;
-    state.restore = (autoRestore && !opts.skipRestore)
-      ? await roster.restoreLast()
-      : { restored: false, reason: opts.skipRestore ? 'roots-changed' : 'config-off' };
+    state.restore = await roster.mount(roots, {
+      restoreExpanded: autoRestore,
+      skipRestore: !(autoRestore && !opts.skipRestore),
+    });
     // 资源根管理（F4）：首次建实例并渲染；之后每次刷新都用最新列表重画
     if (!state.rootManager) {
       state.rootManager = createRootManager({