modelstage 0.5.28 → 0.6.1

package/src/server/data/scan-queue.mjs

@@ -0,0 +1,99 @@
+// data/scan-queue.mjs —— 扫描的并发上限、FIFO 队列、以及"有交互请求在等"的让路提示（P0 退化修复）
+//
+// 为什么需要这个模块：
+//   P0 把扫描改成 async 分片让出之后，**多个根的扫描从"自然串行"变成了并发** ——
+//   页面一次加载会同时对 9 个根发 catalog，于是 9 份扫描一起抢 CIFS/磁盘 IO，
+//   事件循环被切碎到连 `/plugins/*.js` 静态文件都拿不到（实测 P95 984ms、最大 6464ms，
+//   9 个 catalog 里 6 个 120s 超时）。
+//
+// 三道闸门（按生效顺序）：
+//   ① **并发上限**：全局同时只允许 CONCURRENCY 个根在扫，其余 FIFO 排队。
+//      这一条就把"9 倍压力"压回"1 倍"，是 ROI 最高的一步。
+//   ② **让路提示**：有 HTTP 请求在途时（`inflight > 0`），扫描把每 tick 的时间预算调小，
+//      优先把事件循环还给 HTTP/静态文件。与既有的"后台形态探测让路"同一思路。
+//   ③ **排队可见**：排队中的 stream 请求立刻收到一帧 `{type:'queued', position}`，
+//      而不是黑着屏等 120s 让人以为死了。
+
+/** 同时允许几个根在扫。1 = 完全串行（最保守，也最能保证交互 P95）。 */
+const CONCURRENCY = 1;
+
+/** 在途 HTTP 请求数（由 serve.mjs 在请求开始/结束时同步进来） */
+let inflightRequests = 0;
+
+/** 排队表：{ key, resolve }，先进先出 */
+const waiting = [];
+/** 当前在扫的数量 */
+let activeCount = 0;
+
+/** 供 serve.mjs 调用：请求开始 */
+export function noteRequestStart() {
+  inflightRequests += 1;
+}
+
+/** 供 serve.mjs 调用：请求结束（含异常路径，必须成对） */
+export function noteRequestEnd() {
+  inflightRequests = Math.max(0, inflightRequests - 1);
+}
+
+/**
+ * 当前是否有交互请求在等 —— 扫描据此决定"每 tick 干多少活"。
+ * 为什么用"在途请求数"而不是"距上次请求多久"：在途数是**现在**的事实，
+ *   时间差是**过去**的推断；长请求（解包、大文件）期间时间差会误判为"没人"。
+ * @returns {boolean}
+ */
+export function isInteractiveBusy() {
+  // **>1 而不是 >0**：触发扫描的那个 HTTP 请求自己就让计数 >=1，用 >0 会恒真 ⇒
+  //   扫描永远走"更频繁让出"分支（实测单根从 24s 恶化到 47s）。
+  //   >1 的意思才是"除了发起者，还有别的交互请求在等"。
+  return inflightRequests > 1;
+}
+
+/** 诊断用：当前在扫几个、排队几个、在途请求几个 */
+export function scanQueueStats() {
+  return { active: activeCount, queued: waiting.length, inflightRequests, concurrency: CONCURRENCY };
+}
+
+/**
+ * 申请一个扫描槽位。满员时排队（FIFO），轮到时 resolve。
+ *
+ * @param {string} key 去重键（`spine:<rootId>` / `live2d:<rootId>`）。同一 key 只会排一次。
+ * @param {(position: number) => void} [onQueued] 刚被排入队列时回调（用于给 stream 发 queued 帧）
+ * @returns {Promise<void>}
+ */
+export function acquireScanSlot(key, onQueued) {
+  // ① 空闲：直接占位
+  if (activeCount < CONCURRENCY && waiting.length === 0) {
+    activeCount += 1;
+    return Promise.resolve();
+  }
+  // ② 已经在排队：复用同一个位置（同一 kind:rootId 不重复排队）
+  const dup = waiting.find((w) => w.key === key);
+  if (dup) {
+    if (onQueued) onQueued(waiting.indexOf(dup) + 1);
+    return dup.promise;
+  }
+  // ③ 排队
+  let resolveFn;
+  const promise = new Promise((resolve) => { resolveFn = resolve; });
+  const entry = { key, resolve: resolveFn, promise };
+  waiting.push(entry);
+  if (onQueued) onQueued(waiting.length);
+  return promise;
+}
+
+/**
+ * 释放扫描槽位并唤醒队首。
+ * 必须与 acquireScanSlot 成对（放在 finally 里 —— 扫描抛错不能把槽位永久占死）。
+ */
+export function releaseScanSlot() {
+  activeCount = Math.max(0, activeCount - 1);
+  if (activeCount < CONCURRENCY) {
+    const next = waiting.shift();
+    if (next) {
+      activeCount += 1;
+      next.resolve();
+    }
+  }
+}
+
+export { CONCURRENCY };

