dsh-pet-live2d 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,167 @@
 # 更新日志
 
+## 3.1.0（2026-09-29）
+
+这一轮的主线是**桌面端**：托盘的"没有她"查到底了 —— 根因是本项目自己给产物贴错了
+完整性标签（详见下面「完整性标签」那一节）；同时修好了设置两边不同步、插件"以为已经有一只"、
+独立模式页面把自己藏起来，并加上 macOS（arm64）支持。
+
+### 修：桌面端的设置与 DSH 里的不一致（同一类"两份宿主分叉"）
+
+设置原来只走 `localStorage`（浏览器按 origin 隔离 ✗），所以共享存档必须走
+`%DSH_HOME%\pet-settings.json` + `GET|POST /api/live2d-pet/settings` —— 而**桌面端的 Rust
+宿主没有实现这条路由**（JS 侧 `lib/settings.js` 的注释里甚至写着"Rust 侧的对应实现见
+`host/settings.rs`"，而那个文件当时并不存在）。页面取不到就只能退回它自己那份 localStorage，
+于是两个窗口各显示各的。
+
+现在补上 `host/settings.rs`（与 `lib/settings.js` 逐字对应：三个键 `tuning`/`overrides`/
+`outfit`、合并写、**空写不推进 `rev`**（防两端互推）、坏数据只取形状对的部分）与那条路由。
+实测：GET 空存档 → POST `tuning`（rev 1）→ POST `outfit`（rev 2 且 tuning 不被擦掉）→ 落盘一致。
+
+### 修：插件拉起的那只死了以后，插件一直以为"已经有一只了"
+
+`lib/display.js` 只在 `stop()` 里清 `child`/`childPid`，**子进程自己退出（被杀 / 崩了）时不清**
+—— 于是 `reconcile()` 永远认为"已经有一只了"，既不重拉，设置里还显示"桌面已接管"，而桌面上
+什么都没有。现在给子进程挂了 `exit` 处理器，并在 `start()` 里加了一条自愈（记着的 pid 已经不在、
+心跳也不新鲜 ⇒ 忘掉它再拉）。（用户 2026-09 报的"设置说已接管但看不到宠物"有一半是这个。）
+
+### 新：托盘的**自证与诊断**（写给"托盘里没有她"这类问题）
+
+`TrayIconBuilder::build()` 返回 Ok **不代表图标进了通知区域** —— `tray-icon` 在
+`Shell_NotifyIcon(NIM_ADD)` 失败时是**静默忽略**的（源码注释说"等 Explorer 发 TaskbarCreated
+再重注册"，而那个广播只有资源管理器重启时才有）。现在启动后会自证一次
+（`TrayIcon::rect()` = `Shell_NotifyIconGetRect`）并写日志；拿不到矩形时还会**绕开库手工调一次**
+`Shell_NotifyIcon`（用她自己的窗口 + 系统图标），把返回值和 `GetLastError` 写进
+`%DSH_HOME%\pet-desktop.log`。注意：**矩形拿不到不等于失败**（藏在溢出区里的图标也拿不到），
+所以这条日志是"信息"而不是"失败"。
+
+### 改：Windows 产物名改成 ASCII（`DSH-Pet.exe`）
+
+与 Release 资产 / npm 子包那两份（本来都是 ASCII）保持一致，少一个变量。
+
+### 修：手动启动的桌面端"设置里显示已接管，但看不到宠物"
+
+**独立模式**（自己双击 exe / 不走插件）下，窗口起来了、canvas 也在画，但**页面把自己藏了**：
+客户端的判据是"owner 不是我 ⇒ `visibility: hidden`"，而它读的是 `GET /api/live2d-pet/layer`
+—— 桌面端的 Rust 宿主**没有这个路由**（它只有自己的 `/__desktop/owner`），页面取不到就保持
+默认 `owner: "inline"` ⇒ 桌面壳那一份按规则让位 ⇒ 什么都看不到（托盘图标又默认被 Win11 收进
+溢出区，所以连"她还在"都看不出来）。
+
+挂载模式（插件从设置里拉起，`--attach`）不受影响：那条路把整个 API 转发给了 DSH 里的插件，
+而插件那份 JS 宿主是有 `/layer` 的 —— 这就是"插件起的桌面是好的、手动双击看不到"的全部原因。
+
+修法：Rust 宿主补上 **`GET|POST /api/live2d-pet/layer`**（与 JS 宿主同形：`owner` / `mode` /
+`desktopRunning` / `binary` / `download`；POST 支持改「显示位置」），`/__desktop/owner` 保留
+成同形的别名（已有驱动在读它）。
+
+> 这条属于项目最老的那条纪律：**宿主半区有两份实现，路由形状必须一起改**。客户端某一版
+> 把读口从 `/__desktop/owner` 改成了 `{API}/layer`，Rust 那边没跟上。
+
+### 修：**本地构建**出来的 exe 双击起不来（完整性标签，2026-09 用户报的第三次）
+
+症状：双击 exe 弹一个错误框，里面是 `0x800700AA 请求的资源在使用中`（WebView2），
+同时 `%DSH_HOME%` 里既没有 `pet-desktop.log`、偏好也没被改写 —— 而在 DSH 设置里
+让插件拉起的那只一切正常。
+
+根因是 **Windows 的完整性标签（integrity level）**：**在 DSH 会话里写出来的文件会带
+`Low` 标签**（沙箱给工作区新文件打的就是它），而本地构建的那个 exe 正好产在那儿。
+被打上 Low 标签的 exe，双击起来后进程就是 Low 完整性 —— 按 no-write-up 规则，
+**它写不进任何 Medium 对象**：`%DSH_HOME%`（`拒绝访问 (os error 5)`）与
+`%LOCALAPPDATA%\<id>\EBWebView`（WebView2 建不起来）全都中招。
+插件从 npm 下载的那份（普通进程写的、没有标签）因此完全正常 —— 同一个版本、同一个
+二进制，只差一个标签。
+
+修法（构建期，两道）：
+
+- `tools/integrity.mjs`：检查产物的完整性标签，**带 Low/Medium 就摆成 `High`**（= 不设上限）
+  并复查，摆不正直接让构建失败；
+- 接进 `build-portable.mjs`（产物出库）与 `npm-prepare-subpackage.mjs`（发 npm 前），
+  所以**发布物不可能再带压低进程的标签**。
+
+⚠️ 这里有个**曾经的错误修法**：一开始是摆成 `Medium`，结果在"资源管理器跑在 High"的机器上
+（UAC 关闭 ⇒ 整机 High）**连托盘都注册不上**（`Shell_NotifyIcon` 返回 FALSE、
+`GetLastError=5`）—— 因为完整性标签是**上限**，Medium 会把进程压在 Medium，
+它对 shell 的托盘消息被 UIPI 拦掉。**正确做法是没有标签，或者摆成 High。**
+
+已经拿到带标签版本的用户：`icacls "<exe>" /setintegritylevel High` 一条命令即可修好
+（或者重新下载一遍发布包）。
+
+### 修：直接双击桌面端的 exe，她"没显示出来"（2026-09 用户报）
+
+症状：双击 GitHub Release 里那个 exe，**什么都没发生**；但插件从设置里拉起来的那只一切正常。
+
+根因不是 exe 坏了，是**显示层的偏好**：设置里选的是「页面内」时，桌面端按规则必须让位 ——
+它起来、刷心跳、读到 `mode: "inline"`，然后**1 秒内把自己藏了**（进程其实活着，托盘图标也
+在 Win11 的溢出区里）。而插件那条路会先把偏好写成「桌面」再拉起，所以它看着是好的。
+
+现在：**手动启动（不是插件拉起的）遇到「页面内」偏好，就把它切成「桌面」** —— 双击这个动作
+本身就是"我要她在桌面上"。写的是同一个共享文件，所以页面里那只立刻让位，仍然只有一只；
+想改回来，去 DSH 设置里选「页面内」。
+
+顺带把"什么都看不到"这件事本身修了（这才是真正难查的地方）：
+
+- **启动日志**：`%DSH_HOME%\pet-desktop.log`（同时照旧打 stderr），记下**是哪个 exe**、
+  显示层偏好、"显示 / 让位"的结论与原因；写不进 `%DSH_HOME%` 时**退到 exe 旁边**再写一份，
+  两处都写不进去就把原因带进弹框（以前这种写失败是静默的，用户第二次报的就是它：
+  弹框指的日志文件压根没生成）；
+- **起不来会弹框**：GUI 程序没有控制台，以前 panic 是彻底静默的。现在 Windows 上会弹一个
+  错误框，写明**程序路径** + 日志路径（macOS 上只有日志）。
+
+### 修：已经有一只时，第二只不再报"起不来"
+
+WebView2 的 user-data-dir 是**独占**的，第二个实例只会撞 `0x800700AA 请求的资源在使用中`，
+而那个错误以前被 panic 成一个吓人的报错框。现在：启动时先看**心跳**（不是 pid —— 系统会重用
+pid），已经有一只活着就**安静退出**并在手动双击时提示"她已经站在桌面上了（Win11 托盘图标
+默认收在溢出区）"。
+
+同时补了两条：
+
+- **建窗失败会自动重试 3 次**（每次隔 1.5 秒）：上一只刚退出、目录还没放开是常见情形，
+  等一下通常就好了，没必要让用户看报错；重试过程每次都写进日志。
+- **插件收掉桌面端时连整棵进程树一起收**（Windows 上 `taskkill /T`）：`child.kill()` 只杀壳，
+  WebView2 的 `msedgewebview2.exe` 子进程会留下来占着数据目录 —— 那正是"下一次启动撞
+  0x800700AA"的常见来源。
+
+### 新：macOS（Apple Silicon）的桌面端构建
+
+以前桌面端只有 Windows。现在 macOS arm64 也能出产物了 —— 由 GitHub Actions 构建
+（`.github/workflows/desktop-mac.yml`，`macos-14` runner），一次产出两样：
+
+| 产物 | 给谁用 |
+|---|---|
+| `DSH桌宠.app`（zip） | 人：双击就站出来 |
+| `dsh-pet-live2d-desktop`（tar.gz，裸二进制） | 插件：npm 平台子包 `dsh-pet-live2d-desktop-darwin-arm64` 要的那份 |
+
+为此改的东西（都在桌面端那一侧）：macOS 上**读全局光标**改走 CoreGraphics（透明层"哪块
+区域吃鼠标"的判定靠它，以前非 Windows 直接返回"读不到"，等于她永远点不到）；主目录按
+平台取（macOS 是 `HOME`，以前只认 `USERPROFILE`，会退化成当前目录下的 `.dsh`）；macOS 用
+`ActivationPolicy::Accessory` 藏进"不进程序坞"（Windows 的 `skip_taskbar` 在 mac 上没有
+实现）；`.app` 里不再往包内写运行期数据（那会破坏代码签名）。
+
+**没验过的地方，别当既成事实**：本项目所有驱动都跑在 Windows 上，macOS runner 又没有可
+交互的窗口会话 —— "她能不能点、能不能穿透、跟不跟手"目前**只有代码层面的理由**，没有
+实测。Intel Mac 与 Linux 都还没有构建。
+
+### 注意：macOS 那份没有签名
+
+第一次打开会被 Gatekeeper 拦（"无法验证开发者"）：右键→打开，或者
+`xattr -dr com.apple.quarantine <路径>`。想双击就能开，需要 Apple Developer ID（$99/年）
++ 公证 —— 那时 CI 里能一起做，但证书得先有。
+
+## 3.0.1
+
+### 修：「自拍」右手不抬（3.0.0 引入）
+
+3.0.0 那一版把"保姿势录像"里的一道豁免撤掉了，于是自拍时抬手的那条参数每帧又被压回 0，
+**手一直垂着**。3.0.1 把它修回来，并按"动作需要就每帧写值"的正解加固：
+
+自拍的抬手参数（`phone5`）在动作文件里的曲线是 **0 → 9.7 → 0**，也就是说光靠曲线抬不起来；
+现在由动作自己**每帧按住**一个明确的值（写在引擎更新之后，不会再被曲线或回放层盖掉），
+动作一结束就松开，不会留下永久钉住的状态。
+
+判据不再只看"参数值在不在跑"（那个骗过我三次），而是**像素级核对画面**：自拍峰值那一帧
+与"掏出手机定格"必须有实质差异 —— 手机从桌面举到了脸边。
+
 ## 3.0.0
 
 **桌面端正式随插件一起发布。** 装完插件、在设置里选「桌面」，她就在桌面上——

