modelstage 0.0.0-stage → 0.5.28

package/src/server/data/spine.mjs

@@ -0,0 +1,336 @@
+// spine.mjs —— Spine 模型扫描与清单缓存（config/models/spine.<rootId>.json）
+//   本模块只认 Spine（.skel/.json + 同名 .atlas 配对）；Live2D 走 live2d.mjs。
+//   清单路径、目录创建、失效逻辑在 manifest-cache.mjs —— 那是两个扫描器共用的，不属于这里。
+
+const log = createLogger('models');
+//
+// 逻辑逐字搬自 server.mjs（行为等价由 sha256 逐字节比对验证）。
+// 与旧实现的唯一差别是**结构**：原先一个函数里套着全部步骤，这里按阶段拆成
+// 「建索引 → 收集目录条目 → 按 base name 分组 → 组装模型」，便于阅读与单独测试；
+// 路径依赖（清单文件位置）改成显式入参，模块内不持有全局路径。
+import fs from 'node:fs';
+import { createLogger } from '../core/log.mjs';
+import { dirSignature, signatureMatches, generatorFingerprint } from './manifest-stamp.mjs';
+import {
+  spineManifestFile, ensureManifestDir, invalidateManifests,
+} from './manifest-cache.mjs';
+import path from 'node:path';
+import { MIME, encodePath, parseAtlasPages } from '../assets/probe.mjs';
+
+
+
+/**
+ * 头像解析（三条候选路，按优先级）：
+ *   ① 头像仓：<avatarRoot>/<names>/<avatar>（v2 主路；avatarRoot 可配置，见 docs/设计/名表.md §4.1）
+ *   ② 旧 icons.dir：/icons/<rootId>/<文件名>（v1 兼容，双轨期保留）
+ *   ③ 模型目录自带的 icon.png：/files/<rootId>/<相对路径>
+ * 都没有 ⇒ null（前端用占位图，不阻塞）。
+ *
+ * 为什么头像仓要**先 stat 再返回 URL**：头像仓可能与 index 不同步（index 里写了 avatar 文件名，
+ *   但 png 还没提取）。不 stat 就给 URL，前端会拿到 404 的 img，比"没有头像"更难看。
+ *
+ * @param {Function} getNameTable 名表读取函数（由调用方注入，避免本模块依赖项目根）
+ * @param {{avatarRoot?: string}} [opts] avatarRoot = 头像仓根（可配置）
+ */
+export function resolveIconUrl(root, relPath, modelName, dirFiles, getNameTable, opts = {}) {
+  // 名表服务端不认识结构（names.mjs 原样透传）：byAsset[key] 是角色 id（字符串），
+  //   条目里的头像文件名在 `icon` 字段。只取这两样，不碰 name/costume 等业务字段。
+  const t = getNameTable(root);
+  const key = String(modelName).toLowerCase();
+  const map = (t && t.byAsset) ? t.byAsset[key] : null;
+  const id = typeof map === 'string' ? map : (map && map.char) || null;
+  const entry = (id && t.characters) ? t.characters[id] : null;
+  const avatar = entry ? String(entry.icon || '') : '';
+  // ① 头像仓优先
+  if (avatar && opts.avatarRoot && root.names) {
+    const abs = path.join(opts.avatarRoot, String(root.names), avatar);
+    if (fs.existsSync(abs)) {
+      return `/avatars/${encodeURIComponent(root.names)}/${encodeURIComponent(avatar)}`;
+    }
+  }
+  // ② 旧路：icons.dir（v1 兼容）
+  if (avatar && root.icons && root.icons.dir) {
+    return `/icons/${encodeURIComponent(root.id)}/${encodeURIComponent(avatar)}`;
+  }
+  // ③ 模型目录自带的 icon.png（Live2D）
+  if (dirFiles && dirFiles.has('icon.png')) {
+    const rel = relPath ? `${relPath}/icon.png` : 'icon.png';
+    return `/files/${encodeURIComponent(root.id)}/${encodePath(rel)}`;
+  }
+  return null;
+}
+
+/** 按 atlas 声明的页名收集贴图：同目录优先，找不到再退化为全根按文件名找。 */
+export function collectTextures(relPath, atlas, dirFiles, fileIndex) {
+  const pages = parseAtlasPages(atlas.full);
+  const textures = [];
+  const missing = [];
+  for (const p of pages) {
+    const key = p.toLowerCase();
+    let hit = dirFiles.find((f) => f.name.toLowerCase() === key);
+    if (!hit && fileIndex) hit = fileIndex.get(key);
+    if (hit) textures.push(hit);
+    else missing.push(p);
+  }
+  if (missing.length) {
+    log.warn('缺贴图页（同目录与全根均未找到）', { dir: relPath || '.', missing });
+  }
+  return { textures, missing };
+}
+
+/** 生成「文件 → 对外引用」的构造函数（每个文件用它自己的 relPath）。 */
+export function makeFileRef(rootId, relPath) {
+  return (f) => {
+    const rel = f.relPath || (relPath ? `${relPath}/${f.name}` : f.name);
+    return {
+      name: f.name,
+      path: rel,
+      size: f.size,
+      type: MIME[f.ext] || 'application/octet-stream',
+      url: `/api/file?root=${encodeURIComponent(rootId)}&path=${encodeURIComponent(rel)}`,
+    };
+  };
+}
+
+/**
+ * 由一个目录里的「骨架 + 同名图集」构造模型条目。
+ * 注意（职责划分）：后端不做任何分组/聚合，只如实提供原始信息；
+ *   角色归一是前端显示层的职责（见 public/char-tree.js 的 charKeyOf()）。
+ */
+export function buildModelServer(root, relPath, baseName, skel, atlas, dirFiles, fileIndex, deps) {
+  const rootId = root.id;
+  const rootName = root.name;
+  const { textures } = collectTextures(relPath, atlas, dirFiles, fileIndex);
+  // format：照抄原版实现 —— 文件名含 ".skel" 为 "skel"，否则 "json"
+  const format = skel.name.toLowerCase().includes('.skel') ? 'skel' : 'json';
+  const mk = makeFileRef(rootId, relPath);
+  // 归一 key：atlas 内容首行的贴图名（去扩展名 + 小写）—— 该资源的真实标识
+  const assetKey = atlas.assetKey || baseName;
+  const dirPath = `${rootId}/${relPath}`;
+  const idPath = (relPath ? `${relPath}/` : '') + baseName;
+
+  return {
+    id: `local-${rootId}-${idPath.replace(/\//g, '_')}`,
+    name: assetKey,
+    srcDir: relPath,
+    rootId,
+    rootName,
+    directory: `${rootName}/${relPath}`,
+    dirPath,
+    version: skel.spineVersion || '4.0',
+    format,
+    skeletonFile: mk(skel),
+    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）
+    iconUrl: resolveIconUrl(root, relPath, assetKey, new Set(dirFiles.map((f) => f.name)), deps.getNameTable, { avatarRoot: deps.avatarRoot }),
+    animations: [],
+    skins: [],
+    boneCount: 0,
+    slotCount: 0,
+    importedAt: Date.now(),
+    source: 'user',
+    localRoot: true,
+  };
+}
+
+/**
+ * 建全根文件索引（文件名小写 → 文件记录），供跨目录查找图集页。
+ * 必须先建完再建模型：某模型的第 2 页可能位于尚未遍历到的兄弟目录里；
+ * 同名文件保留先遇到的（与原版匹配顺序一致）。
+ */
+export function indexRootFiles(root) {
+  const fileIndex = new Map();
+  (function indexDir(absDir, relPath) {
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    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,
+        });
+      }
+    }
+  })(root.path, '');
+  return fileIndex;
+}
+
+/** 读一个目录的文件与子目录清单（文件附带版本/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;
+    }
+    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 };
+}
+
+/** 由目录内文件按 base name 分组，构造该目录下的模型列表。 */
+export function groupModelsInDir(root, relPath, files, fileIndex, deps) {
+  const models = [];
+  const groups = new Map();
+  for (const f of files) {
+    const base = f.name.replace(/\.[^.]+$/, '');
+    if (!groups.has(base)) groups.set(base, {});
+    groups.get(base)[f.ext] = f;
+  }
+  for (const [base, g] of groups) {
+    // 同名骨架优先取 .skel：二进制体积约为 .json 的一半，且是运行时标准格式
+    const skel = g['.skel'] || g['.json'];
+    const atlas = g['.atlas'];
+    // 纯 png 目录（缺骨架或图集）不构成可加载模型，跳过
+    if (!skel || !atlas) continue;
+    models.push(buildModelServer(root, relPath, base, skel, atlas, files, fileIndex, deps));
+  }
+  return models;
+}
+
+/**
+ * 递归扫描一个资源根，收集所有可加载模型。
+ * 不同资源根层级不统一（BD2 两层、Mod 三层含 char/npc 分类层），
+ * 一律递归到「含骨架+图集的目录」为止，不做针对层级的特殊分支。
+ * 全同步实现：本地磁盘操作，同步遍历比异步更简单，也避免 HTTP 处理函数需要 async。
+ */
+export function scanRootServer(root, deps) {
+  const models = [];
+  const fileIndex = indexRootFiles(root);
+
+  function walk(absDir, relPath) {
+    const { files, dirs } = collectDirEntries(absDir, relPath, deps);
+    models.push(...groupModelsInDir(root, relPath, files, fileIndex, deps));
+    for (const d of dirs) {
+      walk(d.full, relPath ? `${relPath}/${d.name}` : d.name);
+    }
+  }
+
+  walk(root.path, '');
+  return models;
+}
+
+/** Spine 清单文件路径（实现在 manifest-cache 里，与 Live2D 清单同一目录）。 */
+export function spineFile(configFile, rootId) {
+  return spineManifestFile(configFile, rootId);
+}
+
+/** 失效清单（不传 rootId 则全部）。两套清单一并处理，实现在 manifest-cache。 */
+export function invalidateCaches(configFile, rootId) {
+  invalidateManifests(configFile, rootId);
+}
+
+/** 取模型列表（优先读落盘清单，缺失或 force 时才扫描）。同步实现。 */
+export function getSpineModels(configFile, root, force, deps) {
+  const f = spineFile(configFile, root.id);
+
+  if (!force && fs.existsSync(f)) {
+    try {
+      const j = JSON.parse(fs.readFileSync(f, 'utf8'));
+      if (j && Array.isArray(j.models)) {
+        // 两道判据，缺一不可：
+        //   ① 生成者指纹 —— 解析代码变了就该重建（dirStamps 只感知目录增删，感知不到代码改动）
+        //   ② 目录签名  —— 资源文件增删后重建，不必等 ?refresh=1
+        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() };
+        } 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,
+  };
+  // 原子写入，避免写到一半被读到损坏内容
+  ensureManifestDir(configFile);   // 清单目录（config/models/）可能还不存在：首次运行或目录被清空
+  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 };
+}
+
+/**
+ * 绑定型适配器：把 configFile 与探测函数预先固定，调用方只需 (root, force)。
+ * @param {{configFile: string}} p
+ * @param {object} deps 探测与名表函数
+ */
+export function createSpineModels(p, deps) {
+  return {
+    getSpineModels: (root, force) => getSpineModels(p.configFile, root, force, deps),
+    spineFile: (rootId) => spineFile(p.configFile, rootId),
+    invalidateCaches: (rootId) => invalidateCaches(p.configFile, rootId),
+    buildModelServer,
+    scanRootServer: (root) => scanRootServer(root, deps),
+    resolveIconUrl,
+  };
+}

