modelstage 0.0.0-stage → 0.5.28

package/src/shared/bundle-shape.mjs

@@ -0,0 +1,83 @@
+// shared/bundle-shape.mjs —— 资源包"形态"的**唯一判据**（前端 plugin-host 与 node 侧 probe 共用这一份）
+//
+// 回答一个问题：这个 UnityFS 包里到底有没有"模型定义"，还是只有美术资源？
+//   · 有模型定义类（TextAsset / SkeletonDataAsset / AtlasAsset / CubismModel / CubismMoc）
+//     ⇒ 是模型包，交给对应插件去解
+//   · 只有纹理/材质/网格/动画片段、一个模型定义类都没有
+//     ⇒ 是**美术依赖包**：它给同批的模型包提供共享资源，本身不可单独装载
+//
+// 为什么必须共用一份：同一类包在"页面点开"与"直接调 /api/unpack/resolve"两条路径上
+//   必须给同一个答案；判据或文案复制两份，早晚会漂。
+//
+// 铁律：**只看包内 className 构成**，不读文件名、不读目录名、不读角色名 ——
+//   按名字判断等于给某几个具体资源开后门，换个游戏就失效。
+
+/** 能"定义模型"的类：出现任一即视为模型包 */
+export const MODEL_DEFINING_CLASSES = [
+  'TextAsset',          // spine 的 .skel.txt / .atlas.txt；Cubism 的 model3.json / physics3.json
+  'SkeletonDataAsset',  // spine-unity 的资产类
+  'AtlasAsset',         // spine-unity 的资产类
+  'CubismModel',        // Live2D 的资产类
+  'CubismMoc',          // Live2D 的资产类
+];
+
+/** 纯美术资源类：这些有、上面一个都没有 ⇒ 依赖包 */
+export const PURE_ART_CLASSES = [
+  'Texture2D', 'Sprite', 'Material', 'Mesh', 'AnimationClip', 'MeshFilter', 'MeshRenderer', 'Shader',
+];
+
+/**
+ * 从（serialized.parse 的）对象表算 className 直方图。
+ * 两侧注入各自"怎么拿到对象表"的方式，但**统计规则就是这一份**。
+ * @param {{objects?: object[], types?: object[]}} sf serialized 解析结果
+ * @returns {Record<string, number>} className → 数量
+ */
+export function histogramFromObjects(sf) {
+  const objects = (sf && sf.objects) || [];
+  const types = (sf && sf.types) || [];
+  const byId = new Map();
+  for (const t of types) byId.set(t.classID, t.className || t.name);
+  const hist = {};
+  for (const obj of objects) {
+    const name = byId.get(obj.classID) || `ClassID ${obj.classID}`;
+    hist[name] = (hist[name] || 0) + 1;
+  }
+  return hist;
+}
+
+/**
+ * 这个直方图是否描述"美术依赖包"。
+ * @param {Record<string, number>} hist
+ * @returns {boolean}
+ */
+export function isAssetDependencyHistogram(hist) {
+  if (!hist) return false;
+  if (MODEL_DEFINING_CLASSES.some((k) => (hist[k] || 0) > 0)) return false;
+  return PURE_ART_CLASSES.some((k) => (hist[k] || 0) > 0);
+}
+
+/**
+ * 直方图压成一句可读的类型构成（只报数量最多的前几类，避免文案过长）。
+ * 过滤掉 `ClassID 199` 这类占位项：类名没解析出来时对用户没有解释力，
+ *   把它们列进文案只会让人以为"这东西有名字但没显示"。
+ */
+export function describeHistogram(hist) {
+  return Object.entries(hist || {})
+    .filter(([k]) => !/^ClassID \d+$/.test(k))
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([k, v]) => `${k}×${v}`)
+    .join('、');
+}
+
+/**
+ * 依赖包的统一文案（前端 toast / 日志、服务端 JSON 都引用它，保证逐字一致）。
+ * 要求：说清"为什么打不开" + "下一步怎么做"。
+ * @param {Record<string, number>} hist
+ * @returns {string}
+ */
+export function dependencyReason(hist) {
+  return `这是美术依赖包，不能单独装载：包内只有 ${describeHistogram(hist)}，`
+    + '没有任何骨架或模型定义（spine 的 .skel/.atlas、Live2D 的 model3.json 都不在里面）。'
+    + '它提供给同批的模型包共用；请改选同一目录下带骨架的那个包。';
+}

package/src/shared/entry-reasons.mjs

