modelstage 0.0.0-stage → 0.5.28

package/src/server/data/live2d.mjs

@@ -0,0 +1,272 @@
+// live2d.mjs —— Live2D 模型扫描、清单缓存与运行时库探测
+
+//
+// 逻辑逐字搬自 server.mjs（行为等价由 sha256 逐字节比对验证）。
+// 与旧实现的差别只在**结构**：把原先套在工厂里的步骤按职责拆开
+// （引用构造 / 定义归一 / 表情 / 动作 / 组装），并把清单路径改成显式入参。
+//
+// 与 Spine 的关键差异：Live2D 定义文件内部用**相对路径**引用同目录文件，
+//   因此对外必须给**路径式** URL（/files/<rootId>/<相对路径>）——查询串式会在相对解析时丢掉。
+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 path from 'node:path';
+import { encodePath } from '../assets/probe.mjs';
+import { resolveLive2DRuntimes } from '../../../tool/resolve-live2d-runtimes.mjs';
+
+/** 本模块日志（统一形状 {at,level,tag,msg,detail}） */
+const log = createLogger('live2d');
+/** tool/ 层探测消息单独一个 tag：一眼看出是"运行时库探测"而不是"模型清单" */
+const rtLog = createLogger('live2d-runtimes');
+
+/** Live2D 清单缓存的格式版本（结构变更时 +1，旧缓存自动失效重扫） */
+const LIVE2D_MANIFEST_VERSION = 1;
+/** 运行时库文件清单缓存（探测一次即复用） */
+let live2dRuntimeFilesCache = null;
+
+/** Live2D 清单文件路径（与 Spine 的 models.<id>.json 并列，互不干扰）。 */
+export function live2dModelsFile(configFile, rootId) {
+  return live2dManifestFile(configFile, rootId);
+}
+
+/** 构造两个引用工具：对外 URL 与「磁盘上存在才返回」的文件对象。 */
+export function makeLive2DRefs(root, relPath) {
+  const fileUrl = (name) => `/files/${encodeURIComponent(root.id)}/${encodePath(relPath ? `${relPath}/${name}` : name)}`;
+  // 引用可能带子目录（Cubism 4 实测 Textures 为 textures/texture_00.png），
+  //   故直接按磁盘相对模型目录判断存在性，而不是只在本目录直接子文件里找
+  const fileObj = (name) => {
+    if (!name) return null;
+    const abs = path.join(root.path, relPath, name);
+    let st;
+    try {
+      st = fs.statSync(abs);
+    } catch {
+      return null;
+    }
+    if (!st.isFile()) return null;
+    return {
+      name: path.basename(name),
+      path: relPath ? `${relPath}/${name}` : name,
+      size: st.size,
+      url: fileUrl(name),
+    };
+  };
+  return { fileUrl, fileObj };
+}
+
+/**
+ * 归一引用字段：**Cubism 4 在 FileReferences 下，Cubism 2 在顶层**，
+ * 且两者字段名大小写不同（4 首字母大写、2 小写），这里统一成一套内部表示。
+ */
+export function normalizeLive2DRefs(cubism, def) {
+  const fr = (cubism === 4 && def.FileReferences) ? def.FileReferences : def;
+  return {
+    rawMoc: cubism === 4 ? fr.Moc : def.model,
+    rawTextures: (cubism === 4 ? fr.Textures : def.textures) || [],
+    rawExpressions: (cubism === 4 ? fr.Expressions : def.expressions) || [],
+    rawMotions: (cubism === 4 ? fr.Motions : def.motions) || {},
+  };
+}
+
+/** 表情：Cubism 2 用小写 file/name，Cubism 4 用大写 File/Name，两者都要兼容。 */
+export function buildExpressions(rawExpressions, fileObj, fileUrl) {
+  return (Array.isArray(rawExpressions) ? rawExpressions : [])
+    .map((e) => (e ? { name: e.Name || e.name, file: e.File || e.file } : null))
+    .filter((e) => e && e.file && fileObj(e.file))
+    .map((e) => ({
+      name: e.name || path.basename(String(e.file)).replace(/\.[^.]+$/, ''),
+      file: e.file,
+      url: fileUrl(e.file),
+    }));
+}
+
+/** 动作：按分组聚合，只保留磁盘上确实存在的文件。 */
+export function buildMotions(rawMotions, fileObj, fileUrl) {
+  const motions = {};
+  for (const [group, list] of Object.entries(rawMotions)) {
+    const arr = (Array.isArray(list) ? list : [])
+      .map((mo) => (mo ? {
+        file: mo.File || mo.file,
+        fadeIn: mo.FadeIn !== undefined ? mo.FadeIn : mo.fade_in,
+        fadeOut: mo.FadeOut !== undefined ? mo.FadeOut : mo.fade_out,
+      } : null))
+      .filter((mo) => mo && mo.file && fileObj(mo.file))
+      .map((mo) => ({
+        name: path.basename(String(mo.file)).replace(/\.[^.]+$/, ''),
+        file: mo.file,
+        url: fileUrl(mo.file),
+        fadeIn: mo.fadeIn,
+        fadeOut: mo.fadeOut,
+      }));
+    if (arr.length) motions[group] = arr;
+  }
+  return motions;
+}
+
+/** 构造 Live2D 模型对象（一个定义文件 = 一个模型）。 */
+export function buildLive2DModel(root, relPath, defName, cubism) {
+  const absDef = path.join(root.path, relPath, defName);
+  let def;
+  try {
+    def = JSON.parse(fs.readFileSync(absDef, 'utf8'));
+  } catch (e) {
+    log.warn('定义文件解析失败', { file: `${relPath}/${defName}`, err: e.message });
+    return null;
+  }
+
+  const { rawMoc, rawTextures, rawExpressions, rawMotions } = normalizeLive2DRefs(cubism, def);
+  const { fileUrl, fileObj } = makeLive2DRefs(root, relPath);
+  const mocName = rawMoc ? String(rawMoc) : '';
+  const textures = (Array.isArray(rawTextures) ? rawTextures : []).filter((t) => typeof t === 'string' && fileObj(t));
+  const expressions = buildExpressions(rawExpressions, fileObj, fileUrl);
+  const motions = buildMotions(rawMotions, fileObj, fileUrl);
+  const name = (relPath || '').split('/').pop() || relPath || root.id;
+
+  return {
+    id: `live2d-${root.id}-${(relPath || '.').replace(/\//g, '_')}`,
+    kind: 'live2d',
+    cubism,
+    name,
+    srcDir: relPath,
+    rootId: root.id,
+    rootName: root.name,
+    // 前端加载入口：**路径式** URL，定义文件里的相对引用才能正确解析
+    modelUrl: fileUrl(defName),
+    defFile: fileObj(defName),
+    mocFile: fileObj(mocName),
+    textureFiles: textures.map(fileObj).filter(Boolean),
+    expressions,
+    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) {
+  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;
+    }
+    if (e.isDirectory()) {
+      dirs.push({ name: e.name, full });
+      continue;
+    }
+    files.set(e.name, { name: e.name, size: st.size });
+  }
+  const out = [];
+  const def4 = [...files.keys()].find((n) => /\.model3\.json$/i.test(n)) || null;
+  const defName = def4 || (files.has('model.json') ? 'model.json' : null);
+  if (defName) {
+    const m = buildLive2DModel(root, relPath, defName, def4 ? 4 : 2);
+    if (m) out.push(m);
+  }
+  return { models: out, dirs };
+}
+
+/** 扫描一个资源根里的全部 Live2D 模型。 */
+export function scanLive2DRootServer(root) {
+  const models = [];
+
+  function walk(absDir, relPath) {
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      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);
+  }
+
+  walk(root.path, '');
+  return models;
+}
+
+/**
+ * 取 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 清单同口径：两道判据 —— 生成者指纹（解析代码变）+ 目录签名（资源增删）
+        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 };
+        } else {
+          log.info('目录已变化，清单失效重建', { id: cfg.id });
+        }
+      }
+    } catch {
+      /* 缓存损坏则重扫 */
+    }
+  }
+  const models = scanLive2DRootServer(cfg);
+  const ts = Date.now();
+  try {
+    // 目录建一次就够（ensureManifestDir 内部就是 mkdir -p）。原先它前面还有一句
+    //   fs.mkdirSync(path.dirname(file)) —— 建的是同一个目录，重复调用，已删。
+    ensureManifestDir(configFile);
+    const body = JSON.stringify({
+      version: LIVE2D_MANIFEST_VERSION,
+      rootId: cfg.id,
+      ts,
+      dirStamps: dirSignature(cfg.path),   // 同上：目录签名供下次读清单时比对
+      generator: generatorFingerprint(),   // 解析器指纹：解析代码一改，清单自动失效
+      models,
+    });
+    // 与 spine 清单同口径：先写临时文件再 rename，避免并发读拿到半份 JSON
+    fs.writeFileSync(`${file}.tmp`, body, 'utf8');
+    fs.renameSync(`${file}.tmp`, file);
+  } catch (e) {
+    log.warn('清单写入失败（不影响使用）', { err: e.message });
+  }
+  return { models, cached: false, ts };
+}
+
+/** 探测 Live2D 运行时库（Cubism Core 受专有许可约束不入库，从本地已有副本取）。 */
+export function getLive2DRuntimeFiles() {
+  if (!live2dRuntimeFilesCache) {
+    // 注入本模块的 logger：tool 层只认「有 info/warn 的对象」，不 import server 层
+    const r = resolveLive2DRuntimes({ log: rtLog });
+    log.info('运行时来源', { origin: r.origin });
+    log.info('运行时目录', { dir: r.dir });
+    if (r.missingOptional.length) {
+      log.warn('缺少可选文件（仅影响 Cubism 4 的 .moc3 模型）', { missing: r.missingOptional });
+    }
+    live2dRuntimeFilesCache = r.files;
+  }
+  return live2dRuntimeFilesCache;
+}
+
+/**
+ * 绑定型适配器：把清单路径固定，调用方只需 (cfg, force)。
+ * @param {{configFile: string}} p
+ */
+export function createLive2d(p) {
+  return {
+    live2dModelsFile: (rootId) => live2dModelsFile(p.configFile, rootId),
+    buildLive2DModel,
+    scanLive2DRootServer,
+    getLive2DModels: (cfg, force) => getLive2DModels(p.configFile, cfg, force),
+    getLive2DRuntimeFiles,
+  };
+}

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