package/src/server/data/spine.mjs

@@ -12,10 +12,16 @@ import fs from 'node:fs';
 import { createLogger } from '../core/log.mjs';
 import { dirSignature, signatureMatches, generatorFingerprint } from './manifest-stamp.mjs';
 import {
-  spineManifestFile, ensureManifestDir, invalidateManifests,
+  spineManifestFile, spineManifestBase, ensureManifestDir, invalidateManifests,
 } from './manifest-cache.mjs';
 import path from 'node:path';
 import { MIME, encodePath, parseAtlasPages } from '../assets/probe.mjs';
+// 进度节流：与单飞层共用同一份实现（P0 起扫描可见进度，节流规则见设计 §5.1）
+import { createProgressThrottle } from './scan-progress.mjs';
+// P1：清单改 JSONL（边扫边写）+ 双读兼容
+import { openManifestWriter, readManifest } from './manifest-jsonl.mjs';
+// 并发上限 + 让路提示（P0 退化修复：9 根并发扫描会把事件循环切碎）
+import { acquireScanSlot, releaseScanSlot, isInteractiveBusy } from './scan-queue.mjs';
 
 
 
@@ -123,7 +129,6 @@ export function buildModelServer(root, relPath, baseName, skel, atlas, dirFiles,
     atlasFile: mk(atlas),
     textureFiles: textures.map(mk),
     textureCount: textures.length,
-    fileSize: skel.size + atlas.size + textures.reduce((s, t) => s + t.size, 0),
     // atlasPma：true/false/null(未声明=未知)。不可硬编码 false —— 那等于断言"非预乘"
     atlasPma: atlas.atlasPma ?? null,
     // avatarRoot 来自 paths（可配置：--avatar-root > MODELSTAGE_AVATAR_ROOT > <root>/avatars）
@@ -139,86 +144,141 @@ export function buildModelServer(root, relPath, baseName, skel, atlas, dirFiles,
 }
 
 /**
- * 建全根文件索引（文件名小写 → 文件记录），供跨目录查找图集页。
- * 必须先建完再建模型：某模型的第 2 页可能位于尚未遍历到的兄弟目录里；
- * 同名文件保留先遇到的（与原版匹配顺序一致）。
+ * **一次遍历**把整棵目录树读进内存（当前唯一碰磁盘的 readdir 入口）。
+ *
+ * 为什么要合并：原来同一棵树被读两遍 —— `indexRootFiles`（readdir 全根）+ `scanRootServer`
+ *   的 `collectDirEntries`（walk 时再 readdir 每个目录）。合并后 walk 阶段**零 IO**。
+ * 结构（键与现有 relPath 口径一致，根用 ''）：
+ *   Map<relPath, { files: [{name, full, ext}], dirs: [{name, full}] }>
+ *   · files 的顺序 = readdir 返回序（**不改**，因为 models 的顺序依赖它）
+ *   · dirs 的顺序同理
+ * 不存 size：`model.fileSize` 已删（死数据），索引里也不需要。
+ *
+ * @param {{path: string, id?: string}} root
+ * @param {{onProgress?: (p: {dirs: number}) => void}} [opts]
+ * @returns {Promise<Map<string, {files: Array, dirs: Array}>>}
  */
-export function indexRootFiles(root) {
-  const fileIndex = new Map();
-  (function indexDir(absDir, relPath) {
+export async function readTreeIntoMemory(root, opts = {}) {
+  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : null;
+  const tree = new Map();
+  let sinceYield = 0;
+  let lastYieldAt = Date.now();
+  let dirsRead = 0;
+
+  const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
+  async function maybeYield() {
+    sinceYield += 1;
+    // 与现有策略一致：每 20 个目录 或 每 50ms 让出一次（别丢让出，否则进度帧与静态文件都会被卡）
+    if (sinceYield >= 20 || Date.now() - lastYieldAt >= 50) {
+      sinceYield = 0;
+      lastYieldAt = Date.now();
+      if (onProgress) onProgress({ dirs: dirsRead });
+      await yieldToEventLoop();
+    }
+  }
+
+  async function visit(absDir, relPath) {
     let entries;
     try {
       entries = fs.readdirSync(absDir, { withFileTypes: true });
     } catch {
+      tree.set(relPath, { files: [], dirs: [] });
       return;
     }
+    const files = [];
+    const dirs = [];
     for (const e of entries) {
       if (e.name.startsWith('.')) continue;
       const full = path.join(absDir, e.name);
-      const childRel = relPath ? `${relPath}/${e.name}` : e.name;
-      let st;
-      try {
-        st = fs.statSync(full);
-      } catch {
-        continue;
-      }
       if (e.isDirectory()) {
-        indexDir(full, childRel);
-        continue;
-      }
-      const key = e.name.toLowerCase();
-      if (!fileIndex.has(key)) {
-        fileIndex.set(key, {
-          name: e.name,
-          full,
-          ext: path.extname(e.name).toLowerCase(),
-          size: st.size,
-          relPath: childRel,
-        });
+        dirs.push({ name: e.name, full });
+      } else {
+        files.push({ name: e.name, full, ext: path.extname(e.name).toLowerCase() });
       }
     }
-  })(root.path, '');
-  return fileIndex;
+    tree.set(relPath, { files, dirs });
+    dirsRead += 1;
+    await maybeYield();
+    // 递归顺序：**先写本节点、再按 dirs 顺序递归**（与原 walk 的深度优先一致）
+    for (const d of dirs) {
+      await visit(d.full, relPath ? `${relPath}/${d.name}` : d.name);
+    }
+  }
+
+  await visit(root.path, '');
+  return tree;
 }
 
-/** 读一个目录的文件与子目录清单（文件附带版本/assetKey/PMA 探测结果）。 */
-export function collectDirEntries(absDir, relPath, deps) {
-  let entries;
-  try {
-    entries = fs.readdirSync(absDir, { withFileTypes: true });
-  } catch {
-    return { files: [], dirs: [] };
-  }
-  const files = [];
-  const dirs = [];
-  for (const e of entries) {
-    if (e.name.startsWith('.')) continue;
-    const full = path.join(absDir, e.name);
-    let st;
-    try {
-      st = fs.statSync(full);
-    } catch {
-      continue;
-    }
-    if (e.isDirectory()) {
-      dirs.push({ name: e.name, full });
-      continue;
+/**
+ * 建全根文件索引（文件名小写 → 文件记录），供跨目录查找图集页。
+
+ * 必须先建完再建模型：某模型的第 2 页可能位于尚未遍历到的兄弟目录里；
+ * 同名文件保留先遇到的（与原版匹配顺序一致）。
+ */
+/**
+ * 从**已读进内存的树**建文件索引（纯内存，零 IO）。
+ * @param {Map<string, {files: Array, dirs: Array}>} tree
+ * @returns {Map<string, {name: string, full: string, ext: string, relPath: string}>}
+ */
+export function indexFromTree(tree) {
+  const fileIndex = new Map();
+  for (const [relPath, node] of tree) {
+    for (const f of node.files) {
+      const key = f.name.toLowerCase();
+      // 同名文件保留先遇到的（与原版匹配顺序一致：depth-first + readdir 序）
+      if (fileIndex.has(key)) continue;
+      fileIndex.set(key, {
+        name: f.name,
+        full: f.full,
+        ext: f.ext,
+        relPath: relPath ? `${relPath}/${f.name}` : f.name,
+      });
     }
-    const ext = path.extname(e.name).toLowerCase();
-    files.push({
-      name: e.name,
-      full,
-      ext,
-      size: st.size,
-      // 该文件相对资源根的路径（贴图可能来自其他目录，故每个文件各自记录）
-      relPath: relPath ? `${relPath}/${e.name}` : e.name,
-      spineVersion: ext === '.skel' ? deps.detectSkelVersion(full)
-        : ext === '.json' ? deps.detectJsonVersion(full) : null,
-      assetKey: ext === '.atlas' ? deps.detectAtlasKey(full) : null,
-      atlasPma: ext === '.atlas' ? deps.detectAtlasPma(full) : null,
-    });
   }
-  return { files, dirs };
+  return fileIndex;
+}
+
+/** 兼容入口：需要索引但手上没有树时用（内部会读一遍树）。scanRootServer 走的是"读一次树、复用"。 */
+export async function indexRootFiles(root, opts = {}) {
+  const tree = await readTreeIntoMemory(root, opts);
+  return indexFromTree(tree);
+}
+
+
+
+/**
+ * 限流地并发执行异步任务，**保持结果顺序**。
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} limit 同时进行的上限
+ * @param {(item: T, index: number) => Promise<R>} fn
+ * @returns {Promise<R[]>}
+ */
+/** 读一个目录的文件与子目录清单（文件附带版本/assetKey/PMA 探测结果）。 */
+/**
+ * 取某个目录的文件与子目录清单 —— **纯内存**（从 readTreeIntoMemory 的树取）。
+ *
+ * 与旧版的差异只有一处：不再 `readdirSync`。文件顺序仍是 readdir 返回序（树里保存的就是它），
+ *   所以 groupModelsInDir / buildModelServer 产出的 models **顺序与内容都不变**。
+ * detect* 仍在（同步读文件头）：它只对 skel/json/atlas 调用，每目录 1~3 次，不是"每文件都做"。
+ * @param {Map<string, {files: Array, dirs: Array}>} tree
+ * @param {string} relPath 相对根的目录路径（根为 ''）
+ * @param {object} deps
+ */
+export function collectDirEntries(tree, relPath, deps) {
+  const node = tree.get(relPath);
+  if (!node) return { files: [], dirs: [] };   // 树里没有 = 读该目录时失败过（原逻辑同样返回空）
+  const files = node.files.map((f) => ({
+    name: f.name,
+    full: f.full,
+    ext: f.ext,
+    relPath: relPath ? `${relPath}/${f.name}` : f.name,
+    spineVersion: f.ext === '.skel' ? deps.detectSkelVersion(f.full)
+      : f.ext === '.json' ? deps.detectJsonVersion(f.full) : null,
+    assetKey: f.ext === '.atlas' ? deps.detectAtlasKey(f.full) : null,
+    atlasPma: f.ext === '.atlas' ? deps.detectAtlasPma(f.full) : null,
+  }));
+  return { files, dirs: node.dirs };
 }
 
 /** 由目录内文件按 base name 分组，构造该目录下的模型列表。 */
@@ -245,21 +305,89 @@ export function groupModelsInDir(root, relPath, files, fileIndex, deps) {
  * 递归扫描一个资源根，收集所有可加载模型。
  * 不同资源根层级不统一（BD2 两层、Mod 三层含 char/npc 分类层），
  * 一律递归到「含骨架+图集的目录」为止，不做针对层级的特殊分支。
- * 全同步实现：本地磁盘操作，同步遍历比异步更简单，也避免 HTTP 处理函数需要 async。
+ * 分片让出的**异步**实现：`collectDirEntries` / `indexRootFiles` 用的是同步 readdir，
+ *   整棵树的遍历会占满一个事件循环切片 —— 期间 res.write 的数据发不出去（实测 433 帧全挤在末尾 2ms）。
+ *   所以每 20 个目录或每 50ms `await setImmediate` 让出一次，进度帧才真的能"边扫边到"。
+ *   注意：这里**没有**用异步 readdir（fs.promises），因为同步 readdir 单次更快、
+ *   且 CIFS 上并发 readdir 收益不明显；分片让出已足够让出 CPU 给 IO 回调。
  */
-export function scanRootServer(root, deps) {
+export async function scanRootServer(root, deps) {
   const models = [];
-  const fileIndex = indexRootFiles(root);
+  // 进度回调是**可选**的：不传就与改动前逐字一致（现有调用方与测试都不传）。
+  //   节流放在这里而不是调用方，因为只有这里同时知道"已扫到第几个目录"和"累计多少模型"。
+  //   **必须定义在建索引之前** —— indexRootFiles 的 onProgress 要引用它（否则 TDZ ReferenceError）。
+  const throttle = deps && typeof deps.onProgress === 'function'
+    ? createProgressThrottle({ onProgress: deps.onProgress, kind: 'spine', rootId: root.id })
+    : null;
+  // **一次遍历**：整棵树读进内存（walk 阶段零 readdir）。
+  //   原来 indexRootFiles 与 collectDirEntries 各读一遍同一棵树 ⇒ 这里成为唯一的磁盘遍历点。
+  const tree = await readTreeIntoMemory(root, {
+    onProgress: throttle
+      ? () => throttle.bump({ scanned: models.length, dirs: 0, currentPath: '(建索引)', dirCompleted: false })
+      : undefined,
+  });
+  const fileIndex = indexFromTree(tree);
+  let dirsScanned = 0;
 
-  function walk(absDir, relPath) {
-    const { files, dirs } = collectDirEntries(absDir, relPath, deps);
-    models.push(...groupModelsInDir(root, relPath, files, fileIndex, deps));
+  /**
+   * 让出事件循环。
+   *
+   * 为什么必须有：`collectDirEntries` 用的是同步 readdir，整个 walk 会在**一个事件循环切片**里跑完
+   *   ⇒ 期间 `res.write` 只进内核缓冲、一帧都发不出去（实测 433 帧全挤在扫描结束后 2ms 内涌出）。
+   *   每积累一点工作量就 `await setImmediate`，把控制权还给 IO 回调，帧才真的能"边扫边到"。
+   * 为什么用 setImmediate 而不是 setTimeout(0)：setImmediate 在 check 阶段就跑，
+   *   没有 setTimeout 的最小 1ms 计时器开销；扫描一次要让出几百次时这个差别不小。
+   */
+  // setImmediate 而不是 setTimeout(0)：实测 setTimeout 在负载下实际延迟可达几十 ms，
+  //   而扫描要让出上千次 ⇒ 单根扫描从 24s 恶化到 169s（7 倍）。setImmediate 在同一 tick 的 check 阶段跑，代价小得多。
+  const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
+
+  // 让出判据：每 20 个目录 **或** 每 50ms，先到就先让出一次。
+  //   只看目录数不够 —— 遇到单个巨大目录时目录数不变但耗时在涨；只看时间不够 —— 空目录树会几乎不让出。
+  const YIELD_DIRS = 20;
+  const YIELD_MS = 50;
+  let sinceYieldDirs = 0;
+  let lastYieldAt = Date.now();
+  async function maybeYield() {
+    sinceYieldDirs += 1;
+    // 让路：有交互请求时**再**多让一点，但幅度有限（实测把阈值压到 5/10 会让扫描慢 7 倍，
+    //   而 P95 只从 984ms 降到 765ms —— 得不偿失）。真正能压住最大值的是非阻塞 IO，不是更频繁让出。
+    const busy = isInteractiveBusy();
+    const dirThreshold = busy ? 12 : YIELD_DIRS;
+    const msThreshold = busy ? 25 : YIELD_MS;
+    if (sinceYieldDirs >= dirThreshold || Date.now() - lastYieldAt >= msThreshold) {
+      sinceYieldDirs = 0;
+      lastYieldAt = Date.now();
+      await yieldToEventLoop();
+    }
+  }
+
+  // 边扫边写挂点：每产出一条模型就回调一次（P1）。不传则完全无副作用。
+  const onModel = deps && typeof deps.onModel === 'function' ? deps.onModel : null;
+  function collectModels(produced) {
+    if (!produced.length) return;
+    models.push(...produced);
+    if (onModel) {
+      for (const m of produced) onModel(m);
+    }
+  }
+
+  async function walk(absDir, relPath) {
+    const { files, dirs } = collectDirEntries(tree, relPath, deps);
+    collectModels(groupModelsInDir(root, relPath, files, fileIndex, deps));
+    dirsScanned += 1;
+    if (throttle) {
+      throttle.bump({ scanned: models.length, dirs: dirsScanned, currentPath: relPath, dirCompleted: true });
+    }
+    await maybeYield();
     for (const d of dirs) {
-      walk(d.full, relPath ? `${relPath}/${d.name}` : d.name);
+      await walk(d.full, relPath ? `${relPath}/${d.name}` : d.name);
     }
   }
 
-  walk(root.path, '');
+  await walk(root.path, '');
+  // 补发最后一帧：保证前端拿到的最终计数与返回的 models.length 一致，而不是停在某个中间值
+  if (throttle) throttle.flush();
   return models;
 }
 
@@ -274,49 +402,135 @@ export function invalidateCaches(configFile, rootId) {
 }
 
 /** 取模型列表（优先读落盘清单，缺失或 force 时才扫描）。同步实现。 */
-export function getSpineModels(configFile, root, force, deps) {
-  const f = spineFile(configFile, root.id);
+/**
+ * 在跑的扫描：key = `spine:<rootId>` → promise。
+ *
+ * 为什么单飞要放在**这里**（而不是只放在 stream 路由层）：
+ *   非流式请求（`/api/spine/models` 不带 stream）原本各自起一次扫描 ——
+ *   实测同一根 30s 内出现 4 次"清单失效重建"，一次 curl 等了 171s。
+ *   放到扫描本体这里，**所有调用方**（流式 / 非流式 / catalog / 探测）自然共用同一次扫描。
+ * force=1 时若已有扫描在跑也**复用**（用户在 UI 上狂点刷新不该变成 N 次全量扫描）。
+ */
+const spineInflight = new Map();
 
-  if (!force && fs.existsSync(f)) {
-    try {
-      const j = JSON.parse(fs.readFileSync(f, 'utf8'));
-      if (j && Array.isArray(j.models)) {
-        // 两道判据，缺一不可：
-        //   ① 生成者指纹 —— 解析代码变了就该重建（dirStamps 只感知目录增删，感知不到代码改动）
-        //   ② 目录签名  —— 资源文件增删后重建，不必等 ?refresh=1
+export async function getSpineModels(configFile, root, force, deps) {
+  const key = `spine:${root.id}`;
+  const existing = spineInflight.get(key);
+  if (existing) return existing;
+
+  // **先占位，再启动** —— 这一步不能省。
+  //   doGetSpineModels 的第一个 await（onStart 后的 setImmediate）会**让出事件循环**；
+  //   如果先调它、后 set，那么同一 tick 里进来的并发请求都会看到"没人跑" ⇒ 各起一次扫描
+  //   （实测：4 个并发 refresh=1 ⇒ 重建 4 次、总墙钟 334s）。
+  //   先塞一个 pending promise 进表，后来者立刻拿到同一个 promise。
+  let settleResolve;
+  let settleReject;
+  const gate = new Promise((resolve, reject) => { settleResolve = resolve; settleReject = reject; });
+  spineInflight.set(key, gate);
+  doGetSpineModels(configFile, root, force, deps)
+    .then(settleResolve, settleReject)
+    .finally(() => { if (spineInflight.get(key) === gate) spineInflight.delete(key); });
+  return gate;
+}
+
+/** 真正干活的实现（单飞包装见上面的 getSpineModels） */
+async function doGetSpineModels(configFile, root, force, deps) {
+  const base = spineManifestBase(configFile, root.id);
+  // 写入格式：**默认 .json（保持原有行为）**；MODELSTAGE_MANIFEST_FORMAT=jsonl 才写 JSONL。
+  //   两种格式都可读（readManifest 优先当前格式、缺失回落另一种），切换不需要迁移历史文件。
+  const wantJsonl = String(process.env.MODELSTAGE_MANIFEST_FORMAT || 'json').toLowerCase() === 'jsonl';
+
+  if (!force) {
+    // 双读：.jsonl 优先，缺则回落 .json（历史格式，视为 complete=true —— 兼容关键）
+    const m = readManifest(base);
+    if (m.format !== 'none') {
+      if (!m.complete) {
+        // 第三道门：半成品不当结果（进程被杀 / 写入中断）。先重建，别把半截清单当答案。
+        log.info('清单不完整（complete 非 true），重建', { root: root.id, badLines: m.badLines, err: m.error || null });
+      } else {
+        // 前两道门原样保留（现在从 meta 读）：① 解析器指纹 ② 目录签名
         const gen = generatorFingerprint();
-        if (j.generator !== gen) {
-          log.info('解析器已变化，清单失效重建', { root: root.id, from: j.generator || null, to: gen });
-        } else if (signatureMatches(j.dirStamps, root.path)) {
-          return { models: j.models, cached: true, ts: j.ts || Date.now() };
+        if (m.meta.generator !== gen) {
+          log.info('解析器已变化，清单失效重建', { root: root.id, from: m.meta.generator || null, to: gen });
+        } else if (signatureMatches(m.meta.dirStamps, root.path)) {
+          return { models: m.models, cached: true, ts: m.meta.ts || Date.now() };
         } else {
           log.info('目录已变化，清单失效重建', { root: root.id });
         }
       }
-    } catch (e) {
-      log.warn('清单读取失败，将重新扫描', { file: f, err: e.message });
     }
   }
 
-  const models = scanRootServer(root, deps);
-  const payload = {
-    rootId: root.id,
-    rootName: root.name,
-    rootPath: root.path,
-    ts: Date.now(),
-    count: models.length,
-    // 生成时的目录签名：下次读清单先比对它，目录增删即自动重建（详见 manifest-stamp.mjs）
-    dirStamps: dirSignature(root.path),
-    // 生成时的解析器指纹：解析代码一改，这份清单自动失效（无需手工删文件）
-    generator: generatorFingerprint(),
-    models,
-  };
-  // 原子写入，避免写到一半被读到损坏内容
+  // 在真正开始扫描前通知一次 —— 让"首帧到达"不必等 indexRootFiles 那一步（同步建索引，实测 4s+）
+  if (deps && typeof deps.onStart === 'function') {
+    deps.onStart();
+    // **必须紧接着让出一次**：res.write 只是把数据放进 Node 的输出缓冲，
+    //   真正写到 socket 要等事件循环的下一个 tick。而下一步 indexRootFiles 是同步的（实测 4.6s），
+    //   不让出的话首帧照样要等到扫描启动才到达 —— 那样 onStart 就白加了。
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+
+  const ts = Date.now();
+  const generator = generatorFingerprint();
+  // 目录签名在扫描**前**算：它只扫根的一层子目录 mtime（ms 级），不影响首帧；
+  //   而且它必须与"这次扫描看到的内容"对应，放扫描后算反而可能记进别人刚改的结果。
+  const dirStamps = dirSignature(root.path);
+
   ensureManifestDir(configFile);   // 清单目录（config/models/）可能还不存在：首次运行或目录被清空
+
+  // 边扫边写：writer 在 run 内创建、与这次扫描同生命周期 —— 单飞保证同一 key 只有一个 writer。
+  //   同步 append 是微秒级（几十~几百字节），不会像目录遍历那样长时间占住事件循环。
+  const writer = wantJsonl
+    ? openManifestWriter(base, { rootId: root.id, ts, generator, dirStamps })
+    : null;
+  // onModel 双路：一路喂 writer（边扫边写清单），一路喂 deps.onModel（→ emitter → 流式 model 帧）。
+  //   两条路互不影响：没有 writer（json 回退模式）时照样能流式吐模型。
+  const upstreamOnModel = deps && typeof deps.onModel === 'function' ? deps.onModel : null;
+  const scanDeps = (writer || upstreamOnModel)
+    ? {
+      ...deps,
+      onModel: (m) => {
+        if (writer) writer.append(m);
+        if (upstreamOnModel) upstreamOnModel(m);
+      },
+    }
+    : deps;
+
+  // 并发上限：全局同时只允许 1 个根在扫，其余 FIFO 排队。
+  //   为什么必须在扫描**之前**排队：9 根并发时如果都开始扫，事件循环会被切碎到
+  //   连静态文件都拿不到（实测 /plugins/*.js P95 984ms、9 个 catalog 里 6 个 120s 超时）。
+  await acquireScanSlot(`spine:${root.id}`, (position) => {
+    if (deps && typeof deps.onQueued === 'function') deps.onQueued(position);
+  });
+
+  let models;
+  try {
+    models = await scanRootServer(root, scanDeps);
+    if (writer) writer.finish(models.length);
+  } catch (e) {
+    // 失败只 abort：正式 .jsonl 保持上一次的完整版本（tmp 留着供排查）
+    if (writer) writer.abort();
+    throw e;
+  } finally {
+    // 必须成对释放（放 finally）：扫描抛错不能把槽位永久占死，否则后续请求永久排队
+    releaseScanSlot();
+  }
+
+  if (wantJsonl) {
+    log.info('已生成清单（jsonl）', { file: path.basename(base) + '.jsonl', count: models.length, bytes: writer.bytesWritten });
+    return { models, cached: false, ts };
+  }
+
+  // 回退：只写 .json（旧格式，一次性序列化 —— 这个分支本来就不支持"边扫边写"）
+  // 清单头**与 live2d 完全一致**：{ v, rootId, ts, count, generator, dirStamps, models }。
+  //   rootName/rootPath 已移除（grep 过：只有写入方、没有消费方）；
+  //   kind 一律不写进清单（前端需要的类型由 catalog 读取时盖章）。
+  const payload = { rootId: root.id, ts, count: models.length, generator, dirStamps, models };
+  const f = `${base}.json`;
   fs.writeFileSync(`${f}.tmp`, JSON.stringify(payload), 'utf8');
   fs.renameSync(`${f}.tmp`, f);
-  log.info('已生成清单', { file: path.basename(f), count: models.length });
-  return { models, cached: false, ts: payload.ts };
+  log.info('已生成清单（json 回退）', { file: path.basename(f), count: models.length });
+  return { models, cached: false, ts };
 }
 
 /**
@@ -326,11 +540,15 @@ export function getSpineModels(configFile, root, force, deps) {
  */
 export function createSpineModels(p, deps) {
   return {
-    getSpineModels: (root, force) => getSpineModels(p.configFile, root, force, deps),
+    // 第三个参数是**每次调用的额外 deps**（目前只有 onProgress）：与既有 deps 合并即可，
+    //   不传时逐字等同于旧行为。(p.configFile/root/force/deps 都在闭包里)
+    getSpineModels: (root, force, extraDeps) => getSpineModels(
+      p.configFile, root, force, extraDeps ? { ...deps, ...extraDeps } : deps,
+    ),
     spineFile: (rootId) => spineFile(p.configFile, rootId),
     invalidateCaches: (rootId) => invalidateCaches(p.configFile, rootId),
     buildModelServer,
-    scanRootServer: (root) => scanRootServer(root, deps),
+    scanRootServer: (root) => scanRootServer(root, deps),   // 返回 Promise（已 async 化）
     resolveIconUrl,
   };
 }

package/src/server/plugins/registry.mjs

@@ -463,7 +463,7 @@ export function enabledPluginKinds(pluginsDir, switchFile) {
 /**
  * 按**魔数**识别资源包容器（kind:"bundle" 的资源根用）。
  *
- * 为什么不能按扩展名：碧蓝航线的 Live2D 资源包就是**无扩展名**的单文件（实测样本 `adaerbote_3`），
+ * 为什么不能按扩展名：Live2D 资源包常是**无扩展名**的单文件，
  *   按扩展名过滤会一个都列不出来。容器标识在文件头，读前 8 字节即可判定，成本可忽略。
  *
  * @param {string} abs 文件绝对路径