@@ -0,0 +1,119 @@
+// shared/entry-reasons.mjs —— 装载结果 reason 的**唯一码表**（服务端存储、接口、前端渲染都从这里取）
+//
+// 为什么必须收口：同一个失败在四条路上有四套叫法 ——
+//   前端 plugin-host 叫 no-provider、服务端 plugin-runner 叫 not-handled、
+//   插件 lib 抛 ULB_ERR_TEX_DECODE、解包层还可能冒出 insufficient-memory。
+//   契约《条目状态与展示归属》§二 要求 reason 是**结构化码**（"不稳定文案不许进这里"），
+//   所以这里定一份枚举 + 一份边界映射，禁止各处再写字面量。
+//
+// 插件 lib 不改：ULB_ERR_* 是它的内部码，只在边界用 fromUlbError() 映射过来。
+
+/** 契约码枚举（键名给代码用，值是与接口/存储里出现的字符串） */
+export const REASONS = Object.freeze({
+  // ── 认领层：没人愿意/不能接这个文件
+  NO_PROVIDER: 'no-provider',
+  ASSET_DEPENDENCY: 'asset-dependency',
+  // ── 资产层：目录型散文件缺件
+  MISSING_TEXTURES: 'missing-textures',
+  ASSET_MISSING: 'asset-missing',
+  VERSION_UNREADABLE: 'version-unreadable',
+  // ── 容器层
+  CONTAINER_PARSE: 'container-parse',
+  NOT_UNITYFS: 'not-unityfs',
+  NO_CAB: 'no-cab',
+  // ── 纹理解码层
+  TEX_DECODE: 'tex-decode',
+  TEX_FORMAT_UNSUPPORTED: 'tex-format-unsupported',
+  TEX_DATA_SHORT: 'tex-data-short',
+  // ── 资源/环境层
+  INSUFFICIENT_MEMORY: 'insufficient-memory',
+  BAD_ARGS: 'bad-args',
+  NOT_FOUND: 'not-found',
+  UNPACK_FAILED: 'unpack-failed',
+  // ── 渲染层（前端上报用）
+  RENDER_FAILED: 'render-failed',
+  // ── 兜底：宁可说"不知道"，也不要编一个像样的原因
+  UNKNOWN: 'unknown',
+});
+
+const ALL = new Set(Object.values(REASONS));
+
+/**
+ * 契约码 → 中文兜底文案。
+ * 注意：这只是**兜底**（调用方没给 message 时用）。真正的可读原因应尽量由判定方给出
+ *   （如依赖包用 shared/bundle-shape.mjs 的 dependencyReason()），否则会退化成"只知道码、不知道话"。
+ */
+export const REASON_TEXT = Object.freeze({
+  [REASONS.NO_PROVIDER]: '没有插件能处理这个资源包',
+  [REASONS.ASSET_DEPENDENCY]: '这是美术依赖包，不能单独装载',
+  [REASONS.MISSING_TEXTURES]: '缺少贴图文件，渲染必然失败',
+  [REASONS.ASSET_MISSING]: '资源文件缺失',
+  [REASONS.VERSION_UNREADABLE]: '读不出骨架/模型版本',
+  [REASONS.CONTAINER_PARSE]: '资源包结构解析失败',
+  [REASONS.NOT_UNITYFS]: '不是 UnityFS 资源包',
+  [REASONS.NO_CAB]: '资源包里没有资产节点',
+  [REASONS.TEX_DECODE]: '纹理解码失败',
+  [REASONS.TEX_FORMAT_UNSUPPORTED]: '不支持这种纹理格式',
+  [REASONS.TEX_DATA_SHORT]: '纹理数据不完整',
+  [REASONS.INSUFFICIENT_MEMORY]: '可用内存不足，已拒绝解包',
+  [REASONS.BAD_ARGS]: '请求参数不合法',
+  [REASONS.NOT_FOUND]: '路径不存在',
+  [REASONS.UNPACK_FAILED]: '解包失败',
+  [REASONS.RENDER_FAILED]: '渲染失败',
+  [REASONS.UNKNOWN]: '原因未知',
+});
+
+/** 插件内部码 → 契约码。插件 lib 的 ULB_ERR_* 不改，只在这里翻译。 */
+const ULB_MAP = Object.freeze({
+  ULB_ERR_TEX_DECODE: REASONS.TEX_DECODE,
+  ULB_ERR_TEX_FORMAT_UNSUPPORTED: REASONS.TEX_FORMAT_UNSUPPORTED,
+  ULB_ERR_TEX_DATA_SHORT: REASONS.TEX_DATA_SHORT,
+  ULB_ERR_NOT_UNITYFS: REASONS.NOT_UNITYFS,
+  ULB_ERR_NO_CAB: REASONS.NO_CAB,
+  ULB_ERR_CONTAINER_PARSE: REASONS.CONTAINER_PARSE,
+  ULB_ERR_NO_FILE: REASONS.ASSET_MISSING,
+  ULB_ERR_BAD_ARGS: REASONS.BAD_ARGS,
+});
+
+/**
+ * 把任意来源的 reason 归一到契约码。
+ *
+ * 为什么需要：服务端 plugin-runner 用 `not-handled`，前端 plugin-host 用 `no-provider`，
+ *   两者是同一件事（"所有提供者都说不处理"）；不归一会让同一条失败在存储里有两个键，
+ *   前端按码查文案时会漏。
+ * @param {unknown} raw
+ * @returns {string} 契约码（永远落在 REASONS 的值里）
+ */
+export function normalizeReason(raw) {
+  if (raw === null || raw === undefined || raw === '') return REASONS.UNKNOWN;
+  const s = String(raw).trim();
+  if (ALL.has(s)) return s;
+  // 同义合并：服务端 runner 的 not-handled ≡ 前端 host 的 no-provider
+  if (s === 'not-handled') return REASONS.NO_PROVIDER;
+  // 已经带着 ULB_ 前缀的也认（有些路径会把插件内部码直接透上来）
+  if (s.startsWith('ULB_ERR_')) return fromUlbError(s);
+  return REASONS.UNKNOWN;
+}
+
+/**
+ * 插件内部错误码 → 契约码。
+ * @param {string|null|undefined} code 形如 ULB_ERR_TEX_DECODE
+ * @returns {string} 契约码；未登记的 ULB_ERR_* 一律 unpack-failed（不是 unknown：它确实是解包环节失败的）
+ */
+export function fromUlbError(code) {
+  if (!code) return REASONS.UNKNOWN;
+  const s = String(code).trim();
+  if (ULB_MAP[s]) return ULB_MAP[s];
+  if (s.startsWith('ULB_ERR_')) return REASONS.UNPACK_FAILED;
+  return normalizeReason(s);
+}
+
+/**
+ * 取某个契约码的兜底文案。
+ * @param {string} reason 契约码（内部会先归一）
+ * @returns {string}
+ */
+export function reasonText(reason) {
+  const code = normalizeReason(reason);
+  return REASON_TEXT[code] || REASON_TEXT[REASONS.UNKNOWN];
+}