package/lib/client.js

@@ -260,6 +260,19 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      */
     let keptPoses = [];
     const poseSnapshots = new Map();
+    /**
+     * **动作自己要的参数：每帧按住**（`motionOptions.<组>.holdParams = { id: 值 }`）。
+     *
+     * 和 `preset` 的区别就是"每帧"：`preset` 只写一次，之后会被动作曲线与保姿势回放
+     * 盖掉（实测自拍播放中 `phone5` 恒为 0）。抬手这类"动作需要、但它自己又写不对"
+     * 的参数只能每帧按住。跟着 `currentEntry` 一起失效，不会留下永久钉住的状态。
+     */
+    let actionHolds = null;
+    /**
+     * 诊断："每帧按住"那次写入之后，`phone5` 在模型里是多少、写了多少次、有没有抛错。
+     * 用它区分"没执行"与"执行了但之后被覆盖"—— 我在这两者之间来回猜了两轮。
+     */
+    let holdProbe = null;
     /** 参数名 -> 下标 的缓存（见 parameterIndex）。 */
     const paramIndexCache = new Map();
     /** ~5 秒 @60fps，够盖住这只模型 4 秒的待机循环。 */
@@ -1050,30 +1063,29 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      *
      * 写在 applyRelease **之后**（否则会被还原表顶掉），表达式层之前（表情仍然最大）。
      *