@@ -0,0 +1,58 @@
+// data/manifest-cache.mjs —— 模型索引清单的路径、目录与失效（Spine 与 Live2D 共用）
+//
+// 为什么单独一层：两套清单（spine.<id>.json / live2d.<id>.json）落在同一个目录 config/models/，
+//   而「路径怎么拼」「目录不存在先建」「失效某个根 / 失效全部」这三件事与具体扫描器无关。
+//   早期实现把它们塞在 Spine 模块里，导致一个「只管 Spine」的模块同时定义 Live2D 的清单路径、
+//   还负责删两套清单 —— 职责与名字对不上，也没法把文件改成 spine.mjs。
+//
+// 失效只扫 config/models/ 目录、只认 `^(spine|live2d).<id>.json$`：
+//   手工配置（如 config/live2d.json 的渲染开关）不在这个目录里，
+//   所以不存在"按前缀匹配误删用户配置"的风险（旧实现按 config/ 前缀匹配时真出过一次）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 清单目录：<config>/models/ —— 扫描产物与手工配置分开存放 */
+export function manifestDir(configFile) {
+  return path.join(path.dirname(configFile), 'models');
+}
+
+/** Spine 清单路径：config/models/spine.<rootId>.json */
+export function spineManifestFile(configFile, rootId) {
+  return path.join(manifestDir(configFile), `spine.${rootId}.json`);
+}
+
+/** Live2D 清单路径：config/models/live2d.<rootId>.json */
+export function live2dManifestFile(configFile, rootId) {
+  return path.join(manifestDir(configFile), `live2d.${rootId}.json`);
+}
+
+/** 写清单前确保目录存在（首次运行或目录被清空时，不能因为缺目录写失败） */
+export function ensureManifestDir(configFile) {
+  fs.mkdirSync(manifestDir(configFile), { recursive: true });
+}
+
+/**
+ * 失效清单。传 rootId 只删这个根的两套；不传删目录下全部。
+ * 文件不存在、目录不存在都不算错（本来就没有清单可删）。
+ */
+export function invalidateManifests(configFile, rootId) {
+  if (rootId) {
+    for (const f of [spineManifestFile(configFile, rootId), live2dManifestFile(configFile, rootId)]) {
+      try {
+        if (fs.existsSync(f)) fs.unlinkSync(f);
+      } catch {
+        /* 删除失败不影响调用方：清单不可用会被后续扫描覆盖 */
+      }
+    }
+    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));
+    }
+  } catch {
+    /* 目录不存在 = 没有清单要删 */
+  }
+}

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