package/src/shared/names.mjs

@@ -0,0 +1,45 @@
+// names.mjs —— 名表取值（前端与服务端共用的纯函数，无平台依赖）
+//
+// 名表结构见 docs/设计/名表.md：
+//   characters[id] = { id, name: [{lang,text}], costume: [{lang,text}], icon }
+//   byAsset[资源文件名] = 角色 id
+//   _meta.mergeBy 声明用条目的哪个字段做归并键
+//
+// 为什么放在 shared：同一套取值规则前端要用（显示）、工具要用（校验）。
+//   各写一份就会出现"页面显示的和校验认得的不是同一套规则"。
+
+/**
+ * 从多语言名数组里取一个显示名。
+ *
+ * 当前只维护中文 ⇒ 调用方一律用默认 lang（'zh'），**不接受外部传语言**：
+ *   数据里只有中文时，做出"可选语言"只会让用户切过去还是看到中文，是假能力。
+ * 将来接用户语言时，只改调用处传的 lang，本函数不动。
+ *
+ * @param {Array<{lang?: string, text?: string}>} names
+ * @param {string} lang 目标语言（默认 'zh'）
+ * @returns {string} 取不到返回空串，调用方自行回落（例如显示资源名）
+ */
+export function pickName(names, lang = 'zh') {
+  if (!Array.isArray(names) || !names.length) return '';
+  const ok = (n) => n && typeof n.text === 'string' && n.text.trim();
+  const hit = names.find((n) => ok(n) && n.lang === lang);
+  if (hit) return hit.text.trim();
+  const zh = names.find((n) => ok(n) && n.lang === 'zh');
+  if (zh) return zh.text.trim();
+  const first = names.find(ok);
+  return first ? first.text.trim() : '';
+}
+
+/**
+ * 取一个名表条目的归并键。
+ * 归并字段名由 `_meta.mergeBy` 声明（不硬编码字段名），取不到时回落到条目键。
+ *
+ * @param {object} entry 名表条目
+ * @param {string} key 该条目在 characters 里的键
+ * @param {string} mergeBy 声明的归并字段名
+ * @returns {string}
+ */
+export function mergeKeyOf(entry, key, mergeBy = 'id') {
+  const v = entry && entry[mergeBy];
+  return typeof v === 'string' && v ? v : key;
+}