package/src/server/data/tree.mjs

@@ -0,0 +1,126 @@
+// tree.mjs —— 目录树列举（/api/tree 的数据层）
+//
+// 响应对象结构与键序与旧实现保持一致（便于逐字节比对）。
+//   · **不再按资源根类型分流**：同一个根里可以既有普通模型目录、也有容器单文件；
+//   · 普通文件按扩展名识别（Spine 三件套附版本/assetKey）；
+//   · 无扩展名或未知扩展名的文件才读 8 字节头判断是不是容器（UnityFS），命中挂 `container` 标记，
+//     由发现层（roster）决定它是不是一个可装载条目。
+import fs from 'node:fs';
+import path from 'node:path';
+import { SPINE_EXT } from '../assets/probe.mjs';
+
+/**
+ * 已知的「普通文件」扩展名：命中这些就不必探容器魔数（省掉打开文件的代价）。
+ *
+ * 导出给 catalog 的容器列举复用 —— 这份集合若在两处各写一份必然漂移：
+ *   一处加了新扩展名、另一处没加，表现是「某个根能列出容器、另一个根列不出」，
+ *   两边都不报错，最难查。这里是唯一真相。
+ */
+export const KNOWN_FILE_EXT = new Set([
+  '.json', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.txt', '.md', '.bin', '.skel', '.atlas', '.ogg', '.mp3', '.wav',
+]);
+
+/** 读目录条目；失败返回 null（由调用方转 500） */
+function readEntries(abs) {
+  try {
+    return fs.readdirSync(abs, { withFileTypes: true });
+  } catch (e) {
+    return { error: e };
+  }
+}
+
+/**
+ * 通用列举：目录项 + 文件项（**不假设根的内容类型**）。
+ *
+ * 为什么无扩展名/未知扩展名的文件才探魔数：读头是有代价的（打开文件），
+ *   而绝大多数“普通模型文件”靠扩展名就能判定；只对剩下的少数做 8 字节探测，
+ *   既有“混合根”能力，也不会把每个文件都打开一遍。
+ *
+ * @param {object} opts
+ * @param {boolean} opts.containersAvailable 是否有启用的插件能读容器（没有则只计数不列出）
+ */
+function collectEntries(abs, relPosix, entries, probe, plugins, containersAvailable) {
+  const dirs = [];
+  const files = [];
+  let hidden = 0;
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const full = path.join(abs, e.name);
+    let st;
+    try {
+      st = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    if (e.isDirectory()) {
+      dirs.push({ name: e.name, type: 'dir' });
+      continue;
+    }
+    const ext = path.extname(e.name).toLowerCase();
+    const item = { name: e.name, type: 'file', ext, size: st.size };
+
+    if (SPINE_EXT.has(ext)) {
+      // Spine 三件套：只读必要的少量头部信息
+      item.isSpine = true;
+      item.spineVersion = ext === '.skel' ? probe.detectSkelVersion(full) : null;
+      item.assetKey = ext === '.atlas' ? probe.detectAtlasKey(full) : null;
+    } else if (!KNOWN_FILE_EXT.has(ext)) {
+      // 未知/无扩展名：可能是容器单文件（资源包本质就是打包来的模型）
+      const container = plugins.detectBundleContainer(full);
+      if (container) {
+        if (!containersAvailable) { hidden += 1; continue; }
+        item.container = container;
+        item.rel = relPosix ? `${relPosix}/${e.name}` : e.name;
+      }
+    }
+    files.push(item);
+  }
+  return { dirs, files, hidden };
+}
+
+/**
+ * 列某个资源根下的目录（单一列举路径：不再按根类型分流）。
+ * @returns {{status: number, body: object}}
+ */
+export function listTree(deps, rootId, rel) {
+  const { config, plugins, probe } = deps;
+  const cfg = config.readConfig().find((r) => r.id === rootId);
+  if (!cfg) return { status: 400, body: { error: `未找到资源根: ${rootId}` } };
+  const abs = probe.resolveSafe(cfg.path, rel);
+  if (!abs) return { status: 403, body: { error: '路径越界' } };
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+    return { status: 404, body: { error: '目录不存在', path: rel } };
+  }
+
+  const entries = readEntries(abs);
+  if (entries && entries.error) return { status: 500, body: { error: entries.error.message } };
+
+  // 有没有启用的插件能读容器：决定"容器单文件"要不要列出来（没有插件就列了也没用）
+  const containersAvailable = plugins.enabledPluginKinds().has('bundle');
+  const relPosix = rel.split(path.sep).join('/').replace(/^\/+|\/+$/g, '');
+  const collected = collectEntries(abs, relPosix, entries, probe, plugins, containersAvailable);
+
+  const dirs = collected.dirs.sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+  const files = collected.files.sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+
+  // 容器单文件被插件可用性挡掉时把原因带回（可探测，不静默）
+  if (collected.hidden) {
+    return {
+      status: 200,
+      body: {
+        root: rootId,
+        path: rel,
+        dirs,
+        files,
+        hiddenByPlugin: collected.hidden,
+        note: `本根有 ${collected.hidden} 个容器单文件被隐藏：没有启用的插件声明 fileKind 'bundle'（见 config/plugins.json）`,
+      },
+    };
+  }
+  return { status: 200, body: { root: rootId, path: rel, dirs, files } };
+}
+
+/** 绑定型适配器 */
+export function createTree(deps) {
+  return { listTree: (rootId, rel) => listTree(deps, rootId, rel) };
+}

