modelstage 0.5.24 → 0.5.28

package/config/models/spine.npc.json

@@ -1 +1 @@
-{"rootId":"npc","rootName":"棕色尘埃2","rootPath":"/volume1/VirtualDSM/DeepSeekHarness/npc","ts":1793428363103,"count":0,"dirStamps":{"root":null,"dirs":{}},"generator":"0f60b6bf","models":[]}
+{"rootId":"npc","rootName":"棕色尘埃2","rootPath":"/volume1/VirtualDSM/DeepSeekHarness/npc","ts":1793868513580,"count":0,"dirStamps":{"root":null,"dirs":{}},"generator":"642803b7","models":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelstage",
-  "version": "0.5.24",
+  "version": "0.5.28",
   "description": "Spine / Live2D 模型查看器：三级名册、两套渲染面共享相机与面板、UnityFS 资源包解包",
   "type": "module",
   "bin": {
@@ -24,7 +24,12 @@
     "plugins/unity-spine-bundle/",
     "tool/parse-jsonc.mjs",
     "tool/resolve-live2d-runtimes.mjs",
-    "tool/lib/",
+    "tool/lib/bundle-probe-node.mjs",
+    "tool/lib/paths.mjs",
+    "tool/lib/runtime-guides.mjs",
+    "tool/lib/runtime-package.mjs",
+    "tool/lib/spine-meta.mjs",
+    "tool/lib/spine-motions.mjs",
     "tool/spine-motion-rules.json",
     "config/plugins.json",
     "config/models/",

package/src/server/http/write.mjs

@@ -508,7 +508,14 @@ export function createWriteApi({ paths, config, models, names }) {
 
       // ---------- ③ 校验并算出目标状态（纯内存，失败则磁盘不动）----------
       const plan = planChange(action, payload, raw);
-      if (!plan.ok) return fail(plan.status, plan.error, plan.extra);
+      if (!plan.ok) {
+        // planChange 把 path / existing 这类补充字段放在**顶层**（不是 plan.extra），
+        //   这里要显式把除 status/error/ok 之外的字段都透传出去 ——
+        //   否则 409 的 existing、400 的 path 会在响应里变成 undefined，
+        //   前端想提示"已登记的是哪个根"时拿不到依据。
+        const { ok: _ok, status, error, ...extra } = plan;
+        return fail(status, error, extra);
+      }
 
       // ---------- ④ 备份（写盘前）----------
       let backup = null;

package/src/server/serve.mjs

@@ -236,7 +236,54 @@ const ctx = {
  * @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;
@@ -302,6 +349,21 @@ server.listen(PORT, '0.0.0.0', () => {
   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);
+});
+
 /**
  * 收尾钩子：先把**常驻资源**放掉再退出。
  *

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/components.css

@@ -271,6 +271,65 @@
   border-color: var(--color-primary);
 }
 
+/* ------------------------------------------------------------ 类型筛选胶囊行 */
+
+/**
+ * 类型胶囊行（搜索框与名册列表之间）。
+ *
+ * 两个必须的几何约束（设计稿 §4.1 与 §10.2）：
+ *   ① **自动换行、不横向滚动**：类型数量由数据决定（今天 3 种，将来可能更多），
+ *      横向滚动在 304px 的窄栏里几乎不可用；
+ *   ② **单行最小高度**：类型从 2 行回落到 1 行时，若容器随之变矮，下面的列表会"猛地往上一跳"。
+ *      给 min-height 兜住这一档，高度变化只发生在真的加了一整行时。
+ */
+.roster-type-filter {
+  flex: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  min-height: 22px;            /* 单行高度：防列表因胶囊行消失/收缩而跳动 */
+  padding: 0 12px 8px;
+}
+
+.roster-type-filter[hidden] {
+  display: none;
+}
+
+/* 单个类型胶囊：复用 .mini-btn 的视觉语言（描边 + 底色），但高度更小、可换行 */
+.roster-type-chip,
+.roster-type-clear {
+  height: 22px;
+  padding: 0 8px;
+  border: 1px solid var(--color-border);
+  border-radius: 999px;
+  background: var(--color-muted);
+  color: var(--color-foreground);
+  font-size: 12px;
+  line-height: 20px;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.roster-type-chip:hover,
+.roster-type-clear:hover {
+  background: var(--color-secondary);
+}
+
+/* 选中态：主色描边 + 主色底（与工具栏 aria-pressed 同一套语义，颜色浓度略低以免抢眼） */
+.roster-type-chip[aria-pressed='true'] {
+  border-color: var(--color-primary);
+  color: var(--color-primary);
+  background: color-mix(in srgb, var(--color-primary) 18%, transparent);
+  font-weight: 600;
+}
+
+/* 「清除」比胶囊更轻：它是辅助动作，不该和类型胶囊抢视觉权重 */
+.roster-type-clear {
+  border-style: dashed;
+  color: var(--color-muted-foreground, var(--color-foreground));
+  opacity: 0.85;
+}
+
 .roster-list {
   padding: 2px 0 8px;
 }

package/src/web/index.html

@@ -90,6 +90,8 @@
     <input id="roster-search" type="search" autocomplete="off"
       placeholder="搜索角色 / 服装 / 变体…" aria-label="搜索角色、服装、变体" />
   </div>
+  <!-- 类型胶囊行：内容由 roster/view.js 渲染（名册为空时整行隐藏）；放搜索与列表之间 -->
+  <div id="roster-type-filter" class="roster-type-filter" role="group" aria-label="按内容类型筛选" hidden></div>
   <!-- 三级树：资源根 → 角色 → 变体（首次展开某根才请求该根的模型清单） -->
   <div id="roster-list" class="panel-body roster-list" role="tree" aria-label="角色库" aria-live="polite">
     <p class="muted-hint">正在读取资源根…</p>

package/src/web/roster/persist.js

@@ -6,6 +6,14 @@
 
 import * as uiState from '../app/ui-state.js';
 
+/**
+ * 类型筛选的存储键。
+ *
+ * 为什么不并进 TREE_STATE_KEY：两者的生命周期不同——展开态是"临时视图状态"，
+ *   类型筛选是跨会话保留的选择；分开存也让"读不懂的值直接忽略"只影响筛选，不牵动整棵树。
+ */
+export const TYPE_FILTER_KEY = 'roster.typeFilter';
+
 /**
  * 名册状态存储键（**当前唯一键**，不是历史遗留）。
  *
@@ -50,3 +58,35 @@ export function saveState(state) {
     // 隐私模式等写不了就忽略：持久化是增强，不影响当前会话
   }
 }
+
+/**
+ * 读类型筛选的选中集合（数组；读不到/形状不对一律当空）。
+ * 注意：这里**不校验 key 是否仍然有效**——失效项的忽略发生在渲染期（见 roster/type-filter.js
+ *   的 usableTypeSelection），这样存储里的值不会被我们悄悄删掉。
+ * @returns {string[]}
+ */
+export function readTypeFilter() {
+  try {
+    const raw = localStorage.getItem(TYPE_FILTER_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((key) => typeof key === 'string' && key) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 写类型筛选（失败静默：筛选是增强，隐私模式/配额满都不该影响当前会话）。
+ * @param {Iterable<string>} keys
+ * @returns {boolean} 是否写入成功（调用方一般不需要它，测试用）
+ */
+export function saveTypeFilter(keys) {
+  try {
+    const list = [...(keys || [])].map(String).filter(Boolean);
+    localStorage.setItem(TYPE_FILTER_KEY, JSON.stringify(list));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/web/roster/snapshot.js

@@ -25,6 +25,8 @@ export function snapshotRoster({ state, listEl, gameStatus }) {
     expandedGames: [...state.expandedGames],
     expandedChars: [...state.expandedChars],
     keyword: state.keyword,
+    /** 类型筛选的选中集合（**存储原样**，可能含当前名册里不存在的失效项） */
+    typeFilter: state.typeFilter ? [...state.typeFilter] : [],
     selected: state.selected,
     /** 最近一次"定位当前角色"的结果（visible / scrolled / skipped-user-scrolling / …） */
     lastReveal: state.lastReveal || null,

package/src/web/roster/type-filter.js

@@ -0,0 +1,97 @@
+// roster/type-filter.js —— 名册「内容类型」筛选（纯函数，不碰 DOM、不读存储）
+//
+// 与 filter.js 的分工：
+//   · filter.js      管**关键词**（角色整组判定：命中角色名或任一变体即显示整组）
+//   · 本文件         管**类型**（按条目自带的 kind 归并、计数、过滤）
+//   两者正交：视图层先按类型筛，再按关键词筛（或反过来），结果一致（交集）。
+//
+// 类型从哪来：条目的 `kind`（内容类型）。**未解包的容器条目 kind 可能为 null**，
+//   一律归入 UNKNOWN_TYPE_KEY（显示名「待解包」）—— 否则这些条目在"选中任意类型"时会被全部滤掉，
+//   用户会以为资源包不见了（设计稿 §5.1 的关键结论）。
+
+import { UNKNOWN_TYPE_KEY } from '../../shared/type-labels.mjs';
+import { visibleChars } from './filter.js';
+
+/**
+ * 单个变体的类型键：条目 kind 为空 ⇒ unknown。
+ * 为什么看 kind 而不是 container：container 是"装载方式"（要先解包），kind 才是"内容类型"。
+ * @param {{model?: {kind?: string|null}}} variant
+ * @returns {string}
+ */
+export function typeKeyOf(variant) {
+  const model = variant && variant.model ? variant.model : variant;
+  const kind = model && model.kind != null ? String(model.kind).trim() : '';
+  return kind || UNKNOWN_TYPE_KEY;
+}
+
+/**
+ * 类型计数：**当前关键词下、该类型可见的变体数**（不含类型过滤本身的影响）。
+ *
+ * 为什么要排除类型过滤：数字要回答"如果我再选它，会有多少"。
+ *   若把类型过滤也算进去，选中 Spine 后其它胶囊会立刻变 0，用户就没法判断要不要切换。
+ * 为什么仍计入关键词：面板上的数字必须和"现在列表里能看到多少"对得上（设计稿 §5.3）。
+ *
+ * scope 参数是为将来扩维度（如按资源根）预留的：当前只消费 keyword，新增维度时只加 scope 字段，
+ *   不动本函数的排序/计数逻辑（设计稿 §5.4）。
+ *
+ * @param {{games: object[], gameChars: Map, keyword?: string,
+ *          scope?: {keyword?: string}}} input
+ * @returns {Array<{key: string, count: number}>} 按数量降序，并列按 key 字典序（稳定）
+ */
+export function deriveTypeCounts({ games, gameChars, keyword = '', scope = null }) {
+  const effectiveKeyword = String((scope && scope.keyword) != null ? scope.keyword : keyword || '').toLowerCase();
+  const counts = new Map();
+  for (const game of games || []) {
+    // 复用关键词过滤的同一口径（角色整组判定），保证"数字"与"列表可见性"不会两套算法
+    const chars = visibleChars(game, { gameChars, keyword: effectiveKeyword });
+    for (const char of chars) {
+      for (const variant of char.variants || []) {
+        const typeKey = typeKeyOf(variant);
+        counts.set(typeKey, (counts.get(typeKey) || 0) + 1);
+      }
+    }
+  }
+  return [...counts.entries()]
+    .map(([key, count]) => ({ key, count }))
+    .sort((left, right) => (right.count - left.count) || (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+}
+
+/**
+ * 按选中类型过滤角色（并把每个角色的变体裁到命中集合）。
+ *
+ * 语义：selectedTypes 为空 ⇒ 不过滤（等于"全部"）；否则 = 并集（命中任一选中类型即保留）。
+ * 注意返回的是**新数组/新角色对象**，不改动 state.gameChars 里的原对象（渲染层只读）。
+ *
+ * @param {object[]} chars 角色数组（每个带 variants）
+ * @param {Set<string>|string[]} selectedTypes
+ * @returns {object[]}
+ */
+export function filterCharsByType(chars, selectedTypes) {
+  const selected = selectedTypes instanceof Set ? selectedTypes : new Set(selectedTypes || []);
+  if (!selected.size) return chars;
+  const kept = [];
+  for (const char of chars) {
+    const variants = (char.variants || []).filter((variant) => selected.has(typeKeyOf(variant)));
+    if (variants.length) kept.push({ ...char, variants });
+  }
+  return kept;
+}
+
+/**
+ * 把存储里读到的选中集合收敛成"当前可用"的集合。
+ *
+ * 失效项（当前类型集合里没有的 key）在**当前页面生命周期内被忽略**，但**不删存储**——
+ *   这样某个类型暂时消失（例如最后一个资源包被解包）后再出现时，用户的选中会自动恢复。
+ * @param {string[]} storedKeys 存储里读到的 key 列表
+ * @param {Iterable<string>} availableKeys 当前名册实际出现的类型
+ * @returns {Set<string>} 可用的选中集合
+ */
+export function usableTypeSelection(storedKeys, availableKeys) {
+  const available = new Set([...availableKeys].map((key) => String(key)));
+  const out = new Set();
+  for (const raw of Array.isArray(storedKeys) ? storedKeys : []) {
+    const key = String(raw == null ? '' : raw);
+    if (key && available.has(key)) out.add(key);
+  }
+  return out;
+}

package/src/web/roster/view.js

@@ -12,8 +12,10 @@
 
 import { createReveal } from './reveal.js';
 import { visibleChars } from './filter.js';
+import { deriveTypeCounts, filterCharsByType, typeKeyOf, usableTypeSelection } from './type-filter.js';
+import { typeLabel } from '../../shared/type-labels.mjs';
 import { snapshotRoster } from './snapshot.js';
-import { readSaved, saveState } from './persist.js';
+import { readSaved, saveState, readTypeFilter, saveTypeFilter } from './persist.js';
 import {
   createNameIndex, mergeNameTable, loadRootModels, loadRootNames, buildChars,
 } from './list.js';
@@ -43,6 +45,9 @@ function renderLimitPerGame() {
 
 /** 创建名册视图并挂到容器上；返回对外 API（供 main.js 与自动化验证使用） */
 export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSelect }) {
+  // 类型胶囊行：容器由 index.html 提供（#roster-type-filter），这里只取引用；
+  //   取不到（旧页面/单测）就整体降级为"没有类型筛选"，不影响名册其余功能。
+  const typeFilterEl = typeof document !== 'undefined' ? document.getElementById('roster-type-filter') : null;
   const state = {
     games: [],
     loaded: new Map(),
@@ -50,6 +55,12 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
     expandedGames: new Set(),
     expandedChars: new Set(),
     keyword: '',
+    /**
+     * 类型筛选的选中集合（**存储原样**，可能含当前名册里已不存在的 key）。
+     * 为什么不在读入时就剪掉失效项：设计上要求"暂时消失的类型再出现时自动恢复选中"，
+     *   剪掉就丢了这条信息；渲染期用 usableTypeSelection 现算生效集合即可。
+     */
+    typeFilter: new Set(),
     selected: null,
     activeGame: null,
     /**
@@ -288,6 +299,43 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
   /** 单条变体的可搜索文本（资源名 / 目录名 / 角色名 / 服装名） */
   // ------------------------------------------------------------ 渲染
 
+  /**
+   * 渲染类型胶囊行（搜索框下方那一行）。
+   *
+   * 为什么不复用工具栏按钮：胶囊要自动换行、要带计数、要表达 aria-pressed 的选中态，
+   *   与 .mini-btn 的"单行操作按钮"定位不同；只复用它的视觉语言（描边+底色），类名单列。
+   * @param {Array<{key: string, count: number}>} counts 类型与计数（已按数量降序）
+   * @param {Set<string>} activeTypes 当前**生效**的选中集合（已剔除当前不存在的失效项）
+   */
+  function renderTypeFilter(counts, activeTypes) {
+    if (!typeFilterEl) return;
+    // 名册为空（一个类型都没有）⇒ 整行隐藏，不留一条空白（设计稿 §4.4）
+    if (!counts.length) {
+      typeFilterEl.hidden = true;
+      typeFilterEl.replaceChildren();
+      return;
+    }
+    typeFilterEl.hidden = false;
+    const nodes = counts.map(({ key, count }) => {
+      const chip = el('button', 'roster-type-chip', `${typeLabel(key)} ${count}`);
+      chip.type = 'button';
+      chip.dataset.typeKey = key;
+      chip.setAttribute('aria-pressed', activeTypes.has(key) ? 'true' : 'false');
+      chip.title = `只看 ${typeLabel(key)}（当前搜索下 ${count} 个变体）`;
+      return chip;
+    });
+    // 「清除」只在至少选 1 个时出现；不提供「全部」按钮（全部 = 全部取消选中）
+    if (activeTypes.size) {
+      const clear = el('button', 'roster-type-clear', '清除');
+      clear.type = 'button';
+      clear.dataset.role = 'clear-type-filter';
+      clear.setAttribute('aria-label', '清除类型筛选');
+      clear.title = '清除类型筛选（等价于不筛选）';
+      nodes.push(clear);
+    }
+    typeFilterEl.replaceChildren(...nodes);
+  }
+
   /** 渲染整棵树（只渲染可见部分；展开的角色才生成变体行） */
   function render() {
     counters.render += 1;
@@ -303,11 +351,26 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
     let totalVariants = 0;
     let rendered = 0;
     let loadedGames = 0;
+    // 类型胶囊的计数口径 = **当前关键词下**的可见变体数（不含类型过滤本身的影响，见设计稿 §5.3）。
+    //   所以先算 counts（只吃 keyword），再算 activeTypes，最后才把类型过滤作用到列表上。
+    const typeCounts = deriveTypeCounts({ games: state.games, gameChars: state.gameChars, keyword: state.keyword });
+    const activeTypes = usableTypeSelection([...state.typeFilter], typeCounts.map((entry) => entry.key));
+    renderTypeFilter(typeCounts, activeTypes);
+    // 被类型过滤挡掉的变体数 / 留下来的变体数：只用于"当前筛选下没有条目"的提示文案
+    let hiddenByType = 0;
+    let keptVariants = 0;
 
     for (const game of state.games) {
       const status = gameStatus(game);
       if (status === 'ready') loadedGames += 1;
-      const chars = visibleChars(game, state);
+      const charsByKeyword = visibleChars(game, state);
+      const chars = filterCharsByType(charsByKeyword, activeTypes);
+      if (activeTypes.size) {
+        const visibleCount = charsByKeyword.reduce((n, c) => n + c.variants.length, 0);
+        const keptCount = chars.reduce((n, c) => n + c.variants.length, 0);
+        hiddenByType += visibleCount - keptCount;
+        keptVariants += keptCount;
+      }
       const open = state.expandedGames.has(game.key) || (searching && chars.length > 0);
 
       listEl.append(renderGameRow(game, {
@@ -348,6 +411,13 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
       }
     }
 
+    // 类型筛选把所有条目都挡掉时给一句可读提示，不留空白（设计稿 §10.2 第 1 条）。
+    //   不自动改用户的选择：解包完成后条目会从 unknown 跳到 spine/live2d，
+    //   这里只如实说明"被挡掉了多少个"，让用户自己决定是否取消筛选。
+    if (activeTypes.size && keptVariants === 0 && hiddenByType > 0) {
+      listEl.prepend(el('p', 'muted-hint tree-hint', `当前筛选下没有条目（${hiddenByType} 个已移到其它类型）`));
+    }
+
     // 计数文案：全量已加载时用统一口径（N 游戏 / M 角色 / K 变体），否则标注已加载多少
     const allLoaded = loadedGames === state.games.length;
     const prefix = allLoaded ? `${state.games.length} 游戏` : `${state.games.length} 游戏 / 已加载 ${loadedGames}`;
@@ -434,6 +504,25 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
       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') {
+          state.typeFilter.clear();
+        } else {
+          const typeKey = button.dataset.typeKey;
+          if (!typeKey) return;
+          if (state.typeFilter.has(typeKey)) state.typeFilter.delete(typeKey);
+          else state.typeFilter.add(typeKey);
+        }
+        // 写失败静默（隐私模式/配额满）：筛选是增强，不能因此让页面报错
+        saveTypeFilter(state.typeFilter);
+        render();
+      });
+    }
+
     searchEl.addEventListener('input', () => {
       state.keyword = searchEl.value.trim().toLowerCase();
       // 搜索要全局数据：首次输入时把所有游戏补上（之后都走缓存，不再请求）
@@ -460,6 +549,8 @@ export function createRosterView({ listEl, countEl, searchEl, collapseBtn, onSel
    */
   function mount(roots, opts) {
     const restoreExpanded = !opts || opts.restoreExpanded !== false;
+    // 类型筛选：读存储原样恢复（失效项保留在集合里，渲染期再按当前类型集合筛掉）
+    state.typeFilter = new Set(readTypeFilter());
     // 同名根合并成一个游戏节点（照 char-tree.js：name 是归一 key）
     const byName = new Map();
     for (const root of roots) {

package/tool/lib/check-perms.mjs

@@ -1,114 +0,0 @@
-// tool/lib/check-perms.mjs —— 源码文件/目录权限预检（门禁）
-//
-// 为什么要这条门禁：本项目由多人/多 AI 会话并行改文件，各自 umask 不同。
-//   一旦某个 .js/.mjs/.css/.json 被写成 600，**Node 服务端（跑在另一个用户下）读不到它**
-//   ⇒ 该模块 import 失败 ⇒ 整个 app 在初始化早期崩溃（window.__WEB__ 为空、页面只构建少数元素）
-//   ⇒ 所有 e2e 套件拿不到结果、超时被杀 ⇒ 报一堆"未捕获异常"的红。
-//   这种红**全是假红**，比不跑更贵：会让人去查业务代码。已经反复发生三次，所以做成硬门禁。
-//
-// 判据：
-//   · 代码文件（js/mjs/css/json/html）必须 644（可读）
-//   · 目录必须 755（可进入、可列）
-//   · 不检查 node_modules/.git（SCAN_DIRS 已限定在源码目录内）
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-/** 需要检查权限的文件类型（只看我们自己的源码/配置） */
-const CODE_EXT = /\.(js|mjs|css|json|html)$/;
-/** 相对于项目根的扫描目录 */
-const SCAN_DIRS = ['src', 'test', 'tool', 'config', 'public'];
-/**
- * 判据不是"必须是 644"，而是「**其他用户可读**」——服务端跑在另一个用户下，只要 go+r 就够。
- *   · 文件：需要 0o004（other read）。600/640 不行；644/664/755 都行。
- *   · 目录：需要 0o005（other read+execute）。700/750 不行；755/775 都行。
- * 为什么不用精确相等：真实环境 umask 常见 002 ⇒ 664/775 是正常态，卡死它们只会制造假红。
- */
-const FILE_NEED = 0o004;
-const DIR_NEED = 0o005;
-/** 跳过的大目录（不属于源码，权限由各自包管理器管） */
-const SKIP_NAMES = new Set(['node_modules', '.git', 'dist', 'runtime']);
-
-/**
- * 找出权限不对的文件与目录。
- * @param {string} root 项目根绝对路径
- * @returns {{files: Array<{path: string, mode: string}>, dirs: Array<{path: string, mode: string}>}}
- */
-export function findBadPerms(root) {
-  const files = [];
-  const dirs = [];
-  const walk = (dir) => {
-    let entries;
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;   // 目录读不到（本身就可能是权限问题）：由上层目录检查覆盖
-    }
-    for (const entry of entries) {
-      if (SKIP_NAMES.has(entry.name)) continue;
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        const mode = modeOf(full);
-        if (mode !== null && (mode & DIR_NEED) !== DIR_NEED) dirs.push({ path: path.relative(root, full), mode: toOctal(mode) });
-        walk(full);
-        continue;
-      }
-      if (!CODE_EXT.test(entry.name)) continue;
-      const mode = modeOf(full);
-      if (mode !== null && (mode & FILE_NEED) !== FILE_NEED) files.push({ path: path.relative(root, full), mode: toOctal(mode) });
-    }
-  };
-  for (const name of SCAN_DIRS) {
-    const dir = path.join(root, name);
-    if (!fs.existsSync(dir)) continue;
-    const mode = modeOf(dir);
-    if (mode !== null && (mode & DIR_NEED) !== DIR_NEED) dirs.push({ path: name, mode: toOctal(mode) });
-    walk(dir);
-  }
-  return { files, dirs };
-}
-
-/** 取权限位（只有低 9 位有意义）；拿不到返回 null */
-function modeOf(target) {
-  try {
-    return fs.statSync(target).mode & 0o777;
-  } catch {
-    return null;
-  }
-}
-
-/** 转成可读八进制（644 / 755） */
-function toOctal(mode) {
-  return mode.toString(8);
-}
-
-/**
- * 一行话总结（供 test-all / web.sh 直接打印）。
- * @returns {string} 没问题返回空串
- */
-export function summarizeBadPerms({ files, dirs }) {
-  if (!files.length && !dirs.length) return '';
-  const lines = [
-    `源码权限不对：文件 ${files.length} 个、目录 ${dirs.length} 个`,
-    '（Node 服务端跑在另一个用户下，读不到这些文件 ⇒ 模块 import 失败 ⇒ 整个 app 崩、e2e 全部超时假红）',
-  ];
-  for (const item of files.slice(0, 12)) lines.push(`  ${item.mode}  ${item.path}`);
-  if (files.length > 12) lines.push(`  …另有 ${files.length - 12} 个文件`);
-  for (const item of dirs.slice(0, 6)) lines.push(`  ${item.mode}  ${item.path}/（目录须 755）`);
-  lines.push('修复：chmod 644 <文件…>；chmod 755 <目录…>（或 chmod -R u+rwX,go+rX src test tool config public）');
-  return lines.join('\n');
-}
-
-/** CLI 入口：node tool/lib/check-perms.mjs [项目根] —— 有问题的退出码 1 */
-if (process.argv[1] && process.argv[1].endsWith('check-perms.mjs')) {
-  // 必须用 fileURLToPath：项目路径含中文，URL.pathname 是百分号编码，直接当路径会扫空
-  const root = path.resolve(process.argv[2] || path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..'));
-  const bad = findBadPerms(root);
-  const msg = summarizeBadPerms(bad);
-  if (msg) {
-    console.error(msg);
-    process.exit(1);
-  }
-  console.log('源码权限检查通过（其他用户可读：文件 go+r / 目录 go+rx）');
-}