package/src/shared/type-labels.mjs

@@ -0,0 +1,31 @@
+// shared/type-labels.mjs —— 内容类型（kind）的显示名映射（**单一来源**）
+//
+// 谁用：前端名册的类型筛选胶囊、以及将来可能的插件/其它视图。
+// 为什么放 shared 而不是各自写一份：显示名是"同一事实两处表达"的高危点——
+//   前端写一套、插件再写一套，很快就会出现"同一个类型两处叫法不同"。
+//
+// 规则（设计口径）：
+//   · 已知类型 → 可读名（下表）
+//   · 未知类型 → **原样返回 key**，不做大小写美化（避免"看起来认识其实不认识"）
+
+/** kind 为 null/空时的归并键（未解包容器条目走这一档，见设计稿 §5.1） */
+export const UNKNOWN_TYPE_KEY = 'unknown';
+
+/** 内置显示名：键是条目上的 kind 值（null 一律先归成 UNKNOWN_TYPE_KEY） */
+export const TYPE_LABELS = Object.freeze({
+  spine: 'Spine',
+  live2d: 'Live2D',
+  [UNKNOWN_TYPE_KEY]: '待解包',
+  bundle: '资源包',
+});
+
+/**
+ * 取显示名：已知返回中文/品牌名，未知**原值返回**。
+ * @param {string} typeKey 类型键（如 'spine' / 'unknown' / 将来插件的自定义值）
+ * @returns {string}
+ */
+export function typeLabel(typeKey) {
+  const key = String(typeKey == null ? '' : typeKey);
+  if (!key) return String(UNKNOWN_TYPE_KEY);
+  return Object.prototype.hasOwnProperty.call(TYPE_LABELS, key) ? TYPE_LABELS[key] : key;
+}

package/src/web/README.md

