@ganziliang/desktop-pet 0.1.0

package/main.js

@@ -0,0 +1,1143 @@
+'use strict';
+
+/**
+ * 桌面动漫角色小控件 —— 主进程
+ *
+ * 能力：
+ *  - 透明 / 无边框 / 置顶 / 不进任务栏的窗口
+ *  - 精确命中测试：透明像素处自动鼠标穿透（renderer 算好再通知主进程）
+ *  - 托盘 + 右键原生菜单（穿透、置顶、缩放、开机自启、退出）
+ *  - 本地 HTTP 接口，供 pi 扩展 / 其它程序推送消息给角色
+ */
+
+const {
+  app,
+  BrowserWindow,
+  ipcMain,
+  Menu,
+  Tray,
+  nativeImage,
+  screen,
+  globalShortcut,
+} = require('electron');
+const path = require('node:path');
+const fs = require('node:fs');
+const http = require('node:http');
+
+const BASE_W = 420;
+const BASE_H = 420;
+const HTTP_PORT = 8520;
+const ASSETS = path.join(__dirname, 'assets');
+// 角色在屏幕上的标准特征尺寸（scale=1）：站姿是身高，游泳这种横躺姿势是身长
+const BASE_FIGURE_H = 378;
+// 精灵图元信息清单（scripts/spritesheet.py 产出），帧数/帧尺寸/参考尺寸都在里面
+const SPRITE_MANIFEST = path.join(ASSETS, 'sprites.json');
+// 战斗服装 / 觉醒技能清单（觉醒立绘放在 assets/awaken/<id>.png）
+const OUTFITS_FILE = path.join(ASSETS, 'outfits.json');
+// 清单缺失时的兜底（只针对没跑过 spritesheet.py 的原始图）
+const SHEET_FALLBACK = {
+  walk: { frames: 4, refPx: 620 },
+  run: { frames: 4, refPx: 620 },
+  swim: { frames: 6, refPx: 420 },
+};
+
+const DEBUG = !!process.env.PET_DEBUG;
+const debugFile = path.join(__dirname, 'pet-debug.log');
+if (DEBUG) fs.writeFileSync(debugFile, '');
+
+function dbg(...parts) {
+  if (!DEBUG) return;
+  // 同步写，避免流缓冲导致看不到日志
+  try {
+    fs.appendFileSync(debugFile, `${new Date().toISOString().slice(11, 23)} ${parts.join(' ')}\n`);
+  } catch {
+    /* 忽略 */
+  }
+}
+
+let win = null;
+let tray = null;
+let httpServer = null;
+let ignoreMouse = false;
+let saveTimer = null;
+let outfits = { stage: {}, list: [] };
+let manifest = {};
+
+const state = {
+  x: null,
+  y: null,
+  scale: 1,
+  clickThrough: false,
+  alwaysOnTop: true,
+  openAtLogin: false,
+  autoRoam: true, // 自己决定什么时候走动 / 跑步 / 游泳
+  gravity: false, // 拖完松手后是否落回屏幕底部；默认关，拖到哪就在哪
+};
+
+/* ------------------------------------------------------------------ 持久化 */
+
+const stateFile = () => path.join(app.getPath('userData'), 'pet-state.json');
+
+function loadState() {
+  try {
+    Object.assign(state, JSON.parse(fs.readFileSync(stateFile(), 'utf8')));
+  } catch {
+    /* 首次运行，用默认值 */
+  }
+}
+
+function saveState() {
+  try {
+    fs.mkdirSync(path.dirname(stateFile()), { recursive: true });
+    fs.writeFileSync(stateFile(), JSON.stringify(state, null, 2));
+  } catch {
+    /* 忽略写失败 */
+  }
+}
+
+/* -------------------------------------------------------------------- 窗口 */
+
+function assetIfExists(file) {
+  const p = path.join(ASSETS, file);
+  return fs.existsSync(p) ? p : null;
+}
+
+/**
+ * 组装一张精灵图的元信息。figH 是「角色在这张图里有多高」，
+ * 渲染层用例它把角色换算到统一的屏幕身高，换素材时不会忽大忽小。
+ * 归一化过的图（spritesheet.py 产出，固定 SHEET_FIGURE_H）优先；
+ * 只有用户自己新丢进来的原图时，就退回用图片自身高度。
+ */
+function loadSpriteManifest() {
+  // spritesheet.py 的 --manifest 默认是「输出目录/sprites.json」。
+  // 给觉醒素材跑管线时输出目录是 assets/awaken/，忘了带 --manifest 就会写到这里，
+  // 而本进程只读 assets/sprites.json —— 现象是「素材文件明明在，游戏里却没换衣服」，
+  // 而且是静默失败。这里主动报一下，别让人查半天。
+  if (DEBUG && fs.existsSync(path.join(ASSETS, 'awaken', 'sprites.json'))) {
+    dbg('WARN assets/awaken/sprites.json 存在 —— 跑 spritesheet.py 时漏了 --manifest assets/sprites.json');
+  }
+  try {
+    return JSON.parse(fs.readFileSync(SPRITE_MANIFEST, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 读服装 / 觉醒清单。读不到就用一份兜底，保证菜单永远有东西，
+ * 而不会因为少个 json 让整个右键菜单空掉。
+ */
+function loadOutfits() {
+  const fallback = { stage: {}, list: [{ id: 'seraph', name: '圣光 · 炽天使', skill: '圣裁之光' }] };
+  try {
+    const raw = JSON.parse(fs.readFileSync(OUTFITS_FILE, 'utf8'));
+    return {
+      stage: raw.stage || {},
+      list: Array.isArray(raw.list) && raw.list.length ? raw.list : fallback.list,
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * 组装一张精灵图的元信息。
+ * refPx 是「角色在这张图里有多大」（竖构图=身高，横构图=身长），
+ * 渲染层用它把角色换算到统一的屏幕尺寸，所以换素材/加动作不会忽大忽小。
+ * 数据优先从 sprites.json 读；只有用户自己新丢进来的原图才走兜底值。
+ */
+function sheetConf(key, file, fallback = {}) {
+  const p = assetIfExists(file);
+  if (!p) return null;
+  const size = nativeImage.createFromPath(p).getSize();
+  if (!size.width || !size.height) return null;
+
+  const m = manifest[key] || {};
+  const frames = Math.max(1, m.frames || fallback.frames || 1);
+  return {
+    path: p,
+    frames,
+    // fallback.refPx <= 0 表示「把整张图当成角色」（未归一化的原图）
+    refPx: m.refPx || fallback.refPx || size.height,
+    frameW: m.frameW || Math.round(size.width / frames),
+    frameH: m.frameH || size.height,
+    axis: m.axis || 'h',
+    padY: m.padY ?? 0,
+  };
+}
+
+/**
+ * 觉醒素材的三个阶段。
+ * 蓄力和爆发各是一张横向序列图（走 spritesheet.py 管线，和 walk/run 一样）；
+ * still 是旧的单帧立绘，保留兼容。
+ */
+const AWAKEN_PHASES = ['charge', 'burst', 'still'];
+
+function spriteAssets() {
+  // 觉醒素材：一个服装一套，按阶段找文件。
+  //   蓄力：assets/awaken/<id>-charge.png（4 帧，清单 key awaken-<id>-charge）
+  //   爆发：assets/awaken/<id>-burst.png （4 帧，清单 key awaken-<id>-burst）
+  //   旧版单帧立绘：assets/awaken/<id>.png（清单 key awaken-<id>）
+  // 缺哪一张就少哪个 key，渲染层自己退回 idle 帧 —— 缺素材不会崩，只是不换衣服。
+  const awakenArt = {};
+  for (const o of outfits.list) {
+    const phases = {};
+    for (const phase of AWAKEN_PHASES) {
+      const file =
+        phase === 'still' ? path.join('awaken', `${o.id}.png`) : path.join('awaken', `${o.id}-${phase}.png`);
+      const p = assetIfExists(file);
+      if (!p) continue;
+      const size = nativeImage.createFromPath(p).getSize();
+      if (!size.width || !size.height) continue;
+
+      // refPx / frames / padY 都从 sprites.json 读；渲染层用和 idle 完全相同的公式
+      // 换算显示尺寸，所以换装不会忽大忽小。
+      const m = manifest[`awaken-${o.id}-${phase}`] || manifest[`awaken-${o.id}`] || {};
+      const frames = Math.max(1, m.frames || 1);
+      phases[phase] = {
+        path: p,
+        frames,
+        refPx: m.refPx || size.height,
+        frameW: m.frameW || Math.round(size.width / frames),
+        frameH: m.frameH || size.height,
+        padY: m.padY ?? 0,
+      };
+    }
+    if (Object.keys(phases).length) awakenArt[o.id] = phases;
+  }
+
+  return {
+    idle: sheetConf('idle', 'pet-idle.png') || sheetConf('idle', 'pet-base.png', { refPx: 0 }),
+    blink: sheetConf('idle-blink', 'pet-idle-blink.png') || sheetConf('blink', 'pet-blink.png', { refPx: 0 }),
+    sheets: {
+      walk: sheetConf('walk', 'pet-walk.png', SHEET_FALLBACK.walk),
+      run: sheetConf('run', 'pet-run.png', SHEET_FALLBACK.run),
+      swim: sheetConf('swim', 'pet-swim.png', SHEET_FALLBACK.swim),
+    },
+    awaken: awakenArt,
+    figureHeight: BASE_FIGURE_H,
+  };
+}
+
+function createWindow() {
+  manifest = loadSpriteManifest();
+  outfits = loadOutfits();
+  const display = screen.getPrimaryDisplay().workAreaSize;
+  const w = Math.round(BASE_W * state.scale);
+  const h = Math.round(BASE_H * state.scale);
+
+  win = new BrowserWindow({
+    width: w,
+    height: h,
+    x: state.x ?? Math.round(display.width - w - 60),
+    y: state.y ?? Math.round(display.height - h - 20),
+    transparent: true,
+    backgroundColor: '#00000000',
+    frame: false,
+    resizable: false,
+    maximizable: false,
+    minimizable: false,
+    fullscreenable: false,
+    skipTaskbar: true,
+    hasShadow: false,
+    alwaysOnTop: state.alwaysOnTop,
+    title: '桌面小控件',
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      backgroundThrottling: false,
+    },
+  });
+
+  win.setAlwaysOnTop(state.alwaysOnTop, 'screen-saver');
+  win.loadFile(path.join(__dirname, 'renderer', 'index.html'));
+  win.setIgnoreMouseEvents(false);
+  const hwnd =
+    process.platform === 'win32' ? win.getNativeWindowHandle().readBigUInt64LE(0).toString() : 'n/a';
+  const b = win.getBounds();
+  dbg('window-created', `hwnd=${hwnd}`, `bounds=${b.x},${b.y},${b.width}x${b.height}`);
+
+  win.on('resize', () => {
+    if (!win) return;
+    const b = win.getBounds();
+    const cb = win.getContentBounds();
+    dbg(
+      'RESIZE',
+      `bounds=${b.x},${b.y},${b.width}x${b.height}`,
+      `content=${cb.width}x${cb.height}`,
+      `zoom=${win.webContents.getZoomFactor().toFixed(3)}`,
+      `scaleFactor=${screen.getDisplayMatching(b).scaleFactor}`,
+      `resizable=${win.isResizable()}`,
+    );
+    // 尺寸漂移了就钉回去（DIP 变化/混合 DPI 拖动都会触发）
+    pinSize();
+  });
+
+  win.on('moved', () => {
+    if (!win) return;
+    // 巡游中的位置不值得记：重启后回到默认位置就好，否则每秒要写好几次盘
+    if (roamPlan) return;
+    // 觉醒期间窗口是被临时放大的，记下来下次启动就会「大一号」开机
+    if (awakenRect) return;
+    const [x, y] = win.getPosition();
+    state.x = x;
+    state.y = y;
+    dbg('moved', `${x},${y}`);
+    clearTimeout(saveTimer);
+    saveTimer = setTimeout(saveState, 400);
+  });
+
+  win.on('move', () => dbg('move', win ? win.getPosition().join(',') : '-'));
+
+  win.on('closed', () => {
+    awakenRect = null;
+    awakenPrev = null;
+    win = null;
+  });
+}
+
+/**
+ * 把窗口拉回工作区内。
+ * 有必要是因为位置是持久化的：上次退出时如果角色被放在屏幕外（或者那块屏后来拔了），
+ * 下次启动它就是「半截在屏幕外」甚至完全看不见。
+ */
+function clampIntoWorkArea() {
+  if (!win) return false;
+  if (awakenRect) return false; // 演出中不要动窗口
+  const b = win.getBounds();
+  const wa = screen.getDisplayMatching(b).workArea;
+  const { width, height } = targetSize();
+  const x = Math.min(Math.max(b.x, wa.x), Math.max(wa.x, wa.x + wa.width - width));
+  const y = Math.min(Math.max(b.y, wa.y), Math.max(wa.y, wa.y + wa.height - height));
+  if (x === b.x && y === b.y) return false;
+  dbg('clamp', `${b.x},${b.y} -> ${x},${y}`);
+  win.setBounds({ x, y, width, height });
+  return true;
+}
+
+function applyClickThrough(on) {
+  state.clickThrough = on;
+  saveState();
+  if (!win) return;
+  // forward: true -> 忽略鼠标事件时仍把 mousemove 转发给渲染进程，才能再切回来
+  win.setIgnoreMouseEvents(on, { forward: true });
+  if (!on) ignoreMouse = false;
+}
+
+/**
+ * 穿透状态下不能依赖 mouseover/mousemove 来“醒过来”：光标停着不动就永远醒不了，
+ * 按下的那一刻还在穿透 -> 点击直接穿到桌面（就是拖不动的根因）。
+ * 所以由主进程按 220ms 轮询系统光标位置，交给渲染层做像素命中测试。
+ */
+function startHitPoll() {
+  setInterval(() => {
+    if (!win || !ignoreMouse || state.clickThrough) return;
+    const p = screen.getCursorScreenPoint();
+    const b = win.getBounds();
+    win.webContents.send('pet:poll-hit', { x: p.x - b.x, y: p.y - b.y });
+  }, 220);
+}
+
+/** 窗口的目标尺寸（DIP）；窗口大小只由 state.scale 决定 */
+function targetSize(scale = state.scale) {
+  return { width: Math.round(BASE_W * scale), height: Math.round(BASE_H * scale) };
+}
+
+/* ------------------------------------------------ 觉醒演出的临时放大窗口 */
+
+// 觉醒期间窗口的临时目标 bounds；非空即表示「正在演出」
+let awakenRect = null;
+let awakenPrev = null;
+
+/**
+ * 算出觉醒演出要用多大的窗口。
+ * 默认是工作区的 46% x 72%（可在 assets/outfits.json 的 stage 里改），
+ * 不做全屏：一是全屏窗会盖住整个桌面太霸道，二是用户明确说了要「小窗口 / 屏幕的百分之几」。
+ *
+ * 关键：只向上和向两侧长，保住「角色脚下那条线」和水平中心，
+ * 这样窗口变大时角色在屏幕上的位置几乎不动 —— 配合暗幕就完全看不出窗口在变。
+ */
+function awakenTarget() {
+  if (!win) return null;
+  const s = outfits.stage || {};
+  const b = win.getBounds();
+  const wa = screen.getDisplayMatching(b).workArea;
+
+  const w = Math.round(
+    Math.max(s.minWidth ?? 560, Math.min(s.maxWidth ?? 1280, wa.width * (s.widthRatio ?? 0.46))),
+  );
+  const h = Math.round(
+    Math.max(s.minHeight ?? 520, Math.min(s.maxHeight ?? 900, wa.height * (s.heightRatio ?? 0.72))),
+  );
+
+  const cx = b.x + b.width / 2;
+  const bottom = b.y + b.height;
+  const x = Math.max(wa.x, Math.min(Math.round(cx - w / 2), wa.x + wa.width - w));
+  const y = Math.max(wa.y, Math.min(Math.round(bottom - h), wa.y + wa.height - h));
+  return { x, y, width: w, height: h };
+}
+
+/** 开 / 关觉醒演出窗口，返回生效的 bounds（渲染层用它算角色缩放） */
+function awakenWindow(on) {
+  if (!win) return null;
+  if (on) {
+    if (awakenRect) return awakenRect;
+    haltRoam('awaken'); // 巡游引擎也在 setBounds，不先停掉两边会打架
+    awakenPrev = win.getBounds();
+    awakenRect = awakenTarget();
+    if (!awakenRect) return null;
+    dbg('awaken-open', JSON.stringify(awakenRect));
+    win.setBounds(awakenRect);
+    if (tray) tray.setContextMenu(buildTrayMenu());
+    return awakenRect;
+  }
+  if (!awakenRect) return null;
+  const fallback = { ...awakenRect, ...targetSize() };
+  const back = awakenPrev || fallback;
+  dbg('awaken-close', JSON.stringify(back));
+  awakenRect = null;
+  awakenPrev = null;
+  win.setBounds(back);
+  if (tray) tray.setContextMenu(buildTrayMenu());
+  return back;
+}
+
+/**
+ * Windows 混合 DPI 的坑：在缩放不是 100% 的屏幕上，每次 SetWindowPos（拖动时每个 mousemove 都会调）
+ * Chromium 的 DIP<->物理像素换算都会漂 ~1px，窗口尺寸于是一路棘轮式长大——按住拖一会就变成两三倍大。
+ * 本控件是固定尺寸窗，把尺寸钉回目标值即可。
+ * 注：非 100% 缩放下 Electron 对无边框窗口的尺寸取整本身就有 1~3px 偏差（#51572），
+ *     所以用 SIZE_SLACK 容差判断，否则会陷入「改了还是差几 px」的死循环。
+ * 参考：electron/electron#20423、#20683。
+ */
+const SIZE_SLACK = 4;
+
+function pinSize() {
+  if (!win) return false;
+  // 觉醒演出中窗口是「故意」被放大的，按平时尺寸纠回去会把演出直接掐断
+  const want = awakenRect
+    ? { width: awakenRect.width, height: awakenRect.height }
+    : targetSize();
+  // 用 content 尺寸做判据：混合 DPI 下 getBounds() 会把物理像素当成 DIP 报出来，
+  // 照它纠正反而会打架；content 才是 CSS 真正看到的视口。
+  const [cw, ch] = win.getContentSize();
+  if (Math.abs(cw - want.width) <= SIZE_SLACK && Math.abs(ch - want.height) <= SIZE_SLACK) {
+    return false;
+  }
+  dbg('pin-size', `content=${cw}x${ch} -> ~${want.width}x${want.height}`);
+  win.setContentSize(want.width, want.height);
+  return true;
+}
+
+function applyScale(scale) {
+  dbg('applyScale', `${state.scale} -> ${scale}`, new Error('applyScale caller').stack?.split('\n')[2]?.trim());
+  state.scale = scale;
+  saveState();
+  if (!win) return;
+  win.setSize(targetSize(scale).width, targetSize(scale).height, false);
+  win.webContents.send('pet:scale', scale);
+}
+
+/* ------------------------------------------------------ 自动活动（桌面巡游） */
+
+// 每档的巡航速度（DIP/秒）与加速度（DIP/秒²）
+const ROAM = {
+  walk: { speed: 118, accel: 900 },
+  run: { speed: 430, accel: 2600 },
+  swim: { speed: 120, accel: 700 },
+};
+const ROAM_MODES = Object.keys(ROAM);
+const ROAM_TICK_MS = 16;
+
+let roamTimer = null;
+let roamPlan = null;
+
+/** 当前屏幕工作区的底边 = 角色的“地面线”（窗口贴住它） */
+function groundY() {
+  const d = screen.getDisplayMatching(win.getBounds());
+  return d.workArea.y + d.workArea.height - targetSize().height;
+}
+
+/**
+ * 梯形速度曲线：加速 -> 匀速 -> 减速，返回 0..1 的位移比例。
+ * 直接线性插值会“啪”地起步、撞墙一样急停，梯形看起来才像生物在动。
+ */
+function trapezoid(t, duration, accTime) {
+  const a = Math.max(1, Math.min(accTime, duration * 0.45));
+  const v = 1 / (duration - a);
+  if (t <= 0) return 0;
+  if (t >= duration) return 1;
+  if (t < a) return (0.5 * v * t * t) / a;
+  if (t < duration - a) return 0.5 * v * a + v * (t - a);
+  const rest = duration - t;
+  return 1 - (0.5 * v * rest * rest) / a;
+}
+
+function roamGeometry(mode) {
+  const b = win.getBounds();
+  const wa = screen.getDisplayMatching(b).workArea;
+  const { width, height } = targetSize();
+  const minX = wa.x;
+  const maxX = Math.max(minX, wa.x + wa.width - width);
+  const floorY = wa.y + wa.height - height;
+  // 开了重力就贴屏幕底那条地面线；没开就在你放它的高度上走。
+  // （游泳的水面画在窗口内部，窗口在哪水就在哪，不需要为此强行回到屏幕底）
+  const y = state.gravity ? floorY : Math.min(floorY, Math.max(wa.y, b.y));
+  return { b, minX, maxX, floorY, y, width, height, span: maxX - minX };
+}
+
+function pickTargetX({ b, minX, maxX, span }, mode) {
+  const near = mode === 'run' ? 440 : 230;
+  let target;
+  if (span > 60 && Math.random() < 0.7) {
+    // 多数时候就地在附近晃两步，偶尔横跨半屏
+    target = b.x + (Math.random() < 0.5 ? -1 : 1) * near * (0.5 + Math.random() * 0.9);
+    if (target < minX || target > maxX) target = b.x - (target - b.x); // 撞边就掉头
+  } else {
+    target = minX + Math.random() * span;
+  }
+  return Math.round(Math.min(maxX, Math.max(minX, target)));
+}
+
+/** 中止当前巡游；返回是否真的中止了 */
+function haltRoam(reason = 'halt') {
+  if (roamTimer) clearInterval(roamTimer);
+  roamTimer = null;
+  if (!roamPlan) return false;
+  const { mode } = roamPlan;
+  roamPlan = null;
+  win?.webContents.send('pet:loco-end', { mode, reason });
+  return true;
+}
+
+/**
+ * 让角色在屏幕上走 / 跑 / 游一段。
+ * 位置由主进程每帧算好直接推窗口（渲染层不会被 60fps 的 IPC 淹掉），
+ * 渲染层只负责播对应的骨骼动画，两边靠同一份 plan 对齐朝向和时长。
+ */
+function startRoam(mode = 'walk') {
+  if (!win || !win.isVisible()) return null;
+  if (!ROAM_MODES.includes(mode)) mode = 'walk';
+  haltRoam('restart');
+
+  const geo = roamGeometry(mode);
+  const fromX = geo.b.x;
+  const toX = pickTargetX(geo, mode);
+  const dist = Math.abs(toX - fromX);
+  const { speed, accel } = ROAM[mode];
+  const accTime = Math.min(340, Math.max(110, (speed / accel) * 1000));
+  const duration = Math.max(500, (dist / speed) * 1000 + accTime * 0.8);
+
+  const plan = {
+    mode,
+    dir: toX < fromX ? -1 : 1,
+    fromX,
+    toX,
+    dist: Math.round(dist),
+    duration: Math.round(duration),
+    speed,
+  };
+  roamPlan = plan;
+
+  const t0 = performance.now();
+  const timer = setInterval(() => {
+    if (!win || roamPlan !== plan) {
+      clearInterval(timer);
+      return;
+    }
+    const t = performance.now() - t0;
+    // 纵向也平滑过去：关掉重力时可能停在半空，直接瞬移太突兀
+    const yFrac = Math.min(1, t / Math.min(320, duration * 0.4));
+    const y = Math.round(geo.b.y + (geo.y - geo.b.y) * (1 - (1 - yFrac) * (1 - yFrac)));
+    win.setBounds({
+      x: Math.round(fromX + (toX - fromX) * trapezoid(t, duration, accTime)),
+      y,
+      width: geo.width,
+      height: geo.height,
+    });
+    if (t >= duration) {
+      clearInterval(timer);
+      roamTimer = null;
+      roamPlan = null;
+      win.webContents.send('pet:loco-end', { mode, reason: 'arrived' });
+    }
+  }, ROAM_TICK_MS);
+  roamTimer = timer;
+
+  return plan;
+}
+
+/** 把窗口当前位置记下来（Windows 上只有 move 事件，'moved' 是 macOS 专属） */
+function persistPosition() {
+  if (!win) return;
+  const [x, y] = win.getPosition();
+  state.x = x;
+  state.y = y;
+  saveState();
+}
+
+/** 拖完松手后落回地面（重力关掉就原地待着） */
+function settleToGround() {
+  if (!win || !state.gravity || roamPlan || awakenRect) return false;
+  const b = win.getBounds();
+  const y1 = groundY();
+  if (Math.abs(y1 - b.y) <= 2) {
+    persistPosition(); // 已经在地面上了，把落脚点记下来
+    return false;
+  }
+
+  const { width, height } = targetSize();
+  const dur = Math.min(720, 200 + Math.sqrt(Math.abs(y1 - b.y)) * 20);
+  const t0 = performance.now();
+  const timer = setInterval(() => {
+    if (!win) return clearInterval(timer);
+    const p = Math.min(1, (performance.now() - t0) / dur);
+    const frac = 1 - (1 - p) * (1 - p); // 先快后慢，像落在柔软的地面上
+    win.setBounds({ x: b.x, y: Math.round(b.y + (y1 - b.y) * frac), width, height });
+    if (p >= 1) {
+      clearInterval(timer);
+      persistPosition();
+    }
+  }, ROAM_TICK_MS);
+  return true;
+}
+
+function setAutoRoam(on) {
+  state.autoRoam = !!on;
+  saveState();
+  if (tray) tray.setContextMenu(buildTrayMenu());
+  if (!state.autoRoam) haltRoam('auto-off');
+  win?.webContents.send('pet:auto', { enabled: state.autoRoam });
+}
+
+function setGravity(on) {
+  state.gravity = !!on;
+  saveState();
+  if (tray) tray.setContextMenu(buildTrayMenu());
+  if (state.gravity) settleToGround();
+}
+
+/** 托盘 / 右键菜单 / HTTP 都从这里派发动作给渲染层 */
+function sendAction(name) {
+  if (!win) return false;
+  if (!win.isVisible()) win.show();
+  win.webContents.send('pet:action', { name });
+  return true;
+}
+
+/* -------------------------------------------------------------------- 托盘 */
+
+function trayIcon() {
+  const src = assetIfExists('tray.png') || assetIfExists('pet-idle.png') || assetIfExists('pet-base.png');
+  const img = src ? nativeImage.createFromPath(src) : nativeImage.createEmpty();
+  if (img.isEmpty()) return img;
+  const size = img.getSize();
+  // 取角色头部区域（上方中间），缩成托盘大小更易辨认
+  const crop = img.crop({
+    x: Math.round(size.width * 0.3),
+    y: Math.round(size.height * 0.05),
+    width: Math.round(size.width * 0.4),
+    height: Math.round(size.height * 0.35),
+  });
+  return crop.resize({ width: 16, height: 16 });
+}
+
+/**
+ * 「✨ 觉醒技能」子菜单：服装和觉醒是一对一的（轻量档：战斗服只在觉醒演出里出现），
+ * 所以不需要单独再列一个「服装」菜单。
+ */
+function awakenSubmenu() {
+  const items = outfits.list.map((o) => ({
+    label: `✨ ${o.skill}　（${o.name}）`,
+    click: () => sendAction(`awaken:${o.id}`),
+  }));
+  if (items.length > 1) {
+    items.push(
+      { type: 'separator' },
+      {
+        label: '🎲 随机来一个',
+        click: () => {
+          const pick = outfits.list[Math.floor(Math.random() * outfits.list.length)];
+          sendAction(`awaken:${pick.id}`);
+        },
+      },
+    );
+  }
+  items.push(
+    { type: 'separator' },
+    { label: '⏹ 结束演出', click: () => sendAction('awaken-stop') },
+  );
+  return { label: '✨ 觉醒技能', submenu: items };
+}
+
+function buildTrayMenu() {
+  return Menu.buildFromTemplate([    {
+      label: '显示 / 隐藏',
+      click: () => {
+        if (!win) return createWindow();
+        win.isVisible() ? win.hide() : (win.show(), win.focus());
+      },
+    },
+    {
+      label: '鼠标穿透模式（点击穿透到桌面）',
+      type: 'checkbox',
+      checked: state.clickThrough,
+      click: (item) => applyClickThrough(item.checked),
+    },
+    {
+      label: '窗口置顶',
+      type: 'checkbox',
+      checked: state.alwaysOnTop,
+      click: (item) => {
+        state.alwaysOnTop = item.checked;
+        saveState();
+        win?.setAlwaysOnTop(item.checked, 'screen-saver');
+      },
+    },
+    {
+      label: '角色大小',
+      submenu: [0.8, 1, 1.25, 1.5].map((s) => ({
+        label: `${Math.round(s * 100)}%`,
+        type: 'radio',
+        checked: Math.abs(state.scale - s) < 0.01,
+        click: () => applyScale(s),
+      })),
+    },
+    {
+      label: '回到屏幕右下角',
+      click: () => {
+        if (!win) return;
+        haltRoam('tray');
+        const wa = screen.getPrimaryDisplay().workAreaSize;
+        const [w, h] = win.getSize();
+        win.setPosition(wa.width - w - 60, wa.height - h - 20);
+      },
+    },
+    { type: 'separator' },
+    {
+      label: '让它动起来',
+      submenu: [
+        { label: '🚶 走一走', click: () => sendAction('walk') },
+        { label: '🏃 跑一跑', click: () => sendAction('run') },
+        { label: '🏊 游一游', click: () => sendAction('swim') },
+        { type: 'separator' },
+        { label: '⏹ 停下来', click: () => sendAction('stop') },
+      ],
+    },
+    {
+      label: '自动活动（自己走动 / 跑步 / 游泳）',
+      type: 'checkbox',
+      checked: state.autoRoam,
+      click: (item) => setAutoRoam(item.checked),
+    },
+    awakenSubmenu(),
+    {
+      label: '拖完松手后落回屏幕底部（重力）',
+      type: 'checkbox',
+      checked: state.gravity,
+      click: (item) => setGravity(item.checked),
+    },
+    { type: 'separator' },
+    {
+      label: '开机自启',
+      type: 'checkbox',
+      checked: state.openAtLogin,
+      click: (item) => {
+        state.openAtLogin = item.checked;
+        saveState();
+        app.setLoginItemSettings({ openAtLogin: item.checked, args: [] });
+      },
+    },
+    {
+      label: `消息接口：http://127.0.0.1:${HTTP_PORT}/say`,
+      click: () => {
+        require('electron').clipboard.writeText(
+          `curl -X POST http://127.0.0.1:${HTTP_PORT}/say -H "Content-Type: application/json" -d "{\\"text\\":\\"你好呀~\\"}"`,
+        );
+      },
+    },
+    { type: 'separator' },
+    { label: '退出', role: 'quit' },
+  ]);
+}
+
+function createTray() {
+  tray = new Tray(trayIcon());
+  tray.setToolTip('桌面小控件');
+  tray.setContextMenu(buildTrayMenu());
+  tray.on('click', () => tray.popUpContextMenu());
+}
+
+/* -------------------------------------------------------------- 右键菜单 */
+
+function popupContextMenu() {
+  Menu.buildFromTemplate([
+    {
+      label: '😊 打个招呼',
+      click: () => sendAction('greet'),
+    },
+    {
+      label: '💃 跳个舞',
+      click: () => sendAction('dance'),
+    },
+    {
+      label: '🛌 去睡觉',
+      click: () => sendAction('sleep'),
+    },
+    {
+      label: '让它动起来',
+      submenu: [
+        { label: '🚶 走一走', click: () => sendAction('walk') },
+        { label: '🏃 跑一跑', click: () => sendAction('run') },
+        { label: '🏊 游一游', click: () => sendAction('swim') },
+        { type: 'separator' },
+        { label: '⏹ 停下来', click: () => sendAction('stop') },
+      ],
+    },
+    {
+      label: '🗨️ 让它说点什么',
+      click: async () => {
+        const line = await win?.webContents.executeJavaScript('window.__petRandomLine()');
+        win?.webContents.send('pet:say', { text: line });
+      },
+    },
+    { type: 'separator' },
+    {
+      label: '鼠标穿透',
+      type: 'checkbox',
+      checked: state.clickThrough,
+      click: (item) => applyClickThrough(item.checked),
+    },
+    {
+      label: '窗口置顶',
+      type: 'checkbox',
+      checked: state.alwaysOnTop,
+      click: (item) => {
+        state.alwaysOnTop = item.checked;
+        saveState();
+        win?.setAlwaysOnTop(item.checked, 'screen-saver');
+      },
+    },
+    {
+      label: '自动活动',
+      type: 'checkbox',
+      checked: state.autoRoam,
+      click: (item) => setAutoRoam(item.checked),
+    },
+    awakenSubmenu(),
+    {
+      label: '拖完松手后落回屏幕底部（重力）',
+      type: 'checkbox',
+      checked: state.gravity,
+      click: (item) => setGravity(item.checked),
+    },
+    {
+      label: '角色大小',
+      submenu: [0.8, 1, 1.25, 1.5].map((s) => ({
+        label: `${Math.round(s * 100)}%`,
+        type: 'radio',
+        checked: Math.abs(state.scale - s) < 0.01,
+        click: () => applyScale(s),
+      })),
+    },
+    { type: 'separator' },
+    { label: '隐藏（托盘里可再打开）', click: () => win?.hide() },
+    { label: '退出', role: 'quit' },
+  ]).popup({ window: win ?? undefined });
+}
+
+/* -------------------------------------------------------- 本地 HTTP 接口 */
+
+function readJson(req) {
+  return new Promise((resolve) => {
+    let raw = '';
+    req.on('data', (c) => {
+      raw += c;
+      if (raw.length > 64 * 1024) req.destroy();
+    });
+    req.on('end', () => {
+      try {
+        resolve(raw ? JSON.parse(raw) : {});
+      } catch {
+        resolve({});
+      }
+    });
+  });
+}
+
+function json(res, code, body) {
+  res.writeHead(code, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Headers': 'Content-Type',
+  });
+  res.end(JSON.stringify(body));
+}
+
+function startHttpServer() {
+  httpServer = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://127.0.0.1:${HTTP_PORT}`);
+
+    if (req.method === 'OPTIONS') return json(res, 204, {});
+
+    if (req.method === 'GET' && url.pathname === '/health') {
+      return json(res, 200, {
+        ok: true,
+        app: 'desktop-pet',
+        visible: !!win?.isVisible(),
+        // 诊断用：窗口尺寸 + 每块屏的 scaleFactor（排查 DPI 反馈环）
+        bounds: win ? win.getBounds() : null,
+        scale: state.scale,
+        // 自动化探针会先关掉自动活动，需要能读到原值才好恢复
+        autoRoam: state.autoRoam,
+        gravity: state.gravity,
+        displays: screen.getAllDisplays().map((d) => ({
+          scaleFactor: d.scaleFactor,
+          bounds: d.bounds,
+          workArea: d.workArea,
+        })),
+        // 给自动化测试用：暴露原生窗口句柄
+        hwnd:
+          win && process.platform === 'win32'
+            ? win.getNativeWindowHandle().readBigUInt64LE(0).toString()
+            : null,
+      });
+    }
+
+    if (req.method === 'POST' && url.pathname === '/say') {
+      const body = await readJson(req);
+      const text = String(body.text ?? '').slice(0, 500);
+      if (!text) return json(res, 400, { ok: false, error: 'text is required' });
+      if (!win) createWindow();
+      win.show();
+      win.webContents.send('pet:say', { text, mood: body.mood });
+      return json(res, 200, { ok: true });
+    }
+
+    if (req.method === 'POST' && url.pathname === '/action') {
+      const body = await readJson(req);
+      sendAction(String(body.name ?? 'greet'));
+      return json(res, 200, { ok: true });
+    }
+
+    // 让它走 / 跑 / 游一段（mode: walk | run | swim）
+    if (req.method === 'POST' && url.pathname === '/roam') {
+      const body = await readJson(req);
+      const mode = ROAM_MODES.includes(body.mode) ? body.mode : 'walk';
+      const ok = sendAction(mode);
+      return json(res, 200, { ok, mode });
+    }
+
+    if (req.method === 'POST' && url.pathname === '/halt') {
+      const stopped = haltRoam('api');
+      sendAction('stop');
+      return json(res, 200, { ok: true, stopped });
+    }
+
+    // 觉醒技能：{"id":"seraph|nocturne|thunder|astral|random"}
+    if (req.method === 'POST' && url.pathname === '/awaken') {
+      const body = await readJson(req);
+      let id = String(body.id ?? 'random');
+      if (id === 'random' || !outfits.list.some((o) => o.id === id)) {
+        id = outfits.list[Math.floor(Math.random() * outfits.list.length)].id;
+      }
+      sendAction(`awaken:${id}`);
+      return json(res, 200, { ok: true, id });
+    }
+
+    // 演出中途叫停
+    if (req.method === 'POST' && url.pathname === '/awaken/stop') {
+      sendAction('awaken-stop');
+      return json(res, 200, { ok: true });
+    }
+
+    // 当前可用的服装 / 觉醒清单
+    if (req.method === 'GET' && url.pathname === '/outfits') {
+      return json(res, 200, { ok: true, list: outfits.list, stage: outfits.stage });
+    }
+
+    // 开 / 关自动活动（自动化测试里先关掉，免得抢窗口）
+    if (req.method === 'POST' && url.pathname === '/auto') {
+      const body = await readJson(req);
+      setAutoRoam(body.enabled !== false);
+      return json(res, 200, { ok: true, autoRoam: state.autoRoam });
+    }
+
+    if (req.method === 'POST' && url.pathname === '/show') {
+      win ? win.show() : createWindow();
+      return json(res, 200, { ok: true });
+    }
+
+    if (req.method === 'POST' && url.pathname === '/hide') {
+      win?.hide();
+      return json(res, 200, { ok: true });
+    }
+
+    return json(res, 404, { ok: false, error: 'not found' });
+  });
+
+  httpServer.on('error', (err) => {
+    console.error(`[http] 端口 ${HTTP_PORT} 不可用：${err.message}`);
+  });
+
+  httpServer.listen(HTTP_PORT, '127.0.0.1');
+}
+
+/* -------------------------------------------------------------------- IPC */
+
+function registerIpc() {
+  let dragOrigin = null;
+  let moveCount = 0;
+
+  ipcMain.on('pet:debug', (_e, msg) => dbg('renderer:', msg));
+
+  ipcMain.handle('pet:get-config', () => ({
+    scale: state.scale,
+    clickThrough: state.clickThrough,
+    autoRoam: state.autoRoam,
+    debug: DEBUG,
+    // 调参 / 自动化用：PET_ROAM_GAP_MS=700 把自主活动的间隔（含觉醒后的停顿）
+    // 压成固定值，几十秒就能把一整轮发牌看完。不开就是正常的随机区间。
+    roamGapMs: Number(process.env.PET_ROAM_GAP_MS) || null,
+    assets: spriteAssets(),
+    // 觉醒清单交给渲染层：菜单里的名字、角色缩放比例、窗口目标规模都从这取
+    awaken: { list: outfits.list, stage: outfits.stage },
+    httpPort: HTTP_PORT,
+  }));
+
+  // 觉醒演出：先用暗幕盖住 → 再调这里放大窗口 → 演出结束再调一次收回
+  ipcMain.handle('pet:awaken-open', () => awakenWindow(true));
+  ipcMain.on('pet:awaken-close', () => awakenWindow(false));
+
+  // 渲染层决定“想走一下”，主进程算出轨迹并驱动窗口
+  ipcMain.handle('pet:roam', (_e, payload) => {
+    const mode = typeof payload === 'string' ? payload : payload?.mode;
+    return startRoam(mode);
+  });
+
+  ipcMain.on('pet:halt-roam', () => haltRoam('renderer'));
+
+  ipcMain.on('pet:drag-start', () => {
+    if (!win) return;
+    haltRoam('drag'); // 用户上手了，巡游让位
+    moveCount = 0;
+    dragOrigin = { cursor: screen.getCursorScreenPoint(), win: win.getPosition() };
+    dbg('drag-start', `cursor=${dragOrigin.cursor.x},${dragOrigin.cursor.y}`, `win=${dragOrigin.win.join(',')}`);
+    win.webContents.send('pet:dragging', true);
+  });
+
+  ipcMain.on('pet:drag-move', () => {
+    if (!win || !dragOrigin) return;
+    const now = screen.getCursorScreenPoint();
+    const x = dragOrigin.win[0] + (now.x - dragOrigin.cursor.x);
+    const y = dragOrigin.win[1] + (now.y - dragOrigin.cursor.y);
+    // 用 setBounds 并显式带上目标尺寸：只 setPosition 的话窗口会一路变大（见 pinSize 注释）
+    win.setBounds({ x, y, ...targetSize() });
+    if (moveCount++ % 12 === 0) {
+      dbg('drag-move', `cursor=${now.x},${now.y}`, `target=${x},${y}`, `actual=${win.getPosition().join(',')}`);
+    }
+  });
+
+  ipcMain.on('pet:drag-end', () => {
+    dragOrigin = null;
+    dbg('drag-end', `win=${win ? win.getPosition().join(',') : '-'}`);
+    win?.webContents.send('pet:dragging', false);
+    // 开了重力时落地会在结束时记位置；关重力就直接把当前落点记下来
+    if (!settleToGround()) persistPosition();
+  });
+
+  ipcMain.on('pet:context-menu', () => popupContextMenu());
+  ipcMain.on('pet:set-scale', (_e, s) => applyScale(Number(s) || 1));
+  ipcMain.on('pet:set-interactive', (_e, interactive) => {
+    if (!win) return;
+    // 注意：渲染层传的是「光标是否落在角色不透明像素上」
+    // interactive=true -> 窗口要接收鼠标事件 -> setIgnoreMouseEvents(false)
+    const nextIgnore = !interactive;
+    if (ignoreMouse === nextIgnore) return;
+    ignoreMouse = nextIgnore;
+    if (state.clickThrough) return; // 手动穿透模式下不听渲染层的
+    dbg('set-interactive', `interactive=${!!interactive} ignoreMouseEvents=${nextIgnore}`);
+    win.setIgnoreMouseEvents(nextIgnore, { forward: true });
+  });
+  ipcMain.on('pet:quit', () => app.quit());
+}
+
+/* ------------------------------------------------------------------- 启动 */
+
+loadState();
+// 自动化测试用：--no-auto 关掉自动巡游，测试自己控制什么时候动
+if (process.argv.includes('--no-auto')) state.autoRoam = false;
+
+// 截图自检用：--anim=<walk|run|swim|awaken:seraph> 摆到某个状态再截帧
+const DEMO_ANIM = (process.argv.find((a) => a.startsWith('--anim=')) || '').split('=')[1] || '';
+
+if (!app.requestSingleInstanceLock()) {
+  app.quit();
+} else {
+  app.on('second-instance', () => {
+    win ? win.show() : createWindow();
+  });
+
+  app.whenReady().then(() => {
+    if (process.platform === 'win32') app.setAppUserModelId('com.local.desktop-pet');
+
+    createWindow();
+    clampIntoWorkArea(); // 上次的位置可能已经不在屏幕上了
+    createTray();
+    registerIpc();
+    startHttpServer();
+    startHitPoll();
+
+    // 显示器缩放/分辨率变化后同样把尺寸钉回目标值
+    screen.on('display-metrics-changed', () => pinSize());
+
+    if (state.clickThrough) applyClickThrough(true);
+    app.setLoginItemSettings({ openAtLogin: state.openAtLogin });
+
+    globalShortcut.register('Control+Shift+P', () => applyClickThrough(!state.clickThrough));
+    globalShortcut.register('Control+Shift+D', () => {
+      if (!win) return createWindow();
+      win.isVisible() ? win.hide() : win.show();
+    });
+    globalShortcut.register('Control+Shift+A', () => {
+      const pick = outfits.list[Math.floor(Math.random() * outfits.list.length)];
+      sendAction(`awaken:${pick.id}`);
+    });
+
+    // 开发自检：截图后退出，用于无人工确认时验证渲染结果
+    // PET_SNAPSHOT_MS 可以改截帧时刻，配合不同值做两帧差分就能证明逐帧动画真的在走
+    if (process.argv.includes('--snapshot') || DEMO_ANIM) {
+      const wantShot = process.argv.includes('--snapshot');
+      const shotMs = Number(process.env.PET_SNAPSHOT_MS) || 1500;
+      win.webContents.once('did-finish-load', () => {
+        if (DEMO_ANIM) {
+          setTimeout(() => {
+            // 觉醒演出走正常的 action 通道（和菜单点的一样），不是 demo 摆拍
+            if (DEMO_ANIM.startsWith('awaken:')) sendAction(DEMO_ANIM);
+            else win?.webContents.send('pet:demo', { anim: DEMO_ANIM });
+          }, 400);
+        }
+        if (!wantShot) return;
+        setTimeout(async () => {
+          const image = await win.webContents.capturePage();
+          const dst = process.env.PET_SNAPSHOT_OUT || path.join(ASSETS, '_snapshot.png');
+          fs.writeFileSync(dst, image.toPNG());
+          console.log(`[snapshot] 已保存 ${dst}`);
+          app.quit();
+        }, shotMs);
+      });
+    }
+  });
+
+  app.on('window-all-closed', () => {
+    // 托盘常驻，不随窗口关闭退出
+  });
+
+  app.on('will-quit', () => {
+    haltRoam('quit');
+    persistPosition();
+    globalShortcut.unregisterAll();
+    httpServer?.close();
+  });
+}