modelstage 0.0.0-stage → 0.5.28

package/src/web/app/dir-picker.js

@@ -0,0 +1,242 @@
+// app/dir-picker.js —— 资源根「选择目录」的服务端目录浏览器
+//
+// 为什么必须有它：模型在**服务端**磁盘上，浏览器拿不到绝对路径（File System Access API 给的是
+//   客户端沙箱句柄），只能让服务端列目录。只能走服务端列目录（`/api/browse`）：浏览器拿不到任意路径的目录列表。
+//
+// 交互//   点「选择目录」→ 弹出面板
+//   顶部：标题 + 关闭
+//   中部：当前路径（含子目录数 / 含多少 .skel）、「↑ 上级目录」、「选择此目录」、📁 子目录列表
+//   底部：显示名称（可空，同名会合并成一个游戏）+「添加」
+//
+// 面板关掉就销毁，不常驻 DOM（不留隐藏节点）。
+
+/** 打开时的默认起点：上次用过的目录优先，否则从根开始让用户自己走 */
+const LAST_DIR_KEY = 'modelstage.dirpicker.last';
+
+// 目录列举走统一 HTTP 层（api.js）：拿重试 + 去重 + 统一的 TimeoutError 归类，别裸 fetch
+import { getJson } from '../infra/api.js';
+
+/**
+ * 创建目录选择器。
+ * @param {{onPick: (payload: {path: string, name: string}) => Promise<boolean>|boolean, formatError?: Function}} deps
+ *   onPick 返回 true 表示添加成功（面板会自行关闭）
+ */
+export function createDirPicker({ onPick, formatError, getLastError } = {}) {
+  let panel = null;      // 遮罩层（含面板）
+  let currentPath = '';  // 当前浏览到的目录
+  let pickedPath = '';   // 用户点过"选择此目录"的目录（空 = 还没选）
+  let busy = false;
+
+  const q = (sel) => (panel ? panel.querySelector(sel) : null);
+
+  /** 读上次目录（浏览器存储不可用时回落空串） */
+  function lastDir() {
+    try { return localStorage.getItem(LAST_DIR_KEY) || ''; } catch { return ''; }
+  }
+
+  function rememberDir(path) {
+    try { localStorage.setItem(LAST_DIR_KEY, path); } catch { /* 存不了就算了 */ }
+  }
+
+  function ensureShell() {
+    if (panel) return panel;
+    panel = document.createElement('div');
+    panel.id = 'dir-picker';
+    panel.className = 'dir-picker';
+    panel.innerHTML = `
+      <div class="dir-picker-box" role="dialog" aria-modal="true" aria-label="添加资源根">
+        <div class="dir-picker-head">
+          <strong>添加资源根</strong>
+          <span class="dir-picker-spacer"></span>
+          <button type="button" class="mini-btn" data-role="close">关闭</button>
+        </div>
+        <div class="dir-picker-body" data-role="body"></div>
+        <!-- 失败原因显示在对话框**自己身上**：它弹在屏幕中央，左栏那行提示在用户背后等于没有 -->
+        <div class="dir-picker-alert" data-role="alert" role="alert" hidden></div>
+        <div class="dir-picker-foot">
+          <span class="muted-hint">显示名称（同名会合并成一个游戏，用于归类原版／Mod）</span>
+          <input type="text" data-role="name" placeholder="如：棕色尘埃2" aria-label="资源根显示名称" />
+          <button type="button" class="mini-btn is-accent" data-role="add">添加</button>
+        </div>
+      </div>`;
+    document.body.append(panel);
+    // 点遮罩关闭（点面板内部不关）
+    panel.addEventListener('click', (e) => { if (e.target === panel) close(); });
+    q('[data-role="close"]').addEventListener('click', close);
+    q('[data-role="add"]').addEventListener('click', doAdd);
+    return panel;
+  }
+
+  /** 渲染当前目录：路径信息 / 上级 / 选择此目录 / 子目录列表 */
+  async function renderBody() {
+    const body = q('[data-role="body"]');
+    if (!body) return;
+    body.replaceChildren();
+    body.append(text('div', 'dir-picker-hint', '加载中…'));
+    let data = null;
+    try {
+      // 幂等 GET（连点同一目录会被 api.js 去重）⇒ 走统一层；超时 30s 的依据：
+      //   本机 CIFS（vers=3.02）实测 75 条目 5.5ms、241 条目 19ms，**未实测到慢例**，
+      //   按项目既有「catalog 冷启动最坏 31s」（同属目录扫描链路）**类推**取 30s。
+      data = await getJson(`/api/browse?path=${encodeURIComponent(currentPath)}`, { timeoutMs: 30000 });
+      if (!data || data.error) throw new Error((data && data.error) || '服务端返回空目录数据');
+    } catch (err) {
+      body.replaceChildren(text('div', 'dir-picker-error',
+        `读取失败：${typeof formatError === 'function' ? formatError(err) : (err && err.message) || err}`));
+      return;
+    }
+    currentPath = data.path || currentPath;
+    const hint = data.hint || {};
+    const info = text('div', 'dir-picker-hint', '');
+    info.append('当前：');
+    const code = document.createElement('code');
+    code.textContent = currentPath;
+    info.append(code);
+    info.append(`　子目录 ${hint.subDirCount || 0} 个${hint.skelHere ? `，含 ${hint.skelHere} 个 .skel` : ''}`);
+    body.replaceChildren(info);
+
+    // ↑ 上级目录
+    if (data.parent) body.append(navBtn(`↑ 上级目录`, data.parent));
+
+    // 选择此目录（已选过就变成"✓ 已选择"，再点仍是选中当前）
+    const pick = document.createElement('button');
+    pick.type = 'button';
+    // 已选中态用描边强调（与「选择目录」「添加」同一套语言），不再用实心高饱和
+    pick.className = pickedPath === currentPath ? 'mini-btn is-accent' : 'mini-btn';
+    pick.dataset.pick = currentPath;
+    pick.textContent = pickedPath === currentPath ? '✓ 已选择此目录' : '选择此目录';
+    pick.addEventListener('click', () => { pickedPath = currentPath; renderBody(); });
+    const pickRow = text('div', 'dir-picker-pick', '');
+    pickRow.append(pick);
+    body.append(pickRow);
+
+    // 子目录列表
+    const dirs = Array.isArray(data.dirs) ? data.dirs : [];
+    if (!dirs.length) {
+      body.append(text('div', 'dir-picker-hint', '（无子目录）'));
+      return;
+    }
+    const list = text('div', 'dir-picker-list', '');
+    for (const d of dirs) {
+      const btn = navBtn(`📁 ${d.name}`, d.path);
+      btn.dataset.dirName = d.name;
+      list.append(btn);
+    }
+    body.append(list);
+  }
+
+  function text(tag, className, content) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (content) n.textContent = content;
+    return n;
+  }
+
+  function navBtn(label, target) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'mini-btn dir-picker-nav';
+    btn.dataset.nav = target;
+    btn.textContent = label;
+    btn.addEventListener('click', () => {
+      // 换目标 ⇒ 之前的「选择此目录」作废。
+      //   不清的后果（实测过的 bug）：在 A 点过选择、再导航到 B 点添加，提交的却是 A，
+      //   服务端按路径判重正确返回 409「该目录已登记为资源根」——
+      //   用户看到的是"我明明没登记 B，凭什么说已登记"，且「✓ 已选择」还挂在 A 上。
+      pickedPath = '';
+      currentPath = target;
+      renderBody();
+    });
+    return btn;
+  }
+
+  /**
+   * 添加：**只提交当前浏览的目录**。
+   *
+   * 为什么不再用 `pickedPath || currentPath`：pickedPath 是"点过选择此目录"留下的，
+   *   一旦导航没清（历史 bug），它就会是**上一次选过的目录** ⇒ 提交一个与当前视图无关的目标
+   *   ⇒ 服务端按路径判重正确返回 409，而用户完全看不出为什么。
+   *   现在 navBtn 已经"导航即清除"，pickedPath 只可能是空或等于 currentPath；
+   *   这里再兜一层：提交值永远来自 currentPath，两者不一致时不可能发生错位。
+   */
+  async function doAdd() {
+    if (busy) return;
+    const path = currentPath;
+    const nameInput = q('[data-role="name"]');
+    const name = nameInput ? nameInput.value.trim() : '';
+    if (!path) return;
+    clearAlert();
+    busy = true;
+    try {
+      const res = typeof onPick === 'function' ? await onPick({ path, name }) : false;
+      // onPick 可能返回布尔（既有实现）或 { ok, error }（更细的实现）——两种都认
+      const ok = res && typeof res === 'object' ? res.ok === true : res === true;
+      if (ok) { rememberDir(path); close(); return; }
+      // 失败：**对话框不关**，把原因写在底部输入行上方，用户改完就能重试
+      showAlert(pickErrorText(res));
+    } finally {
+      busy = false;
+    }
+  }
+
+  /**
+   * 取失败原因文本。
+   * 优先用 onPick 直接给回来的 error（{ ok:false, error }）；
+   * 否则问 getLastError（root-manager 会把上一次失败文案记下来）。
+   * @param {unknown} res onPick 的返回值
+   * @returns {string}
+   */
+  function pickErrorText(res) {
+    if (res && typeof res === 'object' && typeof res.error === 'string' && res.error) return res.error;
+    try {
+      if (typeof getLastError === 'function') {
+        const t = getLastError();
+        if (typeof t === 'string' && t) return t;
+      }
+    } catch { /* 取不到就退回通用文案 */ }
+    return '添加失败，请检查目录路径与名称后重试';
+  }
+
+  /** 把失败原因显示在对话框内 */
+  function showAlert(text) {
+    const box = q('[data-role="alert"]');
+    if (!box) return;
+    box.textContent = String(text || '');
+    box.hidden = !box.textContent;
+  }
+
+  /** 收起错误行（重试时先清掉，避免旧错误杵在那儿） */
+  function clearAlert() {
+    const box = q('[data-role="alert"]');
+    if (!box) return;
+    box.textContent = '';
+    box.hidden = true;
+  }
+
+  /** 打开面板（默认从上次目录或 / 开始） */
+  function open(startPath) {
+    ensureShell();
+    panel.hidden = false;
+    pickedPath = '';
+    currentPath = startPath || lastDir() || '/';
+    const nameInput = q('[data-role="name"]');
+    if (nameInput) nameInput.value = '';
+    renderBody();
+    return panel;
+  }
+
+  /** 关闭并销毁（不留隐藏容器） */
+  function close() {
+    if (!panel) return;
+    panel.remove();
+    panel = null;
+  }
+
+  return {
+    open, close,
+    /** 只读：当前浏览路径 / 已选路径（断言用） */
+    get state() { return { open: !!panel, currentPath, pickedPath }; },
+    /** 断言用：直接设定路径后重绘（等价于用户一路点进来） */
+    goto(path) { currentPath = path; return panel ? renderBody() : null; },
+  };
+}