package/src/server/http/atomic-json.mjs

@@ -0,0 +1,145 @@
+// http/atomic-json.mjs —— JSON 落盘的原子写法 + 串行队列 + 备份轮转
+//
+// ⚠️ 本项目还有另一处**非原子**的 JSON 写（`http/backgrounds.mjs` 的背景图索引；
+//    以及 config 的写盘路径），尚未迁过来。**新增写盘一律用本模块**，
+//    不要再手写 `writeFileSync` + `rename` —— 少一步 fsync 就可能出现
+//    "rename 成功但内容还是空洞"（断电/崩溃时 rename 先落盘、数据块没落盘）。
+//
+// 为什么需要 fsync：rename 的原子性只保证"看到的是旧文件或新文件"，
+//   不保证新文件的内容已经落盘。崩溃窗口里 rename 已生效而数据块仍在页缓存 ⇒ 得到 0 字节文件。
+//   顺序必须是：写 tmp → fsync(tmp) → rename(tmp→target)。（目录项本身要不要 fsync，见下说明）
+//
+// 零依赖：只用 node:fs。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyFilePortable } from '../core/fs-portable.mjs';
+
+/** 新建文件的默认权限（其他可读；项目 check-perms 前置检查要求 go+r） */
+const FILE_MODE = 0o644;
+
+/** 新建目录的默认权限（其他可进出） */
+const DIR_MODE = 0o755;
+
+/**
+ * 确保目录存在（首次使用时创建，权限 0755）。
+ * @param {string} dir
+ */
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+}
+
+/**
+ * 原子写 JSON：写临时文件 → fsync → rename 覆盖。
+ *
+ * 目录项本身不额外 fsync：目标场景是"进程崩溃/被 kill"，此时 rename 已由内核记录；
+ *   只有"整机掉电"才需要连目录一起 fsync，而本项目是家用 NAS 上的预览器，
+ *   不为此引入 `open(dir)` 平台差异（Windows 上目录 fsync 会直接失败）。
+ *
+ * @param {string} file 目标文件绝对路径
+ * @param {any} value 要写入的 JS 值（JSON 序列化，2 空格缩进）
+ * @returns {{bytes:number}} 写入字节数（便于调用方做"内容是否变化"的判断与日志）
+ */
+export function writeJsonAtomic(file, value) {
+  ensureDir(path.dirname(file));
+  const text = `${JSON.stringify(value, null, 2)}\n`;
+  const tmp = `${file}.tmp`;
+  const fd = fs.openSync(tmp, 'w', FILE_MODE);
+  try {
+    fs.writeFileSync(fd, text, 'utf8');
+    fs.fsyncSync(fd);          // ← 关键：数据落盘后再 rename
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  // rename 之后补一次 chmod：某些文件系统/umask 会让 openSync 的 mode 被削弱
+  try { fs.chmodSync(file, FILE_MODE); } catch { /* 已存在且权限正确时可能失败，忽略 */ }
+  return { bytes: Buffer.byteLength(text) };
+}
+
+/**
+ * 原子写**任意字节**（图片等二进制）：写 tmp → fsync → rename，与 writeJsonAtomic 同一套顺序。
+ *
+ * 为什么图片也要 fsync：上传后"索引里有这条、文件却是 0 字节"的窗口确实存在，
+ *   而取文件路径只校验 `statSync(abs).isFile()` —— 0 字节文件照样算存在，
+ *   没有任何自愈会把这条剔除 ⇒ 用户长期看到破图。图片不大（上限几 MB），一次 fsync 的代价可接受。
+ * @param {string} file 目标文件绝对路径
+ * @param {Uint8Array|Buffer} bytes 内容
+ * @returns {{bytes:number}}
+ */
+export function writeFileAtomic(file, bytes) {
+  ensureDir(path.dirname(file));
+  const tmp = `${file}.tmp`;
+  const fd = fs.openSync(tmp, 'w', FILE_MODE);
+  try {
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);          // ← 数据落盘后再 rename（顺序与 writeJsonAtomic 一致）
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  try { fs.chmodSync(file, FILE_MODE); } catch { /* 已正确时可能失败，忽略 */ }
+  return { bytes: bytes.length };
+}
+
+/**
+ * 串行队列：把"读-改-写"整段排进队列，避免两次并发修改互相覆盖。
+ *
+ * 为什么不是锁：单进程单事件循环下，队列已经足够（并且没有任何"进程崩了锁不释放"的风险）。
+ *   跨进程/多实例共享同一目录**不保证**顺序 —— 见 docs/契约/数据与接口.md 的说明。
+ * @returns {(fn: () => any) => Promise<any>}
+ */
+export function createSerialQueue() {
+  let chain = Promise.resolve();
+  return function enqueue(fn) {
+    const next = chain.then(fn, fn);
+    // 队列自身不能被失败拖死：吞掉拒绝，只把结果（或异常）交给调用方
+    chain = next.then(() => undefined, () => undefined);
+    return next;
+  };
+}
+
+/**
+ * 备份轮转：同名前缀的备份文件只保留最近 keep 份，更早的删除。
+ *
+ * 为什么必须轮转：`reset` 与"损坏自愈"都会留备份，用户多点几次就会堆出几十个文件，
+ *   而这些都是**运行数据**（不入库），堆着只会占空间、还会让 `ls` 失去可读性。
+ *
+ * @param {string} dir 备份所在目录
+ * @param {string} prefix 文件名前缀（如 'solids.bak-'）
+ * @param {number} keep 保留份数（默认 5）
+ * @returns {{kept:string[], removed:string[]}}
+ */
+export function rotateBackups(dir, prefix, keep = 5) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return { kept: [], removed: [] }; }
+  // 文件名形如 solids.bak-1750000000000.json：按前缀筛，按名字倒序（时间戳是定长的 ⇒ 字典序=时间序）
+  const hits = names.filter((n) => n.startsWith(prefix)).sort().reverse();
+  const kept = hits.slice(0, keep);
+  const removed = [];
+  for (const n of hits.slice(keep)) {
+    try { fs.rmSync(path.join(dir, n), { force: true }); removed.push(n); } catch { /* 删不掉不影响主流程 */ }
+  }
+  return { kept, removed };
+}
+
+/**
+ * 备份一份文件（用于"损坏文件留证"与"reset 前存档"）。
+ * @param {string} src 源文件
+ * @param {string} dir 备份目录
+ * @param {string} prefix 备份名前缀（含结尾的 '-'，如 'solids.corrupt-'）
+ * @param {number} at epoch ms（同毫秒多次备份时自动加序号，避免互相覆盖）
+ * @param {number} keep 轮转保留份数
+ * @returns {string|null} 备份文件名（失败返回 null）
+ */
+export function backupFile(src, dir, prefix, at = Date.now(), keep = 5) {
+  let name = `${prefix}${at}.json`;
+  try {
+    if (fs.existsSync(path.join(dir, name))) name = `${prefix}${at}-${process.pid}.json`;
+    copyFilePortable(src, path.join(dir, name));
+    rotateBackups(dir, prefix, keep);
+    return name;
+  } catch {
+    return null;
+  }
+}