-     * ⚠️ **动作驱动的参数不能被保姿势录像压住**（这一条修的是用户报的"装扮里的自拍右手不抬"）：
-     * 自拍（`Selfie`）驱动 `phone5`（抬手；干净试验台实测：推 `phone5` 会让
+     * ⚠️ **动作曲线碰过的参数不能被保姿势录像压住**（这一条修的是用户报的"自拍右手不抬"）：
+     * 自拍（`Selfie`）驱动 `phone5`（抬手，在干净试验台里确认过：推 `phone5` 会让
      * `看手机/ArtMesh26` 那块几何变形），但「掏出手机」定格时录下的那一帧里 `phone5=0`，
      * 于是这一层每帧把它写回 0 —— 写在动作更新之后，**曲线被压住**。干净环境实测：
      * 自拍里 `phone5` 涨到 9.713，而手那块几何一动不动（盒完全相同）。
      *
-     * 判据**由宠物声明**（`motionOptions.<组>.ignoreKeptParams`），不在这里猜：
-     * 我试过"`currentEntry.params` 里有的就跳过"，那是**宿主按曲线生成的清单**，
-     * 可能含动作文件根本没写的参数（实测 `OpenCase` 的清单含 `phone5`，曲线却不写它）——
-     * 结果把相位/别的槽位那套保姿势一起打断了（`cdp-head`「no single hand option
-     * dominates」、`cdp-host-events`「tool phase sustains」当场红，A/B 撤回那一处即全绿）。
-     * 声明式的名单面窄、看得见、改 pet.json 就能调，不会误伤别的路径。
+     * 所以：录像里那些**当前动作曲线碰过**的参数跳过不写，让动作说了算；
+     * 其余（掏出手机自己的 `phone`/`phone2`/`phone4`/`phone6` 之类）照旧保姿势。
+     *
+     * ⚠️ **别把它换成"宠物声明的名单"**：我在 3.0.0 那版换成了
+     * `motionOptions.<组>.ignoreKeptParams`，结果用户立刻报"自拍又被修坏了" ——
+     * 因为 `OpenCase` 的曲线清单本来就含 `phone5`，换名单等于**把这道豁免撤掉**。
+     * 这条判据要看的是"动作碰过哪些参数"，`currentEntry.params` 正是这个语义。
      */
     const applyKeptPoses = (core, values) => {
       if (keptPoses.length === 0 || values === null) return;
-      const skip = currentEntry === null
-        ? null
-        : optionsFor(currentEntry.group)?.ignoreKeptParams ?? null;
-      const skipSet = Array.isArray(skip) ? new Set(skip) : null;
+      const owned = currentEntry === null ? null : currentEntry.params;
+      const ownedSet = owned === null || owned === undefined ? null : new Set(owned);
       for (const group of keptPoses) {
         const frame = poseSnapshots.get(group);
         if (frame === undefined) continue;
         for (const id of Object.keys(frame)) {
-          if (skipSet !== null && skipSet.has(id)) continue;
+          if (ownedSet !== null && ownedSet.has(id)) continue;
           const at = parameterIndex(core, id);
           if (at >= 0) values[at] = frame[id];
         }
@@ -1158,6 +1170,9 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         if (Math.abs(mouthTargetFollow - mouthFollow) < 0.002) mouthFollow = mouthTargetFollow;
         if (Math.abs(mouthTargetLean - mouthLean) < 0.002) mouthLean = mouthTargetLean;
       }
+      // **动作自己要的参数**（`motionOptions.<组>.holdParams`）**不在这里写** ——
+      // 缝隙在 `update()` 之前，而曲线是 `update()` 里写的，写在这儿会被曲线盖掉。
+      // 真正的实现在 `update()` 的钩子里（搜 `actionHolds`）。
       // Blink. Runs before the early return because it is unconditional — it
       // has nothing to do with what is pinned, and the engine's own blink is
       // disabled precisely because its gate never opens for this model.
@@ -1397,6 +1412,31 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
             updateBase();
             updateCalls += 1;
             markSeam("U");
+            // **每帧按住的值写在这里**（`update()` 之后 = 这一帧最后一步）。
+            //
+            // 为什么不在缝隙里（`loadParameters` 那条）：缝隙在 `update()` **之前**，
+            // 而动作曲线是 `update()` 里写的 ⇒ 死死被曲线盖住。实测：表装对了
+            // （`holds={"phone5":10}`）而 `phone5` 读出来仍是曲线的形状
+            // （1.78 → 9.87 → 0）。这正是"动作要写值"必须写在最后的原因。
+            if (actionHolds !== null) {
+              // ⚠️ 这个 try 是**静默**的：里面任何拼错的变量都会把"写入"一起吞掉，
+              // 而外面的症状只是"值没生效"（我在这儿被坑了一轮：探针里写了个不存在的
+              // `probeAt`，于是写入根本没跑，而 `holds` 表看起来完全正常）。
+              try {
+                const values = core._model.parameters.values;
+                for (const id of Object.keys(actionHolds)) {
+                  const at = parameterIndex(core, id);
+                  if (at >= 0) values[at] = actionHolds[id];
+                }
+                const probeAt = parameterIndex(core, "phone5");
+                holdProbe = {
+                  wrote: probeAt >= 0 ? values[probeAt] : null,
+                  calls: (holdProbe?.calls ?? 0) + 1,
+                };
+              } catch (error) {
+                holdProbe = { error: String(error).slice(0, 120), calls: (holdProbe?.calls ?? 0) + 1 };
+              }
+            }
             updateSample = sample();
           };
         }