package/src/web/app/entry-report.js

@@ -0,0 +1,71 @@
+// app/entry-report.js —— 装载结果上报（契约《条目状态与展示归属》§三 的前端侧）
+//
+// 为什么要有这一层：装载成功/失败都必须写进服务端的条目状态，并且**立刻**把那一行画对。
+//   服务端的 POST /api/entries/result 是"写读一体"的：响应里就带回重算后的
+//   display/support/loadResult。所以这里一次请求同时完成两件事，不需要再拉 /api/catalog
+//   （那是秒级扫描，为一行颜色付这个代价是浪费，而且刚解包时它未必已经能看到）。
+//
+// 旁路原则（契约 INV-D3）：上报失败**绝不能**影响装载结果 —— 所有异常在这里吞掉只记日志。
+import { postJson } from '../infra/api.js';
+import { stageLog } from './status.js';
+import { state } from './context.js';
+
+/**
+ * 条目的状态键：与 VFS 前缀同构，`${rootId}/${rel}`。
+ *
+ * 为什么不用条目 id：容器 id 是 `bundle-<rootId>-<rel 把 / 换成 _>` 派生的，**不可逆**，
+ *   不同 rel 可能撞成同一个键；而 rootId/rel 是解包与存储都天然认得的形态。
+ * @param {object} model 名册条目
+ * @returns {string} 空串 = 这个条目没有可用的键（调用方应跳过上报）
+ */
+export function entryStateKey(model) {
+  const rootId = String((model && model.rootId) || '');
+  const rel = String((model && (model.rel || model.srcDir || model.name)) || '');
+  if (!rootId || !rel) return '';
+  return `${rootId}/${rel}`;
+}
+
+/**
+ * 上报一次装载结果，并用响应就地更新名册那一行。
+ *
+ * @param {object} model 名册条目
+ * @param {{result: 'ok'|'failed', reason?: string|null, message?: string|null,
+ *          provider?: string|null}} outcome 结果（reason 用契约码，message 是人话）
+ * @returns {Promise<object|null>} 服务端重算后的三字段；失败/未上报返回 null
+ */
+export async function reportEntryResult(model, outcome) {
+  const key = entryStateKey(model);
+  if (!key) return null;
+  const body = {
+    key,
+    result: outcome.result === 'ok' ? 'ok' : 'failed',
+    reason: outcome.reason || null,
+    message: outcome.message || null,
+    provider: outcome.provider || null,
+    size: Number.isFinite(model && model.size) ? Number(model.size) : undefined,
+    source: 'client',
+  };
+  try {
+    const res = await postJson('/api/entries/result', body, { retries: 0 });
+    const computed = res && res.entry ? res.entry : null;
+    if (computed) {
+      // 必须走名册的写回入口，不能只刷 DOM：
+      //   传进来的 model 是 normalizeEntry 的**副本**（`{ ...entry }`），
+      //   改它不会影响名册渲染用的那个对象 ⇒ 下一次 render 就读回旧值，
+      //   表现为"当场变了色、一切换/搜索就掉回中性色"（实测的老 bug）。
+      //   setEntryState 按 id 找到名册持有的原对象、写回三字段，再重画那一行。
+      const roster = state.roster;
+      const id = String((model && (model.id || model.name)) || '');
+      try {
+        if (roster && typeof roster.setEntryState === 'function' && id) roster.setEntryState(id, computed);
+      } catch { /* 名册刷新失败不影响装载，也不影响已写入的服务端状态 */ }
+    }
+    return computed;
+  } catch (e) {
+    // 旁路：上报失败只记一条 info，绝不升级成装载失败
+    try {
+      stageLog('info', `装载结果未上报（${(e && e.message) || e}）：${key}`, { key, result: body.result });
+    } catch { /* 日志失败也不影响 */ }
+    return null;
+  }
+}