@@ -0,0 +1,135 @@
+// data/manifest-stamp.mjs —— 落盘清单「还跟不跟得上」的两套判据都在这里：
+//   ① dirSignature / signatureMatches —— 目录签名：资源目录增删（只 stat 目录，不扫文件）
+//   ② generatorFingerprint           —— 生成者指纹：解析代码变化（文件内容哈希）
+// 背景：清单一旦落盘就无条件复用，加/删模型目录后不带 ?refresh=1 会一直读旧清单；
+//   而"只改解析代码"连目录 mtime 都不动 ⇒ 必须另有一条"代码变了"的判据，否则改完代码界面还是旧数据。
+// 边界：目录 mtime 只反映**直接子项**增删/改名；记录根 + 一级子目录，
+//   可覆盖"模型目录内增删"这一类最常见的变动。**模型文件内容**变了仍不触发重建（那要 ?refresh=1），
+//   而**解析代码**变了由②兜住 —— 两条判据各管一段，别互相替代。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+/** mtime 取整毫秒（不同文件系统精度不同，浮点尾差会造成假失效） */
+function msOf(p) {
+  try {
+    return Math.round(fs.statSync(p).mtimeMs);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 计算一个资源根的目录签名。
+ * @param {string} rootPath 资源根本机路径
+ * @returns {{root: number|null, dirs: Record<string, number>}} 根目录 mtime + 一级子目录 mtime 表
+ */
+export function dirSignature(rootPath) {
+  const sig = { root: msOf(rootPath), dirs: {} };
+  if (sig.root === null) return sig;
+  try {
+    for (const e of fs.readdirSync(rootPath, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name.startsWith('.')) continue;
+      const m = msOf(path.join(rootPath, e.name));
+      if (m !== null) sig.dirs[e.name] = m;
+    }
+  } catch {
+    /* 目录读不了：签名只保留根，比对时自然判为不一致 */
+  }
+  return sig;
+}
+
+/**
+ * 清单里的签名是否仍与磁盘一致。
+ * @param {{root: number|null, dirs: Record<string, number>}|undefined} sig 清单里存的 dirStamps
+ * @param {string} rootPath 资源根本机路径
+ * @returns {boolean} true = 可用缓存；false = 需重建
+ */
+export function signatureMatches(sig, rootPath) {
+  if (!sig || typeof sig !== 'object' || !sig.dirs || typeof sig.dirs !== 'object') return false;
+  const now = dirSignature(rootPath);
+  // 「根目录不存在」也是**稳定状态**，不是"变了"：
+  //   配置里可能存在一个路径写错/尚未创建的根（实例：live2d 根指向 …/DestinyChildLive2D/assets/live2d，
+  //   该目录不存在）。若把 null 一律判为不一致，就会**每次请求都重建清单**（日志刷
+  //   「目录已变化，清单失效重建」），白白消耗 CPU 与磁盘写。
+  //   正确语义：上次也不存在（sig.root === null）⇒ 没变化 ⇒ 命中缓存。
+  if (now.root === null) return sig.root === null;
+  if (now.root !== sig.root) return false;
+  const before = Object.keys(sig.dirs);
+  const after = Object.keys(now.dirs);
+  if (before.length !== after.length) return false; // 出现新目录 / 目录被删
+  for (const name of after) {
+    if (sig.dirs[name] !== now.dirs[name]) return false; // 目录内增删（mtime 变了）
+  }
+  return true;
+}
+
+// ============================================================================
+// 生成者指纹（generator）
+//
+// 为什么需要它：dirStamps 只感知**目录增删**，改解析代码它一点都察觉不到 ⇒
+//   修好「atlas 首行 BOM 丢第一页」后，界面仍读旧清单（textureCount 还是 1），
+//   必须手工删 config/models/spine.<root>.json 才生效 —— 白验证一轮。
+// 做法：清单里存一份「解析器文件内容哈希」，读清单时比对；不等就重建。
+//   用内容哈希而不是人工版本号：人工号一定会忘（本项目已多次踩"改了判据忘升版本"）。
+//   写法照 src/server/plugins/registry.mjs 的 builtinVersionHash：缓存键用 (mtime, size)，
+//   文件没变不重算哈希。
+// ============================================================================
+
+/** 项目根（本文件在 src/server/data/ ⇒ 往上三层） */
+const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/**
+ * 参与「生成者指纹」的文件。
+ * 选它们的理由：这三处共同决定清单里的元数据长什么样 ——
+ *   · spine.mjs  —— spine 扫描与清单字段
+ *   · live2d.mjs —— live2d 扫描与清单字段
+ *   · probe.mjs  —— 两者共用的资产探测（atlas 页名、纹理尺寸、版本解析都在这里，BOM 那个 bug 就在此）
+ * 缺文件就跳过（不炸）：某个模块被挪走，也不该让清单读不出来。
+ */
+const GENERATOR_FILES = [
+  'src/server/data/spine.mjs',
+  'src/server/data/live2d.mjs',
+  'src/server/assets/probe.mjs',
+];
+
+/** 生成者指纹的进程内缓存（签名 = 参与文件的 mtime/size 串） */
+let generatorCache = { sig: null, value: '0' };
+
+/**
+ * 生成者指纹：解析器文件内容哈希的前 8 位。
+ * @param {string} [root] 项目根（缺省按本文件位置推，不写死绝对路径）
+ * @returns {string} 8 位十六进制（一个文件都读不到时为 '0'）
+ */
+export function generatorFingerprint(root = PROJECT_ROOT) {
+  // 缓存键用 (mtime, size)：文件内容一变就重算；没变则直接返回（probe.mjs 有几百行，别每次读盘+sha256）
+  let sig = '';
+  const stats = [];
+  for (const rel of GENERATOR_FILES) {
+    try {
+      const st = fs.statSync(path.join(root, rel));
+      stats.push({ rel, ok: true });
+      sig += `${rel}:${st.mtimeMs}:${st.size};`;
+    } catch {
+      stats.push({ rel, ok: false });
+      sig += `${rel}:-;`;
+    }
+  }
+  if (generatorCache.sig === sig) return generatorCache.value;
+
+  const h = crypto.createHash('sha256');
+  let used = 0;
+  for (const { rel, ok } of stats) {
+    if (!ok) continue;
+    try {
+      h.update(rel);
+      h.update(fs.readFileSync(path.join(root, rel)));
+      used += 1;
+    } catch { /* 单个文件读不了不影响其它文件 */ }
+  }
+  const value = used ? h.digest('hex').slice(0, 8) : '0';
+  generatorCache = { sig, value };
+  return value;
+}

package/src/server/data/model-meta.mjs

@@ -0,0 +1,114 @@
+// model-meta.mjs —— Spine 模型元数据（/api/model-meta 的数据层）
+
+const log = createLogger('model-meta');
+//
+// 产出字段与 Cubism 的 modelMeta 同名：kind / designSize / bbox / bones / slots / animations / skins / version
+// 解析器按需 import（首次请求才加载几 MB 源码，不在启动时加载）；
+// 动作分组规则来自 tool/spine-motion-rules.json，读一次缓存（改规则后重启生效）。
+import fs from 'node:fs';
+import { createLogger } from '../core/log.mjs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** 仓库根（本文件位于 <root>/src/server/） */
+const MODULE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** 动作规则缓存：null = 尚未加载（改规则后重启生效） */
+let motionRules = null;
+
+/** 懒加载动作分组/循环规则；失败只告警（按"未知名"处理） */
+async function loadMotionRules(rulesPath) {
+  if (motionRules !== null) return motionRules;
+  try {
+    const { loadRules } = await import('../../tool/lib/spine-motions.mjs');
+    motionRules = loadRules(rulesPath);
+  } catch (e) {
+    log.warn('动作规则加载失败，按"未知名"处理', { err: e.message });
+    motionRules = null;
+  }
+  return motionRules;
+}
+
+/**
+ * 定位骨架文件：path 允许给模型目录，此时按稳定顺序取第一个 .skel/.json。
+ * @returns {{ok: true, resolvedFile: string, absFile: string} | {ok: false, status: number, body: object}}
+ */
+export function resolveSkeletonTarget(abs, rel) {
+  let resolvedFile = null;
+  const isDir = fs.statSync(abs).isDirectory();
+  const baseDir = isDir ? abs : path.dirname(abs);
+  if (isDir) {
+    const cands = fs.readdirSync(abs)
+      .filter((n) => /\.(skel|json)$/i.test(n) && !n.startsWith('.'))
+      .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    if (!cands.length) {
+      return { ok: false, status: 404, body: { ok: false, error: '目录里没有 .skel/.json 骨架', path: rel, code: 'SPINE_ERR_NO_FILE' } };
+    }
+    resolvedFile = cands[0];
+  } else {
+    resolvedFile = path.basename(abs);
+  }
+  const absFile = path.join(baseDir, resolvedFile);
+  if (!fs.existsSync(absFile) || !fs.statSync(absFile).isFile()) {
+    return { ok: false, status: 404, body: { ok: false, error: '骨架文件不存在', path: rel, code: 'SPINE_ERR_NO_FILE' } };
+  }
+  return { ok: true, resolvedFile, absFile };
+}
+
+/** 读同名 .atlas 文本（读不到只影响 bbox，不影响计数） */
+export function readAtlasText(absFile) {
+  try {
+    const atlasPath = path.join(path.dirname(absFile), `${path.basename(absFile, path.extname(absFile))}.atlas`);
+    if (fs.existsSync(atlasPath) && fs.statSync(atlasPath).isFile()) return fs.readFileSync(atlasPath, 'utf8');
+  } catch {
+    /* 忽略 */
+  }
+  return null;
+}
+
+/**
+ * @param {{config: object, probe: object, motionRulesFile?: string}} deps
+ */
+export function createModelMeta({ config, probe, motionRulesFile }) {
+  const { readConfig } = config;
+  const { resolveSafe } = probe;
+  const rulesPath = motionRulesFile || path.join(MODULE_ROOT, 'tool', 'spine-motion-rules.json');
+
+  /**
+   * 读模型元数据。
+   * @returns {Promise<{status: number, body: object}>}
+   */
+  async function readModelMeta(rootId, rel) {
+    const cfg = readConfig().find((r) => r.id === rootId);
+    if (!cfg) {
+      return { status: 400, body: { ok: false, error: `未找到资源根: ${rootId}`, code: 'SPINE_ERR_BAD_ARGS' } };
+    }
+    const abs = resolveSafe(cfg.path, rel);
+    if (!abs) return { status: 403, body: { ok: false, error: '路径越界', code: 'SPINE_ERR_BAD_ARGS' } };
+    if (!fs.existsSync(abs)) {
+      return { status: 404, body: { ok: false, error: '路径不存在', path: rel, code: 'SPINE_ERR_NO_FILE' } };
+    }
+
+    const target = resolveSkeletonTarget(abs, rel);
+    if (!target.ok) return { status: target.status, body: target.body };
+    const atlasText = readAtlasText(target.absFile);
+
+    let readSpineMeta;
+    try {
+      ({ readSpineMeta } = await import('../../tool/lib/spine-meta.mjs'));
+    } catch (e) {
+      return { status: 500, body: { ok: false, error: `加载元数据模块失败: ${e.message}`, code: 'SPINE_ERR_NO_RUNTIME' } };
+    }
+
+    try {
+      const bytes = new Uint8Array(fs.readFileSync(target.absFile));
+      const rules = await loadMotionRules(rulesPath);
+      const meta = readSpineMeta({ bytes, fileName: target.resolvedFile, atlasText, rules });
+      return { status: 200, body: Object.assign({ ok: true, resolvedFile: target.resolvedFile }, meta) };
+    } catch (e) {
+      return { status: 200, body: { ok: false, resolvedFile: target.resolvedFile, error: e.message, code: e.code || 'SPINE_ERR_PARSE' } };
+    }
+  }
+
+  return { readModelMeta };
+}