@@ -1516,6 +1556,9 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       // supposed to do the spraying is a separate parameter (`jingyu`) that
       // nothing in that motion touches — which is why it looked like a no-op.
       const preset = opts.preset ?? null;
+      // 每帧按住的参数（见 actionHolds 的注释）。读宠物声明的 `holdParams`。
+      const holdParams = opts.holdParams ?? null;
+      actionHolds = holdParams !== null && typeof holdParams === 'object' ? Object.assign({}, holdParams) : null;
       // Stop ONLY when replaying the very same group+index, which is the one
       // case the engine refuses on its own. Clearing the queue unconditionally
       // removed the outgoing motion instantly, so there was nothing left to
@@ -1581,12 +1624,15 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       restoreHeld();
       playIdle();
     };
+
     /** Return to the looping idle animation; the resting state of the pet. */
     const playIdle = () => {
       clearTimer();
       token += 1;
       kind = "idle";
       currentEntry = null;
+      // 回待机 = 动作结束 ⇒ 松开"每帧按住"的表（见 actionHolds）。
+      actionHolds = null;
       if (model === null || idleName === null) return;
       // Coming back to rest retires the previous action's parameter pins, so
       // the bubble-gum mouth (and anything else action-specific) is released
@@ -1955,6 +2001,19 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       }),
       /** Diagnostic: how shut the eyes were on the last frame, 0..1. */
       blinkAmount: () => blinkWrote,