package/src/web/app/memory-bars.js

@@ -0,0 +1,91 @@
+// app/memory-bars.js —— 内存三色条的两个挂载点（舞台顶部 / 设置面板）统一管理
+//
+// 为什么要这一层：面板会重建、舞台容器常在，两处各有自己的生命周期。
+//   组件本身（panel/memory-bar.js）只管"画一条"；谁该在什么时候拉数据、要不要显示，
+//   集中在这么一个小模块里，免得散落到 model-actions / panel-settings / shell-controls 各处。
+//
+// 刷新时机（事件驱动，无定时器）：
+//   · 模型加载成功后          → refreshStage()
+//   · 面板重建（展开设置时）  → refreshPanel()
+//   · 「显示状态信息」开关    → setStageVisible()（关掉时舞台那条跟着消失，与状态行同策略）
+
+import { mountMemoryBar } from '../panel/memory-bar.js';
+
+/** 舞台顶部那条（容器在 index.html 里） */
+const stageBar = mountMemoryBar('#mem-bar-stage');
+
+/** 设置面板里那条（容器由 schema 的 ctl-memory-bar 提供） */
+const panelBar = mountMemoryBar('#right-panel [data-ctl="ctl-memory-bar"]');
+
+/** 舞台那条是否允许显示（跟「显示状态信息」开关走，默认开） */
+let stageVisible = true;
+
+/**
+ * 刷新舞台顶部那条（模型加载成功后调用）。
+ * @returns {Promise<boolean>} 是否显示成功
+ */
+export async function refreshStage() {
+  if (!stageVisible) { stageBar.hide(); return false; }
+  return stageBar.refresh();
+}
+
+/**
+ * 刷新设置面板那条（面板重建后调用）。
+ * @returns {Promise<boolean>}
+ */
+export async function refreshPanel() {
+  return panelBar.refresh();
+}
+
+/**
+ * 「显示状态信息」开关联动：关掉时舞台那条立即隐藏（不拉数据、不留空壳）。
+ * @param {boolean} on
+ */
+export function setStageVisible(on) {
+  stageVisible = on !== false;
+  if (!stageVisible) { stageBar.hide(); return; }
+  // 打开时补拉一次（此刻可能还没有数据）
+  refreshStage().catch(() => { /* 失败已由组件内部记 warn 并隐藏 */ });
+}
+
+/**
+ * 绑定「展开设置面板 → 拉一次」（文档 §五）。
+ * 面板重建时也会调 refreshPanel，但"点开设置组"不重建面板 ⇒ 单独绑点击。
+ * 幂等：只绑一次。
+ * @returns {boolean} 本次是否新绑定
+ */
+let bound = false;
+export function bindPanelBarRefresh() {
+  if (bound) return false;
+  bound = true;
+  document.addEventListener('click', (ev) => {
+    const trigger = ev.target && typeof ev.target.closest === 'function'
+      ? ev.target.closest('#right-panel .acc-trigger')
+      : null;
+    if (!trigger) return;
+    const label = (trigger.textContent || '').trim();
+    // 只关心「设置」组：其它组与内存无关，不必拉数据
+    if (!label.includes('设置')) return;
+    refreshPanel().catch(() => { /* 失败已由组件记 warn 并隐藏 */ });
+  }, true);
+  return true;
+}
+
+/** 供断言：两处当前显示的数值（无数据返回 null） */
+export function memoryBarSnapshot() {
+  const read = (sel) => {
+    const bar = document.querySelector(sel);
+    if (!bar || bar.hidden) return null;
+    return {
+      aria: bar.getAttribute('aria-label'),
+      text: (bar.querySelector('.mem-bar-text') || {}).textContent || '',
+      pct: {
+        server: bar.dataset.pctServer, other: bar.dataset.pctOther, avail: bar.dataset.pctAvail,
+      },
+    };
+  };
+  return {
+    stage: read('#mem-bar-stage .mem-bar'),
+    panel: read('#right-panel [data-ctl="ctl-memory-bar"] .mem-bar'),
+  };
+}

