modelstage 0.0.0-stage → 0.5.28

package/src/server/routes/data.mjs

@@ -0,0 +1,313 @@
+// routes/data.mjs —— 只读数据 API 与资源文件路由
+//
+// 覆盖：
+//   /api/roots /api/plugins /api/brand /api/web-config   资源根/插件/品牌/前端配置
+//   /api/tree /api/spine/models /api/live2d/models /api/names  目录/模型清单/名表
+//   /api/browse                                          服务端目录浏览（登记资源根用）
+//   /api/catalog /api/bundle/probe /api/model-meta       按需 import 的三条
+//   /api/file /files/<rootId>/<rel> /icons/... /live2d-lib/...  二进制资源（含越界防护）
+//   POST /api/roots                                      资源根增删改名启停（写路径）
+//
+// 为什么归一组：它们共享同一份 data.*（config/models/names/live2d/catalog…）实例，
+//   读写口径必须一致——资源根视图走 http/write.mjs 的 toRootView，避免读写两处漂移。
+
+// 缺 Live2D 运行时时的引导文案：503（解析器不可用）与 404（单个文件不存在）**共用同一份**，
+//   否则两处各说各话（一个说去官网下、另一个只说文件名），用户被堵在门口。
+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';
+
+/** 资源根 / 插件 / 品牌 / 前端配置 */
+function apiBasics(ctx, res, p) {
+  const { data, sendJson, toRootView } = ctx;
+  if (p === '/api/roots') {
+    // 视图映射与写接口共用同一份（http/write.mjs 的 toRootView），避免读写两处口径漂移
+    const list = toRootView(data.config.readConfig());
+    return sendJson(res, 200, { roots: list, groups: data.config.buildGroups(list) });
+  }
+  if (p === '/api/plugins') {
+    return sendJson(res, 200, {
+      ok: true,
+      dir: 'plugins',
+      // 插槽目录全表（S1-a）：前端要在**装之前**知道"有哪些插槽、各自什么风险、开到哪一阶段"，
+      //   否则只能等注册失败才知道。与校验同源（都来自 plugins/slot-catalog.mjs），不会漂移。
+      // 服务端**当前已开放到哪个阶段**（值与 slotCatalog 同源，都来自 plugins/slot-catalog.mjs）。
+      //   为什么单独下发：前端原来自己有一份 CURRENT_SLOT_STAGE 常量 —— 同一事实两处表达，
+      //   抬阶段时只改一处就会出现"服务端放行、前端还拒"（或反之）的漂移。
+      //   注意它与 slotCatalog[i].stage 是**两个概念**：后者是"该插槽从哪个阶段起开放"（固定），
+      //   这里是"现在一共开放到哪"（会随阶段推进变）。别把两者合并。
+      currentStage: CURRENT_STAGE,
+      slotCatalog: SLOT_CATALOG,
+      plugins: data.plugins.readPlugins(),
+      // 角色注册表（角色 → 插件 id）：前端按 provides 决定把插件挂到哪个注册表；
+      //   排障时也能一眼看出"某角色有没有插件认领"
+      roles: data.plugins.roleIndex(),
+    });
+  }
+  if (p === '/api/brand') {
+    const env = data.env.readDotEnv();
+    const title = (env.APP_TITLE || '').trim();
+    const icon = (env.APP_ICON || '').trim();
+    const looksLikeImage = /^(https?:|data:|\/)/i.test(icon) || /\.(png|jpe?g|svg|webp|gif|ico)$/i.test(icon);
+    return sendJson(res, 200, { ok: true, title: title || null, icon: icon || null, iconKind: !icon ? null : (looksLikeImage ? 'image' : 'text') });
+  }
+  if (p === '/api/web-config') {
+    const env = data.env.readDotEnv();
+    return sendJson(res, 200, {
+      ok: true,
+      autoRestoreLast: data.env.parseEnvFlag(env.AUTO_RESTORE_LAST),
+      debugLog: data.env.parseEnvFlag(env.DEBUG_LOG),
+      // 准入堆比例：前端读不到 env，所以由服务端下发（env 覆盖见 core/env-num.mjs）。
+      //   非法值在服务端就回落缺省并 warn，不透传脏值给浏览器。
+      admitHeapRatio: readRatioEnv('MODELSTAGE_ADMIT_HEAP_RATIO', 0.85),
+      // 容量系数一并下发，只为"面板/排障能看到当前实际生效值"，不参与前端判定
+      admitCapacityRatio: readRatioEnv('MODELSTAGE_ADMIT_CAPACITY_RATIO', 0.5),
+    });
+  }
+  return false;
+}
+
+/** 目录 / 模型清单 / 名表 / 配置导出 / 目录浏览 */
+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') || '');
+    return sendJson(res, r.status, r.body);
+  }
+  // /api/spine/models 与 /api/live2d/models 是**单路原始扫描**（各自只管一种渲染器，
+  //   返回形状也各不相同）。要"某个根下的全部模型"一律走 /api/catalog（它内部复用这两个，
+  //   输出统一 ModelEntry）。历史教训：曾叫 /api/models，名字像"所有模型"但实际只返回 Spine，
+  //   导致在纯 Live2D 的资源根上翻页/加载拿到 0 个模型而误判为"根目录为空"。
+  if (p === '/api/spine/models' || p === '/api/live2d/models') {
+    const rootId = url.searchParams.get('root') || '';
+    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,
+      });
+    } catch (e) {
+      return sendJson(res, 500, { error: `${p === '/api/spine/models' ? 'Spine 扫描失败' : 'Live2D 扫描失败'}: ${e.message}` });
+    }
+  }
+  if (p === '/api/names') return apiNames(ctx, res, url);
+  // /api/config/export 与 /api/config/import 同属配置组，见 routes/config.mjs（此处不重复实现）
+  if (p === '/api/browse') {
+    const r = browseDir(url.searchParams.get('path') || '/');
+    return sendJson(res, r.status, r.body);
+  }
+  return false;
+}
+
+/**
+ * 名表（v2 index 优先、v1 兜底）：返回**归一化**后的表。
+ *
+ * 为什么不再每次现读 JSON：名表是纯数据文件（见 docs/设计/名表.md），读取只做「读 + 缓存 + 原样返回」
+ *   只在 names.mjs 里存在一份；这里再读一遍就等于复制第二份解析规则。
+ *   缓存失效由 names.clearNameCache()（导入配置时）负责，对外行为仍是"导入后立刻生效"。
+ *
+ * 三种情况必须可区分（不能静默返回空表 —— 那会让整片名字消失且界面无任何提示）：
+ *   ① 该根没配 names        → 200 + names:null + reason（不是错误，是配置选择）
+ *   ② 配了但两个文件都没有   → 404 + 明确说明"index 与 v1 都不存在"
+ *   ③ 文件坏了             → 500 + 解析失败原因
+ */
+function apiNames(ctx, res, url) {
+  const { data, sendJson } = ctx;
+  const rootId = url.searchParams.get('root') || '';
+  const cfg = data.config.readConfig().find((r) => r.id === rootId);
+  if (!cfg) return sendJson(res, 400, { error: `未找到资源根: ${rootId}` });
+  if (!cfg.names) return sendJson(res, 200, { root: rootId, names: null, reason: '该资源根未配置 names 名表' });
+
+  const { table, error, detail } = data.names.loadNamesTable(cfg.names);
+  if (!table) {
+    const status = error === 'BROKEN' ? 500 : 404;
+    return sendJson(res, status, { root: rootId, tableId: cfg.names, error: detail, code: error });
+  }
+  // 原样透传（规范 §二 的唯一出口形状）：多挑一个字段就是"服务端理解结构"，
+  //   名表一改形状就得改这里 —— 结构解释全在 src/shared/names.mjs 与前端。
+  return sendJson(res, 200, { root: rootId, tableId: cfg.names, ...table });
+}
+
+/** 需要按需 import 的三条（catalog / bundle probe / model meta） */
+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}` });
+  // 最近一次各根 catalog 构建的服务端耗时（只读内存，零副作用：不会触发任何重建）。
+  //   必须放在 /api/catalog 分支之前：两条件互斥（等值比较），但顺序写清更不会被后来人改错。
+  if (p === '/api/catalog/stats') {
+    const s = data.catalog.getCatalogStats();
+    return sendJson(res, 200, { ok: true, at: s.at, totalMs: s.totalMs, roots: s.roots });
+  }
+  if (p === '/api/catalog') {
+    // 入参分流（只在路由层做，不动 listCatalog 内部报错）：
+    //   · 缺 root / 空串 ⇒ 400（调用方错误）。以前一律回 404，于是"路径拼错了"
+    //     和"根真的不存在"看起来一模一样，排查时白费一轮。
+    //   · 给了非空但找不到的 id ⇒ 仍交 listCatalog 回 404（那才是"资源不存在"）。
+    const rootId = (url.searchParams.get('root') || '').trim();
+    if (!rootId) {
+      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));
+  }
+  if (p === '/api/bundle/probe') {
+    data.bundleProbe.probeBundle(url.searchParams.get('root') || '', url.searchParams.get('path') || '')
+      .then(done).catch(fail('预检失败'));
+    return true;
+  }
+  if (p === '/api/model-meta') {
+    data.modelMeta.readModelMeta(url.searchParams.get('root') || '', url.searchParams.get('path') || '')
+      .then(done).catch(fail('读取元数据失败'));
+    return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------- 二进制路由
+
+/** /api/file?root=&path= 与 /files/<rootId>/<rel>：模型资源流（带 CORS，供纹理跨源） */
+function serveModelFile(ctx, req, res, p, url) {
+  const { data, fs, resolveSafe, sendJson, sendFile } = ctx;
+  let rootId;
+  let rel;
+  let cors = { 'Access-Control-Allow-Origin': '*' };
+  if (p === '/api/file') {
+    rootId = url.searchParams.get('root') || '';
+    rel = url.searchParams.get('path') || '';
+  } else if (p.startsWith('/files/')) {
+    const rest = decodeURIComponent(p.slice('/files/'.length));
+    const slash = rest.indexOf('/');
+    rootId = slash < 0 ? rest : rest.slice(0, slash);
+    rel = slash < 0 ? '' : rest.slice(slash + 1);
+  } else {
+    return false;
+  }
+  const cfg = data.config.readConfig().find((r) => r.id === rootId);
+  if (!cfg) {
+    if (p === '/api/file') { sendJson(res, 400, { error: `未找到资源根: ${rootId}` }); return true; }
+    res.writeHead(404); res.end('root not found');
+    return true;
+  }
+  const abs = resolveSafe(cfg.path, rel);
+  if (!abs) {
+    if (p === '/api/file') { sendJson(res, 403, { error: '路径越界' }); return true; }
+    res.writeHead(403); res.end('forbidden');
+    return true;
+  }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    if (p === '/api/file') { sendJson(res, 404, { error: '文件不存在', path: rel }); return true; }
+    res.writeHead(404); res.end('file not found');
+    return true;
+  }
+  sendFile(req, res, abs, cors);
+  return true;
+}
+
+/** /icons/<rootId>/<文件名>：头像目录在资源根之外，单独一条（含越界防护） */
+function serveIcon(ctx, req, res, p) {
+  const { data, fs, path, sendFile } = ctx;
+  if (!p.startsWith('/icons/')) return false;
+  const rest = decodeURIComponent(p.slice('/icons/'.length));
+  const slash = rest.indexOf('/');
+  const rootId = slash < 0 ? rest : rest.slice(0, slash);
+  const name = path.basename(slash < 0 ? '' : rest.slice(slash + 1));
+  const cfg = data.config.readConfig().find((r) => r.id === rootId);
+  if (!cfg || !cfg.icons || !cfg.icons.dir) { res.writeHead(404); res.end('no icons dir'); return true; }
+  const base = path.resolve(cfg.icons.dir);
+  const abs = path.resolve(base, name);
+  if (abs !== base && !abs.startsWith(base + path.sep)) { res.writeHead(403); res.end('forbidden'); return true; }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) { res.writeHead(404); res.end('not found'); return true; }
+  sendFile(req, res, abs);
+  return true;
+}
+
+/**
+ * /avatars/<game>/<文件名>：头像仓（v2 主路）。
+ *
+ * 与 /icons/ 的区别：`/icons/` 读的是"每个资源根自己配的 icons.dir"（v1 遗留，一个根一套）；
+ *   `/avatars/` 读的是**全局可配置的头像根**（`<avatarRoot>/<game>/<file>`），
+ *   因为头像仓是独立私有仓、与资源根无关（见 docs/设计/名表.md §4.1）。
+ *
+ * `<game>` 直接落在文件系统路径里 ⇒ 必须防越界：只接受一层合法目录名 + 一层合法文件名，
+ *   两级都做 path.resolve 后的前缀校验（防 `../` 与绝对路径注入）。
+ */
+function serveAvatar(ctx, req, res, p) {
+  const { data, fs, path, sendFile } = ctx;
+  if (!p.startsWith('/avatars/')) return false;
+  const rest = decodeURIComponent(p.slice('/avatars/'.length));
+  const parts = rest.split('/').filter(Boolean);
+  if (parts.length !== 2) { res.writeHead(404); res.end('bad avatar path'); return true; }
+  const game = path.basename(parts[0]);
+  const name = path.basename(parts[1]);
+  if (game !== parts[0] || name !== parts[1]) { res.writeHead(403); res.end('forbidden'); return true; }
+  const root = path.resolve(data.paths.avatarRoot);
+  const abs = path.resolve(root, game, name);
+  if (!abs.startsWith(root + path.sep)) { res.writeHead(403); res.end('forbidden'); return true; }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) { res.writeHead(404); res.end('not found'); return true; }
+  sendFile(req, res, abs);
+  return true;
+}
+
+/** /live2d-lib/<文件>：Cubism Core 等运行时库（由 resolver 探测出的映射表） */
+function serveLive2DLib(ctx, req, res, p) {
+  const { data, path, sendJson, sendFile } = ctx;
+  if (!p.startsWith('/live2d-lib/')) return false;
+  const name = path.basename(decodeURIComponent(p.slice('/live2d-lib/'.length)));
+  let files;
+  try {
+    files = data.live2d.getLive2DRuntimeFiles();
+  } catch (e) {
+    sendJson(res, 503, { error: `Live2D 运行时不可用: ${e.message}` });
+    return true;
+  }
+  const abs = files[name];
+  if (!abs) {
+    // 404（某个文件缺失）与 503（整套库不可用）用户撞到的概率相当 ⇒ 都给完整引导。
+    //   文案复用 live2dGuide（与 503 同源），只补"该往哪放、从哪下、为什么不代下"。
+    sendJson(res, 404, { error: `未找到运行时文件: ${name}\n` + live2dGuide(data.paths.dataRoot) });
+    return true;
+  }
+  sendFile(req, res, abs);
+  return true;
+}
+
+/**
+ * 入口：按顺序尝试本组路由。
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} p
+ * @param {URL} url
+ * @param {object} ctx 需要 data/fs/path/sendJson/sendFile/resolveSafe/browseDir/toRootView/writeApi/readBody
+ * @returns {boolean} 是否已处理
+ */
+export function handleData(req, res, p, url, ctx) {
+  const { sendJson, readBody, writeApi } = ctx;
+
+  // 资源根写操作（增 / 删 / 改名 / 启停）：校验 → 备份 → 写 → 失效缓存
+  // 具体管道在 http/write.mjs；这里只负责读请求体与发响应。
+  if (p === '/api/roots' && req.method === 'POST') {
+    readBody(req, res, (body) => {
+      writeApi.writeRoots(body)
+        .then((r) => sendJson(res, r.status, r.body))
+        .catch((e) => sendJson(res, 500, { ok: false, error: `写资源根异常: ${(e && e.message) || e}` }));
+    });
+    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;
+  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;
+  if (serveLive2DLib(ctx, req, res, p)) return true;
+  return false;
+}

package/src/server/routes/diag.mjs

@@ -0,0 +1,37 @@
+// routes/diag.mjs —— 诊断相关三条：/api/diag（GET 读最近条目 / POST 上报）、/api/diag/upload(s)（落盘与查询）
+//
+// 为什么单独一组：诊断是"只写 data/ 的旁路"——它不参与资源根/模型读取，
+//   出问题时即使模型链路坏了，这条通道也应该还能用（便于事后读现场）。
+//
+// 约定：handler 返回 true 表示"这个请求我处理了（可能已写响应）"，返回 false 表示没我的事。
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} p 已解析的 pathname
+ * @param {URL} url
+ * @param {object} ctx 由 serve.mjs 组装的依赖（sendJson / readBody / diag / diagUpload）
+ * @returns {boolean} 是否已处理
+ */
+export function handleDiag(req, res, p, url, ctx) {
+  const { diag, diagUpload, sendJson, readBody } = ctx;
+
+  // 只读：取最近的诊断条目（页面自己记录的那份，供外部/AI 直接读现场）
+  if (p === '/api/diag' && req.method === 'GET') {
+    const limit = Number(url.searchParams.get('limit')) || undefined;
+    const sid = url.searchParams.get('sid') || undefined;
+    sendJson(res, 200, diag.readDiag({ limit, sid }));
+    return true;
+  }
+  if (p === '/api/diag' && req.method === 'POST') {
+    readBody(req, res, (body) => sendJson(res, 200, diag.appendDiag(body)));
+    return true;
+  }
+  // 调试日志上传（data/logs/）：先**同步**判命中，再异步处理
+  //   （handle 是 async，直接判返回值会恒真、把后续路由整条截断——踩过）。
+  if (diagUpload.matches(req.method, p)) {
+    diagUpload.handle(req, res, p);
+    return true;
+  }
+  return false;
+}

package/src/server/routes/entries.mjs

@@ -0,0 +1,170 @@
+// routes/entries.mjs —— 条目状态的两条接口（契约《条目状态与展示归属》§三）
+//
+//   POST /api/entries/result        写读一体：上报"最近一次装载尝试"，响应直接带回重算后的三字段
+//   GET  /api/entries/result?key=…  单条查询（零扫描、零重建）
+//   GET  /api/entries/probe         后台探测的计数与队列深度（S10 的佐证口）
+//   POST /api/entries/probe?root=…  手动重探一轮（§八 触发判据 c）
+//
+// 为什么把"写"和"读"做成同一次响应（这是契约 S1/S2 的根治点）：
+//   前端装载完成那一刻既要"记下结果"，又要"立刻把这一行画对"。
+//   若拆成两次请求，中间必然存在"前端已改行、服务端还没存"的窗口，
+//   表现为"当场变了色、刷新又变回去"（或反过来）——两张皮就是这么来的。
+//   这里写入与读取用的是**同一个 recompute()**，响应就是存储层算出来的那份数据。
+//
+// 旁路原则（INV-D3）：本接口出任何错都不得影响装载。前端调用处必须吞掉失败只记日志。
+
+// 指纹判据只有一份实现（INV-D6）：上报路径漏传 providerFingerprint 时，
+//   recompute 里规则①会因"没有当前指纹"整段跳过 —— 插件升级后旧结论永远挂着。
+import { providerFingerprintOf, assetFingerprintOf } from '../data/entry-states.mjs';
+
+/** 从请求体里挑出 put() 需要的字段（其余一律忽略，不把未知字段写进存储） */
+function pickIncoming(body) {
+  const src = body && typeof body === 'object' ? body : {};
+  const result = src.result === 'ok' ? 'ok' : (src.result === 'failed' ? 'failed' : null);
+  if (!result) return null;
+  const out = { result };
+  if (typeof src.reason === 'string' && src.reason) out.reason = src.reason;
+  if (typeof src.message === 'string' && src.message) out.message = src.message;
+  if (typeof src.provider === 'string' && src.provider) out.provider = src.provider;
+  if (Number.isFinite(src.at)) out.at = Number(src.at);
+  if (src.source === 'server' || src.source === 'client') out.source = src.source;
+  return out;
+}
+
+/**
+ * 条目状态这一族的入口：按路径分给两个处理函数（各自再管自己的方法）。
+ * @param {object} ctx serve.mjs 注入：{ entryStates, shapeProbe, catalog, contextFor, sendJson, readBody, log }
+ */
+export function handleEntries(req, res, p, url, ctx) {
+  // 解构放函数最前面：两条分支都要用（放在中间会踩 TDZ，实测报
+  //   "Cannot access 'sendJson' before initialization"）
+  const { sendJson } = ctx;
+  if (p === '/api/entries/probe') return handleProbeRoute(req, res, url, ctx);
+  if (p !== '/api/entries/result') return false;
+  if (!ctx.entryStates) {
+    // 存储没装配（理论上不会）：如实 500，不假装成功——前端会按"上报失败只记日志"处理
+    sendJson(res, 500, { ok: false, error: '条目状态存储未就绪' });
+    return true;
+  }
+  if (req.method === 'GET') return handleResultGet(req, res, url, ctx);
+  if (req.method === 'POST') return handleResultPost(req, res, ctx);
+  sendJson(res, 405, { ok: false, error: `不支持的方法：${req.method}` });
+  return true;
+}
+
+/**
+ * GET /api/entries/result?key=…
+ *
+ * 查询也走 recompute：否则"存储里有、算出来没有"的字段会让诊断和列表对不上。
+ * @returns {true} 已处理
+ */
+function handleResultGet(req, res, url, ctx) {
+  const key = (url.searchParams.get('key') || '').trim();
+  if (!key) {
+    ctx.sendJson(res, 400, { ok: false, error: '缺少 key 参数（?key=<rootId>/<rel> 或条目 id）' });
+    return true;
+  }
+  const computed = ctx.entryStates.recompute(ctx.entryStates.get(key), ctx.contextFor(key));
+  ctx.sendJson(res, 200, { ok: true, key, entry: computed });
+  return true;
+}
+
+/**
+ * POST /api/entries/result：写入一次装载结果，响应带回重算后的三字段（写读一体）。
+ *
+ * readBody 回调给的是**原始字符串**（各路由自己 parse，与 backgrounds/ready 同口径）。
+ * @returns {true} 已处理（响应在回调里发出）
+ */
+function handleResultPost(req, res, ctx) {
+  const { sendJson, readBody } = ctx;
+  readBody(req, res, (raw) => {
+    let body = {};
+    try { body = raw ? JSON.parse(raw) : {}; } catch {
+      sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+      return;
+    }
+    const key = String((body && body.key) || '').trim();
+    if (!key) {
+      sendJson(res, 400, { ok: false, error: '缺少 key（形如 <rootId>/<rel>）' });
+      return;
+    }
+    writeResult(key, body, res, ctx);
+  });
+  return true;
+}
+
+/**
+ * 真正的写入动作（从 POST 回调里拆出来，单独可读）。
+ * 旁路原则：存储写失败只记日志 + 如实 500，绝不升级成"装载失败"。
+ */
+function writeResult(key, body, res, ctx) {
+  const { sendJson, entryStates } = ctx;
+  const incoming = pickIncoming(body);
+  if (!incoming) {
+    sendJson(res, 400, { ok: false, error: 'result 必须是 ok 或 failed' });
+    return;
+  }
+  try {
+    // put() 内部先落内存表再 recompute：返回的就是"现在存储的真相"
+    const r = entryStates.put(key, incoming, ctx.contextFor(key, body));
+    sendJson(res, 200, { ok: true, key, applied: r.applied === true, entry: r.computed });
+  } catch (e) {
+    try {
+      if (ctx.log && ctx.log.warn) ctx.log.warn('条目状态写入失败', { err: (e && e.message) || String(e) });
+    } catch { /* 日志本身失败也不能影响响应 */ }
+    sendJson(res, 500, { ok: false, error: `条目状态写入失败：${(e && e.message) || e}` });
+  }
+}
+
+/**
+ * /api/entries/probe：后台形态探测的状态（GET）与手动重探（POST）。
+ * 与 /result 同属"条目状态"这一族，共用同一份存储，所以放在同一模块。
+ */
+function handleProbeRoute(req, res, url, ctx) {
+  const { sendJson, shapeProbe } = ctx;
+  const stats = shapeProbe ? shapeProbe.stats() : null;
+  if (req.method === 'GET') {
+    const queue = ctx.catalog && typeof ctx.catalog.probeQueueSize === 'function'
+      ? ctx.catalog.probeQueueSize() : null;
+    sendJson(res, 200, { ok: true, stats, queue, running: shapeProbe ? shapeProbe.isRunning() : false });
+    return true;
+  }
+  if (req.method === 'POST') {
+    // 手动重探（调试入口）：不 await —— 探测按根串行、跑完即停，调用方拿到受理回执即可。
+    //   触发来源标 manual：日志里要能与 catalog/fingerprint 区分（三者混成一条就查不出谁触发的）
+    const rootId = (url.searchParams.get('root') || '').trim() || undefined;
+    const running = shapeProbe ? shapeProbe.kick(rootId, 'manual') : null;
+    sendJson(res, 200, { ok: true, accepted: !!running, stats });
+    return true;
+  }
+  sendJson(res, 405, { ok: false, error: `不支持的方法：${req.method}` });
+  return true;
+}
+
+/**
+ * 造 contextFor：把"这条目的静态事实"（候选提供者、缺贴图、尺寸）从 catalog 侧喂给 recompute。
+ *
+ * 为什么放在路由层而不是 entry-states 里：存储层不该知道 catalog 的形状（谁认领这个条目、
+ *   目录型缺哪些贴图，都是扫描阶段的事）；它只负责"把状态和上下文合成三字段"。
+ * @param {{providers: Function, describe: Function}} deps
+ */
+export function createContextFor(deps) {
+  return function contextFor(key, body) {
+    const providers = (deps.providers && deps.providers()) || [];
+    const desc = (deps.describe && deps.describe(key)) || {};
+    // size 优先取请求体（前端最清楚自己装的是哪个文件），其次取扫描结果
+    const size = Number.isFinite(body && body.size) ? Number(body.size) : (Number.isFinite(desc.size) ? desc.size : undefined);
+    return {
+      providers,
+      candidates: Array.isArray(desc.candidates) ? desc.candidates : [],
+      missingTextures: Array.isArray(desc.missingTextures) ? desc.missingTextures : undefined,
+      assetDependency: desc.assetDependency || null,
+      size,
+      // 三处写入方必须传同源指纹（INV-D6）：
+      //   providerFingerprint = 当前注册表指纹（规则①判据），
+      //   assetFingerprint    = 同一份 size 派生的字符串（规则②判据，三处同格式）
+      providerFingerprint: providerFingerprintOf(providers),
+      assetFingerprint: assetFingerprintOf(size),
+    };
+  };
+}

package/src/server/routes/ready.mjs

@@ -0,0 +1,122 @@
+// routes/ready.mjs —— 就绪信号通道（契约 docs/契约/交互与实现约束.md）
+//
+// 三条同路径不同方法：
+//   GET  /api/ready         快照（幂等；未登记阶段名 ⇒ 400，已登记未上报 ⇒ 200 pending）
+//   GET  /api/ready/stream  长连接（先推 snapshot，再推 update）
+//   POST /api/ready         页面侧上报入口
+//
+// 为什么与 diag 分开：就绪信号描述"能不能开始渲染"，是状态机；调试日志描述"发生了什么"，是流水。
+//   两者混在一起会让"未就绪"被淹没在日志噪音里（契约里明确要求分离，不进调试面板）。
+//
+// 拆分口径（原单函数圈复杂度 28）：这个函数不是"采集 + 判定"那种形态，而是**三个独立路由分支**
+//   各自带自己的错误处理。所以按「一条路由一个函数」拆，另把"上报体处理"与"到达日志"再各提一层 ——
+//   边界按"一条路由的完整处理"划，而不是硬套采集/判定。响应结构、状态码、字段名一字未改。
+
+/**
+ * 就绪通道入口：只做**方法 + 路径分发**，具体处理交给下面几个函数。
+ */
+
+// 错误消息写进日志前截断的字符上限：避免一条超长异常把日志撑爆。
+//   两个值不同（100 / 120）是原样保留的历史取值，不要合并成一个。
+const ERR_MSG_MAX_BAD_JSON = 100;
+const ERR_MSG_MAX_APPLY = 120;
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} reqPath 请求路径（如 /api/ready）
+ * @param {URL} url
+ * @param {object} ctx 需要 ready / diag / sendJson / readBody
+ * @returns {boolean} 是否已处理
+ */
+export function handleReady(req, res, reqPath, url, ctx) {
+  const { ready, diag, sendJson, readBody } = ctx;
+
+  if (reqPath === '/api/ready' && req.method === 'GET') return sendReadySnapshot(url, res, ready, sendJson);
+  if (reqPath === '/api/ready/stream' && req.method === 'GET') {
+    ready.subscribe(req, res);   // 长连接：先 snapshot 事件，后 update 事件
+    return true;
+  }
+  if (reqPath === '/api/ready' && req.method === 'POST') return sendReadyPost(req, res, ready, diag, sendJson, readBody);
+  return false;
+}
+
+/**
+ * GET /api/ready —— 返回快照。
+ * 未登记的阶段名 = 调用方写错（契约 §三：阶段必须先登记）⇒ 400 并回可用清单；
+ *   已登记但尚未上报的返回 state:'pending'（200），两者语义不同，别混。
+ */
+function sendReadySnapshot(url, res, ready, sendJson) {
+  const stage = url.searchParams.get('stage') || '';
+  const snap = ready.snapshot(stage || undefined);
+  sendJson(res, snap && snap.ok === false ? 400 : 200, snap);
+  return true;
+}
+
+/** POST /api/ready —— 读请求体后交给 handleReadyBody 处理 */
+function sendReadyPost(req, res, ready, diag, sendJson, readBody) {
+  const arrivedAt = Date.now();
+  readBody(req, res, (raw) => handleReadyBody(raw, res, ready, diag, sendJson, arrivedAt));
+  return true;
+}
+
+/**
+ * 处理上报体（原 readBody 回调体）。
+ * 注意：readBody 给的是**原始字符串**（diag 自己在内部 parse），这里必须自行解析。
+ */
+function handleReadyBody(raw, res, ready, diag, sendJson, arrivedAt) {
+  const logReady = makeReadyLog(diag, arrivedAt, raw);
+  const parsed = parseReadyBody(raw, logReady);
+  if (!parsed.ok) return sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+  return applyReadyBody(parsed.body, res, ready, logReady, sendJson);
+}
+
+/** 解析上报体。失败时写一条到达日志并返回 {ok:false}（状态码由调用方给） */
+function parseReadyBody(raw, logReady) {
+  try {
+    return { ok: true, body: raw ? JSON.parse(raw) : {} };
+  } catch (e) {
+    logReady(false, { reason: 'bad-json', msg: String((e && e.message) || e).slice(0, ERR_MSG_MAX_BAD_JSON) });
+    return { ok: false };
+  }
+}
+
+/** 成功上报时写进日志的附加字段（updates 条数 / 是否清空） */
+function readyLogExtra(body) {
+  return { updates: (body && body.updates && body.updates.length) || 0, clear: body && body.clear === true };
+}
+
+/** 应用上报体并输出。apply 抛错时写日志并回 500（错误文本原样回给调用方） */
+function applyReadyBody(body, res, ready, logReady, sendJson) {
+  try {
+    const out = ready.apply(body);
+    logReady(true, readyLogExtra(body));
+    return sendJson(res, 200, out);
+  } catch (e) {
+    logReady(false, { reason: 'apply-threw', msg: String((e && e.message) || e).slice(0, ERR_MSG_MAX_APPLY) });
+    return sendJson(res, 500, { ok: false, error: String((e && e.message) || e) });
+  }
+}
+
+/**
+ * 构造「到达日志」写入器。
+ *
+ * **到达日志**：这条通道以前完全不记录 ⇒ 出现 "Failed to fetch" 时无法区分
+ *   "请求没到达" / "到达后出错" / "返回了但回不到浏览器"。第一步必须能看见。
+ *   只记到达 + 字节数 + 耗时，不记 body 内容（会很吵）。
+ */
+function makeReadyLog(diag, arrivedAt, raw) {
+  return (ok, extra) => {
+    try {
+      diag.appendDiag(JSON.stringify({
+        sid: 'server',
+        entries: [{
+          level: ok ? 'info' : 'warn',
+          at: arrivedAt,
+          event: ok ? 'ready.post' : 'ready.post.error',
+          data: { bytes: raw ? raw.length : 0, ms: Date.now() - arrivedAt, ...extra },
+        }],
+      }));
+    } catch { /* 日志失败不影响就绪通道 */ }
+  };
+}