+      /**
+       * Diagnostic: "每帧按住"那张表（`motionOptions.<组>.holdParams`）。
+       *
+       * 加它的原因：我按"抬手要每帧写值"实现了 `holdParams`，但实机读 `phone5` 仍是
+       * 曲线值（8.88 而不是 10）—— 必须能直接看到"表到底有没有被装上、里面是什么"，
+       * 否则只能在外面猜是没传进来还是被覆盖了。
+       */
+      holdDebug: () => ({
+        holds: actionHolds === null ? null : Object.assign({}, actionHolds),
+        group: currentEntry === null ? null : currentEntry.group,
+        kind: kind,
+        probe: holdProbe === null ? null : Object.assign({}, holdProbe),
+      }),
       /** Force a blink now, so a test does not have to wait for one. */
       blinkNow: () => { blinkAt = 0; blinkStart = (typeof performance !== "undefined" ? performance.now() : Date.now()); },
       /** Diagnostic: how many motions the engine is cross-fading right now. */

package/lib/desktop.js

@@ -26,7 +26,11 @@ const HERE = dirname(fileURLToPath(import.meta.url))
 export function desktopPackageName(platform = process.platform, arch = process.arch) {
   const table = {
     'win32-x64': 'dsh-pet-live2d-desktop-win32-x64',
-    // 将来加构建时在这里补：'darwin-arm64' / 'linux-x64' …
+    // macOS arm64（Apple Silicon）。**只有构建与代码就绪，npm 上还没有这个子包** ——
+    // 发布前要补两步，顺序不能反（否则用户拿到的主包会指向一个不存在的子包）：
+    //   1. `node tools/npm-prepare-subpackage.mjs --sub darwin-arm64` 后把子包发上 npm；
+    //   2. 主包 `optionalDependencies` 加一行 `"dsh-pet-live2d-desktop-darwin-arm64": "<主包版本>"`。
+    'darwin-arm64': 'dsh-pet-live2d-desktop-darwin-arm64',
   }
   return table[platform + '-' + arch]
 }