package/src/web/app/memory-budget.js

@@ -0,0 +1,228 @@
+// app/memory-budget.js —— 内存判据的**唯一决策入口**（策略层）
+//
+// 为什么要有这一层：项目里曾经同时存在三处"防内存打爆"的判断，各写各的
+//   ① capacity.mjs 用「可用内存 × 0.5 vs 预估峰值」——有权威翻译器、受开关控、文案带数字
+//   ② memory-guard.js 用「JS 堆 85%」——受开关控
+//   ③ plugin-host.js 用「裸包字节 > 512MB 硬编码」——不受开关控、文案丢数字、更不看内存余量
+//   同一个包在 8GB 机器上没事、在 2GB 机器上必炸，第③处却一视同仁地拦。
+//   所以这里把"能不能做"收成一个函数，谁要判断都问它。
+//
+// 🔴 铁律：**前端不自己算倍数**。
+//   「包字节 → 预估峰值」的权威实现只有服务端 capacity.mjs 的 estimatePeakMb（三档实测上包络），
+//   前端自己写 bytes*20 之类的倍数 = 又造一个新口径，正是本任务要消灭的东西。
+//
+// 数据源分工（不许越界）：
+//   · 服务端内存：只能从 GET /api/unpack/capacity 拿（浏览器里读不到系统内存）
+//   · 前端堆占用：只能从浏览器 performance.memory 拿（服务端读不到）
+
+import { memStats } from '../infra/mem-stats.js';
+import { stageLog } from './status.js';
+
+/**
+ * 前端堆占用阈值（路径 B / C 与 assess 共用**同一个**值）。
+ * 为什么放在这里：判据口径只允许有一份，memory-guard 从这里 import ——
+ *   两边各写一个 0.85 就是新一轮"同一事实两处表达"，迟早漂移。
+ *
+ * 缺省 0.85；服务端可用 **MODELSTAGE_ADMIT_HEAP_RATIO** 覆盖，
+ *   经 `GET /api/web-config` 的 `admitHeapRatio` 下发到前端（前端读不到 env）。
+ * 这里用 `let` 而不是 const：下发值要在启动后覆盖缺省，而 import 方拿到的是**活绑定**，
+ *   memory-guard 里那些 `h.pct > HEAP_RATIO` 无需改动就会看到新值。
+ */
+export let HEAP_RATIO = 0.85;
+/** 缺省值（下发值缺失/非法时回落到它；也是文档里写的那个数） */
+export const DEFAULT_HEAP_RATIO = 0.85;
+
+/**
+ * 应用服务端下发的准入配置（幂等；非法值回落缺省并 warn 一次）。
+ * @param {{admitHeapRatio?: number}} cfg /api/web-config 的响应
+ * @returns {{ratio: number, applied: boolean}}
+ */
+export function applyAdmitConfig(cfg) {
+  if (!cfg || cfg.admitHeapRatio === undefined || cfg.admitHeapRatio === null) {
+    return { ratio: HEAP_RATIO, applied: false };
+  }
+  const v = Number(cfg.admitHeapRatio);
+  const ok = Number.isFinite(v) && v > 0 && v <= 1;
+  if (!ok) {
+    // 不静默：下发值非法时说明白用的是哪个数，否则"为什么阈值没变"只能靠猜
+    try { stageLog('warn', `准入堆比例下发值非法（${JSON.stringify(cfg.admitHeapRatio)}）—— 继续用 ${HEAP_RATIO}`); } catch { /* 日志失败不影响判据 */ }
+    return { ratio: HEAP_RATIO, applied: false };
+  }
+  HEAP_RATIO = v;
+  try { stageLog('info', `准入堆比例已按服务端下发调整：${v}`); } catch { /* 同上 */ }
+  return { ratio: HEAP_RATIO, applied: true };
+}
+
+/** 服务端判据缓存时长：同一个包在短时间内反复判断不该每次都打服务端 */
+const CAP_TTL_MS = 5000;
+
+/** 开关状态镜像（由 memory-guard.setMemoryGuard 同步过来，避免两层互相 import 成环） */
+let guardEnabled = true;
+
+/** 缓存：key = 包 MB（取整）/ 'machine' → { at, value } */
+const capCache = new Map();
+
+/** 实际发起过的服务端请求次数（验收"缓存生效"用） */
+let fetchCount = 0;
+
+/**
+ * 同步"内存保护开关"状态。memory-guard.setMemoryGuard 里会调它。
+ * @param {boolean} on
+ */
+export function setBudgetGuardEnabled(on) {
+  guardEnabled = on !== false;
+}
+
+/** @returns {boolean} 当前是否受开关约束 */
+export function isBudgetGuardEnabled() {
+  return guardEnabled;
+}
+
+/**
+ * 取服务端判据（带 5 秒缓存）。
+ * @param {number} sourceMb 包大小（MB）；0/缺省 ⇒ 只问机器级信息
+ * @returns {Promise<object|null>} 拿不到返回 null（调用方按"这一路不可用"处理）
+ */
+async function fetchServerJudgement(sourceMb) {
+  const key = sourceMb > 0 ? String(Math.round(sourceMb)) : 'machine';
+  const hit = capCache.get(key);
+  if (hit && Date.now() - hit.at < CAP_TTL_MS) return hit.value;
+  const qs = sourceMb > 0 ? `?sourceMb=${encodeURIComponent(sourceMb)}` : '';
+  try {
+    fetchCount += 1;
+    const res = await fetch(`/api/unpack/capacity${qs}`, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const j = await res.json();
+    capCache.set(key, { at: Date.now(), value: j });
+    return j;
+  } catch (err) {
+    stageLog('warn', `内存判据取不到服务端数据：${String((err && err.message) || err)}`, { sourceMb });
+    return null;
+  }
+}
+
+/** 读前端堆占用（不可用返回 null，不瞎估） */
+function heapStats() {
+  try {
+    const s = memStats();
+    if (s.jsHeapPct === null || s.jsHeapPct === undefined) return null;
+    return { pct: s.jsHeapPct, usedMB: s.jsHeapMB, limitMB: s.jsHeapLimitMB };
+  } catch {
+    return null;
+  }
+}
+
+/** 百分比显示：不足 1% 写成 <1%（写 0% 会让人以为没数据） */
+function pctText(pct) {
+  return pct < 0.01 ? '<1' : String(Math.round(pct * 100));
+}
+
+/**
+ * 统一决策：这次操作能不能做。
+ *
+ * 判据取**更严格的一路**（任一路不通过即不通过）；两路都拿不到 ⇒ **放行 + 记日志**
+ *   —— 拿不到真值时不假装保护，否则会变成"在某些浏览器上永远加载不了"。
+ *
+ * @param {object} opts
+ * @param {number} [opts.bytesHint] 已知的包字节数（能算出预估峰值）
+ * @param {'web-load'|'web-unpack'|'web-long-op'} [opts.where] 调用场景（只影响文案与默认策略）
+ * @param {string} [opts.label] 对象名（写进文案，让用户知道是哪一步被拦）
+ * @returns {Promise<{ok:boolean, reason:string, numbers:object, message:string}>}
+ *   numbers: { pkgBytes, peakEstMb, budgetMb, availMb, heapPct, usedMB, limitMB }
+ */
+export async function assess(opts = {}) {
+  const where = opts.where || 'web-load';
+  const label = String(opts.label || '').trim();
+  const bytes = Number(opts.bytesHint) > 0 ? Number(opts.bytesHint) : 0;
+  const numbers = {
+    pkgBytes: bytes || null,
+    peakEstMb: null,
+    budgetMb: null,
+    availMb: null,
+    heapPct: null,
+    usedMB: null,
+    limitMB: null,
+  };
+
+  if (!guardEnabled) {
+    // 开关关闭：**连绝对兜底也不拦**（用户明示要试）
+    return { ok: true, reason: 'guard-off', numbers, message: '' };
+  }
+
+  // 路 A｜服务端：包字节 → 预估峰值 / 预算 / 可用
+  const srv = await fetchServerJudgement(bytes > 0 ? bytes / 1024 / 1024 : 0);
+  const heap = heapStats();
+  let serverJudged = false;
+  let serverFails = false;
+  let serverDetail = '';
+  if (srv && Number.isFinite(srv.peakEstMb) && Number.isFinite(srv.budgetMb)) {
+    serverJudged = true;
+    numbers.peakEstMb = srv.peakEstMb;
+    numbers.budgetMb = srv.budgetMb;
+    numbers.availMb = Number.isFinite(srv.memAvailableMb) ? srv.memAvailableMb : null;
+    if (srv.peakEstMb > srv.budgetMb) {
+      serverFails = true;
+      serverDetail = `预估峰值 ${srv.peakEstMb}MB 超过可用预算 ${srv.budgetMb}MB（当前可用 ${numbers.availMb}MB × 0.5）`;
+    }
+  }
+  if (heap) {
+    numbers.heapPct = heap.pct;
+    numbers.usedMB = heap.usedMB;
+    numbers.limitMB = heap.limitMB;
+  }
+
+  // 两路都拿不到 ⇒ 放行 + 记日志（不假装保护）
+  if (!serverJudged && !heap) {
+    stageLog('warn', `内存判据两路都不可用，放行（${where}${label ? ` · ${label}` : ''}）`, { where, bytes });
+    return { ok: true, reason: 'unjudgeable', numbers, message: '' };
+  }
+
+  const heapFails = !!(heap && heap.pct > HEAP_RATIO);
+  if (serverFails || heapFails) {
+    return {
+      ok: false,
+      reason: serverFails ? 'insufficient-memory' : 'heap-high',
+      numbers,
+      message: buildMessage({ where, label, serverFails, heapFails, serverDetail, numbers }),
+    };
+  }
+  return { ok: true, reason: 'ok', numbers, message: '' };
+}
+
+/**
+ * 统一文案模板（三处同一套格式）：`无法<动作>「<对象>」：<判据含真实数字>。<能怎么办>`
+ *
+ * 为什么必须带数字：只说"内存不足/文件过大"，用户无法判断该关标签页、拆包还是换机器。
+ * @returns {string}
+ */
+export function buildMessage({ where, label, serverFails, heapFails, serverDetail, numbers }) {
+  const obj = label ? `「${label}」` : '';
+  const verb = where === 'web-unpack' ? '解包' : (where === 'web-long-op' ? '继续' : '加载');
+  const parts = [];
+  if (serverFails && serverDetail) parts.push(serverDetail);
+  if (heapFails && numbers.heapPct !== null) {
+    parts.push(`内存占用较高（${numbers.usedMB} MB / ${numbers.limitMB} MB，${pctText(numbers.heapPct)}%）`);
+  }
+  const why = parts.join('；');
+  const advice = where === 'web-unpack'
+    ? '可先关闭其他程序，或改用更小的包。'
+    : (where === 'web-long-op'
+      ? '已完成的文件保留，可稍后重试剩余部分。'
+      : '请关闭其他标签页后重试。');
+  return `无法${verb}${obj}：${why}。${advice}`;
+}
+
+/** 验收用：已发起的服务端判据请求次数 */
+export function budgetStats() {
+  return { fetchCount, cachedKeys: [...capCache.keys()] };
+}
+
+/** 供测试重置 */
+export function __resetMemoryBudgetForTest() {
+  capCache.clear();
+  fetchCount = 0;
+  guardEnabled = true;
+}