modelstage 0.5.28 → 0.6.1

package/src/web/infra/ready.js

@@ -38,6 +38,11 @@ import { fetchWithRetry } from './api.js';
 //   又不会让就绪信号明显滞后。
 const FLUSH_DEBOUNCE_MS = 400;
 
+/** 轮询超时记录的保留条数（环形）：只留最近若干条，长时间运行不堆积 */
+const TRACK_STOP_KEEP = 20;
+/** 同一阶段同一结局的告警限频（ms）：换模型可能反复超时，不能让同一句话刷屏 */
+const TRACK_WARN_WINDOW_MS = 10000;
+
 const st = {
   stages: {},          // stage → { state, at, detail?, reason? }
   rev: 0,              // 本地 rev（服务端才是权威；这里供 __WEB__.ready() 立即可读）
@@ -50,6 +55,11 @@ const st = {
   fails: 0,            // 上报失败次数（限频记日志，不刷屏）
   lastFailAt: 0,
   lastFail: null,   // {at,name,msg,attempts}：一次失败就能看出是网络层还是超时（排障唯一途径）
+  // 轮询跟踪的"结束记录"（环形，最近 TRACK_STOP_KEEP 条）：
+  //   超时不再静默——每条都留下 阶段 / 等多久 / 最后观测到什么 / 属于哪种结局，
+  //   由 stats().trackStops 暴露（与 lastFail 同一条诊断面，不新造日志体系）。
+  trackStops: [],
+  trackWarnAt: new Map(),   // `${stage}:${outcome}` → 上次告警时间（限频用）
 };
 
 /**
@@ -140,7 +150,12 @@ export function resetStages(names, opts) {
  *   上报次数 / 待发条数 / 本地 rev / 因 in-flight 被跳过的次数 / 失败次数 / 是否在飞
  */
 export function stats() {
-  return { flushes: st.flushes, pending: st.pending.size, rev: st.rev, dropped: st.dropped, fails: st.fails, inflight: st.inflight, lastFail: st.lastFail };
+  return {
+    flushes: st.flushes, pending: st.pending.size, rev: st.rev, dropped: st.dropped, fails: st.fails,
+    inflight: st.inflight, lastFail: st.lastFail,
+    // 轮询跟踪的结束记录（含超时与外部取消）：排障时先看这里，再看阶段本身
+    trackStops: st.trackStops.slice()
+  };
 }
 
 /** 页面内直读快照（契约 §5.1）：ready() 全量，ready('model') 单阶段 */
@@ -210,8 +225,9 @@ function flush(opts) {
   };
   try {
     if (keepalive) {
-      // 卸载前：**不重试**（页面已经在走，没时间退避），keepalive 保证尽力送达
-      fetch('/api/ready', { method: 'POST', headers, body: payload, keepalive: true, signal: AbortSignal.timeout(5000) })
+      // 卸载前：**不重试**（页面已经在走，没时间退避），keepalive 保证尽力送达。
+      //   不设时限：页面卸载时浏览器自己会掐断。
+      fetch('/api/ready', { method: 'POST', headers, body: payload, keepalive: true })
         .catch((e) => onFail(e, 1))
         .finally(() => { st.inflight = false; });
     } else {
@@ -250,6 +266,41 @@ export function flushNow() {
   flush({ keepalive: true });
 }
 
+/**
+ * 记录一次"跟踪结束"（超时 / 外部取消），并做限频告警。
+ *
+ * 为什么必须分三种结局（混成一句"超时"会把排错方向带偏）：
+ *   · 'no-observation' —— 全程**没有任何观测**（未挂载、帧数恒 0、元素始终不存在）⇒ 这才是真的"没来"
+ *   · 'not-interactive' —— 有观测但没到 interactive 门槛（已 painted/settled、动作数 0 等）⇒ "到了但不够"
+ *   · 'cancelled' —— 被调用方主动 stop() 取消 ⇒ **不是超时**，不告警、绝不判失败
+ *
+ * 落点选择：本模块与 diag 分离是既定契约（见文件头），所以这里不发明新日志，
+ *   而是把记录挂到**既有诊断面** stats() 上（页面侧 `__WEB__.readyStats()` 可读），
+ *   并配一条限频 console.warn 给看控制台的人。
+ *
+ * @param {{stage:string, outcome:'no-observation'|'not-interactive'|'cancelled',
+ *          waitedMs:number, timeoutMs:number, state:string|null, last:object}} rec
+ */
+function recordTrackStop(rec) {
+  const entry = { at: Date.now(), ...rec };
+  st.trackStops.push(entry);
+  if (st.trackStops.length > TRACK_STOP_KEEP) st.trackStops.shift();
+  if (entry.outcome === 'cancelled') return entry;   // 外部取消：不是异常，保持安静
+  const key = `${entry.stage}:${entry.outcome}`;
+  const lastAt = st.trackWarnAt.get(key) || 0;
+  const now = entry.at;
+  if (now - lastAt > TRACK_WARN_WINDOW_MS) {
+    st.trackWarnAt.set(key, now);
+    try {
+      if (typeof console !== 'undefined' && console.warn) {
+        console.warn(`[ready] ${entry.stage} 阶段 ${entry.waitedMs}ms 未达 interactive（${entry.outcome}）`
+          + `：当前 ${entry.state || 'pending'}，最后观测 ${JSON.stringify(entry.last || {})}`);
+      }
+    } catch { /* 忽略 */ }
+  }
+  return entry;
+}
+
 /**
  * 跟踪「模型」阶段的三级状态（契约 §2.2）。
  *
@@ -265,57 +316,57 @@ export function trackModelStage(opts) {
   const { kind, id, canvas, getFrames, getActions } = opts || {};
   const timeoutMs = Number(opts && opts.timeoutMs) || 8000;
   const t0 = Date.now();
-  let stopped = false;
   const base = { kind: kind || null, id: id || null };
   // 换模型（或第一次装载）时重新起算 model 阶段：
   //   否则上一轮的 interactive 会被新模型继承，"等 painted"在新模型上永远不会重新发生。
   const prevId = st.stages.model && st.stages.model.detail ? st.stages.model.detail.id : null;
   if (prevId !== base.id) resetStage('model');
 
-  const mountedNow = () => {
-    const el = canvas || null;
-    if (!el || el.isConnected !== true) return false;
-    const w = Math.max(el.width || 0, el.clientWidth || 0);
-    const h = Math.max(el.height || 0, el.clientHeight || 0);
-    return w > 0 && h > 0;
-  };
-  const frames = () => {
-    try { return Number(getFrames && getFrames()) || 0; } catch { return 0; }
-  };
-  const actions = () => {
-    try { return Number(getActions && getActions()) || 0; } catch { return 0; }
-  };
+  const mountedNow = () => canvasMounted(canvas);
+  const frames = () => safeCount(getFrames);
+  const actions = () => safeCount(getActions);
 
   // 严格按 mounted → painted → interactive 推进（契约 §2.2）：
   //   interactive 不得越过 painted —— 动作清单在装载完成瞬间就可能非空，
   //   若不拦住，会在"一帧都还没画"时报 interactive，等于把分级做成了摆设。
   let painted = false;
+  // 最后一次观测到的值：超时时它是"卡在哪一步"的唯一证据（帧数/动作数/是否挂载）
+  const lastSeen = { mounted: false, frames: 0, actions: 0 };
+  // 收尾：done=正常达标 / timeout=等到了上限 / cancelled=被调用方主动取消。
+  //   判失败的条件 = 全无观测 **且** 阶段还没到 painted（模型画布不该缺席，所以允许判失败）。
+  const finisher = createTrackFinisher({
+    stage: 'model', t0, timeoutMs,
+    last: () => ({ ...base, ...lastSeen, painted }),
+    currentState: () => (st.stages.model ? st.stages.model.state : null),
+    allowFail: () => (RANK[st.stages.model ? st.stages.model.state : null] || 0) < RANK.painted,
+    failDetail: () => ({ ...base, ...lastSeen }),
+    failReason: (waitedMs) => `模型 ${timeoutMs}ms 内无任何观测（画布未挂载 / 已绘帧数 0；已等 ${waitedMs}ms）`,
+  });
+  const finish = finisher.finish;
+  const isStopped = finisher.isStopped;
   const tick = () => {
-    if (stopped) return;
-    if (mountedNow()) markStage('model', 'mounted', { ...base });
+    if (isStopped()) return;
+      lastSeen.mounted = mountedNow();
+    if (lastSeen.mounted) markStage('model', 'mounted', { ...base });
     const f = frames();
+    lastSeen.frames = f;
     if (!painted && f >= 1) {
       painted = true;
       markStage('model', 'painted', { ...base, frames: f });
     }
     const a = actions();
+    lastSeen.actions = a;
     if (painted && a > 0) {
       markStage('model', 'interactive', { ...base, frames: f, actions: a });
-      stop();
+      finish('done');
       return;
     }
-    if (Date.now() - t0 > timeoutMs) { stop(); return; }
+    if (Date.now() - t0 > timeoutMs) { finish('timeout'); return; }
     setTimeout(tick, MODEL_POLL_MS);
   };
 
-  function stop() {
-    if (stopped) return;
-    stopped = true;
-    scheduleFlush(); // 走合并窗口：装载完成会连标多个阶段，立刻发会撞上模型文件的连接占用
-  }
-
   tick();
-  return stop;
+  return () => finish('cancelled');
 }
 
 /**
@@ -342,6 +393,52 @@ function safeProbe(fn) {
   }
 }
 
+/**
+ * 造一个"跟踪收尾器"：三个 track* 共用的结局记录逻辑。
+ *
+ * 抽出来的原因：三段代码的收尾几乎一样（记录 → 是否判失败 → 合并上报），
+ *   分开写会让每个 track 函数都超出单函数代码行上限，而且三处判断容易走偏。
+ *
+ * @param {{stage:string, t0:number, timeoutMs:number, last:()=>object,
+ *          currentState:()=>string|null, allowFail:()=>boolean,
+ *          failDetail:()=>object, failReason:(waitedMs:number)=>string}} spec
+ * @returns {{finish:(kind:'done'|'timeout'|'cancelled')=>void, isStopped:()=>boolean}}
+ */
+function createTrackFinisher(spec) {
+  let stopped = false;
+  const finish = (kind) => {
+    if (stopped) return;
+    stopped = true;
+    if (kind !== 'done') {
+      const waitedMs = Date.now() - spec.t0;
+      const stateNow = spec.currentState();
+      const last = spec.last();
+      const observed = last && (last.connected === true || last.mounted === true
+        || Number(last.frames) > 0 || Number(last.actions) > 0 || last.seen === true);
+      const outcome = kind === 'cancelled' ? 'cancelled' : (observed ? 'not-interactive' : 'no-observation');
+      // 只记录，不判死：这里等的是"画布自己走到 interactive"，没有任何事件可以订阅，
+      //   所以只能轮询；但轮询的结论只能是"观测到多少"，不能是"失败"——
+      //   慢（机器忙、资源大）不等于坏。真要判失败只有一种情形：调用方明确要求（allowFail）。
+      recordTrackStop({ stage: spec.stage, outcome, waitedMs, timeoutMs: spec.timeoutMs, state: stateNow, last });
+    }
+    scheduleFlush();
+  };
+  return { finish, isStopped: () => stopped };
+}
+
+/** 画布是否已挂载且有非零尺寸（模型阶段 mounted 的判据：detached/0 尺寸都不算挂上） */
+function canvasMounted(canvas) {
+  if (!canvas || canvas.isConnected !== true) return false;
+  const w = Math.max(canvas.width || 0, canvas.clientWidth || 0);
+  const h = Math.max(canvas.height || 0, canvas.clientHeight || 0);
+  return w > 0 && h > 0;
+}
+
+/** 读一个计数型探针（抛错按 0 处理：探针异常不能把跟踪器带崩） */
+function safeCount(read) {
+  try { return Number(read && read()) || 0; } catch { return 0; }
+}
+
 /** 元素当前包围盒的紧凑表示（两次采样相等 ⇒ 布局稳定） */
 function boxOf(node) {
   try {
@@ -371,21 +468,36 @@ export function trackElementStage(opts) {
   const { name, el } = opts || {};
   const timeoutMs = Number(opts && opts.timeoutMs) || 8000;
   const t0 = Date.now();
-  let stopped = false;
   let prevBox = null;
   let stableHits = 0;
+  // 最后观测：元素是否在文档里、包围盒、是否有动画、是否被挡住、探针结论
+  const lastSeen = { connected: false, box: null, animating: null, blocked: null, probeOk: null };
 
-  const stop = () => { if (!stopped) { stopped = true; scheduleFlush(); } };
+  // DOM 阶段默认**不判失败**：元素不存在可能是正常配置（如未开调试日志时的调试面板），
+  //   把它标成失败是另一种撒谎；只留可归因记录。调用方要"缺席即失败"时显式传 failOnNoObservation。
+  const finisher = createTrackFinisher({
+    stage: name, t0, timeoutMs,
+    last: () => ({ ...(opts && opts.detail ? opts.detail : {}), ...lastSeen }),
+    currentState: () => (st.stages[name] ? st.stages[name].state : null),
+    allowFail: () => opts && opts.failOnNoObservation === true
+      && (RANK[st.stages[name] ? st.stages[name].state : null] || 0) < RANK.mounted,
+    failDetail: () => ({ ...(opts && opts.detail ? opts.detail : {}), ...lastSeen }),
+    failReason: (waitedMs) => `${timeoutMs}ms 内元素未挂载（${name}；已等 ${waitedMs}ms）`,
+  });
+  const { finish, isStopped } = finisher;
 
   const tick = () => {
-    if (stopped) return;
+    if (isStopped()) return;
+    lastSeen.connected = !!(el && el.isConnected === true);
     if (!el || el.isConnected !== true) {
-      if (Date.now() - t0 > timeoutMs) stop(); else setTimeout(tick, 80);
+      if (Date.now() - t0 > timeoutMs) finish('timeout'); else setTimeout(tick, 80);
       return;
     }
     markStage(name, 'mounted', opts && opts.detail ? { ...opts.detail } : null);
     const box = boxOf(el);
     const busy = animating(el);
+    lastSeen.box = box;
+    lastSeen.animating = busy;
     if (!busy && box && box === prevBox) stableHits += 1; else stableHits = 0;
     prevBox = box;
     // 连续两次采样都稳定且无动画 ⇒ 视为布局/动画稳定
@@ -394,17 +506,19 @@ export function trackElementStage(opts) {
       // interactive 可在通用判据之外再加该阶段自己的条件（如"声明内的控件都构建了"）：
       //   探针返回 {ok, detail}；不 ok 就继续等，绝不为了"报绿"放宽。
       const probe = opts && typeof opts.interactiveProbe === 'function' ? safeProbe(opts.interactiveProbe) : { ok: true, detail: {} };
-      if (!blocked(el) && probe.ok) {
+      lastSeen.probeOk = probe.ok;
+      lastSeen.blocked = blocked(el);
+      if (!lastSeen.blocked && probe.ok) {
         markStage(name, 'interactive', { ...(opts && opts.detail ? opts.detail : {}), ...(probe.detail || {}), box });
-        stop();
+        finish('done');
         return;
       }
     }
-    if (Date.now() - t0 > timeoutMs) { stop(); return; }
+    if (Date.now() - t0 > timeoutMs) { finish('timeout'); return; }
     setTimeout(tick, ELEMENT_POLL_MS);
   };
   tick();
-  return stop;
+  return () => finish('cancelled');
 }
 
 /**
@@ -418,15 +532,39 @@ export function trackElementWhenReady(opts) {
   const t0 = Date.now();
   let inner = null;
   let stopped = false;
+  // 元素是否曾经出现过：没出现过 = 'no-observation'（连跟踪都没开始），
+  //   出现过则由内层 trackElementStage 自己记录（它才知道卡在哪一步）。
+  let seen = false;
+
+  const finish = (kind) => {
+    if (stopped) return;
+    stopped = true;
+    if (inner) { inner(); return; }   // 交给内层收尾（它会记录自己那份）
+    if (kind !== 'done') {
+      const stateNow = st.stages[name] ? st.stages[name].state : null;
+      const outcome = kind === 'cancelled' ? 'cancelled' : (seen ? 'not-interactive' : 'no-observation');
+      recordTrackStop({
+        stage: name, outcome, waitedMs: Date.now() - t0, timeoutMs, state: stateNow,
+        last: { selector, seen },
+      });
+      if (outcome === 'no-observation' && opts && opts.failOnNoObservation === true
+        && (RANK[stateNow] || 0) < RANK.mounted) {
+        markStage(name, 'failed', { ...(opts.detail || {}), selector, waitedMs: Date.now() - t0 },
+          `${timeoutMs}ms 内未找到元素 ${selector}（${name}）`);
+      }
+    }
+    scheduleFlush();
+  };
+
   const tryStart = () => {
     if (stopped || inner) return;
     const el = document.querySelector(selector);
-    if (el) { inner = trackElementStage({ ...opts, name, el }); return; }
-    if (Date.now() - t0 > timeoutMs) { stopped = true; return; }
+    if (el) { seen = true; inner = trackElementStage({ ...opts, name, el }); return; }
+    if (Date.now() - t0 > timeoutMs) { finish('timeout'); return; }
     setTimeout(tryStart, MODEL_POLL_MS);
   };
   tryStart();
-  return () => { stopped = true; if (inner) inner(); };
+  return () => { if (inner) { stopped = true; inner(); return; } finish('cancelled'); };
 }
 
 /** 标记模型阶段失败（带可读原因，测试可立即报错而不必等超时） */

package/src/web/live2d/bridge.js

@@ -229,7 +229,7 @@ function createLoadGroup(ctx, st, note) {
         // 换模型 = 换内容：清掉上一个模型的"当前动作"标签。
         //   为什么必须清：loadForEngine 的返回值会作为 info.motion 回传给应用层，
         //   而 fillTransportOptions 会把它当成"新模型要播的动作"。旧 label 若恰好同名
-        //   （碧蓝航线 live2d 的动作全叫 idle/home/…）⇒ 新模型真的会去播上一个模型选的那条。
+        //   ⇒ 新模型真的会去播上一个模型选的那条。
         st.currentLabel = '';
       } else {
         note(`Live2D 复用已加载模型：${model.name}`);

package/src/web/live2d/runtime-adapter.js

@@ -86,10 +86,8 @@ function pixiLib() {
  */
 async function readServerError(url) {
   try {
-    // 5s：这一步是在 <script> **已失败**之后补读一次响应体，结果会被 await 进 reject 之前，
-    //   所以它自己绝不能挂住 —— 否则"加载失败"永远不 reject，Live2D 激活会一直悬着。
-    //   5s 依据：服务端这条是纯本地 JSON（服务端已实测毫秒级返回），5s 只作兜底。
-    const r = await fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(5000) });
+    // 不设时限。调用方要放弃就传自己的 signal。
+    const r = await fetch(url, { cache: 'no-store' });
     const text = await r.text();
     try {
       const j = JSON.parse(text);

package/src/web/panel/panel-settings.js

@@ -261,7 +261,13 @@ const slotDeclaredDefaultById = new Map();
 
 const docFilesCache = new Map();
 const docFilesPending = new Set();
-const docFilesStats = { lists: 0, repaints: 0 };
+const docFilesStats = { lists: 0, repaints: 0, failures: 0 };
+/**
+ * 失败记录：key → { reason, at, timedOut }。
+ * 为什么单独存一份而不是只加计数：提示行要显示"哪一条、因为什么失败"，
+ *   而且重试成功后必须能把它清掉（只留计数会永远显示"失败过"）。
+ */
+const docFilesFailures = new Map();
 
 /**
  * 目录清单请求（/api/catalog）的超时上限（ms）。
@@ -277,7 +283,11 @@ const DOC_FILES_TIMEOUT_MS = 6000;
 function publishDocFilesStats() {
   try {
     if (typeof window === 'undefined') return;
-    window.__DOC_FILES__ = { lists: docFilesStats.lists, repaints: docFilesStats.repaints, cached: docFilesCache.size };
+    window.__DOC_FILES__ = {
+      lists: docFilesStats.lists, repaints: docFilesStats.repaints, cached: docFilesCache.size,
+      // 失败次数（只增）：用来回答"到底请求了多少次失败"这个排障问题；前三个键语义不变
+      failures: docFilesStats.failures,
+    };
   } catch { /* 无 window 忽略 */ }
 }
 
@@ -318,6 +328,8 @@ function docFilesKeyOf(model) {
  * @returns {string[]|null} 未就绪返回 null
  */
 function docFilesOf(model) {
+  // 每次读取都同步一次提示行：换文档、成功后、失败后三种状态下提示都不会残留/迟到
+  renderDocFilesHint(model);
   if (!model) return null;
   const key = docFilesKeyOf(model);
   if (docFilesCache.has(key)) return docFilesCache.get(key).slice();
@@ -358,6 +370,65 @@ function safeVfsList(prefix) {
  *   而 document 是 getter、必须同步出值 —— 所以这里"先记 pending、拿到再回填 + 重建一次"。
  * @param {object} model 条目 @param {string} key 缓存键
  */
+/**
+ * 清单失败时的**内联提示**（宿主自己的 UI，不弹 toast / 不弹 modal）。
+ *
+ * 位置与呈现：绝对定位叠加在右栏顶部（.panel 本身是 position:fixed，绝对定位相对它），
+ *   **不参与布局** ⇒ 提示出现/消失都不会挤动下方控件（这是刻意的：插一行会把整列控件往下推）。
+ * 文案区分"超时"与"其它失败"：前者用户知道"再点一次可能就好"，后者往往是服务端/网络问题。
+ */
+const DOC_FILES_HINT_ID = 'doc-files-retry';
+
+/** 失败原因 → 人话（超时/取消都是"没等到"，其余给通用文案，具体原因仍在日志里） */
+function docFilesFailText(reason) {
+  const text = String(reason || '');
+  if (/超时|Timeout|Abort/i.test(text)) return '清单获取失败（超时）';
+  return '清单获取失败';
+}
+
+/**
+ * 画/刷/藏 那一行提示（幂等：没有失败就移除，有失败就复用同一个节点）。
+ * @param {object|null} model 当前文档（用于重试时定位条目）
+ */
+function renderDocFilesHint(model) {
+  try {
+    const host = dom.panelBody && dom.panelBody.parentElement;   // 右栏 <aside class="panel">
+    if (!host) return;
+    const key = model ? docFilesKeyOf(model) : '';
+    const failure = key ? docFilesFailures.get(key) : null;
+    let node = document.getElementById(DOC_FILES_HINT_ID);
+    if (!failure) { if (node) node.remove(); return; }
+    if (!node) {
+      node = document.createElement('button');
+      node.id = DOC_FILES_HINT_ID;
+      node.type = 'button';
+      node.className = 'doc-files-hint';
+      host.appendChild(node);
+    }
+    node.textContent = `${docFilesFailText(failure.reason)} · 点击重试`;
+    node.title = `原因：${failure.reason}（不会再自动重试）`;
+    // 点击重试：清缓存/pending/失败记录后**复用同一条请求路径**（不新开请求链路）
+    node.onclick = () => { retryDocFiles(model); };
+  } catch { /* 提示是增强：任何一步失败都不影响面板 */ }
+}
+
+/**
+ * 点击重试：清掉该条目的缓存与 pending，再走 requestDocFiles。
+ *
+ * 为什么重试也要清缓存：失败路径本来就不写缓存，但"半截成功后又被判失败"这类情况
+ *   可能留下旧值；清掉能保证重试拿到的就是服务端当前结果。
+ * @param {object} model
+ */
+function retryDocFiles(model) {
+  if (!model) return;
+  const key = docFilesKeyOf(model);
+  docFilesFailures.delete(key);
+  docFilesCache.delete(key);
+  docFilesPending.delete(key);
+  renderDocFilesHint(model);
+  requestDocFiles(model, key);
+}
+
 function requestDocFiles(model, key) {
   if (docFilesPending.has(key)) return;
   docFilesPending.add(key);
@@ -385,7 +456,9 @@ function requestDocFiles(model, key) {
       if (!names.length) return;
       docFilesStats.lists += 1;
       docFilesCache.set(key, names);
+      docFilesFailures.delete(key);       // 成功即清失败态：提示行随之消失
       publishDocFilesStats();
+      renderDocFilesHint(model);
       // 清单就绪 ⇒ 面板重建一次，让插件的 render 拿到真实清单（与插件装载走同一条重建链）
       if (state.panel) {
         docFilesStats.repaints += 1;
@@ -402,6 +475,12 @@ function requestDocFiles(model, key) {
       stageLog('warn', `目录清单获取失败：${String(model.name || model.id || '')}（${reason}）——该条目文件列表保持为空，可再次触发重试`, {
         rootId: rawRootId, url, reason, timeoutMs: DOC_FILES_TIMEOUT_MS,
       });
+      // 用户可见性：把"失败了、可以再试"直接摆在文件区（面板顶部叠加一行），
+      //   **不做自动重试** —— 自动重试会把"服务端持续挂"伪装成"慢一点但能出来"。
+      docFilesFailures.set(key, { reason, at: Date.now(), timedOut });
+      docFilesStats.failures += 1;
+      publishDocFilesStats();
+      renderDocFilesHint(model);
     } finally {
       docFilesPending.delete(key);
     }
@@ -446,11 +525,17 @@ function slotPropsFor(entry) {
     get document() {
       const m = state.selectedModel;
       if (!m) return null;
+      const files = docFilesOf(m);
+      // filesError / retryFiles 与 files 同批给出：插件既能显示"为什么空"，也能自己接一个重试入口，
+      //   而不必猜宿主内部状态（两者都只是**读**与**复用**宿主已有请求路径，不新开链路）。
+      const failure = docFilesFailures.get(docFilesKeyOf(m)) || null;
       return {
         rootId: m.rootId ? String(m.rootId) : null,
         rel: m.rel ? String(m.rel) : null,
         kind: m.kind ? String(m.kind) : (m.container ? 'bundle' : null),
-        files: docFilesOf(m),
+        files,
+        filesError: failure ? String(failure.reason) : null,
+        retryFiles: () => retryDocFiles(m),
       };
     },
     /** 插件写设置也走面板同一条通道（校验 → 生效 → 落盘） */

package/src/web/roster/events.js

@@ -0,0 +1,159 @@
+// roster/events.js —— 名册的 DOM 事件层（从 view.js 原样搬出：监听目标、分派规则、文案一字不改）
+//
+// 负责什么：
+//   · 树行的事件委托（点击 + 键盘 Enter/空格，两者共用同一个 activate 分派）；
+//   · 类型胶囊（点击 / 清除）、游戏行「加载失败·重试」、扫描状态行〔重试〕；
+//   · 搜索框输入（含"首次输入补全量"）、「收起」按钮、用户滚动信号挂载。
+//
+// 不负责什么：DOM 结构与文案（render.js）、加载编排（load.js）、装配（view.js）。
+// 依赖方向（单向）：store ← load ← events ← view。
+//   load 提供"点开要加载"的动作，render 提供"改完重画"，本文件只做分派。
+
+import { saveState, saveLastModel } from './persist.js';
+
+/**
+ * @param {object} deps 全部由 view 注入
+ * @param {object} deps.store       名册 store（状态读写一律走它的动作）
+ * @param {HTMLElement} deps.listEl 名册列表容器（树行的委托挂在这里）
+ * @param {HTMLElement} deps.searchEl 搜索框
+ * @param {HTMLElement} deps.collapseBtn 「收起」按钮
+ * @param {HTMLElement|null} deps.typeFilterEl 类型胶囊行容器（null ⇒ 本功能整体不生效）
+ * @param {object} deps.reveal      定位控制器（挂用户滚动信号 + 选中后定位）
+ * @param {() => void} deps.render  立即整棵重绘
+ * @param {object} deps.load        加载编排（loadGroup / retryScan / ensureGroupLoaded / ensureAllLoaded）
+ * @param {Map} deps.modelById      modelId → { model, rootId }（选中后回调 onSelect 用）
+ * @param {Function} [deps.onSelect] 选中变体后的回调（装载由调用方负责）
+ */
+export function createRosterEvents({
+  store, listEl, searchEl, collapseBtn, typeFilterEl, reveal, render, load, modelById, onSelect,
+}) {
+  const state = store.state;
+
+  /** 点一级：折叠/展开游戏（首次展开触发该游戏所有根的数据加载） */
+  async function onGroupClick(groupKey) {
+    if (state.expandedGroups.has(groupKey)) {
+      store.toggleGroup(groupKey);
+      render();
+      saveState(state);
+      return;
+    }
+    store.expandGroup(groupKey);
+    // 先渲染一次：已加载过的游戏直接出角色行（ensureGroupLoaded 在无待加载根时不会单独渲染）
+    render();
+    const group = state.groups.find((g) => g.key === groupKey);
+    if (group) await load.ensureGroupLoaded(group);
+    saveState(state);
+  }
+
+  /** 点二级：折叠/展开角色（变体已在内存，不发请求） */
+  function onCharClick(charKey) {
+    store.toggleChar(charKey);
+    render();
+    saveState(state);
+  }
+
+  /** 点三级：选中变体（高亮 + 记录状态，M4 用它去渲染） */
+  function onVariantClick(modelId, groupKey, charKey) {
+    const group = state.groups.find((g) => g.key === groupKey);
+    store.selectModel({ modelId, groupKey, groupName: group ? group.name : null, charKey });
+    store.setActiveGroup(group ? group.name : state.activeGroup);
+    // 记「上次所用模型」指针（rootId/kind/modelId）：下次冷启动只加载它所在的那一个根
+    try { saveLastModel((modelById.get(modelId) || {}).model || null); } catch { /* 指针只是加速启动 */ }
+    render();
+    store.setLastReveal(reveal.revealActive()); // 选中后把这一行滚到可视区（已可见/用户正在滚都会跳过）
+    saveState(state);
+    if (typeof onSelect === 'function') {
+      const hit = modelById.get(modelId);
+      // 把装载的 promise 交回调用方：冷启动要能等"首个模型真的出来"再放行后面的加载队列，
+      //   否则队列的整根扫描会和首个模型的资源请求抢同一份磁盘 IO。
+      return onSelect(hit ? hit.model : null);
+    }
+  }
+
+  /** 事件委托：树行是动态生成的，统一在容器上监听一次 */
+  function bindEvents() {
+    /** 按行的类型分派到对应动作（鼠标与键盘共用，避免两套逻辑走偏） */
+    function activate(row) {
+      if (row.dataset.modelId) {
+        onVariantClick(row.dataset.modelId, row.dataset.groupKey, row.dataset.charKey);
+      } else if (row.dataset.charKey) {
+        onCharClick(row.dataset.charKey);
+      } else if (row.dataset.groupKey) {
+        onGroupClick(row.dataset.groupKey);
+      }
+    }
+
+    // 用户滚动信号由 reveal 控制器统一挂（滚轮 / 触摸 / 指针 / 滚动条）
+    reveal.attachUserScrollListeners();
+
+    listEl.addEventListener('click', (e) => {
+      const row = e.target.closest('[data-model-id], [data-char-key], [data-group-key]');
+      if (row) activate(row);
+    });
+
+    // 键盘可达：树行带 tabindex="0"，Enter / 空格与点击等价
+    listEl.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter' && e.key !== ' ') return;
+      const row = e.target.closest('[data-model-id], [data-char-key], [data-group-key]');
+      if (!row) return;
+      e.preventDefault();
+      activate(row);
+    });
+
+    // 类型胶囊：事件委托（胶囊每次重渲染都会换新节点，逐个绑定会漏）
+    if (typeFilterEl) {
+      typeFilterEl.addEventListener('click', (event) => {
+        const button = event.target && event.target.closest ? event.target.closest('button') : null;
+        if (!button || !typeFilterEl.contains(button)) return;
+        if (button.dataset.role === 'clear-type-filter') {
+          store.clearTypeFilter();
+        } else {
+          const typeKey = button.dataset.typeKey;
+          if (!typeKey) return;
+          store.toggleTypeFilter(typeKey);
+        }
+        // 不写 localStorage：筛选只在内存里生效（刷新后回到不筛选），
+        //   否则旧的筛选会在下次启动时把上次所用的模型挡住。
+        render();
+      });
+    }
+
+    // 游戏行的「加载失败 · 重试」：事件委托，且不能顺带折叠/展开这一行。
+    //   「未加载 · 点击加载」按钮已经取消（改由加载队列自动推进），所以这里只处理重试。
+    listEl.addEventListener('click', (event) => {
+      const target = event.target && event.target.closest ? event.target.closest('[data-group-retry]') : null;
+      if (!target) return;
+      event.preventDefault();
+      event.stopPropagation();
+      load.loadGroup(target.dataset.groupRetry, { reset: true });
+    });
+
+    // 扫描状态行上的〔重试〕：事件委托（行会被重建，逐个绑会漏）
+    listEl.addEventListener('click', (event) => {
+      const button = event.target && event.target.closest ? event.target.closest('[data-scan-retry]') : null;
+      if (!button) return;
+      event.preventDefault();
+      event.stopPropagation();     // 别让点重试顺带把游戏行折叠/展开
+      load.retryScan(button.dataset.scanRetry);
+    });
+
+    searchEl.addEventListener('input', () => {
+      store.setKeyword(searchEl.value);
+      // 搜索要全局数据：首次输入时把所有游戏补上（之后都走缓存，不再请求）
+      if (state.keyword && [...state.groupChars.keys()].length < state.groups.length) {
+        load.ensureAllLoaded();
+      } else {
+        render();
+      }
+    });
+
+    // 「收起」：只清空两级展开状态，面板保留
+    collapseBtn.addEventListener('click', () => {
+      store.collapseAll();
+      render();
+      saveState(state);
+    });
+  }
+
+  return { bindEvents, onGroupClick, onCharClick, onVariantClick };
+}