package/lib/display.js

@@ -16,7 +16,7 @@
 //
 // 为什么不走 DSH 的进程内服务：桌面端是另一个进程，拿不到 `ctx.on(...)`。一个文件加一条
 // 纯规则，是这两边唯一都能用的东西。
-import { spawn } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -155,8 +155,20 @@ export function createDisplayLayer(options) {
   function stop() {
     if (child === null) return false
     try {
-      child.kill()
-      note('已收掉桌面端（pid ' + childPid + '）')
+      // ⚠️ Windows 上 `child.kill()` 是 TerminateProcess：**只杀壳自己**。WebView2 的
+      // `msedgewebview2.exe` 子进程会留下来继续占着 `%LOCALAPPDATA%\<id>\EBWebView`
+      // （那是独占的），于是**下一次**启动撞 `0x800700AA 请求的资源在使用中`
+      // —— 用户 2026-09 报的那个报错框就是这么来的。
+      // 所以 Windows 上连整棵进程树一起收（`/T`），别留孤儿。
+      if (process.platform === 'win32') {
+        spawnSync('taskkill', ['/pid', String(childPid), '/T', '/F'], {
+          stdio: 'ignore',
+          windowsHide: true,
+        })
+      } else {
+        child.kill()
+      }
+      note('已收掉桌面端（pid ' + childPid + '，含子进程）')
     } catch {
       /* 已经退了 */
     }
@@ -173,6 +185,15 @@ export function createDisplayLayer(options) {
       note('找不到桌面端二进制，无法拉起（' + (options.hint ?? '') + '）')
       return { ok: false, reason: 'binary-missing' }
     }
+    // **先自愈**：我们记着的那个子进程可能早就没了（被杀 / 崩了 / 崩溃后没人收），
+    // 而 `exit` 事件也没到（比如进程被 `taskkill /T` 连带干掉）。不清理的话
+    // `childPid !== 0` 会让下面那条守卫永远返回"已经有一只了" —— 于是设置里显示
+    // **"桌面已接管"、桌面上却什么都没有**（用户 2026-09 报的现象）。
+    if (childPid !== 0 && !pidAlive(childPid) && !running()) {
+      note('记着的桌面端进程（pid ' + childPid + '）已经不在了 —— 忘掉它')
+      child = null
+      childPid = 0
+    }
     if (childPid !== 0 || running()) return { ok: true, reason: 'already-running' }
     if (Date.now() - lastAttempt < RETRY_MS && lastAttempt !== 0) {
       return { ok: false, reason: 'retry-cooldown' }
@@ -180,13 +201,27 @@ export function createDisplayLayer(options) {
     lastAttempt = Date.now()
     try {
       // `detached` + `unref`：她是**独立的**窗口进程，DSH 关掉她还得站着。
-      child = spawn(binary.path, ['--attach', dshUrl], {
+      //
+      // `--from-plugin`：告诉壳"这一份是插件按设置拉起的" —— 壳据此**严格尊重**用户的
+      // 「页面内」选择。**手动双击**时没有这个参数，壳会把「页面内」改写成「桌面」：
+      // 双击的意图就是"我要她在桌面上"，否则用户看到的是"双击了，什么都没发生"
+      // （2026-09 用户报的就是这个；见壳里 `host::display::manual_launch_overrides_inline`）。
+      child = spawn(binary.path, ['--attach', dshUrl, '--from-plugin'], {
         detached: true,
         stdio: 'ignore',
         windowsHide: true,
       })
       childPid = child.pid ?? 0
       child.unref()
+      // **子进程退出要当场忘掉它**：否则 `childPid` 永远非 0，reconcile 会一直认为
+      // "已经有一只了"，她死了插件也不重拉（设置里还显示"桌面已接管"）。
+      child.on('exit', () => {
+        if (childPid === (child?.pid ?? 0)) {
+          note('桌面端进程退出了（pid ' + childPid + '）')
+          child = null
+          childPid = 0
+        }
+      })
       note('已拉起桌面端：' + binary.path + ' --attach ' + dshUrl + '（pid ' + childPid + '）')
       return { ok: true, reason: 'spawned', pid: childPid }
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pet-live2d",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Live2D 桌宠插件：为 DSH Web GUI 挂一只可拖动、会跟随鼠标、能换动作与表情的 Live2D 宠物。",
   "type": "module",
   "main": "lib/index.js",
@@ -49,7 +49,7 @@
     }
   },
   "optionalDependencies": {
-    "dsh-pet-live2d-desktop-win32-x64": "3.0.0"
+    "dsh-pet-live2d-desktop-win32-x64": "3.1.0"
   },
   "devDependencies": {
     "esbuild": "^0.25.10",

package/pets/ds-whale-girl/pet.json

@@ -44,9 +44,9 @@
         "hold": true
       },
       "Selfie": {
-        "ignoreKeptParams": [
-          "phone5"
-        ]
+        "holdParams": {
+          "phone5": 10
+        }
       }
     },
     "expressionSlots": [