modelstage 0.5.28 → 0.6.1

package/config/models/spine.nikke_2.json

@@ -1 +1 @@
-{"rootId":"nikke_2","rootName":"NIKKE","rootPath":"/volume1/VirtualDSM/DeepSeekHarness/工作区/资源/NIKKE","ts":1793458443470,"count":0,"dirStamps":{"root":1793370056514,"dirs":{"PC預覽可用 - 新":1730713861813,"[Seireiko]":1793370082759}},"generator":"642803b7","models":[]}
+{"rootId":"nikke_2","ts":1794127311813,"count":0,"generator":"793f6b2e","dirStamps":{"root":1793370056514,"dirs":{"PC預覽可用 - 新":1730713861813,"[Seireiko]":1793370082759}},"models":[]}

package/config/models/spine.npc.json

@@ -1 +1 @@
-{"rootId":"npc","rootName":"棕色尘埃2","rootPath":"/volume1/VirtualDSM/DeepSeekHarness/npc","ts":1793868513580,"count":0,"dirStamps":{"root":null,"dirs":{}},"generator":"642803b7","models":[]}
+{"rootId":"npc","ts":1794078060417,"count":0,"generator":"07d15bbe","dirStamps":{"root":null,"dirs":{}},"models":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelstage",
-  "version": "0.5.28",
+  "version": "0.6.1",
   "description": "Spine / Live2D 模型查看器：三级名册、两套渲染面共享相机与面板、UnityFS 资源包解包",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "config/resources.example.json",
     "config/diag-upload.example.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "!**/.tmp-*",
     "!**/*.bak",

package/src/server/assets/probe.mjs

@@ -150,7 +150,7 @@ export function parseAtlasPages(atlasPath) {
   try {
     // 先剥一次 BOM 再按行匹配。原因：JS 的 \s **包含 U+FEFF**，而 AssetStudio 导出的 atlas
     //   首行是「BOM + 页名」（EF BB BF ...）⇒ 不剥的话首行被 /^[^\s]/ 判成"有前导空白"整行跳过
-    //   ⇒ 多页图集的**第一页页名丢失**（现场：NIKKE 根 247 个模型里 34 份 atlas 带 BOM，均丢第一页 ⇒ 贴图拿不到、画面空白）。
+    //   ⇒ 多页图集的**第一页页名丢失** ⇒ 贴图拿不到、画面空白。
     // 为什么前端 src/web/engine/textures.js 没这个坑：它**先 trim() 再匹配**，而 trim() 会把 U+FEFF
     //   当空白吃掉 —— 所以那边页名本来就干净。这里剥 BOM 就是与"先 trim"等价，别删。
     // 只剥解析用的文本：**不改 atlas 落盘字节、不改页名大小写**（产物必须逐字节不变）。

package/src/server/core/config.mjs

@@ -126,8 +126,8 @@ function readHeader() {
  * 按 name（显示名称 = 归一 key）把资源根归并成组，供前端直接渲染。
  *
  * 归一语义：name 相同的多个资源根合并为一个条目。
- *   例：「棕色尘埃2 原版」与「棕色尘埃2 mod」两个目录若都命名为"棕色尘埃2"，
- *      界面合并成一个"棕色尘埃2"，其下汇总各 root 的模型（原版 + mod 共存不覆盖）。
+ *   例：原版目录与 Mod 目录若填了同一个显示名，界面合并成一个条目，
+ *      其下汇总各 root 的模型（原版 + Mod 共存不覆盖）。
  *
  * @param {Array} roots 资源根数组
  * @returns {Array<{name:string, rootCount:number, roots:Array}>}

package/src/server/core/log.mjs

@@ -6,7 +6,7 @@
 //
 // 记录形状（与前端同一套字段名）：{ at, level, tag, msg, detail }
 // 输出格式（单行，人读 + 可解析兼顾）：
-//   14:32:07.981 INFO  [models] 已生成清单 models.bd2.json {"count":389}
+//   14:32:07.981 INFO  [models] 已生成清单 spine.<rootId>.json {"count":0}
 //   └ 固定宽度前缀 ⇒ 正则 /^(\d{2}:\d{2}:\d{2}\.\d{3}) (\w+)\s+\[(\S+)\] (.*?)(\{.*\})?$/ 可切四段
 // 流向：error → stderr（真正的异常），debug/info/warn → stdout。
 //   项目启动脚本是 `nohup … >"$LOG_FILE" 2>&1`，两流合并写同一文件，所以分流不丢日志，

package/src/server/data/catalog.mjs

@@ -209,7 +209,6 @@ export function toSpineEntry(cfg, m) {
       skins: m.skins || [],
       expressions: [],
       textureCount: m.textureCount,
-      fileSize: m.fileSize,
       extras: {
         versionLabel: m.version,
         format: m.format,
@@ -316,7 +315,6 @@ function buildLive2DMeta(lm, fromDef, textureCheck) {
     textureCount: (lm.textureFiles || []).length,
     // 声明了但磁盘缺失的纹理（前端据此预判并给出明确提示，不必等渲染报错）
     missingTextures: textureCheck.missing,
-    fileSize: lm.fileSize,
     extras: { cubism: lm.cubism, defFile: lm.defFile, mocFile: lm.mocFile },
   };
 }
@@ -446,9 +444,9 @@ export function toBundleEntry(cfg, file, provider, owner = null) {
 /**
  * 容器列举的规模上限 —— 值来自**实测**，不是拍脑袋。
  *
- * 实测 6 个 enabled 资源根（2026-10 现场）：
- *   文件最大深度 3（bd2）｜目录数 max 535（azurlane）｜容器命中最多 19（azurlane_bundle，全在根层）
- *   nikke_2 的 3 个容器在**第二层**（`<角色名>/<包>`）—— 这正是"只扫根层"会漏掉的那类。
+ * 实测多个真实资源根：
+ *   文件最大深度 3 ｜ 目录数数百 ｜ 容器命中十几个
+ *   也有根的容器在**第二层**（`<角色名>/<包>`）—— 这正是"只扫根层"会漏掉的那类。
  * 深度取「实测 max + 1」，给未来更深的 Mod 类根留一层余量。
  *
  * 超限**绝不静默截断**：stopped 带回原因，由调用方写进 warnings
@@ -469,7 +467,7 @@ const BUNDLE_SCAN_MAX_HITS = 500;
  *   "顺手统一成 listTree"会把冷启动拖回 31 秒 —— 这条注释就是防这个的。
  *
  * 只对**未知扩展名**的文件读 8 字节魔数，扩展名集合复用 tree 的 `KNOWN_FILE_EXT`（同一份真相）：
- *   实测 bd2 / azurlane / azurlane_spine 三个大根的未知扩展名文件数都是 **0**，
+ *   实测常见资源根的未知扩展名文件数为 **0**，
  *   即这三个根一次文件打开都不需要，成本全在 readdir 本身。
  *
  * 返回 `byDir`（按目录聚合）是为将来「按 dirSignature 缓存」留的钩子：
@@ -535,9 +533,8 @@ export function findContainerFiles(rootPath, detectContainer, opts = {}) {
 /**
  * 列资源包根下的条目（递归，不再只看根层）。
  *
- * 为什么必须递归：资源包的实际摆法不统一 —— 有的根把包平铺在根层
- *   （azurlane_bundle：19 个包全在 L0），有的按 `<角色名>/<包>` 分目录
- *   （nikke_2：3 个包都在 L1）。只看根层时后者 catalog 条目为 0，
+ * 为什么必须递归：资源包的实际摆法不统一 —— 有的根把包平铺在根层，
+ *   有的按 `<角色名>/<包>` 分目录。只看根层时后者 catalog 条目为 0，
  *   表现是"资源包明明在盘上，模型列表里却没有"。
  *
  * @returns {{entries: Array, warnings: string[], skipped: number}}
@@ -764,7 +761,7 @@ export function createCatalog({ config, spine, live2d, tree, plugins, unpack = n
    * @returns {{entries: Array, warnings: string[], scanErrors: Error[],
    *            cachedAll: boolean, pathProblem: string|null}}
    */
-  function scanRootEntries(cfg) {
+  async function scanRootEntries(cfg) {
     const entries = [];
     const warnings = [];
     /** 扫描过程中抛的错（用于判断 rootWarning 该说"扫不动"还是"真的空"） */
@@ -775,7 +772,7 @@ export function createCatalog({ config, spine, live2d, tree, plugins, unpack = n
     const pathProblem = inspectRootPath(cfg.path);
 
     try {
-      const scan = spine.getSpineModels(cfg, false);
+      const scan = await spine.getSpineModels(cfg, false);
       for (const m of scan.models) entries.push(toSpineEntry(cfg, m));
       if (scan.cached !== true) cachedAll = false;
     } catch (e) {
@@ -783,7 +780,7 @@ export function createCatalog({ config, spine, live2d, tree, plugins, unpack = n
       warnings.push(`spine 扫描失败：${e.message}`);
     }
     try {
-      const scan = live2d.getLive2DModels(cfg, false);
+      const scan = await live2d.getLive2DModels(cfg, false);
       for (const lm of scan.models) entries.push(toLive2DEntry(cfg, lm));
       if (scan.cached !== true) cachedAll = false;
     } catch (e) {
@@ -801,14 +798,14 @@ export function createCatalog({ config, spine, live2d, tree, plugins, unpack = n
     return { entries, warnings, scanErrors, cachedAll, pathProblem, skipped: bundle.skipped };
   }
 
-  function listCatalog(rootId) {
+  async function listCatalog(rootId) {
     const t0 = performance.now();
     const cfg = config.readConfig().find((r) => r.id === rootId);
     if (!cfg) {
       // 形状与其它接口的错误体保持一致；按约定这里用 404（资源根不存在）
       return { status: 404, body: { error: `未找到资源根: ${rootId}` } };
     }
-    const { entries, warnings, scanErrors, cachedAll, pathProblem, skipped } = scanRootEntries(cfg);
+    const { entries, warnings, scanErrors, cachedAll, pathProblem, skipped } = await scanRootEntries(cfg);
     const { sawStale } = assembleEntryStates(cfg, entries);
     // §八 触发来源（三选一，别混成一条）：这一根里只要有一条是"旧结论作废"排进来的，
     //   就说明这轮探测是**能力变化**引起的（fingerprint）；否则是清单重建引起的（catalog）。

package/src/server/data/live2d.mjs

@@ -10,10 +10,16 @@
 import fs from 'node:fs';
 import { createLogger } from '../core/log.mjs';
 import { dirSignature, signatureMatches, generatorFingerprint } from './manifest-stamp.mjs';
-import { live2dManifestFile, ensureManifestDir } from './manifest-cache.mjs';
+import { live2dManifestFile, ensureManifestDir, live2dManifestBase } from './manifest-cache.mjs';
 import path from 'node:path';
 import { encodePath } from '../assets/probe.mjs';
 import { resolveLive2DRuntimes } from '../../../tool/resolve-live2d-runtimes.mjs';
+// 进度节流：与 Spine 侧共用同一份实现
+import { createProgressThrottle } from './scan-progress.mjs';
+// P1：清单改 JSONL（边扫边写）+ 双读兼容
+import { openManifestWriter, readManifest } from './manifest-jsonl.mjs';
+// 并发上限 + 让路提示（同 spine，理由见 scan-queue.mjs 顶部）
+import { acquireScanSlot, releaseScanSlot, isInteractiveBusy } from './scan-queue.mjs';
 
 /** 本模块日志（统一形状 {at,level,tag,msg,detail}） */
 const log = createLogger('live2d');
@@ -21,7 +27,6 @@ const log = createLogger('live2d');
 const rtLog = createLogger('live2d-runtimes');
 
 /** Live2D 清单缓存的格式版本（结构变更时 +1，旧缓存自动失效重扫） */
-const LIVE2D_MANIFEST_VERSION = 1;
 /** 运行时库文件清单缓存（探测一次即复用） */
 let live2dRuntimeFilesCache = null;
 
@@ -125,7 +130,6 @@ export function buildLive2DModel(root, relPath, defName, cubism) {
 
   return {
     id: `live2d-${root.id}-${(relPath || '.').replace(/\//g, '_')}`,
-    kind: 'live2d',
     cubism,
     name,
     srcDir: relPath,
@@ -140,30 +144,26 @@ export function buildLive2DModel(root, relPath, defName, cubism) {
     motions,
     // 列表缩略图：模型目录里的 icon.png（有则用）
     iconUrl: fileObj('icon.png') ? fileUrl('icon.png') : null,
-    fileSize: [defName, mocName, ...textures, ...expressions.map((e) => e.file),
-      ...Object.values(motions).flat().map((mo) => mo.file)]
-      .map(fileObj).filter(Boolean).reduce((sum, f) => sum + f.size, 0),
   };
 }
 
 /** 扫一个目录：识别 Cubism 4（*.model3.json）优先于 Cubism 2（model.json）。 */
 function modelsInDir(root, absDir, relPath, entries) {
+  // 同步（回退理由同 spine.collectDirEntries：异步化在 CIFS 上更慢）
   const dirs = [];
   const files = new Map(); // 文件名 -> { name, size }
   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;
-    }
+    // **不再逐文件 stat**：目录判定用 Dirent（`e.isDirectory()`）；
+    //   这里原来的 size 唯一用途是 `model.fileSize`（前端从未读过，死数据）。
+    //   注意：`fileObj()` 里的 stat **保留** —— 它要 `st.isFile()` 判「文件真的在不在」，
+    //   去掉会让「引用不存在的贴图」从告警变成沉默（缺贴图页数会变多）。
     if (e.isDirectory()) {
       dirs.push({ name: e.name, full });
       continue;
     }
-    files.set(e.name, { name: e.name, size: st.size });
+    files.set(e.name, { name: e.name });
   }
   const out = [];
   const def4 = [...files.keys()].find((n) => /\.model3\.json$/i.test(n)) || null;
@@ -176,10 +176,33 @@ function modelsInDir(root, absDir, relPath, entries) {
 }
 
 /** 扫描一个资源根里的全部 Live2D 模型。 */
-export function scanLive2DRootServer(root) {
+export async function scanLive2DRootServer(root, opts = {}) {
   const models = [];
+  // 进度回调可选：不传时与改动前逐字一致（现有调用方不传）
+  const throttle = typeof opts.onProgress === 'function'
+    ? createProgressThrottle({ onProgress: opts.onProgress, kind: 'live2d', rootId: root.id })
+    : null;
+  let dirsScanned = 0;
+
+  // 分片让出：与 spine 侧同一套策略（每 20 个目录或每 50ms），理由见 spine.mjs 里的注释
+  // setImmediate 而不是 setTimeout(0)：后者在负载下实际延迟可达几十 ms，扫描让出上千次会累积成数倍劣化（实测 24s→169s）
+  const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
+  const YIELD_DIRS = 20;
+  const YIELD_MS = 50;
+  let sinceYieldDirs = 0;
+  let lastYieldAt = Date.now();
+  async function maybeYield() {
+    sinceYieldDirs += 1;
+    // 让路：有交互请求时再多让一点，但幅度有限（理由见 spine.mjs 同处注释）
+    const busy = isInteractiveBusy();
+    if (sinceYieldDirs >= (busy ? 12 : YIELD_DIRS) || Date.now() - lastYieldAt >= (busy ? 25 : YIELD_MS)) {
+      sinceYieldDirs = 0;
+      lastYieldAt = Date.now();
+      await yieldToEventLoop();
+    }
+  }
 
-  function walk(absDir, relPath) {
+  async function walk(absDir, relPath) {
     let entries;
     try {
       entries = fs.readdirSync(absDir, { withFileTypes: true });
@@ -187,11 +210,25 @@ export function scanLive2DRootServer(root) {
       return;
     }
     const found = modelsInDir(root, absDir, relPath, entries);
-    models.push(...found.models);
-    for (const d of found.dirs) walk(d.full, relPath ? `${relPath}/${d.name}` : d.name);
+    // 边扫边写挂点（P1）：不传则完全无副作用
+    if (found.models.length) {
+      models.push(...found.models);
+      if (typeof opts.onModel === 'function') {
+        for (const m of found.models) opts.onModel(m);
+      }
+    }
+    dirsScanned += 1;
+    if (throttle) {
+      throttle.bump({ scanned: models.length, dirs: dirsScanned, currentPath: relPath, dirCompleted: true });
+    }
+    await maybeYield();
+    for (const d of found.dirs) {
+      await walk(d.full, relPath ? `${relPath}/${d.name}` : d.name);
+    }
   }
 
-  walk(root.path, '');
+  await walk(root.path, '');
+  if (throttle) throttle.flush();
   return models;
 }
 
@@ -199,41 +236,103 @@ export function scanLive2DRootServer(root) {
  * 取 Live2D 模型列表（带落盘缓存，逻辑与 Spine 的 getModels 一致）。
  * 为什么缓存：天命之子有 2000+ 角色目录，每次刷新全量扫描会明显变慢。
  */
-export function getLive2DModels(configFile, cfg, force) {
-  const file = live2dModelsFile(configFile, cfg.id);
-  if (!force && fs.existsSync(file)) {
-    try {
-      const payload = JSON.parse(fs.readFileSync(file, 'utf8'));
-      if (payload.version === LIVE2D_MANIFEST_VERSION && Array.isArray(payload.models)) {
-        // 与 spine 清单同口径：两道判据 —— 生成者指纹（解析代码变）+ 目录签名（资源增删）
+/**
+ * 在跑的扫描：key = `live2d:<rootId>` → promise（与 spine 同口径，理由见 spine.mjs 里的注释）。
+ */
+const live2dInflight = new Map();
+
+export async function getLive2DModels(configFile, cfg, force, onProgress, onStart, onModel) {
+  const key = `live2d:${cfg.id}`;
+  const existing = live2dInflight.get(key);
+  if (existing) return existing;
+  // 先占位再启动（同 spine，理由见其注释）
+  let settleResolve;
+  let settleReject;
+  const gate = new Promise((resolve, reject) => { settleResolve = resolve; settleReject = reject; });
+  live2dInflight.set(key, gate);
+  doGetLive2DModels(configFile, cfg, force, onProgress, onStart, onModel)
+    .then(settleResolve, settleReject)
+    .finally(() => { if (live2dInflight.get(key) === gate) live2dInflight.delete(key); });
+  return gate;
+}
+
+/** 真正干活的实现（单飞包装见上面的 getLive2DModels） */
+async function doGetLive2DModels(configFile, cfg, force, onProgress, onStart, onModel) {
+  const base = live2dManifestBase(configFile, cfg.id);
+  // 与 spine 同口径：默认 .json，env=jsonl 才写 JSONL（两种都能读）
+  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），重建', { id: cfg.id, badLines: m.badLines });
+      } else {
         const gen = generatorFingerprint();
-        if (payload.generator !== gen) {
-          log.info('解析器已变化，清单失效重建', { id: cfg.id, from: payload.generator || null, to: gen });
-        } else if (signatureMatches(payload.dirStamps, cfg.path)) {
-          return { models: payload.models, cached: true, ts: payload.ts };
+        if (m.meta.generator !== gen) {
+          log.info('解析器已变化，清单失效重建', { id: cfg.id, from: m.meta.generator || null, to: gen });
+        } else if (signatureMatches(m.meta.dirStamps, cfg.path)) {
+          return { models: m.models, cached: true, ts: m.meta.ts };
         } else {
           log.info('目录已变化，清单失效重建', { id: cfg.id });
         }
       }
-    } catch {
-      /* 缓存损坏则重扫 */
     }
   }
-  const models = scanLive2DRootServer(cfg);
+
   const ts = Date.now();
+  const generator = generatorFingerprint();
+  const dirStamps = dirSignature(cfg.path);
+  ensureManifestDir(configFile);
+
+  const writer = wantJsonl
+    ? openManifestWriter(base, { rootId: cfg.id, ts, generator, dirStamps })
+    : null;
+
+  // 并发上限（同 spine）：全局只允许 1 个根在扫
+  await acquireScanSlot(`live2d:${cfg.id}`);
+
+  let models;
+  try {
+    models = await scanLive2DRootServer(cfg, {
+      ...(onProgress ? { onProgress } : {}),
+      ...(typeof onStart === 'function' ? { onStart } : {}),
+      ...((writer || typeof onModel === 'function')
+        ? {
+          onModel: (m) => {
+            if (writer) writer.append(m);
+            if (typeof onModel === 'function') onModel(m);
+          },
+        }
+        : {}),
+    });
+    if (writer) writer.finish(models.length);
+  } catch (e) {
+    if (writer) writer.abort();
+    throw e;
+  } finally {
+    releaseScanSlot();
+  }
+
+  if (wantJsonl) {
+    log.info('已生成清单（jsonl）', { id: cfg.id, count: models.length, bytes: writer.bytesWritten });
+    return { models, cached: false, ts };
+  }
+
+  // 回退：只写 .json（旧格式）
   try {
-    // 目录建一次就够（ensureManifestDir 内部就是 mkdir -p）。原先它前面还有一句
-    //   fs.mkdirSync(path.dirname(file)) —— 建的是同一个目录，重复调用，已删。
-    ensureManifestDir(configFile);
+    const file = `${base}.json`;
+    // 清单头与 spine 完全一致（见 docs：v 是唯一的格式版本字段；kind 一律不写进清单，
+    //   由 catalog 读取时盖章；rootName/rootPath 无消费方已移除）
     const body = JSON.stringify({
-      version: LIVE2D_MANIFEST_VERSION,
       rootId: cfg.id,
       ts,
-      dirStamps: dirSignature(cfg.path),   // 同上：目录签名供下次读清单时比对
-      generator: generatorFingerprint(),   // 解析器指纹：解析代码一改，清单自动失效
+      count: models.length,
+      generator,
+      dirStamps,
       models,
     });
-    // 与 spine 清单同口径：先写临时文件再 rename，避免并发读拿到半份 JSON
     fs.writeFileSync(`${file}.tmp`, body, 'utf8');
     fs.renameSync(`${file}.tmp`, file);
   } catch (e) {
@@ -266,7 +365,7 @@ export function createLive2d(p) {
     live2dModelsFile: (rootId) => live2dModelsFile(p.configFile, rootId),
     buildLive2DModel,
     scanLive2DRootServer,
-    getLive2DModels: (cfg, force) => getLive2DModels(p.configFile, cfg, force),
+    getLive2DModels: (cfg, force, onProgress, onStart, onModel) => getLive2DModels(p.configFile, cfg, force, onProgress, onStart, onModel),
     getLive2DRuntimeFiles,
   };
 }

package/src/server/data/manifest-cache.mjs

@@ -17,14 +17,28 @@ export function manifestDir(configFile) {
   return path.join(path.dirname(configFile), 'models');
 }
 
-/** Spine 清单路径：config/models/spine.<rootId>.json */
+/**
+ * 清单的**基名**（不带扩展名）：config/models/spine.<rootId>
+ * 为什么引入 base：同一份清单现在有两种落盘格式（.jsonl 当前 / .json 历史），
+ *   读写层需要"同一个名字 + 不同后缀"，而不是各自拼一遍字符串（拼两处早晚拼歪）。
+ */
+export function spineManifestBase(configFile, rootId) {
+  return path.join(manifestDir(configFile), `spine.${rootId}`);
+}
+
+/** Live2D 清单基名：config/models/live2d.<rootId> */
+export function live2dManifestBase(configFile, rootId) {
+  return path.join(manifestDir(configFile), `live2d.${rootId}`);
+}
+
+/** Spine 清单路径（历史 JSON 格式）：config/models/spine.<rootId>.json */
 export function spineManifestFile(configFile, rootId) {
-  return path.join(manifestDir(configFile), `spine.${rootId}.json`);
+  return `${spineManifestBase(configFile, rootId)}.json`;
 }
 
-/** Live2D 清单路径：config/models/live2d.<rootId>.json */
+/** Live2D 清单路径（历史 JSON 格式）：config/models/live2d.<rootId>.json */
 export function live2dManifestFile(configFile, rootId) {
-  return path.join(manifestDir(configFile), `live2d.${rootId}.json`);
+  return `${live2dManifestBase(configFile, rootId)}.json`;
 }
 
 /** 写清单前确保目录存在（首次运行或目录被清空时，不能因为缺目录写失败） */
@@ -37,21 +51,50 @@ export function ensureManifestDir(configFile) {
  * 文件不存在、目录不存在都不算错（本来就没有清单可删）。
  */
 export function invalidateManifests(configFile, rootId) {
+  // **只删成品**（.jsonl / .json），**不删 tmp**。
+  //
+  //   为什么 tmp 不能删：tmp 是"扫描正在写的那份"。invalidate 可能被**并发触发**
+  //   （另一个根 refresh、或任何一次失效），删掉正在写的 tmp ⇒ 那个扫描 finish 时 rename ENOENT
+  //   （实测日志：`rename 'spine.<rootId>.jsonl.tmp' -> 'spine.<rootId>.jsonl'`）。
+  //   tmp 现在带 pid+seq 唯一名，靠"年龄"清理：只删老到不可能是"正在写"的。
+  const FINAL_SUFFIXES = ['.jsonl', '.json'];
+  const TMP_MAX_AGE_MS = 60 * 60 * 1000;   // 1 小时：正常扫描远用不到，超过即视为残留
+  const TMP_RE = /\.\d+\.\d+\.jsonl\.tmp$/;   // <base>.<pid>.<seq>.jsonl.tmp
+
+  function cleanupStaleTmp(dir) {
+    const now = Date.now();
+    try {
+      for (const n of fs.readdirSync(dir)) {
+        if (!TMP_RE.test(n)) continue;
+        const full = path.join(dir, n);
+        try {
+          // 只删老的：新 tmp 可能正是另一个扫描正在写的
+          if (now - fs.statSync(full).mtimeMs > TMP_MAX_AGE_MS) fs.unlinkSync(full);
+        } catch { /* 单个文件处理失败不影响整体 */ }
+      }
+    } catch { /* 目录读不了就算了 */ }
+  }
+
   if (rootId) {
-    for (const f of [spineManifestFile(configFile, rootId), live2dManifestFile(configFile, rootId)]) {
-      try {
-        if (fs.existsSync(f)) fs.unlinkSync(f);
-      } catch {
-        /* 删除失败不影响调用方：清单不可用会被后续扫描覆盖 */
+    for (const base of [spineManifestBase(configFile, rootId), live2dManifestBase(configFile, rootId)]) {
+      for (const suffix of FINAL_SUFFIXES) {
+        const f = `${base}${suffix}`;
+        try {
+          if (fs.existsSync(f)) fs.unlinkSync(f);
+        } catch {
+          /* 删除失败不影响调用方：清单不可用会被后续扫描覆盖 */
+        }
       }
     }
+    cleanupStaleTmp(manifestDir(configFile));
     return;
   }
   try {
     const dir = manifestDir(configFile);
     for (const n of fs.readdirSync(dir)) {
-      if (/^(?:spine|live2d)\..+\.json$/.test(n)) fs.unlinkSync(path.join(dir, n));
+      if (/^(?:spine|live2d)\..+\.(?:jsonl|json)$/.test(n)) fs.unlinkSync(path.join(dir, n));
     }
+    cleanupStaleTmp(dir);
   } catch {
     /* 目录不存在 = 没有清单要删 */
   }