modelstage 0.0.0-stage → 0.5.28

package/src/server/serve.mjs

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+// serve.mjs —— 服务入口。所有请求都由这里处理：
+//   · /api/*            数据层：调 src/server/** 的实现
+//   · /api/file /files  模型资源流式返回（安全路径解析 + MIME 复用 probe.mjs）
+//   · /icons/*          头像（资源根配置里的 icons 目录）
+//   · /live2d-lib/*     Live2D 运行时库（tool/resolve-live2d-runtimes.mjs 探测结果）
+//   · /plugins/*        展示类型插件 js
+//   · /spine-runtimes/* Spine 运行时（含 index.json 版本清单）
+//   · 引擎模块          src/web/engine/**（ESM，随下面的 src/web 静态托管一起发出；无单独的引擎打包产物）
+//   · 其余              静态托管 src/web
+//
+// 写接口：`POST /api/roots`（资源根增删改名启停）与 `POST /api/config/import`（导入配置）
+//   均已开放，共用 http/write.mjs 的管道：校验 → 备份 → 写 → 失效缓存 → 回读自检。
+//
+// 用法：PORT=8804 node src/server/serve.mjs
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServerData } from './index.mjs';
+import { resolveSafe } from './assets/probe.mjs';
+import { browseDir } from './assets/browse.mjs';
+import { createStaticRoutes, sendFile } from './http/static.mjs';
+import { createDiag } from './http/diag.mjs';
+import { createReady } from './http/ready.mjs';
+import { createWriteApi, toRootView } from './http/write.mjs';
+import { createBackgrounds } from './http/backgrounds.mjs';
+import { createBackgroundSolids } from './http/background-solids.mjs';
+import { createDiagUpload } from './http/diag-upload.mjs';
+import { createLogger } from './core/log.mjs';
+import { createUnpackStore } from './unpack/plugin-store.mjs';
+import { createUnpackRoutes } from './unpack/routes.mjs';
+import { handleData } from './routes/data.mjs';
+import { handleConfig } from './routes/config.mjs';
+import { handleDiag } from './routes/diag.mjs';
+import { handleReady } from './routes/ready.mjs';
+import { handleBackgrounds } from './routes/backgrounds.mjs';
+import { handleBackgroundSolids } from './routes/background-solids.mjs';
+import { handleEntries, createContextFor } from './routes/entries.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const WEB_ROOT = path.join(ROOT, 'src', 'web');
+const RUNTIME_DIR = path.join(ROOT, 'src', 'spine-runtimes');
+const PLUGINS_DIR = path.join(ROOT, 'plugins');
+/**
+ * 数据根：`MODELSTAGE_DATA_ROOT` 环境变量（缺省空 = 项目根 ⇒ **行为完全不变**）。
+ *
+ * 只影响 config/ data/ runtime/ 三处；代码目录（plugins/ src/ tool/）始终跟随 ROOT。
+ * 为什么需要它：测试与生产共用同一实例时，验证过程中的重启会打断正在加载的页面
+ *   （实测把 /live2d-lib 的加载掐断过），且两边同时写 config 会互相覆盖。
+ *   有了它，测试可以起第二实例（不同端口 + 不同数据根），互不干扰。
+ */
+const DATA_ROOT = (process.env.MODELSTAGE_DATA_ROOT || '').trim();
+const PORT = Number(process.env.PORT) || Number(process.argv[2]) || 8804;
+
+/**
+ * 头像根解析：`--avatar-root <dir>` > 环境变量 `MODELSTAGE_AVATAR_ROOT` > `<项目根>/avatars`（默认占位）。
+ * 为什么要可配置：头像仓是独立私有仓，而项目根可能在 CIFS/SMB 上（不允许 chmod ⇒ 那里 clone 不出来），
+ *   所以头像仓要能放到任意可写位置再指过来（见 docs/设计/名表.md §4.1）。
+ */
+function resolveAvatarRoot() {
+  const i = process.argv.indexOf('--avatar-root');
+  const fromArg = i >= 0 ? process.argv[i + 1] : '';
+  return fromArg || process.env.MODELSTAGE_AVATAR_ROOT || '';
+}
+
+/** 服务端日志（统一形状 {at,level,tag,msg,detail}；error→stderr，其余→stdout） */
+const log = createLogger('serve');
+
+/**
+ * 请求活跃度探针：给后台任务判断"现在是不是真空闲"（契约 §八 的"不抢装载资源"）。
+ *
+ * 为什么需要：catalog / 解包这些同步解析会占满主线程（探测单包 ~543ms），
+ *   后台任务只要在"有请求在飞"时动 CPU，用户就会看到某个请求莫名慢几百毫秒。
+ *   有了这份计数，后台可以主动让路（见 data/shape-probe.mjs 的 waitUntilIdle）。
+ *
+ * 统计口径：**只算短请求**。SSE（/api/ready/stream）会一直挂着不结束，
+ *   把它算进来会得到"永远不空闲"——探测当场饿死。
+ */
+const activity = {
+  inflight: 0,
+  lastRequestAt: Date.now(),
+  /** 有短请求正在处理（长连接不算） */
+  idle() { return this.inflight <= 0; },
+  /** 距上一次短请求开始过了多久（ms） */
+  msSinceLastRequest() { return Date.now() - this.lastRequestAt; },
+};
+
+// log 注入：后台形态探测（§八）要能把"启动/完成/失败"写进同一条服务端日志，
+//   否则 S10 的"探测启动次数 = 0"没有可核对的凭据。
+// activity 注入：探测据此让路（有请求在飞 / 刚有请求 ⇒ 不推进），避免抢主线程。
+const data = createServerData({
+  root: ROOT,
+  dataRoot: DATA_ROOT || undefined,
+  avatarRoot: resolveAvatarRoot() || undefined,
+  log,
+  activity,
+});
+// 静态/资源类路由（/plugins、/spine-runtimes、src/web 静态）单独成模块
+// dataRuntimesDir = tool/fetch-runtimes.mjs 的下载落点（<dataRoot>/runtimes/spine）。
+//   传进去之后 /spine-runtimes/index.json 才列得出它、/spine-runtimes/* 才发得出文件
+//   —— 否则"下载成功但前端看不到"（resolver 能找到、清单里没有）。
+const staticRoutes = createStaticRoutes({
+  root: ROOT,
+  webRoot: WEB_ROOT,
+  runtimeDir: RUNTIME_DIR,
+  pluginsDir: PLUGINS_DIR,
+  dataRuntimesDir: path.join(data.paths.dataRoot, 'runtimes', 'spine'),
+  live2dRuntimesDir: path.join(data.paths.dataRoot, 'runtimes', 'live2d'),
+  dataRoot: data.paths.dataRoot,
+});
+const diag = createDiag(data.paths);
+// 自定义背景图存储：落盘在 data/backgrounds/（运行时数据，换机/备份需单独带走）
+const backgrounds = createBackgrounds(data.paths);
+// 纯色背景预设：落盘 data/backgrounds/solids.json（运行时数据，与背景图同目录）
+const solids = createBackgroundSolids(data.paths);
+// 调试日志上传：落盘在 data/logs/（页面把内存里的日志一次性交上来，供 AI 事后读现场）
+const diagUpload = createDiagUpload({ dataDir: data.paths.dataDir, configDir: data.paths.configDir });
+
+// 服务端解包 + 落盘缓存（17b）：产物在 data/unpacked/<fingerprint>/，前端命中后只 fetch 文件
+const unpackStore = createUnpackStore({
+  rootDir: path.join(data.paths.dataDir, 'unpacked'),
+  // 传插件根而不是某一个插件目录：解包插件不止一个（live2d / spine 各一个），
+  //   只读其中一个的版本会让另一个升级时缓存不失效（产物陈旧但一切"正常"）。
+  //   plugin-store 会把根下每个插件的版本汇总进指纹。
+  pluginDir: data.paths.pluginsDir,
+});
+// 只读注入：catalog 用它查"这个包被哪个插件解出来过"（列表徽标的展示归属）。
+//   只是读缓存索引，不触发任何解包，也不改变 catalog 的缓存行为。
+data.catalog.setUnpackStore(unpackStore);
+const unpackRoutes = createUnpackRoutes({
+  store: unpackStore,
+  readConfig: () => data.config.readConfig(),
+  resolveSafe,
+  sendJson,
+  readBody,
+});
+// 就绪信号通道（契约 就绪信号契约.md）：与 diag 完全分离的状态机，不进调试面板
+const ready = createReady();
+// 写接口（资源根增删改名启停 / 导入配置）：读路径与写路径共用同一份 config/spine/names 实例
+const writeApi = createWriteApi({
+  paths: data.paths, config: data.config, spine: data.spine, names: data.names,
+});
+
+/** 统一的 JSON 响应（与 server.mjs 的 sendJson 同形：无缩进、no-store） */
+function sendJson(res, status, body) {
+  // 统一守卫：某个 handler 已响应过、但没 return true 让流程继续时，这里直接放弃，
+  //   否则会抛 ERR_HTTP_HEADERS_SENT（曾导致日志刷错 + 进程异常退出）。
+  if (res.headersSent || res.writableEnded) return;
+  const text = JSON.stringify(body);
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(text),
+    'Cache-Control': 'no-store',
+  });
+  res.end(text);
+}
+
+/** 简单文本响应 */
+function sendText(res, status, text, type) {
+  res.writeHead(status, { 'Content-Type': type || 'text/plain; charset=utf-8' });
+  res.end(text);
+}
+
+/**
+ * 读请求体；超限直接断开连接（不截断，避免把半个 JSON 当成完整内容去写盘）。
+ *
+ * ⚠️ 必须**收齐 Buffer 再统一解码**，不能逐 chunk `body += chunk`：
+ *   chunk 是 Buffer，`+=` 会按 utf8 逐段解码；一个多字节字符（中文正好 3 字节）
+ *   被切在两个 chunk 边界上时，两半各自解成 U+FFFD ⇒ 内容被写坏。
+ *   实测：导入 588KB 名表时「喀琅施塔得」被写成「喀琅��塔得」，文件凭空多 3 字节。
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {(body: string) => void} onBody
+ * @param {number} [maxBytes] 上限（字节）：默认 2MB；导入配置传 5MB
+ */
+function readBody(req, res, onBody, maxBytes = 2e6) {
+  const chunks = [];
+  let size = 0;
+  req.on('data', (chunk) => {
+    size += chunk.length;
+    if (size > maxBytes) {
+      req.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  req.on('end', () => {
+    // 空请求体也要回调（由各接口自己判断"缺少字段"并给出明确错误）
+    const body = Buffer.concat(chunks).toString('utf8');
+    try {
+      onBody(body);
+    } catch (e) {
+      log.error('POST 处理异常', { err: (e && e.stack) ? e.stack : String(e) });
+      sendJson(res, 500, { ok: false, error: String((e && e.message) || e) });
+    }
+  });
+}
+
+// ------------------------------------------------------------------ 入口
+
+/**
+ * 请求上下文：路由模块只拿它需要的东西（显式依赖，便于单测替换）。
+ * 不把 req/res 之外的全局状态藏进模块级变量——之前那个 127 行的大回调就是这种耦合的产物。
+ */
+const ctx = {
+  data, staticRoutes, diag, diagUpload, ready, writeApi, backgrounds, solids, unpackRoutes,
+  resolveSafe, browseDir, sendFile, toRootView, sendJson, sendText, readBody, fs, path, log,
+  // 条目状态（契约 §三）：写读一体的存储实例与"条目静态事实"查询
+  entryStates: data.entryStates,
+  // 后台形态探测（契约 §八）：计数/手动重探走 /api/entries/probe（S10 的佐证口）
+  shapeProbe: data.shapeProbe,
+  catalog: data.catalog,
+  contextFor: createContextFor({
+    providers: () => data.plugins.readPlugins(),
+    describe: (key) => data.catalog.describeEntry(key),
+  }),
+};
+
+/**
+ * 顶层分发：按**前缀归属**依次交给路由模块，谁先认领就结束。
+ *
+ * 顺序有讲究（与拆分前完全一致，不能随意调换）：
+ *   1. unpack 三条（/api/unpack/*，与资源读取解耦，命中即返回）
+ *   2. diag（/api/diag、/api/diag/upload|uploads）
+ *   3. ready（/api/ready GET/POST、/api/ready/stream）
+ *   4. config（/api/config/export|import）
+ *   5. backgrounds（/api/backgrounds*）
+ *   6. data（/api/roots 写 + 只读数据 API + 二进制资源）
+ *   7. 静态资源（/plugins、/spine-runtimes、src/web）
+ *   8. 兜底：未匹配的 /api/* ⇒ 404 JSON；GET/HEAD ⇒ 静态；其余 ⇒ 405
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} p
+ * @param {URL} url
+ */
+/**
+ * 版本号：读 package.json（它是版本号的唯一权威，与 bin 的 --version 同源）。
+ * 读不到时返回 'unknown' 而不是抛错 —— 探活端点不该因为包元信息缺失而 500。
+ */
+function readVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * GET /api/health —— 探活端点（`web.sh status` 与外部监控用）。
+ *
+ * 为什么单独一条而不复用 /api/ready：ready 是"能否开始服务请求"的业务就绪信号
+ *   （要扫资源根、可能 503），而 health 只回答"进程活着吗、什么版本、数据在哪"。
+ *   两者语义不同，混一起会让监控在"资源根还没扫完"时误判进程已死。
+ *
+ * 只暴露排障必需的粗粒度信息：版本 / 运行时长 / 数据根绝对路径 / 插件数。
+ *   **不返回**配置内容、资源根清单、任何凭据或环境变量。
+ */
+function handleHealth(req, res, p) {
+  if (p !== '/api/health') return false;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    sendJson(res, 405, { ok: false, error: '仅支持 GET' });
+    return true;
+  }
+  // 插件数：直接问数据层（与 /api/plugins 同源）。
+  //   早先这里写的是 ctx.providers()，但本函数没有 ctx 参数 —— 异常被 catch 吞成 0，
+  //   结果 health 永远报 plugins:0（实测 5 个插件时也报 0）。探活字段报假数比不报更糟，故改为同源直取。
+  let pluginCount = 0;
+  try {
+    pluginCount = (data.plugins.readPlugins() || []).length;
+  } catch { /* 插件系统未就绪也算 0，探活不该因此失败 */ }
+  sendJson(res, 200, {
+    ok: true,
+    uptimeSec: Math.round(process.uptime()),
+    version: readVersion(),
+    dataRoot: data.paths.dataRoot,
+    plugins: pluginCount,
+  });
+  return true;
+}
+
+function dispatch(req, res, p, url) {
+  // 探活放最前：它不该被其它路由的鉴权/副作用影响（也就不会因为那些逻辑出错而"连探活都挂"）
+  if (handleHealth(req, res, p)) return true;
+  if (unpackRoutes(req, res, p, url)) return true;
+  if (handleDiag(req, res, p, url, ctx)) return true;
+  if (handleReady(req, res, p, url, ctx)) return true;
+  if (handleConfig(req, res, p, ctx)) return true;
+  // 注意顺序：/api/backgrounds/solids 是 /api/backgrounds 的**子路径**，
+  //   必须先让纯色预设那组认领，否则会被 backgrounds 的 404 分支吃掉
+  if (handleBackgroundSolids(req, res, p, ctx)) return true;
+  if (handleBackgrounds(req, res, p, ctx)) return true;
+  // 条目状态（写读一体）：必须在 handleData 之前认领，否则 /api/ 前缀兜底会当未知接口 404
+  if (handleEntries(req, res, p, url, ctx)) return true;
+  if (handleData(req, res, p, url, ctx)) return true;
+  if (staticRoutes.serveAssets(req, res, p)) return true;
+  if (res.headersSent) return true;
+  if (p.startsWith('/api/')) {
+    sendJson(res, 404, { error: `未知接口: ${p}` });
+    return true;
+  }
+  if (req.method === 'GET' || req.method === 'HEAD') return staticRoutes.serveStatic(req, res, p);
+  sendText(res, 405, `405: ${req.method} ${p}`);
+  return true;
+}
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+  // 长连接（SSE）不计入活跃度：它一挂几分钟，计入就等于"服务永远忙"
+  const longLived = url.pathname.includes('/stream');
+  if (!longLived) {
+    activity.inflight += 1;
+    activity.lastRequestAt = Date.now();
+    let counted = true;
+    const done = () => {
+      if (!counted) return;      // close 与 finish 都会来，只减一次
+      counted = false;
+      activity.inflight -= 1;
+      activity.lastRequestAt = Date.now();
+    };
+    res.on('finish', done);
+    res.on('close', done);
+  }
+  try {
+    dispatch(req, res, url.pathname, url);
+  } catch (e) {
+    log.error('请求处理异常', { err: (e && e.stack) ? e.stack : String(e) });
+    try {
+      if (!res.headersSent) sendJson(res, 500, { error: `服务内部错误: ${e.message}` });
+    } catch {
+      try { res.writeHead(500); res.end('internal error'); } catch { /* 忽略 */ }
+    }
+  }
+});
+
+// HTTP keep-alive 超时（消除"客户端复用已被服务端关闭的连接"这类 race）：
+//   Node 默认 keepAliveTimeout=5s，浏览器常把空闲连接留着复用 ⇒ 拿到已关闭连接 ⇒ fetch 直接 Failed to fetch。
+//   现场表现：加载过很多模型后 Spine 空白（模型文件是几十个并发裸 fetch），而资源包正常（走 blob 不走网络）。
+//   注意 headersTimeout **必须严格大于** keepAliveTimeout，否则 Node 会在读 header 阶段就断连。
+server.keepAliveTimeout = 65000;
+server.headersTimeout = 66000;
+server.requestTimeout = 0; // 0 = 不主动超时（长请求如大模型文件不被中途砍断）
+server.listen(PORT, '0.0.0.0', () => {
+  log.info(`内置服务 on http://0.0.0.0:${PORT}`);
+  log.info(`静态根 ${WEB_ROOT}`);
+  log.info(`数据根 ${data.paths.dataRoot}${DATA_ROOT ? '（MODELSTAGE_DATA_ROOT 覆盖）' : '（默认=项目根）'}`);
+  log.info('资源根已登记', { roots: data.config.readConfig().map((r) => `${r.id}=${r.name}`) });
+});
+
+// 监听失败要**说人话**：不处理的话用户看到的是 EADDRINUSE 原始堆栈（一大坨，且不说下一步做什么）。
+//   退出码用 2 而不是 1：1 留给"参数/配置错误"这类，端口占用是环境问题，靠退出码就能区分。
+server.on('error', (e) => {
+  const code = (e && e.code) || '';
+  if (code === 'EADDRINUSE') {
+    log.error(`端口 ${PORT} 已被占用：用 --port <其他端口> 换一个，或先停掉占用该端口的进程`);
+    log.error(`排查提示：lsof -i :${PORT}（macOS/Linux）或 netstat -ano | findstr :${PORT}（Windows）`);
+    process.exit(2);
+  }
+  // 其它监听错误（EACCES 权限不足、EADDRNOTAVAIL 地址不可用…）：保留原始信息，同样给出下一步
+  log.error(`监听端口 ${PORT} 失败：${(e && e.message) || e}`, { code });
+  log.error('可尝试：换一个端口（--port），或检查是否有权限监听该端口/该地址');
+  process.exit(2);
+});
+
+/**
+ * 收尾钩子：先把**常驻资源**放掉再退出。
+ *
+ * 为什么必须有：后台形态探测为省掉"每批重建解析沙箱"（一批 4.5s → 76s）会保留一个 worker 线程。
+ *   `worker.unref()` 只让它不单独撑住进程，挡不住 `worker.on('message')` 把事件循环 hold 住 ——
+ *   不显式关掉就表现为"服务收到 SIGTERM 停不下来"（同样的问题在 `node --test` 里就是退出码 124）。
+ */
+function registerShutdown() {
+  const stop = async (signal) => {
+    log.info(`收到 ${signal}，开始收尾`);
+    try {
+      if (data.shapeProbe && typeof data.shapeProbe.close === 'function') await data.shapeProbe.close();
+    } catch (e) {
+      log.warn('收尾时关闭探测 worker 失败（继续退出）', { err: (e && e.message) || String(e) });
+    }
+    try { server.close(); } catch { /* 已经关了 */ }
+    // 兜底强退：keep-alive 连接可能把 close() 拖住（这里不等它们）
+    const t = setTimeout(() => process.exit(0), 200);
+    if (typeof t.unref === 'function') t.unref();
+  };
+  let stopping = false;
+  const once = (signal) => {
+    if (stopping) return;                      // 连按两次 Ctrl-C 不重复走流程
+    stopping = true;
+    stop(signal);
+  };
+  process.once('SIGINT', () => once('SIGINT'));
+  process.once('SIGTERM', () => once('SIGTERM'));
+}
+registerShutdown();

