dsh-pighub 0.9.61 → 0.9.66

package/README.md

@@ -285,6 +285,15 @@ sha256 `30b82f48…` 与用户给的文件逐字节相同），整幅由 `GET /p
 - **草地**：只铺在给定红框里（`8.37% / 91.47% × 18.26% / 96.65%`），红框外**不铺草**；猪圈自己 `background:transparent`、
   没有描边、没有铺满全圈的叠层，所以草地与围栏之外的区域 alpha=0，直接露宿主页面底色（亮/暗两种底色都实测过）。
 - 猪圈里其余的东西（仓库小屋、踩踏土、草簇）保持原样，只是被红框裁住。逐项读数与三次真机截图见 `archive/pen-fence-art.md`。
+## 猪圈主题包
+
+猪圈的草地与围栏（远侧/近侧两层）可以整体换掉，默认外观是内置主题 `classic`。
+
+主题放 `~/.PigHub/themes/<name>/`，一个目录一个主题：`theme.json`（`geometry{grass,inner,box}` 百分比 + `fence{image,split,back,front}`，缺项逐字段回落 classic）+ 可选的 `fence-back.png` / `fence-front.png` / `grass.png` / `house.png`。
+
+三种换法：设置里选（立即生效）、把目录丢进 `~/.PigHub/themes/` 后重载、或用设置里的 **「更换主题包（.zip）…」** 选一个 zip 导入（校验失败会给出可读原因且不动现有主题）。
+
+格式细节见 `archive/pen-themes.md`。
 ## 与其他桌宠插件共存
 
 插件市场上的桌宠（例如 [dsh-pet](https://www.npmjs.com/package/dsh-pet)）都是页面级浮层，所以按同一套既有约定来：容器 `pointer-events: none`、自有 z-index 层、样式标签与类名全带 `dsh-pighub` / `.pighub-` 前缀、尊重 `prefers-reduced-motion`。

package/lib/auto-update.js

@@ -0,0 +1,126 @@
+/**
+ * 静默自动更新（用户口径 2026-11-14）：
+ *   「启动自动静默检查 npm 最新并自主静默更新到最新版本，不通知用户，不提供自动更新开关。」
+ *
+ * 三条硬约束：
+ *   1. **不打扰**：没有任何 UI、没有开关；失败只写日志。
+ *   2. **不阻塞**：调用方延迟触发、本模块内部全部 try/catch，永远 resolve。
+ *   3. **不误判**：版本比较必须是语义化的（0.9.9 < 0.9.10），不能拿字符串比。
+ *
+ * 这个模块刻意做成「依赖注入」形状：fetch / exec / 日志写入都可以被测试替换，
+ * 所以三条分支（有新版 / 已最新 / 网络失败）能在离线测试里全部覆盖。
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFile as execFileCallback } from 'node:child_process';
+
+export const PACKAGE_NAME = 'dsh-pighub';
+export const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/' + PACKAGE_NAME + '/latest';
+export const INSTALL_TIMEOUT_MS = 180 * 1000;
+
+/** 语义化版本比较：返回 -1 / 0 / 1。只比较数字段，忽略预发布后缀。 */
+export function compareSemver(a, b) {
+  const parse = (value) => String(value || '')
+    .trim()
+    .replace(/^v/i, '')
+    .split('-')[0]
+    .split('.')
+    .map((part) => {
+      const n = Number.parseInt(part, 10);
+      return Number.isFinite(n) ? n : 0;
+    });
+  const left = parse(a);
+  const right = parse(b);
+  const len = Math.max(left.length, right.length, 3);
+  for (let index = 0; index < len; index += 1) {
+    const x = left[index] || 0;
+    const y = right[index] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/** 往 ~/.PigHub/logs/auto-update.log 追加一行；任何失败都吞掉（日志不能反过来搞坏功能）。 */
+export function makeFileLogger(rootDir) {
+  const dir = join(rootDir, 'logs');
+  const file = join(dir, 'auto-update.log');
+  return (line) => {
+    try {
+      mkdirSync(dir, { recursive: true });
+      appendFileSync(file, new Date().toISOString() + ' ' + line + '\n', 'utf8');
+    } catch { /* ignore */ }
+    return file;
+  };
+}
+
+/** 读 registry 上的 latest 版本号；失败返回 null（调用方据此判「离线」）。 */
+export async function fetchLatestVersion(fetchImpl) {
+  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (!doFetch) return null;
+  try {
+    const res = await doFetch(REGISTRY_LATEST_URL, { headers: { accept: 'application/json' } });
+    if (!res || !res.ok) return null;
+    const body = await res.json();
+    const version = body && typeof body.version === 'string' ? body.version.trim() : '';
+    return version || null;
+  } catch {
+    return null;
+  }
+}
+
+/** 在 profile 目录里装指定版本；用 npm（pnpm 的 profile 目录结构里 npm 也能装到 node_modules）。 */
+function runInstall({ version, profileDir, execFileImpl }) {
+  const exec = execFileImpl || execFileCallback;
+  return new Promise((resolve) => {
+    try {
+      const child = exec(
+        process.platform === 'win32' ? 'npm.cmd' : 'npm',
+        ['install', PACKAGE_NAME + '@' + version, '--no-audit', '--no-fund', '--loglevel=error'],
+        { cwd: profileDir, timeout: INSTALL_TIMEOUT_MS, windowsHide: true, stdio: 'ignore' },
+        (error) => resolve({ ok: !error, error: error ? String(error.message || error).slice(0, 200) : '' }),
+      );
+      if (child && typeof child.unref === 'function') child.unref();
+    } catch (error) {
+      resolve({ ok: false, error: String((error && error.message) || error).slice(0, 200) });
+    }
+  });
+}
+
+/**
+ * 跑一次检查 + 可能的升级。永远 resolve，永远不抛。
+ * 返回 { status: 'current' | 'installed' | 'offline' | 'failed', ... } 供日志与测试断言。
+ */
+export async function runAutoUpdate(options = {}) {
+  const currentVersion = String(options.currentVersion || '0.0.0');
+  const profileDir = String(options.profileDir || '');
+  const writeLog = typeof options.writeLog === 'function' ? options.writeLog : () => '';
+  const fetchImpl = options.fetchImpl;
+  const execFileImpl = options.execFileImpl;
+
+  const latest = await fetchLatestVersion(fetchImpl);
+  if (!latest) {
+    writeLog('check offline_or_failed current=' + currentVersion);
+    return { status: 'offline', currentVersion, latest: null };
+  }
+
+  const compare = compareSemver(latest, currentVersion);
+  if (compare <= 0) {
+    writeLog('check up_to_date current=' + currentVersion + ' latest=' + latest);
+    return { status: 'current', currentVersion, latest };
+  }
+
+  if (!profileDir) {
+    writeLog('skip install: no profile dir (current=' + currentVersion + ' latest=' + latest + ')');
+    return { status: 'failed', currentVersion, latest, reason: 'no_profile_dir' };
+  }
+
+  writeLog('install start current=' + currentVersion + ' -> ' + latest + ' profile=' + profileDir);
+  const result = await runInstall({ version: latest, profileDir, execFileImpl });
+  if (result.ok) {
+    writeLog('install ok latest=' + latest);
+    return { status: 'installed', currentVersion, latest };
+  }
+  writeLog('install failed latest=' + latest + ' error=' + result.error);
+  return { status: 'failed', currentVersion, latest, reason: result.error };
+}

package/lib/client.js

@@ -722,10 +722,33 @@ window.__ModuleLoader__.load({
       return Math.round(value * 100) / 100;
     }
 
+    /* ---------------- 主题包（用户口径 2026-11-14） ----------------
+     * 快照里的 activeTheme 已经在宿主侧逐字段回落过 classic，所以这里只做「取到就用、取不到就用常量」。
+     * geometry 存的是 [left, top, right, bottom]（百分比），客户端内部用的是 {x0,x1,y0,y1}。 */
+    const CLASSIC_THEME_FALLBACK = { name: 'classic' };
+    function themeRect(list, fallback) {
+      if (!Array.isArray(list) || list.length !== 4) return fallback;
+      const [left, top, right, bottom] = list.map((n) => Number(n));
+      if (![left, top, right, bottom].every((n) => Number.isFinite(n)) || !(left < right) || !(top < bottom)) return fallback;
+      return { x0: left, x1: right, y0: top, y1: bottom };
+    }
+    /** 主题里某一张图的 URL；没有就用包内那张默认布景（观感与主题化之前完全一致）。 */
+    function themeFenceUrl(theme, which) {
+      const name = theme && theme.name ? String(theme.name) : 'classic';
+      const fence = (theme && theme.fence) || {};
+      const file = (which === 'front' ? fence.front : fence.back) || fence.image || '';
+      if (!file) return '/pighub/pen/pen-fence.png';
+      return '/pighub/theme/' + encodeURIComponent(name) + '/' + encodeURIComponent(String(file));
+    }
+
     /** 一层栅栏：裁剪盒只决定「看得到哪一半」，盒里的 shot 永远是整张图、贴在猪圈的位置上。 */
     function PenFence(props) {
       const front = !!(props && props.front);
-      const split = penRound(PEN_FENCE_SPLIT);
+      const theme = (props && props.theme) || CLASSIC_THEME_FALLBACK;
+      const splitRatio = theme.fence && Number(theme.fence.split);
+      const split = penRound(Number.isFinite(splitRatio) && splitRatio > 0.05 && splitRatio < 0.95
+        ? splitRatio * 100
+        : PEN_FENCE_SPLIT);
       return h('div', {
         className: 'pighub-fence ' + (front ? 'is-front' : 'is-back'),
         style: front ? { top: split + '%', bottom: 0 } : { top: 0, height: split + '%' },
@@ -733,7 +756,7 @@ window.__ModuleLoader__.load({
       },
         h('div', {
           className: 'pighub-fence-shot',
-          style: { backgroundImage: 'url("' + PEN_FENCE_URL + '")' },
+          style: { backgroundImage: 'url("' + themeFenceUrl(theme, front ? 'front' : 'back') + '")' },
         }),
       );
     }
@@ -772,9 +795,11 @@ window.__ModuleLoader__.load({
       return blade(-0.45, 1.5, 0.45) + ' ' + blade(0.05, 2.05, 0.9) + ' ' + blade(0.55, 1.25, 0.3);
     }
 
-    function Meadow() {
-      const G = PEN_GRASS;
-      const I = PEN_INNER;
+    function Meadow(props) {
+      const theme = (props && props.theme) || CLASSIC_THEME_FALLBACK;
+      const geo = theme.geometry || {};
+      const G = themeRect(geo.grass, PEN_GRASS);
+      const I = themeRect(geo.inner, PEN_INNER);
       const gw = G.x1 - G.x0;
       const gh = G.y1 - G.y0;
       /* SVG 的坐标系仍然是「猪圈 0..100」（草簇/波浪的坐标不用改），
@@ -1523,6 +1548,10 @@ window.__ModuleLoader__.load({
         setTimeout(() => setSquished((list) => list.filter((item) => item !== id)), 600);
       };
       const starMode = (data && data.prefs && data.prefs.starDisplay) || 'hover';
+      /* 当前主题（快照里的 activeTheme 已在宿主侧回落过 classic）：
+       * 设置浮层要画选择器、猪圈的栅栏与草地要吃几何，所以在这里定义一次、全文共用。
+       * 注意必须在使用之前——设置浮层比 poolAll 那段构造得更早，放后面会踩 const 的 TDZ。 */
+      const activeTheme = (data && data.activeTheme) || { name: 'classic' };
 
       /* 设置浮层。星级显示三档改的是 prefs，落盘在 Host 半，所以刷新/换机器后仍然生效。 */
       const [settingsOpen, setSettingsOpen] = useState(false);
@@ -1659,6 +1688,56 @@ window.__ModuleLoader__.load({
                 ),
               ),
               h('div', { className: 'row' }, h('span', null, '默认：划过猪猪显示 5 秒；常驻：一直显示在它上方')),
+              /* 猪圈主题（用户口径 2026-11-14）：列出快照里的 themes（内置 classic 永远第一 + ~/.PigHub/themes 下的目录），
+               * 点一下走 {action:'theme'}，宿主落 prefs；rev 令牌带 theme，所以切换后立刻重取快照、不用重载插件。 */
+              h('h4', null, '猪圈主题'),
+              h('div', { className: 'pighub-seg' },
+                ((data && data.themes) || [{ name: 'classic', title: 'classic（默认）' }]).map((item) =>
+                  h('button', {
+                    key: 'theme-' + item.name,
+                    type: 'button',
+                    'aria-pressed': activeTheme.name === item.name ? 'true' : 'false',
+                    title: item.title || item.name,
+                    onClick: () => { request({ action: 'theme', name: item.name }).then(apply).catch(() => {}); },
+                  }, item.title || item.name),
+                ),
+              ),
+              /* 「更换主题包」：用隐藏的 <input type=file accept=.zip> 唤起系统文件选择器（Electron 里就是原生对话框），
+               * 选中的 zip 原样 POST 到 /pighub/theme-import；宿主校验并解压后**自动切到新主题**，这里只负责刷新快照。 */
+              h('div', { className: 'row' },
+                h('span', null, '主题包放在 ' + ((data && data.root) || '~/.PigHub') + '\\themes 下，或从 zip 导入'),
+              ),
+              h('label', { className: 'pighub-ghostbtn', style: { display: 'inline-block', marginTop: '6px', cursor: 'pointer' } },
+                '更换主题包（.zip）…',
+                h('input', {
+                  type: 'file',
+                  accept: '.zip,application/zip',
+                  style: { display: 'none' },
+                  onChange: (event) => {
+                    const input = event && event.target;
+                    const file = input && input.files && input.files[0];
+                    if (!file) return;
+                    const finish = () => { if (input) input.value = ''; };
+                    // 走状态路由上的 action（不走单独的 /theme-import：宿主的 exact 路由按前缀先命中，
+                    // 二进制会被状态路由当 JSON 解析）。base64 多 33%，但一定命中。
+                    file.arrayBuffer()
+                      .then((buffer) => {
+                        let binary = '';
+                        const bytes = new Uint8Array(buffer);
+                        for (let i = 0; i < bytes.length; i += 1) binary += String.fromCharCode(bytes[i]);
+                        return fetch(ROUTE, {
+                          method: 'POST',
+                          headers: { 'content-type': 'application/json' },
+                          body: JSON.stringify({ action: 'theme-import', zipBase64: btoa(binary) }),
+                        });
+                      })
+                      .then((response) => response.json())
+                      .then((payload) => { if (payload && payload.ok) apply(payload); })
+                      .catch(() => {})
+                      .then(finish);
+                  },
+                }),
+              ),
               // 客户端版本号：面板里能看到，用来确认浏览器半真的换上了新 bundle。
               h('div', { className: 'row' }, h('span', null, '插件版本：v' + ((data && data.version) || '?'))),
               h('h4', null, '素材库（本版本冻结）'),
@@ -1768,6 +1847,8 @@ window.__ModuleLoader__.load({
       /* 图鉴：池子里每一只都列出来；没拿到的是暗色剪影 + 「？？？」。 */
       const ownedIds = {};
       for (const pig of (data && data.pigs) || []) ownedIds[pig.id] = pig;
+      /* 当前主题（快照里的 activeTheme 已在宿主侧回落过 classic）：养在这里，供栅栏/草地/小屋共用。 */
+      const theme = activeTheme;
       // 已获取的排前面（否则 256 格里很难找到自己的猪），未获取的保持原序
       const poolAll = (data && data.pool) || [];
       const pool = poolAll
@@ -1810,9 +1891,9 @@ window.__ModuleLoader__.load({
         revealLayer,
         h('div', { className: 'pighub-left' },
           h('div', { className: 'pighub-pen', ref: penRef },
-            h(Meadow, null),
+            h(Meadow, { theme }),
             // 远侧栅栏（顶横梁 + 上角草石 + 侧栏上半）：画在猪的后面（z1）
-            h(PenFence, { key: 'fence-back' }),
+            h(PenFence, { key: 'fence-back', theme }),
             h('div', { className: 'pighub-house', ref: houseRef, title: '把小猪拖进来收进仓库（不再加载）' },
               h(HouseArt, null),
             ),
@@ -1881,7 +1962,7 @@ window.__ModuleLoader__.load({
                 }),
             // 近侧栅栏（底横梁 + 下角草石 + 侧栏下半）：最后画 → 压在猪身上（z4），
             // 走到底边的猪被挡住一截，这就是「景深」。
-            h(PenFence, { key: 'fence-front', front: true }),
+            h(PenFence, { key: 'fence-front', front: true, theme }),
           ),
         ),
         h('div', { className: 'pighub-right' },

package/lib/index.js

@@ -12,9 +12,12 @@
  * 服务依赖只声明 tools（工具表身份）；webServer 按需查找——写进 inject 会让没有 Web 的
  * profile 整个启动失败（dsh: 1 entry did not activate），一个只少了面板的插件不该有那个权力。
  */
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync, rmSync, renameSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { runAutoUpdate, makeFileLogger } from './auto-update.js';
+import { THEME_ROUTE, CLASSIC_THEME_NAME, listThemes, readThemeDir, themeAssetPath } from './themes.js';
+import { readZip, isSafeZipName } from './zip.js';
 import { extname } from 'node:path';
 import { readAssetManifest, assetPool, assetSummary, assetUrlOf, IMAGE_DIR, ASSET_ROUTE, PEN_ROUTE, PEN_ART } from './assets.js';
 import {
@@ -40,7 +43,7 @@ export const inject = ['tools'];
 import { startDesktopPet, stopDesktopPet, syncDesktopPet, desktopPetState, sayOnDesktop, reclaimStaleSessions } from './desktop-pet.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const VERSION = '0.9.61';
+const VERSION = '0.9.66';
 /** 桌面桌宠的精灵边长（CSS px 基准，= manifest 里 sizeRatio 的中位数）。 */
 const DESKTOP_PET_SIZE = 96;
 /** 全局尺寸系数（用户口径 2026-11-13：「整体猪猪缩小到 75% 大小」）。三层一起乘。 */
@@ -195,7 +198,16 @@ function snapshot(root, { sort, note } = {}) {
     // 当前下发给原生窗口的猪圈屏幕矩形（物理像素）；null 表示浏览器半还没报过。
     penRect: penRectOnScreen,
     sort: prefs.sort,
-    prefs,
+    // prefs.theme 缺省即 classic（用户口径：现有外观是默认主题）
+    prefs: Object.assign({}, prefs, { theme: prefs.theme || CLASSIC_THEME_NAME }),
+    // 设置面板要的主题列表：内置 classic 永远第一，然后是 ~/.PigHub/themes 下的目录
+    themes: listThemes(join(here, '..', 'assets', 'themes'), join(root, 'themes')),
+    /* 当前生效的主题**完整定义**（几何 + 布景文件名）：客户端据此注入 CSS 变量与图片 URL。
+     * 主题缺失/损坏时 readThemeDir 会逐字段回落 classic，所以这里拿到的一定是可用值。 */
+    activeTheme: readThemeDir(
+      join(root, 'themes', prefs.theme || CLASSIC_THEME_NAME),
+      prefs.theme || CLASSIC_THEME_NAME,
+    ),
     draws: state.draws,
     assets: assetSummary(manifest),
     note: note || '',
@@ -269,6 +281,56 @@ export function pickSayPet(ids, random = Math.random) {
 export function apply(ctx, config) {
   const root = (config && typeof config.root === 'string' && config.root.trim()) || resolveRoot();
 
+  /* ---------------- 主题包（用户口径 2026-11-14） ---------------- */
+  /** 包内主题目录（classic 在这里）与用户主题目录（~/.PigHub/themes）。 */
+  const themeRoot = join(here, '..', 'assets', 'themes');
+  const userThemesDir = join(root, 'themes');
+  const themeMime = (file) => {
+    const ext = extname(String(file || '')).toLowerCase();
+    if (ext === '.png') return 'image/png';
+    if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+    if (ext === '.webp') return 'image/webp';
+    if (ext === '.svg') return 'image/svg+xml';
+    return 'application/octet-stream';
+  };
+  /** 扫出「主题名 → 该主题目录下的图片文件名」，用于逐张注册 exact 路由。 */
+  const themeFileNames = () => {
+    const out = [];
+    const push = (name, dir) => {
+      const files = [];
+      try {
+        for (const file of readdirSync(dir)) {
+          if (/\.(png|jpg|jpeg|webp|svg)$/i.test(file)) files.push(file);
+        }
+      } catch { /* 目录不存在就当没有图 */ }
+      if (files.length) out.push({ name, files });
+    };
+    push(CLASSIC_THEME_NAME, join(themeRoot, CLASSIC_THEME_NAME));
+    // classic 也可以直接引用包内 assets/img 里的布景图（现有那张 pen-fence.png 就在那）
+    out.push({ name: CLASSIC_THEME_NAME, files: PEN_ART.slice() });
+    try {
+      for (const entry of readdirSync(userThemesDir)) {
+        if (entry === CLASSIC_THEME_NAME) continue;
+        push(entry, join(userThemesDir, entry));
+      }
+    } catch { /* 没有用户主题 */ }
+    // 去重（同一主题同一文件只注册一次，否则 exact 路由会重复）
+    const seen = new Set();
+    return out
+      .flatMap((group) => group.files.map((file) => ({ name: group.name, file })))
+      .filter(({ name, file }) => {
+        const key = name + '/' + file;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      })
+      .reduce((acc, { name, file }) => {
+        const hit = acc.find((g) => g.name === name);
+        if (hit) hit.files.push(file); else acc.push({ name, files: [file] });
+        return acc;
+      }, []);
+  };
+
   // 原生桌宠开关：config.desktopPet === false 时完全不碰原生进程（离线测试/不想要桌宠的 profile 用）。
   const nativePetEnabled = !(config && config.desktopPet === false);
   const log = { warn: (message) => { try { ctx.logger?.warn?.(message); } catch { /* 日志失败不影响功能 */ } } };
@@ -286,6 +348,41 @@ export function apply(ctx, config) {
   /** 本次 apply 的 unload 旗子：置位后启动链/同步路径一律不再拉起进程（模块实例会跨 enable/disable 复用）。 */
   let stopped = false;
 
+  /* ---------------- 静默自动更新（用户口径 2026-11-14：不通知、不提供开关） ----------------
+   * 延迟 15s 跑一次（避开启动抢资源），每次 enable 只跑一次；失败静默，只写 ~/.PigHub/logs/auto-update.log。
+   * 不自动重启宿主：装好之后，下次宿主启动/插件重载自然生效。 */
+  const autoUpdateDelayMs = 15000;
+  let autoUpdateTimer = null;
+  const scheduleAutoUpdate = () => {
+    // 没有 profile 目录就无从安装；离线测试里 profileDir 为空时这一步直接跳过（只记日志）。
+    const profileDir = (() => {
+      try {
+        const candidate = typeof config?.profileDir === 'string' ? config.profileDir : '';
+        if (candidate) return candidate;
+        // 从插件自身路径反推：<profile>/node_modules/dsh-pighub/lib/index.js → <profile>
+        return join(here, '..', '..', '..');
+      } catch { return ''; }
+    })();
+    autoUpdateTimer = setTimeout(() => {
+      autoUpdateTimer = null;
+      if (stopped) return;
+      Promise.resolve()
+        .then(() => runAutoUpdate({
+          currentVersion: VERSION,
+          profileDir,
+          writeLog: makeFileLogger(root),
+        }))
+        .catch(() => { /* runAutoUpdate 自己不会抛；这里再兜一层 */ });
+    }, autoUpdateDelayMs);
+    if (autoUpdateTimer && typeof autoUpdateTimer.unref === 'function') autoUpdateTimer.unref();
+  };
+  ctx.effect(() => {
+    scheduleAutoUpdate();
+    return () => {
+      if (autoUpdateTimer) { clearTimeout(autoUpdateTimer); autoUpdateTimer = null; }
+    };
+  }, 'pighub-auto-update');
+
   /** 把当前 state 同步给原生窗口；没有桌面猪就停掉进程（不留在后台）。 */
   const syncNativePet = () => {
     if (!nativePetEnabled) return { ok: true, disabled: true };
@@ -393,9 +490,59 @@ export function apply(ctx, config) {
           try {
             if (req.method === 'GET') { sendJson(res, 200, snapshot(root)); return; }
             if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method_not_allowed' }); return; }
-            const body = await readBody(req);
+            /* 状态路由的 body 上限提到 24 MB：主题包导入是 base64（738 KB 的 zip → 约 1 MB 的报文），
+             * 默认 64 KB 会把它判成 body_too_large。这是个只监听回环的本地服务，放宽是安全的。 */
+            const body = await readBody(req, 24 * 1024 * 1024);
             const action = typeof body.action === 'string' ? body.action : 'state';
 
+            /* 主题包导入走**状态路由上的 action**（用户口径 2026-11-14）。
+             * 为什么不另开 /pighub/theme-import：宿主的 exact 路由按前缀先命中，二进制 zip 会被
+             * 这条状态路由抢走当 JSON 解析（实测报 "Unexpected token 'P'"，P 就是 zip 魔数 PK）。
+             * base64 多 33% 传输，换来路由一定命中。 */
+            if (action === 'theme-import') {
+              const b64 = typeof body.zipBase64 === 'string' ? body.zipBase64 : '';
+              if (!b64) { sendJson(res, 200, { ok: false, error: 'empty_body' }); return; }
+              let raw = null;
+              try { raw = Buffer.from(b64, 'base64'); } catch { raw = null; }
+              if (!raw || !raw.length) { sendJson(res, 200, { ok: false, error: 'bad_base64' }); return; }
+              const parsed = readZip(raw);
+              if (!parsed.ok) { sendJson(res, 200, { ok: false, error: parsed.reason }); return; }
+              const jsonEntry = parsed.files.find((file) => /(^|\/)theme\.json$/i.test(file.name));
+              if (!jsonEntry) { sendJson(res, 200, { ok: false, error: 'theme_json_missing' }); return; }
+              const prefix = jsonEntry.name.replace(/theme\.json$/i, '');
+              let meta;
+              try { meta = JSON.parse(jsonEntry.data.toString('utf8')); } catch { sendJson(res, 200, { ok: false, error: 'theme_json_invalid' }); return; }
+              const themeName = String(meta && meta.name ? meta.name : prefix.replace(/\/$/, '')).trim();
+              if (!/^[a-zA-Z0-9._-]{1,48}$/.test(themeName) || themeName === CLASSIC_THEME_NAME) {
+                sendJson(res, 200, { ok: false, error: 'theme_name_invalid', name: themeName });
+                return;
+              }
+              const targetDir = join(userThemesDir, themeName);
+              const staging = join(userThemesDir, '.' + themeName + '.tmp-' + Date.now());
+              try {
+                rmSync(staging, { recursive: true, force: true });
+                mkdirSync(staging, { recursive: true });
+                for (const file of parsed.files) {
+                  const rel = file.name.startsWith(prefix) ? file.name.slice(prefix.length) : file.name;
+                  if (!rel || rel.endsWith('/')) continue;
+                  if (!/\.(json|png|jpg|jpeg|webp|svg)$/i.test(rel)) continue;
+                  if (!isSafeZipName(rel)) { sendJson(res, 200, { ok: false, error: 'unsafe_entry_name', name: file.name }); return; }
+                  const target = join(staging, rel);
+                  mkdirSync(dirname(target), { recursive: true });
+                  writeFileSync(target, file.data);
+                }
+                rmSync(targetDir, { recursive: true, force: true });
+                renameSync(staging, targetDir);
+              } catch (error) {
+                try { rmSync(staging, { recursive: true, force: true }); } catch { /* ignore */ }
+                sendJson(res, 200, { ok: false, error: 'write_failed', detail: String((error && error.message) || error).slice(0, 120) });
+                return;
+              }
+              const nextPrefs2 = writePrefs(root, { theme: themeName });
+              sendJson(res, 200, { ...snapshot(root), ok: true, theme: themeName, prefs: nextPrefs2 });
+              return;
+            }
+
             if (action === 'state') { sendJson(res, 200, snapshot(root)); return; }
 
             /*
@@ -412,6 +559,20 @@ export function apply(ctx, config) {
              * **位置(pos)故意不进令牌**：猪圈里每只猪每 ~1.7 s 就写一次 pos，进令牌等于让客户端
              * 每 1.7 s 拉一张 38 KB 的快照；位置仍由客户端自己写、并由 10 s 的整张快照兜底对齐。
              */
+            /* 切换主题：只落 prefs，不碰 state；客户端下一次对账（rev 变化）就会重新取几何与图片。 */
+            if (action === 'theme') {
+              const wanted = String(body.name || '').trim();
+              const known = listThemes(join(here, '..', 'assets', 'themes'), join(root, 'themes'))
+                .some((item) => item.name === wanted);
+              if (!known) {
+                sendJson(res, 200, { ...snapshot(root), ok: false, error: 'unknown_theme', name: wanted });
+                return;
+              }
+              const nextPrefs = writePrefs(root, { theme: wanted });
+              sendJson(res, 200, { ...snapshot(root), ok: true, theme: wanted, prefs: nextPrefs });
+              return;
+            }
+
             if (action === 'rev') {
               const state = readState(root);
               const prefs = readPrefs(root);
@@ -430,6 +591,7 @@ export function apply(ctx, config) {
                   pigs,
                   prefs.sort || '',
                   prefs.starDisplay || '',
+                  prefs.theme || CLASSIC_THEME_NAME,
                   currentManifest().assetVersion || '',
                   desktopPetState().running ? 'run' : 'idle',
                 ].join('|'),
@@ -611,6 +773,70 @@ export function apply(ctx, config) {
       effectName,
     );
   }
+  /* ---------------- 主题包导入（zip） ----------------
+   * 客户端把用户选中的 .zip 原样 POST 到这个 exact 路由（不走 JSON/base64，省一次 33% 膨胀）。
+   * 校验顺序：大小上限 → zip 结构 → theme.json 存在且可解析 → 文件名白名单 → 原子落盘。
+   * 任何一步失败都返回可读原因，并且**不动现有主题**。 */
+  if (webServer) {
+    const THEME_IMPORT_MAX = 12 * 1024 * 1024;
+    ctx.effect(
+      () =>
+        webServer.register({
+          kind: 'exact',
+          path: ROUTE + '/theme-import',
+          handler: async (req, res) => {
+            try {
+              if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method_not_allowed' }); return; }
+              const body = await readBody(req, THEME_IMPORT_MAX);
+              if (!body || !body.length) { sendJson(res, 200, { ok: false, error: 'empty_body' }); return; }
+              const parsed = readZip(body);
+              if (!parsed.ok) { sendJson(res, 200, { ok: false, error: parsed.reason }); return; }
+              // theme.json 可能在根上，也可能在一个顶层目录里（Windows 的 Compress-Archive 会包一层）
+              const jsonEntry = parsed.files.find((file) => /(^|\/)theme\.json$/i.test(file.name));
+              if (!jsonEntry) { sendJson(res, 200, { ok: false, error: 'theme_json_missing' }); return; }
+              const prefix = jsonEntry.name.replace(/theme\.json$/i, '');
+              let raw;
+              try { raw = JSON.parse(jsonEntry.data.toString('utf8')); } catch { sendJson(res, 200, { ok: false, error: 'theme_json_invalid' }); return; }
+              const themeName = String(raw && raw.name ? raw.name : prefix.replace(/\/$/, '')).trim() || 'imported';
+              if (!/^[a-zA-Z0-9._-]{1,48}$/.test(themeName) || themeName === CLASSIC_THEME_NAME) {
+                sendJson(res, 200, { ok: false, error: 'theme_name_invalid', name: themeName });
+                return;
+              }
+              // 只落这个主题目录里的文件，且文件名必须安全
+              const targetDir = join(userThemesDir, themeName);
+              const staging = join(userThemesDir, '.' + themeName + '.tmp-' + Date.now());
+              try {
+                rmSync(staging, { recursive: true, force: true });
+                mkdirSync(staging, { recursive: true });
+                for (const file of parsed.files) {
+                  const rel = file.name.startsWith(prefix) ? file.name.slice(prefix.length) : file.name;
+                  if (!rel || rel.endsWith('/')) continue;
+                  if (!/\.(json|png|jpg|jpeg|webp|svg)$/i.test(rel)) continue;
+                  if (!isSafeZipName(rel)) { sendJson(res, 200, { ok: false, error: 'unsafe_entry_name', name: file.name }); return; }
+                  const target = join(staging, rel);
+                  mkdirSync(dirname(target), { recursive: true });
+                  writeFileSync(target, file.data);
+                }
+                rmSync(targetDir, { recursive: true, force: true });
+                renameSync(staging, targetDir);
+              } catch (error) {
+                try { rmSync(staging, { recursive: true, force: true }); } catch { /* ignore */ }
+                sendJson(res, 200, { ok: false, error: 'write_failed', detail: String((error && error.message) || error).slice(0, 120) });
+                return;
+              }
+              // 成功后自动切到新主题（用户口径：成功后自动切换并立即可见）
+              const nextPrefs = writePrefs(root, { theme: themeName });
+              sendJson(res, 200, { ...snapshot(root), ok: true, theme: themeName, prefs: nextPrefs });
+            } catch (error) {
+              const message = error && error.message ? String(error.message) : 'internal_error';
+              try { sendJson(res, 500, { ok: false, error: message }); } catch { /* 已结束 */ }
+            }
+          },
+        }),
+      'pighub-theme-import',
+    );
+  }
+
   if (webServer) {
     // 路由按**全部**素材注册：incomplete 的猪只是不进抽池，已拥有它的用户还要能看到它。
     for (const pig of fullPool.images) {
@@ -619,6 +845,44 @@ export function apply(ctx, config) {
     }
     // 猪圈布景（木栅栏）：不是素材库的一部分，单独一条前缀，别让「每只猪一条路由」的断言变味。
     for (const artFile of PEN_ART) registerStaticImage(PEN_ROUTE, artFile, 'pighub-pen-art-' + artFile);
+    /* 主题包的图片：**逐张注册 exact 路由**（宿主只证实了 exact 这一种 kind）。
+     * 主题目录在启动时扫一遍；运行中新丢进来的主题要重载插件才认得——这一点写进 README。 */
+    for (const themeName of themeFileNames()) {
+      for (const file of themeName.files) {
+        const id = 'pighub-theme-' + themeName.name + '-' + file;
+        ctx.effect(
+          () =>
+            webServer.register({
+              kind: 'exact',
+              path: THEME_ROUTE + '/' + themeName.name + '/' + file,
+              handler: async (req, res) => {
+                try {
+                  if (req.method !== 'GET') { sendJson(res, 405, { ok: false, error: 'method_not_allowed' }); return; }
+                  const file2 = themeAssetPath({
+                    name: themeName.name,
+                    file,
+                    builtinDir: join(themeRoot, CLASSIC_THEME_NAME),
+                    userThemesDir,
+                  });
+                  if (!file2) { sendJson(res, 404, { ok: false, error: 'theme_asset_not_found' }); return; }
+                  const body = readFileSync(file2);
+                  res.writeHead(200, {
+                    'content-type': themeMime(file),
+                    'content-length': String(body.length),
+                    'cache-control': 'private, no-cache, must-revalidate',
+                    'x-content-type-options': 'nosniff',
+                  });
+                  res.end(body);
+                } catch (error) {
+                  const message = error && error.message ? String(error.message) : 'internal_error';
+                  try { sendJson(res, 500, { ok: false, error: message }); } catch { /* 已结束 */ }
+                }
+              },
+            }),
+          id,
+        );
+      }
+    }
   }
   ctx.effect(
     () =>

package/lib/store.js

@@ -22,7 +22,7 @@ import { join, dirname } from 'node:path';
  * 为什么要有：素材会被补全/替换，但 URL 一直相同，浏览器就会一直显示旧图——
  * 用户 2026-11-13 报「猪圈里的斗鸡眼猪还是只有头、桌宠是全身」就是这个问题。
  * 每次发版改这里，旧的图片缓存自然失效。 */
-const ASSET_TAG = '0961';   // 与 package.json / index.js 的 VERSION 同步（发版 +1；0.9.56 之前漏改，仍是 0955）
+const ASSET_TAG = '0962';   // 与 package.json / index.js 的 VERSION 同步（发版 +1；0.9.56 之前漏改，仍是 0955）
 /* 幂等：先去干净再挂一次。
  * 为什么不幂等会出事（2026-11-13 实测）：readState() 每次读都调它，writeState() 又把结果落盘，
  * 于是每读一次 URL 就多一个 v=0955。真机 state.json 里三个 URL 各带 **352 个** v=0955、
@@ -386,7 +386,12 @@ export function listPigs(state, sort = 'time') {
 function normalisePrefs(raw) {
   const sort = raw && SORTS.includes(raw.sort) ? raw.sort : 'time';
   const starDisplay = raw && STAR_DISPLAY.includes(raw.starDisplay) ? raw.starDisplay : STAR_DISPLAY_DEFAULT;
-  return { sort, starDisplay };
+  // 主题包（用户口径 2026-11-14）：名字只允许安全字符；缺省 classic。
+  // 注意：这个函数是 prefs 的**唯一白名单**——不加进来，writePrefs({theme}) 会被静默丢弃。
+  const theme = raw && typeof raw.theme === 'string' && /^[a-zA-Z0-9._-]{1,48}$/.test(raw.theme)
+    ? raw.theme
+    : 'classic';
+  return { sort, starDisplay, theme };
 }
 
 export function readPrefs(root) {

package/lib/themes.js

@@ -0,0 +1,118 @@
+/**
+ * 猪圈主题包（用户口径 2026-11-14）：
+ *   「将猪圈主题配置（草地、栏杆-前后左右）打包并开发自定义，在设置中更换，主题包保存在 .PigHub。」
+ *
+ * 结构：一个目录 = 一个主题
+ *   ~/.PigHub/themes/<name>/
+ *     theme.json   { name?, title?, author?, version?, geometry?{grass,inner,box}, fence?{image?,split?,back?,front?}, grassImage?, house? }
+ *     fence-back.png / fence-front.png / grass.png / house.png（都可以缺）
+ *
+ * 原则：
+ *   1. **内置 classic 必须永远可用**——外部主题缺字段、缺图、JSON 坏掉，一律回落它，绝不白屏；
+ *   2. geometry 是**百分比**（与 client 里 PEN_GRASS/PEN_INNER/PEN_BOX 同构），缺省就用 classic 的值；
+ *   3. 这个模块只做「读 + 校验 + 归一」，不碰 DOM、不碰路由（路由在 index.js）。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const THEME_ROUTE = '/pighub/theme';
+export const CLASSIC_THEME_NAME = 'classic';
+
+/** classic 的几何：与 lib/client.js 的 PEN_GRASS / PEN_INNER / PEN_BOX 完全一致（改这里就必须同步改那边）。 */
+export const CLASSIC_GEOMETRY = {
+  grass: [8.37, 18.26, 91.47, 96.65],
+  inner: [13.40, 19.70, 86.60, 81.74],
+  box: [24.04, 29.16, 75.96, 72.28],
+};
+
+/** classic 的布景：用包内那一张 pen-fence.png，按 50.68% 切成远/近两层。 */
+export const CLASSIC_FENCE = { image: 'pen-fence.png', split: 0.5068 };
+
+/** 主题里允许的图片文件名（防穿越：不许 ../、不许绝对路径）。 */
+const SAFE_FILE = /^[a-zA-Z0-9._-]+\.(png|jpg|jpeg|webp|svg)$/;
+
+function normaliseRect(value, fallback) {
+  if (!Array.isArray(value) || value.length !== 4) return fallback.slice();
+  const nums = value.map((n) => Number(n));
+  if (nums.some((n) => !Number.isFinite(n))) return fallback.slice();
+  // 百分比一律夹到 0..100，且保证 left<right / top<bottom，否则回落（坏数据不该把猪圈画崩）
+  const [left, top, right, bottom] = nums.map((n) => Math.min(100, Math.max(0, n)));
+  if (!(left < right) || !(top < bottom)) return fallback.slice();
+  return [left, top, right, bottom];
+}
+
+/** 把任意 theme.json 归一成「一定可用」的形状；坏字段逐项回落 classic。 */
+export function normaliseTheme(raw, name) {
+  const source = raw && typeof raw === 'object' ? raw : {};
+  const geometry = source.geometry && typeof source.geometry === 'object' ? source.geometry : {};
+  const fence = source.fence && typeof source.fence === 'object' ? source.fence : {};
+  const split = Number(fence.split);
+  return {
+    name: String(source.name || name || CLASSIC_THEME_NAME),
+    title: String(source.title || name || CLASSIC_THEME_NAME),
+    author: typeof source.author === 'string' ? source.author : '',
+    version: typeof source.version === 'string' ? source.version : '',
+    geometry: {
+      grass: normaliseRect(geometry.grass, CLASSIC_GEOMETRY.grass),
+      inner: normaliseRect(geometry.inner, CLASSIC_GEOMETRY.inner),
+      box: normaliseRect(geometry.box, CLASSIC_GEOMETRY.box),
+    },
+    fence: {
+      image: SAFE_FILE.test(String(fence.image || '')) ? String(fence.image) : CLASSIC_FENCE.image,
+      back: SAFE_FILE.test(String(fence.back || '')) ? String(fence.back) : '',
+      front: SAFE_FILE.test(String(fence.front || '')) ? String(fence.front) : '',
+      split: Number.isFinite(split) && split > 0.05 && split < 0.95 ? split : CLASSIC_FENCE.split,
+    },
+    grassImage: SAFE_FILE.test(String(source.grassImage || '')) ? String(source.grassImage) : '',
+    houseImage: source.house && SAFE_FILE.test(String(source.house.image || '')) ? String(source.house.image) : '',
+  };
+}
+
+/** 读一个主题目录；theme.json 坏掉/缺失就返回 classic 的形状（不抛）。 */
+export function readThemeDir(dir, name) {
+  const fallback = normaliseTheme({}, name);
+  try {
+    if (!dir || !existsSync(dir)) return fallback;
+    const jsonPath = join(dir, 'theme.json');
+    if (!existsSync(jsonPath)) return fallback;
+    const raw = JSON.parse(readFileSync(jsonPath, 'utf8'));
+    return normaliseTheme(raw, name);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * 列主题：内置 classic 永远排第一，然后是 ~/.PigHub/themes 下的目录（按名字排序）。
+ * 每个条目只有 name/title，够设置面板渲染；完整定义由 readThemeDir 再读。
+ */
+export function listThemes(builtinDir, userThemesDir) {
+  const seen = new Set([CLASSIC_THEME_NAME]);
+  const items = [{ name: CLASSIC_THEME_NAME, title: 'classic（默认）', builtin: true }];
+  try {
+    if (userThemesDir && existsSync(userThemesDir)) {
+      for (const entry of readdirSync(userThemesDir)) {
+        if (seen.has(entry)) continue;
+        const dir = join(userThemesDir, entry);
+        let isDir = false;
+        try { isDir = statSync(dir).isDirectory(); } catch { isDir = false; }
+        if (!isDir) continue;
+        seen.add(entry);
+        const theme = readThemeDir(dir, entry);
+        items.push({ name: entry, title: theme.title || entry, builtin: false });
+      }
+    }
+  } catch { /* 目录读不了就当没有外部主题 */ }
+  return items;
+}
+
+/** 主题图片的绝对路径；找不到返回 null（路由据此 404，客户端回落到 classic）。 */
+export function themeAssetPath({ name, file, builtinDir, userThemesDir }) {
+  if (!SAFE_FILE.test(String(file || ''))) return null;
+  if (name && name !== CLASSIC_THEME_NAME) {
+    const candidate = join(userThemesDir || '', String(name), String(file));
+    if (userThemesDir && existsSync(candidate)) return candidate;
+  }
+  const builtin = join(builtinDir || '', String(file));
+  return existsSync(builtin) ? builtin : null;
+}

package/lib/zip.js

@@ -0,0 +1,77 @@
+/**
+ * 最小 ZIP 读取器（主题包以 zip 分发，用户口径 2026-11-14）。
+ *
+ * 不引依赖：包要能离线安装。只支持现实中会遇到的两种存储方式：
+ *   0 STORED（不压缩）、8 DEFLATE（node:zlib 的 inflateRawSync 正好对应裸 deflate）。
+ * 其余算法一律拒绝并给出可读原因。
+ *
+ * 安全：三道上限（条目数 / 单文件 / 解压总量）防 zip 炸弹；名字不许穿越或绝对路径。
+ */
+import { inflateRawSync } from 'node:zlib';
+
+export const ZIP_LIMITS = { entries: 500, fileBytes: 8 * 1024 * 1024, totalBytes: 40 * 1024 * 1024 };
+
+function findEocd(buffer) {
+  const min = Math.max(0, buffer.length - 66000);
+  for (let offset = buffer.length - 22; offset >= min; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === 0x06054b50) return offset;
+  }
+  return -1;
+}
+
+export function isSafeZipName(name) {
+  const value = String(name || '').replace(/\\/g, '/');
+  if (!value || value.startsWith('/') || /^[a-zA-Z]:/.test(value)) return false;
+  const parts = value.split('/').filter(Boolean);
+  return parts.length > 0 && parts.every((part) => part !== '..' && part !== '.');
+}
+
+export function readZip(buffer) {
+  try {
+    if (!buffer || buffer.length < 22) return { ok: false, reason: 'empty_or_too_small', files: [] };
+    const eocd = findEocd(buffer);
+    if (eocd < 0) return { ok: false, reason: 'not_a_zip', files: [] };
+    const count = buffer.readUInt16LE(eocd + 10);
+    const cdOffset = buffer.readUInt32LE(eocd + 16);
+    if (count === 0) return { ok: false, reason: 'zip_has_no_entries', files: [] };
+    if (count > ZIP_LIMITS.entries) return { ok: false, reason: 'too_many_entries', files: [] };
+    const files = [];
+    let total = 0;
+    let cursor = cdOffset;
+    for (let index = 0; index < count; index += 1) {
+      if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== 0x02014b50) {
+        return { ok: false, reason: 'corrupt_central_directory', files: [] };
+      }
+      const method = buffer.readUInt16LE(cursor + 10);
+      const compressedSize = buffer.readUInt32LE(cursor + 20);
+      const uncompressedSize = buffer.readUInt32LE(cursor + 24);
+      const nameLength = buffer.readUInt16LE(cursor + 28);
+      const extraLength = buffer.readUInt16LE(cursor + 30);
+      const commentLength = buffer.readUInt16LE(cursor + 32);
+      const localOffset = buffer.readUInt32LE(cursor + 42);
+      const name = buffer.slice(cursor + 46, cursor + 46 + nameLength).toString('utf8');
+      cursor += 46 + nameLength + extraLength + commentLength;
+      if (name.endsWith('/')) continue;
+      if (!isSafeZipName(name)) return { ok: false, reason: 'unsafe_entry_name:' + name, files: [] };
+      if (uncompressedSize > ZIP_LIMITS.fileBytes) return { ok: false, reason: 'entry_too_large:' + name, files: [] };
+      total += uncompressedSize;
+      if (total > ZIP_LIMITS.totalBytes) return { ok: false, reason: 'uncompressed_too_large', files: [] };
+      if (buffer.readUInt32LE(localOffset) !== 0x04034b50) {
+        return { ok: false, reason: 'corrupt_local_header:' + name, files: [] };
+      }
+      const localNameLength = buffer.readUInt16LE(localOffset + 26);
+      const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+      const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+      const raw = buffer.slice(dataStart, dataStart + compressedSize);
+      let data;
+      if (method === 0) data = raw;
+      else if (method === 8) {
+        try { data = inflateRawSync(raw); } catch { return { ok: false, reason: 'inflate_failed:' + name, files: [] }; }
+      } else return { ok: false, reason: 'unsupported_method:' + method + ':' + name, files: [] };
+      files.push({ name, data });
+    }
+    return { ok: true, reason: '', files };
+  } catch (error) {
+    return { ok: false, reason: 'zip_read_error:' + String((error && error.message) || error).slice(0, 120), files: [] };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pighub",
-  "version": "0.9.61",
+  "version": "0.9.66",
   "description": "猪猪库 PigHub 的 DeepSeek Harness 插件：侧边栏猪圈面板、每日一只猪猪、重复获得升星、可拖出的置顶桌宠，数据落在 ~/.PigHub。不内嵌任何上游图片。",
   "type": "module",
   "main": "./lib/index.js",
@@ -49,14 +49,14 @@
     "node": ">=22.12.0"
   },
   "scripts": {
-    "test": "node test/smoke.mjs && node test/store.test.mjs && node test/host.test.mjs && node test/imaging.test.mjs && node test/client.test.mjs && node test/lifecycle.test.mjs",
+    "test": "node test/smoke.mjs && node test/store.test.mjs && node test/host.test.mjs && node test/imaging.test.mjs && node test/client.test.mjs && node test/lifecycle.test.mjs && node test/auto-update.test.mjs",
     "test:client": "node test/client.test.mjs",
     "assets:build": "node scripts/build-assets.mjs",
     "assets:adopt": "node scripts/adopt-cards.mjs",
     "cards:make": "node scripts/make-cards.mjs",
     "cards:report": "node scripts/cards-report.mjs",
     "cards:select": "node scripts/cards-selection.mjs",
-    "prepublishOnly": "node test/smoke.mjs && node test/store.test.mjs && node test/host.test.mjs && node test/imaging.test.mjs && node test/client.test.mjs && node test/lifecycle.test.mjs"
+    "prepublishOnly": "node test/smoke.mjs && node test/store.test.mjs && node test/host.test.mjs && node test/imaging.test.mjs && node test/client.test.mjs && node test/lifecycle.test.mjs && node test/auto-update.test.mjs"
   },
   "license": "MIT",
   "author": {

package/test/auto-update.test.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * 静默自动更新的三分支测试（离线，不联网、不装包）：
+ *   高版本 → 发起安装并写日志 / 同版本 → 不动作 / 网络失败 → 不抛且只记一条。
+ * 依赖注入让这三条都能在本地跑出来。
+ */
+import assert from 'node:assert/strict';
+import { compareSemver, runAutoUpdate } from '../lib/auto-update.js';
+
+let pass = 0;
+let fail = 0;
+const check = (name, fn) => {
+  try {
+    fn();
+    pass += 1;
+    console.log('PASS  ' + name);
+  } catch (error) {
+    fail += 1;
+    console.log('FAIL  ' + name + ' :: ' + (error && error.message));
+  }
+};
+const acheck = async (name, fn) => {
+  try {
+    await fn();
+    pass += 1;
+    console.log('PASS  ' + name);
+  } catch (error) {
+    fail += 1;
+    console.log('FAIL  ' + name + ' :: ' + (error && error.message));
+  }
+};
+
+check('版本比较是语义化的（0.9.9 < 0.9.10，不能按字符串比）', () => {
+  assert.equal(compareSemver('0.9.9', '0.9.10'), -1);
+  assert.equal(compareSemver('0.9.10', '0.9.9'), 1);
+  assert.equal(compareSemver('0.9.61', '0.9.61'), 0);
+  assert.equal(compareSemver('v0.9.61', '0.9.61'), 0);
+  assert.equal(compareSemver('1.0.0', '0.9.99'), 1);
+  assert.equal(compareSemver('0.9', '0.9.0'), 0);
+});
+
+await acheck('远端更高：发起一次安装，并在日志里写下 start/ok', async () => {
+  const logs = [];
+  const calls = [];
+  const out = await runAutoUpdate({
+    currentVersion: '0.9.61',
+    profileDir: 'C:/fake/profile',
+    writeLog: (line) => logs.push(line),
+    fetchImpl: async () => ({ ok: true, json: async () => ({ version: '0.9.62' }) }),
+    execFileImpl: (_file, args, _opts, cb) => { calls.push(args.join(' ')); cb(null); return { unref() {} }; },
+  });
+  assert.equal(out.status, 'installed');
+  assert.equal(calls.length, 1, '应当恰好安装一次');
+  assert.ok(calls[0].indexOf('dsh-pighub@0.9.62') >= 0, '安装目标版本要正确：' + calls[0]);
+  assert.ok(logs.some((l) => l.indexOf('install start') >= 0), '要有 start 日志');
+  assert.ok(logs.some((l) => l.indexOf('install ok') >= 0), '要有 ok 日志');
+});
+
+await acheck('远端同版本：一次安装都不发起', async () => {
+  const logs = [];
+  let installed = 0;
+  const out = await runAutoUpdate({
+    currentVersion: '0.9.61',
+    profileDir: 'C:/fake/profile',
+    writeLog: (line) => logs.push(line),
+    fetchImpl: async () => ({ ok: true, json: async () => ({ version: '0.9.61' }) }),
+    execFileImpl: () => { installed += 1; },
+  });
+  assert.equal(out.status, 'current');
+  assert.equal(installed, 0, '同版本不许安装');
+  assert.ok(logs.some((l) => l.indexOf('up_to_date') >= 0));
+});
+
+await acheck('远端更老：也不安装（只升不降）', async () => {
+  let installed = 0;
+  const out = await runAutoUpdate({
+    currentVersion: '0.9.61',
+    profileDir: 'C:/fake/profile',
+    writeLog: () => {},
+    fetchImpl: async () => ({ ok: true, json: async () => ({ version: '0.9.10' }) }),
+    execFileImpl: () => { installed += 1; },
+  });
+  assert.equal(out.status, 'current');
+  assert.equal(installed, 0);
+});
+
+await acheck('网络失败：不抛、不安装、只记一条 offline', async () => {
+  const logs = [];
+  const out = await runAutoUpdate({
+    currentVersion: '0.9.61',
+    profileDir: 'C:/fake/profile',
+    writeLog: (line) => logs.push(line),
+    fetchImpl: async () => { throw new Error('ENOTFOUND'); },
+    execFileImpl: () => { throw new Error('不该安装'); },
+  });
+  assert.equal(out.status, 'offline');
+  assert.equal(logs.length, 1, '只记一条，不要重试风暴');
+  assert.ok(logs[0].indexOf('offline') >= 0);
+});
+
+await acheck('安装失败：静默降级为 failed，不抛出', async () => {
+  const logs = [];
+  const out = await runAutoUpdate({
+    currentVersion: '0.9.61',
+    profileDir: 'C:/fake/profile',
+    writeLog: (line) => logs.push(line),
+    fetchImpl: async () => ({ ok: true, json: async () => ({ version: '0.9.62' }) }),
+    execFileImpl: (_f, _a, _o, cb) => { cb(new Error('EACCES')); return { unref() {} }; },
+  });
+  assert.equal(out.status, 'failed');
+  assert.ok(logs.some((l) => l.indexOf('install failed') >= 0));
+});
+
+await acheck('没有 profile 目录：不安装，记 skip', async () => {
+  const logs = [];
+  let installed = 0;
+  const out = await runAutoUpdate({
+    currentVersion: '0.9.61',
+    profileDir: '',
+    writeLog: (line) => logs.push(line),
+    fetchImpl: async () => ({ ok: true, json: async () => ({ version: '0.9.62' }) }),
+    execFileImpl: () => { installed += 1; },
+  });
+  assert.equal(out.status, 'failed');
+  assert.equal(out.reason, 'no_profile_dir');
+  assert.equal(installed, 0);
+});
+
+console.log('\n' + pass + ' PASS / ' + fail + ' FAIL  —  auto update');
+process.exit(fail === 0 ? 0 : 1);

package/test/host.test.mjs

@@ -64,7 +64,10 @@ await acheck('GET 快照：素材库随包、今日未抽、偏好默认值', as
   assert.equal(json.assets.version, manifest.assetVersion);
   assert.ok(json.assets.bytes > 0, '素材体积应可统计');
   assert.equal(json.catalog, undefined, '运行时不再有上游目录');
-  assert.deepEqual(json.prefs, { sort: 'time', starDisplay: 'hover' });
+  // prefs 现在多一个 theme（主题包，用户口径 2026-11-14）；未设置时必须是 classic
+  assert.deepEqual(json.prefs, { sort: 'time', starDisplay: 'hover', theme: 'classic' });
+  assert.ok(Array.isArray(json.themes) && json.themes.length >= 1, '快照要带主题列表');
+  assert.equal(json.themes[0].name, 'classic', '内置 classic 永远排第一');
   assert.equal(json.today.drawn, false);
   // 新用户开局就带一只普通猪（标准猪）
   assert.deepEqual(json.pigs.map((pig) => pig.id), ['standard-pig']);

package/test/smoke.mjs

@@ -9,7 +9,7 @@
  * 任何一条不成立就非零退出——坏包发不出去。
  */
 import assert from 'node:assert/strict';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -200,9 +200,12 @@ check('注册了 pighub_about / pig-say 工具、状态路由与每张素材的
 });
 check('每个注册都包在 ctx.effect 里（可回收）', () => {
   const manifestCount = JSON.parse(readFileSync(new URL('../assets/manifest.json', here), 'utf8')).pigs.length;
-  // 两个工具 + 状态路由 + 每张素材 + 猪圈布景图（PEN_ART）+ 原生桌面桌宠的生命周期 effect
-  assert.equal(disposers.length, manifestCount + PEN_ART.length + 4,
-    '两个工具 + 状态路由 + 每张素材 + 每张布景 + 桌面桌宠各一个 disposer');
+  // 两个工具 + 状态路由 + 每张素材 + 猪圈布景图（PEN_ART）+ 原生桌面桌宠 + 静默自动更新的定时器
+  // 主题包的图片也是逐张注册的（classic 目录里有几张就几条），这里一起算进去
+  const themeImageCount = readdirSync(new URL('../assets/themes/classic', here)).filter((f) => /\.(png|jpg|jpeg|webp|svg)$/i.test(f)).length;
+  // PEN_ART 会被注册两次：一次是 /pighub/pen（布景），一次是 /pighub/theme/classic（主题包里的同一张图）
+  assert.equal(disposers.length, manifestCount + PEN_ART.length * 2 + 6 + themeImageCount,
+    '两个工具 + 状态路由 + 每张素材 + 每张布景 + 桌面桌宠 + 自动更新定时器 + 主题导入路由 + 每张主题图，各一个 disposer');
   for (const dispose of disposers) assert.equal(typeof dispose, 'function');
 });
 check('pighub_about 的参数 schema 封闭、描述非空', () => {

package/test/store.test.mjs

@@ -210,12 +210,13 @@ check('运动开关：显式布尔可写、null 回到素材默认、落在 stat
 });
 
 check('prefs：排序与星级显示各自独立，非法值退回默认', () => {
-  assert.deepEqual(mod.writePrefs(root, { sort: 'stars' }), { sort: 'stars', starDisplay: 'hover' });
+  // prefs 现在固定包含 theme（主题包，用户口径 2026-11-14），缺省 classic
+  assert.deepEqual(mod.writePrefs(root, { sort: 'stars' }), { sort: 'stars', starDisplay: 'hover', theme: 'classic' });
   assert.equal(mod.readPrefs(root).sort, 'stars');
   assert.equal(mod.writePrefs(root, { sort: 'nonsense' }).sort, 'time');
   // 只改星级显示，不能把排序重置掉（反之亦然）
-  assert.deepEqual(mod.writePrefs(root, { starDisplay: 'always' }), { sort: 'time', starDisplay: 'always' });
-  assert.deepEqual(mod.writePrefs(root, { sort: 'rarity' }), { sort: 'rarity', starDisplay: 'always' });
+  assert.deepEqual(mod.writePrefs(root, { starDisplay: 'always' }), { sort: 'time', starDisplay: 'always', theme: 'classic' });
+  assert.deepEqual(mod.writePrefs(root, { sort: 'rarity' }), { sort: 'rarity', starDisplay: 'always', theme: 'classic' });
   assert.equal(mod.writePrefs(root, { starDisplay: 'nope' }).starDisplay, 'hover');
 });