@@ -0,0 +1,193 @@
+# ModelStage · 前端（`src/web/`）
+
+纯 HTML + 原生 ES 模块 + 手写 CSS，无构建步骤。页面与接口由同一个服务提供
+（`src/server/serve.mjs`：静态文件 + `/api/*` + `/files/*` 模型资源），同源、无反向代理。
+
+## 一、怎么起
+
+```bash
+bash web.sh start|stop|restart|status   # 默认 8804
+```
+
+打开 `http://<本机IP>:8804/`。
+
+| 变量 | 默认 | 作用 |
+|---|---|---|
+| `PORT` | `8804` | 监听端口 |
+| `MODELSTAGE_AVATAR_ROOT` | `<项目根>/avatars` | 头像根（也可用 `--avatar-root` 传）|
+
+启停一律走 `web.sh`（PID 与日志由脚本统一管理，不要用 nohup）。
+
+## 二、目录结构
+
+```
+src/web/
+├── index.html        五区域骨架：顶栏 / 左栏（名册）/ 舞台 / 右栏 / 底栏
+├── style.css         变量 + 基础重置 + 舞台 + 五区域容器几何
+├── components.css    控件外观：品牌、按钮、搜索框、三级树行、分组行、底栏、错误横幅
+├── main.js           入口：只做装配（品牌、面板开关、资源根、名册挂载、渲染器、错误兜底、__WEB__）
+├── transport.js      底部播放条渲染
+│
+├── infra/            与业务无关的基础设施
+│   ├── api.js        同源 JSON 请求封装（统一错误口径）
+│   ├── vfs.js        内存资源视图（登记表 + 字节缓存）
+│   ├── diag.js       诊断探针 __DIAG__（错误/警告/关键事件 + 落盘）
+│   └── plugin-host.js 插件宿主适配
+│
+├── roster/           左栏名册
+│   ├── list.js       数据层：按根取清单 + 名表归并 + 角色聚合
+│   ├── filter.js     搜索过滤
+│   ├── view.js       视图层：状态、事件、懒加载、选中态、持久化
+│   └── rows.js       三级树行渲染（纯 DOM 工厂，无状态）
+│
+├── panel/            右栏控制面板
+│   ├── schema.js     控件声明（9 组 + 播放条）
+│   ├── view.js       手风琴渲染（能力不支持的不构建）
+│   ├── shell-controls.js / dom.js / memory-bar.js
+│   └── panel.css     右栏/播放条内部样式
+│
+├── render/           舞台与渲染面
+│   ├── surface.js    渲染面：几何唯一来源、背景模式、渲染器切换与生命周期
+│   ├── spine.js      Spine 渲染器
+│   ├── live2d.js     Live2D 渲染器
+│   ├── interaction.js 交互层：滚轮/拖动/双指/重置
+│   └── camera/       统一相机（范围、步进、钳制）
+│
+├── spine/            Spine 运行时（引擎封装、多版本运行时选择）
+├── live2d/           Live2D 运行时（库加载、模型挂载、缩放平移桥）
+└── debug/            调试（环形日志、日志面板、模型差异采集）
+```
+
+**目录约定**
+
+| 目录 | 放什么 | 不放什么 |
+|---|---|---|
+| `infra/` | 通用能力（请求、存储、诊断） | 模型/渲染逻辑 |
+| `roster/` `panel/` | 左右栏的视图与数据 | 渲染与相机 |
+| `render/` | 渲染面、渲染器、相机、交互 | 具体模型的加载（在 `spine/`、`live2d/`） |
+| `spine/` `live2d/` | 各自运行时的加载与能力封装 | 跨渲染器公共逻辑 |
+| `debug/` | 日志与排障 | 生产路径依赖 |
+
+规则：单文件 ≤ 400 行；文件名不带模块前缀（目录已表达归属）；`main.js` 只装配。
+
+## 三、尺寸与相机的唯一来源
+
+| 事 | 唯一负责人 | 约束 |
+|---|---|---|
+| 舞台几何（CSS 像素） | `render/surface.js` 的 `geometry()` | 渲染器只读取，不得自行测 DOM |
+| 背板像素尺寸 | 由 `geometry()` 推导后交给渲染器 | 不允许第二处 DPR 计算 |
+| 相机（范围/步进/锚点/复位） | `render/camera/index.js` | 唯一钳制点，Spine 与 Live2D 语义一致 |
+| 交互（滚轮/拖动/双指） | `render/interaction.js` | 绑 `surface.interactionTarget`，不绑某块画布 |
+| 背景（棋盘/纯色/透明） | `surface.setBackground()` | 写 `data-bg` 的唯一入口，渲染器不画背景 |
+
+调参只改 `render/camera/constants.js`（`MIN 0.125 / MAX 16 / STEP 0.1 / FIT_MARGIN 0.05`），逻辑里不出现同样的裸数字。
+
+## 四、品牌与标题
+
+品牌不写死在前端：启动时 `GET /api/brand` 取 `title` / `icon` / `iconKind`，同时应用到顶栏与 `document.title`；
+配置为空时回落默认名 `ModelStage`。
+
+- `iconKind === 'text'`：按文字/emoji 渲染
+- `iconKind === 'image'`：按 `<img>` 渲染（站内绝对路径 / http(s) / data:）
+- 均空：保留 `index.html` 里的内联 SVG 图标
+
+改配置后刷新即生效，无需重启。
+
+## 五、诊断（`window.__DIAG__`）
+
+`main.js` 在模块体第一件事就安装它，保证早期错误也能抓到。
+
+采什么（只收错误/警告/关键事件，不做每帧采样）：
+
+- `window.onerror`（含 img/script/link/video/audio 资源加载失败，capture 阶段）
+- `unhandledrejection`
+- 包装 `console.error / warn / info`（幂等；内部日志不自激）
+- 业务主动上报：`__DIAG__.event('stage.load', { … })`
+
+```js
+__DIAG__.__installed     // 已安装
+__DIAG__.errors()        // error 级条目
+__DIAG__.warnings()
+__DIAG__.timeline()      // 一行一条时间线（便于贴出来排查）
+__DIAG__.tail(10) / dump() / size() / clear() / flushNow()
+```
+
+落盘：批量 `POST /api/diag` → 追加写 `data/diag.jsonl`；失败静默降级为仅内存，不影响页面。
+
+## 六、自定义背景图存储（`data/backgrounds/`）
+
+- 索引 `index.json`：原子写（tmp → fsync → rename），进程内串行排队，避免并发上传互相覆盖
+- 文件名由服务端生成（`bg-<时间戳>-<随机>.<ext>`），不用用户提供的名字
+- 删除：文件移入 `data/backgrounds/.trash/`（可恢复），索引同步移除
+- 上限 5MB；只收 png / jpeg / webp（按文件头判定，不信 Content-Type 与扩展名）；
+  刻意不收 gif —— 动画背景在软渲染机上持续重绘，与「暂停不空转」冲突
+
+| 方法 | 路径 | 说明 | 失败码 |
+|---|---|---|---|
+| GET | `/api/backgrounds` | 列表（新的在前） | — |
+| POST | `/api/backgrounds` | 上传（原始二进制 + `x-filename` 显示名） | `too-large`(413) / `bad-type`(415) / `empty`(400) / `disk-error`(500) |
+| POST | `/api/backgrounds/rename` | 只改显示名，重名自动加 `(2)` | `bad-name`(400) / `not-found`(404) |
+| POST | `/api/backgrounds/delete` | 删除（文件进 `.trash/`） | `not-found`(404) |
+| GET | `/api/backgrounds/file/<id>` | 出图（只查索引，不拼路径） | `not-found`(404) |
+
+`data/backgrounds/` 是部署侧数据：换机或备份要一起带走（已 gitignore）。
+
+## 七、自测方式
+
+自动门禁只跑 node-test（13 套，约 100s）；浏览器注入脚本在 `test/browser/`，手动单跑。
+
+```bash
+node tool/test-all.mjs                     # 自动门禁（13 套 node-test）
+node tool/test-all.mjs --only f3-reveal    # 单跑一个浏览器脚本
+node tool/test-all.mjs --browser           # 把浏览器脚本也纳入
+```
+
+三道静态/数据门禁，失败即拦：
+
+```bash
+node tool/check-wiring.mjs    # 控件声明 ↔ 接线
+node tool/check-index.mjs     # 名表结构校验
+node tool/check-single-source.mjs
+```
+
+零错误自证（四类信号：console.error / 未捕获异常 / 浏览器 error 日志 / 4xx 与请求失败）：
+
+```bash
+node tool/check-console.mjs http://127.0.0.1:8804/     # 有错退出码 2
+```
+
+### 浏览器脚本的硬规矩
+
+1. **前置条件由脚本自己建立或自己断言**，不依赖「上次跑时环境正好合适」
+2. **不出现硬编码绝对路径**：需要路径的一律由调用方传参或从项目相对位置派生
+3. **缺前置 = skip，不是 fail**：文案以 `skipped:` 开头，报告里单列计数；该失败的仍然 fail
+
+| 脚本 | 前置 | 传参 |
+|---|---|---|
+| `f1-controls` | 页面已启动；至少一个能扫出模型的资源根 | 无（自动发现） |
+| `f2-topbar` | 同上（截图要有画面可截） | 无 |
+| `f3-reveal` | 名册有足够长的列表 | 无（自己挑变体最多的游戏） |
+| `f4-roots` | 服务端存在探针目录 | **要**：`?f4probe=<服务端已存在目录>` |
+| `spine-actions` | 至少一个能扫出模型的根；WebGL 可用 | 无 |
+| `panel-actions` / `roster-actions` / `anim-list` / `debug-drag` | 页面已启动 | 无 |
+
+F4 的探针目录别用点开头的隐藏目录（`/api/browse` 不列隐藏项，会被预检判成不存在）。
+
+### 页面状态快照
+
+```js
+window.__WEB__.rosterSnapshot()
+// → { games:[{key,name,roots,status,sources,chars,variants,miss}],
+//     expandedGames, expandedChars, keyword, selected, domRows }
+```
+
+自动化断言也读这个出口。
+
+## 八、决策记录
+
+1. **一级节点按 name 合并**：一个游戏一个节点，角色**跨根归并**（同一角色的 Live2D 与 Spine 聚成一个）
+2. **搜索补加载全部游戏**：首次输入关键词时并行拉齐各游戏（服务端有清单缓存，实测 <1s）。
+   取舍：宁可多一次请求，也要搜得到 —— 只搜已展开的游戏会让人以为列表缺内容
+3. **不做区域几何 diff 工具**：视觉已降级，改用截图比对或人工核对
+4. **改左栏行为后先跑 `roster-actions`**（穷举实操 + 断言）
+5. **名字与头像来自名表**，不从资源目录名现场推断：目录名只作匹配线索，名字以名表为准