package/src/server/unpack/capacity.mjs

@@ -0,0 +1,217 @@
+// unpack/capacity.mjs —— 解包的准入判据（只按**可用内存**动态判断，不设可调阈值）
+//
+// 设计取舍（前一版是"包大小阈值 + 内存百分比 + 三个 env"，属过度设计）：
+//   包大小阈值本来就是为了控内存 ⇒ 两者是同一件事。现在直接算「这个包解包后的预估峰值
+//   会不会超过"可用内存的一半"」，一次判断，不拍脑袋定包大小门槛。
+//
+// 三条实测依据（本机测量，决定了下面的分段系数）：
+//   · VmHWM 峰值：12MB→176MB（14.7×）、19MB→451MB（23.7×）、42MB→479MB（11.4×）
+//     ⇒ **非线性**（19MB 比 42MB 还费内存），所以不能用单一倍数，按档取上包络。
+//   · 解包耗时：12MB→2.3s、19MB→10.0s、42MB→8.6s（同样非线性，19MB 最费）
+//     ⇒ 预估耗时只作为参考信息返回（日志里能看"大概多久"），**不参与任何判断**：
+//       曾经用它做过预热门槛，结果 15MB 以上的包永远进不了预热、服务端缓存永远填不上。
+//   · `os.freemem()` 在 Linux 不含可回收 buff/cache，会严重低估 ⇒ 必须优先 /proc/meminfo 的 MemAvailable。
+import fs from 'node:fs';
+import os from 'node:os';
+
+import { readRatioEnv } from '../core/env-num.mjs';
+
+/**
+ * 预算比例：只用可用内存的一部分，给系统/渲染留另一半。
+ *
+ * 缺省 0.5；可用 **MODELSTAGE_ADMIT_CAPACITY_RATIO** 覆盖（服务端容量判据）。
+ * 非法值（NaN / ≤0 / >1）⇒ 回落 0.5 + 一条 warn（见 core/env-num.mjs），
+ *   绝不把 NaN 传进乘法 —— 那会让预算恒为 NaN、判据静默失效。
+ * 每次判断现读（进程内改 env/测试注入即生效；进程外改 env 仍要重启）。
+ */
+const DEFAULT_MEM_BUDGET_RATIO = 0.5;
+function memBudgetRatio() {
+  return readRatioEnv('MODELSTAGE_ADMIT_CAPACITY_RATIO', DEFAULT_MEM_BUDGET_RATIO);
+}
+
+/**
+ * 可用内存（MB）——**每次判断时现取，绝不缓存**。
+ *
+ * 三个分支（跨平台）：
+ *   ① Linux：读 /proc/meminfo 的 MemAvailable。这是内核估算的"真要用了能腾出多少"，
+ *      含可回收的 buff/cache；`os.freemem()` 不含 ⇒ 本机实测会低估数倍，不能用作准入判据。
+ *   ② macOS / Windows：`os.freemem()` 相对准确（没有 Linux 那个 buff/cache 的口径问题）。
+ *   ③ 兜底（拿不到或为 0）：总内存的一半 —— 保守方向，宁可少解包也不误放行。
+ * @returns {{mb: number, source: 'MemAvailable'|'freemem'|'totalmem/2'}}
+ */
+export function memAvailableMb() {
+  try {
+    const m = /MemAvailable:\s+(\d+)\s*kB/.exec(fs.readFileSync('/proc/meminfo', 'utf8'));
+    if (m) return { mb: Math.round(Number(m[1]) / 1024), source: 'MemAvailable' };
+  } catch { /* 非 Linux / 无该文件：落到下一分支 */ }
+  const free = os.freemem();
+  if (free > 0) return { mb: Math.round(free / 1024 / 1024), source: 'freemem' };
+  return { mb: Math.round(os.totalmem() / 1024 / 1024 / 2), source: 'totalmem/2' };
+}
+
+/**
+ * 源包大小 → 预估解包峰值（MB）。**仅供第③段回落**（插件没有声明 memory 时，保证不倒退）。
+ * 现在**只作第③段兜底**：准不准是插件的事（它声明 peakBytes 就用它的），核心不再维护容器结构模型。
+ *   12MB→240（实测 176，留 36% 余量）
+ *   19MB→494（实测 451，留 10% 余量）
+ *   42MB→630（实测 479，留 32% 余量）
+ * @param {number} sourceMb
+ * @returns {number}
+ */
+export function estimatePeakMb(sourceMb) {
+  if (sourceMb <= 12) return Math.ceil(sourceMb * 20);
+  if (sourceMb <= 19) return Math.ceil(sourceMb * 26);
+  return Math.ceil(sourceMb * 15);
+}
+
+/**
+ * 源包大小 → 预估解包耗时（秒）。同样按实测分段（非线性，19MB 那档最费）。
+ *   12MB→3s（实测 2.3s）/ 19MB→9.3s（实测 10.0s）/ ≥20MB→9s 起（42MB 实测 8.6s）
+ * @param {number} sourceMb
+ * @returns {number}
+ */
+export function estimateUnpackSec(sourceMb) {
+  if (sourceMb <= 12) return +(sourceMb * 0.25).toFixed(1);
+  if (sourceMb <= 20) return +(3 + (sourceMb - 12) * 0.9).toFixed(1);
+  return 9;
+}
+
+/**
+ * 当前机器 + 某个包的准入判断（前端只读 `allowWarmup` 一个布尔，不再自己算）。
+ * @param {number} [sourceMb] 源包大小（MB）；不传则只返回机器级信息，allowWarmup=true（不下结论）
+ * @returns {object}
+ */
+export function capacity(sourceMb, memory) {
+  const avail = memAvailableMb();
+  const ratio = memBudgetRatio();
+  const budgetMb = Math.round(avail.mb * ratio);
+  const base = {
+    memTotalMb: Math.round(os.totalmem() / 1024 / 1024),
+    memAvailableMb: avail.mb,
+    memAvailableSource: avail.source,
+    budgetMb,
+    ratio,
+    rssMb: Math.round(process.memoryUsage().rss / 1048576),
+  };
+  if (!(sourceMb > 0)) {
+    return { ...base, sourceMb: null, peakEstMb: null, estUnpackSec: null, allowWarmup: true, reason: 'no-package', basis: null };
+  }
+  // 与准入判断（checkUnpackMemory）**同源**：都走 estimatePeakWithBasis，同一个包只该有一个数字
+  const est = estimatePeakWithBasis(sourceMb, memory);
+  const peakEstMb = est.peakEstMb;
+  // 预估耗时只作参考信息（日志里能看"大概多久"），**不参与任何判断**
+  const estUnpackSec = estimateUnpackSec(sourceMb);
+  if (peakEstMb > budgetMb) {
+    return { ...base, sourceMb, peakEstMb, estUnpackSec, allowWarmup: false, reason: 'insufficient-memory', basis: est.basis };
+  }
+  // 预热只看内存：**不再有时间门槛**。旧实现"预估 >6s 就不预热"导致 15.4MB 以上的包永远进不了预热，
+  //   data/unpacked 永远填不上 ⇒ 前端一直回落本地解包，服务端为判断付的 probe/内存读取全都白跑。
+  return { ...base, sourceMb, peakEstMb, estUnpackSec, allowWarmup: true, reason: 'ok', basis: est.basis };
+}
+
+/**
+ * 三段回落，选出本次判据用的「预估峰值」。
+ *
+ * 顺序固定（契约 §2.2）：
+ *   ① 插件/缓存给了 peakBytes        → **直接采信，不再叠加安全垫**（责任在声明方）
+ *   ② 给了 decompressedBytes（或缓存里的实测解压量）→ 按模型算（模型自带 15% 垫）
+ *   ③ 什么都没有（第三方/旧插件）     → 回落到「源包大小分段」= 既有行为，保证不倒退
+ *
+ * 另外：**实测峰值（measuredPeakBytes）不再参与判定**，只随返回值回传供观测
+ *   —— 解包搬进 worker 后它含 worker 常驻内存，随执行线程变化（详见下方 ② 的注释）。
+ * @param {number} sourceMb 源包大小（MB）
+ * @param {{peakBytes?:number, decompressedBytes?:number, measuredPeakBytes?:number}} [memory]
+ * @returns {{peakEstMb:number, basis:'plugin-peak'|'model-decompressed'|'legacy-source', declaredMb:number, measuredMb:number}}
+ */
+export function estimatePeakWithBasis(sourceMb, memory) {
+  const mem = memory || {};
+  const toMb = (bytes) => Math.ceil(bytes / (1024 * 1024));
+
+  // ① 插件声明值（peakFromDecompressed 表，按 max-of-runs 标定）—— 主值
+  //    没有声明才退回"源包大小分段粗估"（核心不维护容器结构模型，那是插件的责任）
+  const declaredMb = mem.peakBytes > 0 ? toMb(mem.peakBytes) : estimatePeakMb(sourceMb);
+  const declaredBasis = mem.peakBytes > 0 ? 'plugin-peak' : 'legacy-source';
+
+  // ② 实测回填值 —— **只作下限兜底，不能压声明值**
+  //
+  //    measuredPeakBytes 的成因与局限**详见 src/server/unpack/plugin-store.mjs 里
+  //    recordMeasuredPeak 的注释**（那里讲清了为什么它不是"这一包的成本"、以及实测 225MB vs 1195MB 的证据）。
+  //
+  // ② 实测回填值 —— **不再参与准入判定**，只作为观测数据回传（probe.json / 日志 / 前端提示）
+  //
+  //    为什么从"取 max"改成"完全不采信"（实测取证）：
+  //      解包搬进 worker 后，measured 的公式 `峰值 = 起始 RSS + 本次 VmHWM 增量` 里的**起始 RSS
+  //      已经含 worker 的常驻内存**（独立 V8 isolate + 预热装载的插件 lib + vm 沙盒）。
+  //      同一个包、同一台机器：搬 worker 前 136.7MB → 搬之后 212~225MB（+55~65%）；
+  //      即使预热把"首次装载插件"的一次性开销移出了测量窗口，第 2 次仍偏高（212MB）。
+  //    ⇒ 一个**随执行线程（以及"是不是该线程的第一个包"）变化**的数不能当准入依据，
+  //      否则同样大小的包会"有时过有时不过"。准入只信 declared（插件声明值，按 max-of-runs 标定）。
+  const measuredMb = mem.measuredPeakBytes > 0 ? Math.ceil((mem.measuredPeakBytes / (1024 * 1024)) * 1.05) : 0;
+
+  return { peakEstMb: declaredMb, basis: declaredBasis, declaredMb, measuredMb };
+}
+
+/**
+ * 「已放行」时的说明文案（用户关掉了内存保护开关，请求仍然超预算）。
+ *
+ * 为什么单独抽一个函数：这条文案要在放行与拒绝两种结果里都用同一套数字，
+ *   而且必须是可读的——"放行了"不等于"没风险"，要让用户看到预估峰值与当前可用。
+ * @param {number} peakEstMb
+ * @param {number} budgetMb
+ * @param {number} availMb
+ * @returns {string}
+ */
+export function overLimitText(peakEstMb, budgetMb, availMb) {
+  return `已按「内存保护」开关放行：预估峰值 ${peakEstMb}MB 超过预算 ${budgetMb}MB`
+    + `（当前可用 ${availMb}MB）—— 本次解包可能引起内存紧张，若加载失败请开启内存保护或稍后重试`;
+}
+
+/**
+ * 解包入口的内存判据（服务端 resolve 用；**不含时间上限**——用户主动加载不能因为"慢"被拒）。
+ *
+ * 内存保护开关的落地口径：
+ *   默认（不传 opts）＝现状，超预算就拒绝 —— 保持既有行为，现有调用方零改动；
+ *   前端把面板里的「内存保护」开关关掉后，请求带上 allowOverLimit:true ⇒ 这里放行，
+ *   但仍把真实数字一起返回（调用方要能提示"你放行了 X MB 的包"）。
+ * @param {number} sourceBytes 源文件字节数
+ * @param {{allowOverLimit?: boolean}} [opts] 是否允许越过内存预算强行解包
+ * @returns {{ok: boolean, reason?: string, message?: string, budgetMb: number, peakEstMb: number, availMb: number, overLimit?: boolean}}
+ */
+export function checkUnpackMemory(sourceBytes, opts = {}) {
+  const sourceMb = sourceBytes / 1024 / 1024;
+  const avail = memAvailableMb();
+  const ratio = memBudgetRatio();
+  const budgetMb = Math.round(avail.mb * ratio);
+  const est = estimatePeakWithBasis(sourceMb, opts.memory);
+  const peakEstMb = est.peakEstMb;
+  if (peakEstMb > budgetMb) {
+    // 开关关闭 ⇒ 放行（用户自担风险），但 overLimit 标记与文案都要带出去
+    if (opts && opts.allowOverLimit === true) {
+      return {
+        ok: true,
+        reason: 'over-limit-allowed',
+        message: overLimitText(peakEstMb, budgetMb, avail.mb),
+        budgetMb,
+        peakEstMb,
+        availMb: avail.mb,
+        overLimit: true,
+        basis: est.basis,
+      };
+    }
+    return {
+      ok: false,
+      reason: 'insufficient-memory',
+      // 说清"为什么被拒 + 还能怎么办"：解包本来就是**串行**的（plugin-store 的 enqueue 链），
+      //   所以这里不是"并发太多"，而是这个包自己就要这么多 —— 能做的只有等内存回来再试。
+      //   不提高全局上限（那等于把守护关掉），也不自动重试（会在内存紧张时形成抖动重试风暴）。
+      message: `预估峰值 ${peakEstMb}MB 超过可用预算 ${budgetMb}MB（当前可用 ${avail.mb}MB × ${ratio}）`
+        + '；解包串行执行，稍后内存释放后可重试（或先关掉其它已加载模型）',
+      budgetMb,
+      peakEstMb,
+      availMb: avail.mb,
+      overLimit: true,
+      basis: est.basis,
+    };
+  }
+  return { ok: true, budgetMb, peakEstMb, availMb: avail.mb, overLimit: false, basis: est.basis };
+}

package/src/server/unpack/mem-probe.mjs

@@ -0,0 +1,27 @@
+// server/unpack/mem-probe.mjs —— 读进程内存（RSS 与内核记录的峰值 VmHWM）
+//
+// 为什么抽成模块：解包搬进 worker 后，worker 里也要在解包前后各读一次（算本次峰值增量），
+//   而主线程的准入/统计路径同样要读 —— 两边必须同一份实现、同一口径。
+//
+// **口径不变（关键）**：worker_threads 里 `/proc/self` 指向同一个进程，
+//   所以在 worker 里读与在主线程读得到的是同一组数字，VmHWM 语义完全不变 —— 不需要改测量代码。
+
+import fs from 'node:fs';
+
+/**
+ * 读当前 RSS 与进程峰值。
+ * @param {number} [peakFallback] 非 Linux（读不到 /proc）时的兜底峰值基线
+ * @returns {{rss:number, peak:number, source:'vmhwm'|'sample'}}
+ */
+export function rssNow(peakFallback = 0) {
+  try {
+    const txt = fs.readFileSync('/proc/self/status', 'utf8');
+    const hwm = /VmHWM:\s+(\d+)\s+kB/.exec(txt);
+    const rss = /VmRSS:\s+(\d+)\s+kB/.exec(txt);
+    if (hwm) return { rss: rss ? Number(rss[1]) * 1024 : process.memoryUsage().rss, peak: Number(hwm[1]) * 1024, source: 'vmhwm' };
+  } catch { /* 非 Linux：退回抽样 */ }
+  const rss = process.memoryUsage().rss;
+  return { rss, peak: Math.max(peakFallback, rss), source: 'sample' };
+}
+
+export default rssNow;