dsh-pet-live2d 2.3.1 → 2.3.3

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # 更新日志
 
+## 2.3.3
+
+### 修：互动反应补上**内置默认值** —— 宠物没声明那三组也演得出来
+
+「摸头 / 摸尾巴 / 转圈」演什么，之前**只**认宠物 `pet.json` 里的 `patReactions` /
+`tailReactions` / `spinReactions`，插件代码里一个默认值都没有。于是**自己做的宠物**
+（最小 `pet.json` 里根本没有这三个键）上：
+
+| 互动 | 以前 | 现在（没声明时） |
+|---|---|---|
+| 摸头 | 只有台词，**不演重锤出击** | 重锤出击 / 问号 / 星星眼 随机一个 |
+| 摸尾巴 | 只有台词 | 吐魂 / 问号 |
+| 转圈转晕 | 演不出来 | 晕晕 |
+
+兜底顺序和台词、摸鱼池是同一套：**用户改过的 <- 宠物声明的 <- 内置默认**。
+宠物自己声明了就一直用宠物那份（这只鲸鱼娘一字未变），只是"没写"不再等于"没反应"。
+
+设置页「互动」卡里那三组候选现在显示的就是**有效那一组**（和运行时会演的完全一致），
+行尾会标明来历：`（宠物默认）` / `（内置默认）` / `（已改过）` —— 看到的是内置值时
+你就知道"改宠物也能改这一组"。
+
+### 修：随包宠物的默认值**终于能到老用户手里**（原来装过一次就再也不会更新）
+
+`installBundledPets()` 以前是"目标目录存在就跳过"。插件目录随 `dsh plugin add` / npm
+更新，用户的宠物目录 `%DSH_HOME%\pets\<id>\` **不会** —— 于是宠物**自己的默认值永远停在
+装它的那一天**：2.3.0 往 `pet.json` 里加的那批（台词 / 互动反应候选 / 摸鱼槽位 /
+`asking`·`helper`·`queued` 三个相位、自拍等三个槽位）一个都没到过桌面。
+
+症状和你这次报的一模一样，而且**看起来完全像插件的 bug**：互动只有台词不演反应、
+相位台词一句不弹、装扮里少三个槽位、`会话相位` 列表里少三个状态。
+
+现在按**内容**判定，三条：
+
+| 宠物目录里那份 | 行为 |
+|---|---|
+| 不存在 | 装一份，并把版本与内容指纹记进 `pets/.synced.json` |
+| 就是我们装下去的那一份（指纹逐字节相同） | 整份更新到随包版本 |
+| 你自己改过（指纹对不上） | **一个字都不碰**（日志里会说一句"跳过更新"） |
+
+冷启动（同步记录出现之前装的副本，也就是所有老装机）靠一张**历史内容指纹表**认人：
+与历史上任何一次随包分发逐字节相同才升级 —— 改过名字、槽位、任何一个字，哈希就不同，
+所以"用户自己改过的宠物永远优先"这条没有被削弱。
+
+升级会在宿主日志里说清楚：
+
+```
+[live2d-pet] ds-whale-girl：宠物默认值更新到 1.1.0（原先 1.0.1）
+```
+
+> 顺带把随包宠物的版本抬到 **1.1.0**。升级判定只看内容指纹、不看版本号 ——
+> 同一个版本号下补默认值也能发出去（这次就是）。
+
+### 修：互动候选「改不动」的隐患
+
+`PHASE_OVERRIDES`（设置覆盖的存放处）初始化时**漏了 `interactions` 这个键**，而
+`applyOverride()` 是直接往这个对象上写的 —— 也就是说第一次点候选时覆盖会被静默丢掉。
+读的地方都写了 `?.`，所以它一直"读得出来、写不进去"，只有正面写它的设置界面会踩到。
+
+现在五个键（`phases` / `fidget` / `relations` / `interactions` / `lines`）都在初始化时给出来，
+并加了一条断言盯着"点一下候选 → 覆盖真的落盘"。
+
+### 诊断：新增 `reactionDiagnostics()`
+
+三组候选各自的**来历**（`user` / `pet` / `builtin` / `none`）、内置默认值、以及最终生效值。
+"点了她没反应"这类问题一眼就能分出是"用户覆盖成了空数组"、"宠物没声明"还是"连兜底都没了"
+—— 只看 `effectiveReactions()` 是分不出来的。
+
+## 2.3.2
+
+### 修：摸尾巴又摸不到了（这次是真的）
+
+用户报的："现在又摸不到尾巴了。"（还发了一张圈出尾巴位置的截图，帮了大忙 —— 尾巴是
+**右侧那只鲸鱼尾鳍**，不是翅膀。）
+
+**真正的根因**：判定每块 drawable 时用的是**映射时算好并存下来的下标**（`entry.index`），
+而不是**调用时按 id 现查的下标**。这两者只要有一处对不上，取到的顶点就是别人的 ——
+表现是"每块单独测都能命中，聚合起来一个都不中"。
+
+单块测（`drawableProbe`）之所以一直正常，正是因为它**每次都按 id 现查下标**。
+现在聚合路径也这么做了：`hitsPartsGeometry` 在循环里用 `im.getDrawableIndex(entry.id)`
+重新解一次，解不出来才退回缓存值。
+
+修好后同一网格上的读数：`hitsTail` 从 **0 → 509** 命中（48×48），头部 1113、重叠 689
+—— 重叠仍然存在（翅膀的几何本来就伸到头顶上方），所以**摸头优先于摸尾巴**那条继续保留：
+点头部给摸头，尾巴自己的区域照样摸得到。
+
+### 一段该记下来的教训：坏掉的诊断比没有诊断更糟
+
+这轮我查了很久，很大一部分时间是被**自己写的诊断函数**骗了：`partHitCounts` 里调了
+`api.drawableProbe(...)`，而 `api` 是控制器**返回出去**的对象，控制器内部根本看不到它
+—— 每次调用都抛 `api is not defined`，被外面的 try/catch 吞掉，于是 `hitsAll`/`hitsVisible`
+**恒为 0**。外面看到的却是"这个部件完全没有几何"，一条**看起来像产品坏了**的读数。
+
+代价：我据此排除了三个正确假设（透明度过滤、下标空间、包围盒预筛），还改坏过一次
+（把顶点整条换成 core 层，连头部判定都变成 0 命中，已还原）。
+
+教训：**诊断函数自己也要先自证**（拿一个已知能命中的样本去测它），读数与事实矛盾时
+先怀疑测量工具，再怀疑被测对象。
+
 ## 2.3.1
 
 ### 修：摸头会出摸尾巴的效果

package/README.md

@@ -3,7 +3,12 @@
 给 **DSH**（DeepSeek Harness）Web GUI 用的 **Live2D 桌宠插件**：一只可以拖动、跟着鼠标看、
 点她会害羞、还会跟着会话状态换动作的桌宠。
 
-自带 **DS鲸鱼娘**（8 组动作 + 44 个表情/道具），开箱即用。更新日志见 [CHANGELOG.md](CHANGELOG.md)。
+自带 **DS鲸鱼娘**（8 组动作 + 44 个表情/道具），开箱即用。
+
+> **宠物会跟着插件一起更新**：随包的那只（以及它的默认设置：台词、互动反应、
+> 会话相位、摸鱼槽位）在插件升级时**自动同步**到 `%DSH_HOME%\pets\ds-whale-girl\`。
+> 你自己改过的那份**不会被覆盖**（判定是内容指纹，改过就一个字都不碰），
+> 想拿回随包版本就把目录删掉、重启 `dsh web`，它会重新装一份。更新日志见 [CHANGELOG.md](CHANGELOG.md)。
 
 ![桌宠](docs/preview.png)
 
@@ -131,6 +136,11 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 - 转圈看的是**累计转角**（不是位置绕了几圈），所以贴着角色转小圈、远远转大圈都算。
 - 三个互动各自可开关，反应也能改（见下）。共用的三句台词在「气泡」设置里。
 
+> 上表那三组是**默认反应**，来源分两层：宠物 `pet.json` 里声明了就用它的；**没声明就用
+> 插件内置的这几个**（重锤出击 / 问号 / 星星眼、吐魂 / 问号、晕晕）—— 自己做的宠物不写
+> 这三个键也有反应。设置页「互动」卡的行尾会标明当前用的是哪一层（宠物默认 / 内置默认 /
+> 已改过），候选勾选本来就是最高优先级。
+
 ### 气泡：说什么、在哪、要不要
 
 她说话时会弹一个小气泡（问候、点击、摸头、摸尾巴、转晕、归位，以及**每个会话相位一句**：
@@ -237,6 +247,11 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
     "looksByPhase": { "done": { "whale": "头顶鲸", "mood": "开心兴奋" } },
     // 摸鱼默认盯哪些槽位（用户还能再加；不写就是"手/情绪/脸红/嘴/眼"那五个兜底）
     "fidgetSlots": ["rhand", "lhand", "mood", "cheek", "mouth", "eyes", "selfie"],
+    // 互动反应候选（标签 = 动作的中文名或表情名）。**三个键都可以不写** ——
+    // 不写就用插件内置的：摸头 重锤出击/问号/星星眼、摸尾巴 吐魂/问号、转晕 晕晕
+    "patReactions": ["重锤出击", "问号", "星星眼"],
+    "tailReactions": ["吐魂", "问号"],
+    "spinReactions": ["晕晕"],
     // 可选；模型自己表达不了的「作者意图」
     "motionOptions": {
       "OpenCase":   { "hold": true },

package/lib/client.js

@@ -307,18 +307,40 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      */
     const drawableIndicesForParts = (parts) => {
       const raw = model?.internalModel?.coreModel?._model;
+      const im = model?.internalModel;
       const parent = raw?.drawables?.parentPartIndices;
       const partIds = raw?.parts?.ids;
-      if (parent === undefined || partIds === undefined) return null;
+      const coreIds = raw?.drawables?.ids;
+      if (parent === undefined || partIds === undefined || coreIds === undefined) return null;
       const ids = Array.from(partIds).map(String);
       if (ids.length === 0 || parts.length === 0) return null;
       const wanted = new Set(parts);
+      const coreIndexById = new Map();
+      for (let i = 0; i < coreIds.length; i += 1) coreIndexById.set(String(coreIds[i]), i);
+      // **以包装层的顺序为主**：顶点就是按 `internalModel.getDrawableIDs()` 的顺序读的
+      // （单块 `drawableProbe` 走得通的正是这条路）。反过来"遍历原始表再翻译下标"，
+      // 只要两套顺序有一处不一致，取到的顶点就是别的 drawable —— 表现就是"几何明明
+      // 又大又真，聚合判定一个都不中"。这里逐个 id 反查它属于哪个部件，不存在歧义。
+      const wrapperIds = typeof im?.getDrawableIDs === "function"
+        ? Array.from(im.getDrawableIDs()).map(String)
+        : null;
       const out = [];
-      for (let i = 0; i < parent.length; i += 1) {
-        const partIndex = parent[i];
-        if (partIndex < 0 || partIndex >= ids.length) continue;
-        if (!wanted.has(ids[partIndex])) continue;
-        out.push({ index: i, part: partIndex });
+      if (wrapperIds !== null) {
+        for (let w = 0; w < wrapperIds.length; w += 1) {
+          const coreIndex = coreIndexById.get(wrapperIds[w]);
+          if (coreIndex === undefined) continue;
+          const partIndex = parent[coreIndex];
+          if (partIndex === undefined || partIndex < 0 || partIndex >= ids.length) continue;
+          if (!wanted.has(ids[partIndex])) continue;
+          out.push({ id: wrapperIds[w], index: w, coreIndex, part: partIndex });
+        }
+      } else {
+        for (let i = 0; i < parent.length; i += 1) {
+          const partIndex = parent[i];
+          if (partIndex < 0 || partIndex >= ids.length) continue;
+          if (!wanted.has(ids[partIndex])) continue;
+          out.push({ id: String(coreIds[i]), index: i, coreIndex: i, part: partIndex });
+        }
       }
       return out.length > 0 ? out : null;
     };
@@ -359,25 +381,30 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     const hitsPartsGeometry = (indices, x, y) => {
       const im = model?.internalModel;
       if (im === undefined || im === null) return null;
-      // 顶点在**包装层**、三角形索引在**core 层**（实测：`im` 有 getDrawableVertices，
-      // `im.coreModel` 才有 getDrawableVertexIndices）—— 只查一个就会静默返回 null、
-      // 悄悄退回方框判定。两边各取所长。
+      // 顶点用**包装层**的（core 的 `getDrawableVertices` 不在同一个坐标空间里：整条换成
+      // core 之后连头部判定都变成 0 命中）。三角形索引只有 core 有；两套按**同一个下标**
+      // 取用时是自洽的（单块 `drawableProbe` 用同一组合能命中，已实测）。
+      const core = im.coreModel;
       const verticesOf = typeof im.getDrawableVertices === "function"
         ? (index) => im.getDrawableVertices(index)
-        : (typeof im.coreModel?.getDrawableVertices === "function"
-          ? (index) => im.coreModel.getDrawableVertices(index)
-          : null);
-      const indicesOf = typeof im.getDrawableVertexIndices === "function"
-        ? (index) => im.getDrawableVertexIndices(index)
-        : (typeof im.coreModel?.getDrawableVertexIndices === "function"
-          ? (index) => im.coreModel.getDrawableVertexIndices(index)
-          : null);
+        : (typeof core?.getDrawableVertices === "function" ? (index) => core.getDrawableVertices(index) : null);
+      const indicesOf = typeof core?.getDrawableVertexIndices === "function"
+        ? (index) => core.getDrawableVertexIndices(index)
+        : (typeof im.getDrawableVertexIndices === "function" ? (index) => im.getDrawableVertexIndices(index) : null);
       if (verticesOf === null || indicesOf === null) return null;
       if (indices === null) return null;
       let read = false;
       try {
         for (const entry of indices) {
-          const verts = verticesOf(entry.index);
+          // **调用时用 id 重新解一次下标**，别信缓存的 `entry.index`：
+          // 单块 `drawableProbe` 走得通、聚合路径走不通，两者剩下的唯一差别就是这个
+          // （它每次都用 id 现查，聚合路径用映射时算好并存下来的那份）。
+          let index = entry.index;
+          if (typeof entry.id === "string" && typeof im.getDrawableIndex === "function") {
+            const fresh = im.getDrawableIndex(entry.id);
+            if (fresh >= 0) index = fresh;
+          }
+          const verts = verticesOf(index);
           if (verts === undefined || verts === null || verts.length < 6) continue;
           read = true;
           // 先用这个 drawable 的包围盒排除（绝大多数部件一眼就出局，不用扫三角形）。
@@ -2114,10 +2141,130 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
             box: maxX > minX ? { minX: Math.round(minX), maxX: Math.round(maxX), minY: Math.round(minY), maxY: Math.round(maxY) } : null,
             hitsAll,
             hitsVisible,
+            // 每块报：id / 包装层下标 / 原始表下标。
+            // **别再在这里调 `api.xxx`**：`api` 是控制器返回出去的那个对象，控制器内部
+            // 看不到它 —— 调了就是 `api is not defined`，整个函数抛异常、所有读数变 0，
+            // 而外面看起来像"这个部件完全没有几何"（我为此白查了三轮）。
+            entries: entries.map((entry) => ({
+              id: entry.id ?? null,
+              index: entry.index,
+              core: entry.coreIndex,
+              part: entry.part,
+            })),
           });
         }
         return out;
       },
+      /**
+       * Diagnostic: 全部 drawable 的 id / 所属部件名 / 顶点数 / 包围盒（模型空间）。
+       *
+       * 找"她身上真正在画尾巴的那一个"用这个：作者给**部件**起了中文名（尾巴翅膀/猫尾/
+       * 大翅膀…），但 drawable 本身多半叫 `ArtMesh123`。按包围盒的位置就能认出来
+       * （尾巴在身体下后方、翅膀在两侧）。
+       */
+      drawableTable: () => {
+        const im = model?.internalModel;
+        const raw = im?.coreModel?._model;
+        const ids = typeof im?.getDrawableIDs === "function" ? Array.from(im.getDrawableIDs()).map(String) : [];
+        const partIds = raw?.parts?.ids === undefined ? [] : Array.from(raw.parts.ids).map(String);
+        const parent = raw?.drawables?.parentPartIndices;
+        const cdi3Names = MANIFEST.current?.partNames ?? {};
+        return ids.map((id, index) => {
+          const partIndex = parent === undefined ? -1 : parent[index];
+          const partId = partIndex >= 0 && partIndex < partIds.length ? partIds[partIndex] : null;
+          let minX = Infinity;
+          let minY = Infinity;
+          let maxX = -Infinity;
+          let maxY = -Infinity;
+          let vertexCount = 0;
+          try {
+            const verts = im?.getDrawableVertices?.(index);
+            if (verts !== undefined && verts !== null) {
+              vertexCount = Math.floor(verts.length / 2);
+              for (let k = 0; k < verts.length; k += 2) {
+                if (verts[k] < minX) minX = verts[k];
+                if (verts[k] > maxX) maxX = verts[k];
+                if (verts[k + 1] < minY) minY = verts[k + 1];
+                if (verts[k + 1] > maxY) maxY = verts[k + 1];
+              }
+            }
+          } catch {
+            /* 跳过 */
+          }
+          return {
+            id,
+            index,
+            partId,
+            partName: partId === null ? "(无部件)" : (cdi3Names[partId] ?? partId),
+            vertexCount,
+            box: maxX > minX ? { minX: Math.round(minX), maxX: Math.round(maxX), minY: Math.round(minY), maxY: Math.round(maxY) } : null,
+          };
+        });
+      },
+      /**
+       * Diagnostic: 单看一个 drawable 的三角面判定为什么命中/不命中。
+       *
+       * 头部判定好用、尾巴判定一个都不中（而它的几何明明又大又真）——这种"同一段代码
+       * 对不同 drawable 表现不同"的问题，只能把中间量摊开看：顶点数、索引数、索引范围、
+       * 以及用**它自己的重心**去测的结果。
+       */
+      drawableProbe: (id) => {
+        const im = model?.internalModel;
+        const index = typeof im?.getDrawableIndex === "function" ? im.getDrawableIndex(id) : -1;
+        if (index < 0) return { id, found: false };
+        const vertices = im?.getDrawableVertices?.(index);
+        const indices = (typeof im?.getDrawableVertexIndices === "function"
+          ? im.getDrawableVertexIndices(index)
+          : im?.coreModel?.getDrawableVertexIndices?.(index));
+        const verts = vertices === undefined || vertices === null ? [] : Array.from(vertices);
+        const idx = indices === undefined || indices === null ? [] : Array.from(indices);
+        let minIndex = Infinity;
+        let maxIndex = -Infinity;
+        for (const value of idx) {
+          if (value < minIndex) minIndex = value;
+          if (value > maxIndex) maxIndex = value;
+        }
+        const vertexCount = Math.floor(verts.length / 2);
+        // 用顶点的平均位置当查询点：它一定在几何内部（凸的情况下）。
+        let sumX = 0;
+        let sumY = 0;
+        for (let i = 0; i < verts.length; i += 2) {
+          sumX += verts[i];
+          sumY += verts[i + 1];
+        }
+        const cx = vertexCount === 0 ? 0 : sumX / vertexCount;
+        const cy = vertexCount === 0 ? 0 : sumY / vertexCount;
+        let triangles = 0;
+        let degenerate = 0;
+        let contains = 0;
+        for (let i = 0; i + 2 < idx.length; i += 3) {
+          triangles += 1;
+          const a = idx[i];
+          const b = idx[i + 1];
+          const c = idx[i + 2];
+          if (a * 2 + 1 >= verts.length || b * 2 + 1 >= verts.length || c * 2 + 1 >= verts.length) continue;
+          const area = (verts[b * 2] - verts[a * 2]) * (verts[c * 2 + 1] - verts[a * 2 + 1])
+            - (verts[c * 2] - verts[a * 2]) * (verts[b * 2 + 1] - verts[a * 2 + 1]);
+          if (Math.abs(area) < 1e-6) {
+            degenerate += 1;
+            continue;
+          }
+          if (pointInTriangle(cx, cy, verts, a, b, c)) contains += 1;
+        }
+        return {
+          id,
+          found: true,
+          index,
+          vertexCount,
+          indexCount: idx.length,
+          minIndex: Number.isFinite(minIndex) ? minIndex : null,
+          maxIndex: Number.isFinite(maxIndex) ? maxIndex : null,
+          triangles,
+          degenerate,
+          centroidHits: contains,
+          centroid: { x: Math.round(cx), y: Math.round(cy) },
+        };
+      },
       /**
        * Play a motion with its declared policy applied; used by the panel, the
        * tap reaction and the session-phase driver.
@@ -2694,8 +2841,11 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    * fidgetNone 与各选项的 fidgetWeight）；这里只放用户改过的部分，
    * 键都按名字存，换宠物时对不上的覆盖会被忽略（和装扮存档同一套思路）。
    *
-   *   phases: { <相位>: { motion: 组名|null, expression: 表情名|null } }
-   *   fidget: { <槽位>: { none: 权重, options: { <选项标签>: 权重 } } }
+   *   phases: { <相位>: { pools: { <槽位>: 条目表 } } }
+   *   fidget: { <槽位>: { entries: 条目表 } }
+   *   relations: { "<槽位>:<标签>": { pairs, requires } }
+   *   interactions: { <patReactions|tailReactions|spinReactions>: [标签] }
+   *   lines: { <键>: [台词] , phase: { <相位>: 台词 } }
    */
   /** 当前宠物的清单，给设置界面用（DSH 设置页拿不到组件里的 pet）。 */
   const MANIFEST = { current: null };
@@ -2710,7 +2860,10 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    * 姿势本身的性质 —— 在摸鱼表里改它，右键面板点同一个姿势、相位池里抽到它，
    * 行为必须一致。所以它单独存一层，而不是挂在条目上。
    */
-  const PHASE_OVERRIDES = { phases: {}, fidget: {}, relations: {}, lines: {} };
+  // 五个键都要在这里给出来（哪怕只是空壳）：`applyOverride()` 是**原地往这个对象上写**的，
+  // 少一个键就等于那条路径第一次改设置时静默丢掉 —— 互动反应候选原来就是这么漏的
+  // （读的地方全写着 `?.`，所以"能读、写不进去"，只有正面写它的界面会踩到）。
+  const PHASE_OVERRIDES = { phases: {}, fidget: {}, relations: {}, interactions: {}, lines: {} };
 
   /** 槽位 id -> 中文标签（关系行显示「贴纸」而不是 `sticker`）。 */
   const slotLabelOf = (slotId) =>
@@ -3428,28 +3581,60 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
 
 
   /**
-   * What a head pat may answer with (requirement #5).
+   * 三个互动**内置的**反应候选（用户覆盖 <- 宠物声明 <- 这里）。
+   *
+   * 这三组原来只在 pet.json 里声明，代码侧没有任何默认值（`HEAD_PAT_REACTIONS`
+   * 是上一版实现留下的死常量，谁都没读它）—— 于是**没声明这三组的宠物，互动看着
+   * 是好的、其实什么都不演**：摸头/摸尾巴只有台词，转圈连台词都不弹。而这恰恰是
+   * 「做一只自己的宠物」最常见的状态（最小 pet.json 里根本没有这几个键）。
    *
-   * One of these at random, and no blush — the blush is what a tap used to add
-   * unconditionally, which made every pat look identical.
+   * 标签按同一个顺序解读：先当**动作组的中文名**找（catalog.json 里作者起的名），
+   * 找不到就当**表达式**闪一下。所以这里写的是用户看得懂的名字，不是 group / file id。
    */
-  const HEAD_PAT_REACTIONS = [
-    { motion: "Hammer" },
-    { expression: "问号" },
-    { expression: "星星眼" },
-  ];
+  const DEFAULT_REACTIONS = {
+    /** 摸头：随机一个，并且**故意不脸红** —— 脸红是以前每次摸头都加的东西，让每一下都一样。 */
+    patReactions: ["重锤出击", "问号", "星星眼"],
+    /** 摸尾巴：吐魂是表情，问号是符号表情。 */
+    tailReactions: ["吐魂", "问号"],
+    /** 转圈转晕：演「晕晕」。 */
+    spinReactions: ["晕晕"],
+  };
+
+  /** 一组反应候选的来历（诊断用，见 reactionSource）。 */
+  const REACTION_KEYS = Object.keys(DEFAULT_REACTIONS);
+
+  /** 洗一遍候选：只留非空字符串（那份清单可能来自 localStorage，不可信）。 */
+  const cleanReactionList = (list) =>
+    (Array.isArray(list) ? list : []).filter((name) => typeof name === "string" && name !== "");
 
   /**
-   * 互动的反应候选：宠物默认（pet.json 的 `patReactions` / `tailReactions` /
-   * `spinReactions`）+ 用户覆盖（`PHASE_OVERRIDES.interactions`）。
+   * 互动的反应候选：**用户覆盖 <- 宠物声明 <- 内置默认**。
    *
    * 条目是**标签**（「重锤出击」「星星眼」这种）：先当动作组找（宠物会给动作起中文名），
    * 找不到就当表达式名。这样设置界面里可以拿宠物自己的清单当候选，用户不用记 id。
+   *
+   * 这里的兜底顺序和台词（`linesNow`）、摸鱼池（`fidgetEntriesFor`）是同一套：
+   * 用户没改过就用宠物声明的，宠物没声明就用内置的 —— **任何一层为空都不能变成
+   * "这个互动没反应"**。
    */
   const interactionReactions = (key) => {
-    const mine = PHASE_OVERRIDES.interactions?.[key];
-    const list = Array.isArray(mine) && mine.length > 0 ? mine : (MANIFEST.current?.[key] ?? []);
-    return Array.isArray(list) ? list.filter((name) => typeof name === "string" && name !== "") : [];
+    const mine = cleanReactionList(PHASE_OVERRIDES.interactions?.[key]);
+    if (mine.length > 0) return mine;
+    const declared = cleanReactionList(MANIFEST.current?.[key]);
+    if (declared.length > 0) return declared;
+    return cleanReactionList(DEFAULT_REACTIONS[key]);
+  };
+
+  /**
+   * 这一组候选是从哪一层来的（"没反应"这类问题要一眼看出是哪一层空了）。
+   *
+   * 诊断读口，不参与行为：`user` / `pet` / `builtin` / `none`。
+   */
+  const reactionSource = (key) => {
+    if (cleanReactionList(PHASE_OVERRIDES.interactions?.[key]).length > 0) return "user";
+    if (cleanReactionList(MANIFEST.current?.[key]).length > 0) return "pet";
+    if (cleanReactionList(DEFAULT_REACTIONS[key]).length > 0) return "builtin";
+    return "none";
   };
 
   /** 跑一条反应（由点击/转圈触发）。 */
@@ -3841,6 +4026,17 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       api.effectiveLines = () => linesNow();
       /** 某个互动的**有效**反应候选（同样是与宠物默认合并后的结果）。 */
       api.effectiveReactions = (key) => interactionReactions(key);
+      /**
+       * 诊断：三组候选各自的**来历**（user / pet / builtin / none）与内置默认值。
+       *
+       * "点了她没反应"要先分清是哪一层空了：用户覆盖成了空数组、宠物没声明、
+       * 还是连内置默认都没有。只看 `effectiveReactions()` 是分不出来的。
+       */
+      api.reactionDiagnostics = () => ({
+        source: Object.fromEntries(REACTION_KEYS.map((key) => [key, reactionSource(key)])),
+        builtin: Object.fromEntries(REACTION_KEYS.map((key) => [key, DEFAULT_REACTIONS[key].slice()])),
+        effective: Object.fromEntries(REACTION_KEYS.map((key) => [key, interactionReactions(key)])),
+      });
       /** 台词的字段清单（测试用它确认"每一个字段都有输入框"）。 */
       api.lineFields = () => ({
         plain: LINE_FIELDS.map((field) => field.key),
@@ -6271,12 +6467,9 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    */
   function InteractControls() {
     useSettings();
-    const listFor = (key) => {
-      const mine = PHASE_OVERRIDES.interactions?.[key];
-      if (Array.isArray(mine) && mine.length > 0) return mine;
-      const base = MANIFEST.current?.[key];
-      return Array.isArray(base) ? base : [];
-    };
+    // 候选显示的是**有效那一组**（用户覆盖 <- 宠物声明 <- 内置默认），和运行时
+    // `interactionReactions()` 同一个函数：界面上没勾的选项就不该演，勾着的必须真演。
+    const listFor = (key) => interactionReactions(key);
     const toggle = (key, label) => {
       const next = listFor(key).slice();
       const at = next.indexOf(label);
@@ -6299,8 +6492,16 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       h("span", { "data-row-label": "" }, label),
       note === undefined ? null : h("span", { "data-note-inline": "" }, note),
     );
-    const reactionRow = (key, title, note) => h("div", { "data-reaction-set": key },
-      h("div", { "data-row-label": "" }, title, note === undefined ? null : h("span", { "data-note-inline": "" }, note)),
+    // 从哪里来的写在行尾：**这只宠物没声明这一组**时，用户看到的默认值其实是插件
+    // 内置的那几个 —— 不说清楚他会以为"这是宠物自己的设定，改宠物就能改默认"。
+    const sourceNote = (key) => {
+      const source = reactionSource(key);
+      if (source === "user") return "（已改过）";
+      return source === "pet" ? "（宠物默认）" : "（内置默认）";
+    };
+    const reactionRow = (key, title) => h("div", { "data-reaction-set": key, ...(reactionSource(key) === "builtin" ? { "data-reaction-builtin": "" } : {}) },
+      h("div", { "data-row-label": "" }, title,
+        h("span", { "data-note-inline": "" }, sourceNote(key), "（随机一个）")),
       h("div", { "data-chips": "" }, candidates.length === 0
         ? h("span", { "data-note-inline": "" }, "这只宠物没有可选的动作/表情")
         : candidates.map((label) => {
@@ -6319,9 +6520,9 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       switchRow("tailEnabled", "摸尾巴有反应"),
       switchRow("spinEnabled", "鼠标绕着转圈会晕"),
       h(TuningControls, { key: "spin", group: "interact" }),
-      reactionRow("patReactions", "摸头时演什么", "（随机一个）"),
-      reactionRow("tailReactions", "摸尾巴时演什么", "（随机一个）"),
-      reactionRow("spinReactions", "转晕时演什么", "（随机一个）"),
+      reactionRow("patReactions", "摸头时演什么"),
+      reactionRow("tailReactions", "摸尾巴时演什么"),
+      reactionRow("spinReactions", "转晕时演什么"),
     );
   }
 

package/lib/index.js

@@ -21,6 +21,7 @@
  */
 
 import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, extname, join, sep } from 'node:path'
@@ -356,6 +357,31 @@ function readReactionList(value) {
   return Array.isArray(value) ? value.filter((name) => typeof name === 'string' && name !== '') : []
 }
 
+/**
+ * 部件 id → 作者给的中文名（`Part46` → `脸蛋`）。
+ *
+ * 诊断用（`drawableTable()`）：把 drawable 归到有意义的部件名下，才能一眼看出
+ * "她身上真正在画尾巴的是哪个 drawable" —— 光看 `ArtMesh123` 是认不出来的。
+ */
+function readPartNames(dir, modelPath) {
+  try {
+    const base = modelPath.replace(/\.model3\.json$/i, '')
+    const file = findCdi3(dir, base)
+    if (file === undefined) return {}
+    const parts = readJson(file)?.Parts
+    if (!Array.isArray(parts)) return {}
+    const out = {}
+    for (const part of parts) {
+      if (part === null || typeof part !== 'object') continue
+      if (typeof part.Id !== 'string' || typeof part.Name !== 'string') continue
+      if (part.Name !== '') out[part.Id] = part.Name
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
 /** Scan one pet directory into a catalog entry, or undefined when unusable. */
 export function scanPet(dir, id) {
   const manifestFile = join(dir, 'pet.json')
@@ -512,6 +538,8 @@ export function scanPet(dir, id) {
     // 空数组 = 没 cdi3 或没挑到，浏览器半区退回旧行为。
     headParts: readPartsMatching(dir, modelPath, HEAD_PART_NAME_HINTS),
     tailParts: readPartsMatching(dir, modelPath, TAIL_PART_NAME_HINTS),
+    // 部件 id → 中文名（诊断用，见客户端 drawableTable()）。
+    partNames: readPartNames(dir, modelPath),
     // 台词：宠物自己的声音（问候 / 点击 / 摸头 / 摸尾巴 / 转晕 / 归位 / 每个相位）。
     // 用户能在设置里逐条改，改过的存浏览器；这里是**默认值**。
     lines: typeof block.lines === 'object' && block.lines !== null ? block.lines : {},
@@ -540,9 +568,89 @@ export function scanPet(dir, id) {
   }
 }
 
-/** Build the live catalog from disk (fresh per request, so installs are picked up). */
 /**
- * 把**随包分发**的宠物装进用户的宠物目录。
+ * 随包宠物 pet.json 的**历史内容指纹**（SHA-256），一份一行。
+ *
+ * 只为一件事存在：认出"用户宠物目录里那份是我们**某一次发出去的**原样副本"。
+ * 认出来才敢升级（`syncBundledPet`），认不出来就一个字都不碰。
+ *
+ * 为什么必须从 git 历史里现算、不能手抄：抄错一位的两种后果都是静默的 ——
+ * 要么永远不升级（老用户拿不到新的默认值），要么把用户自己改过的副本覆盖掉。
+ * 生成命令：`node tools/print-pet-hashes.mjs dsh-live2d-pet/pets/ds-whale-girl/pet.json --at <提交> --code`
+ * （每份内容取它**最后**出现的那个提交，否则第一次安装与仓库当时状态对不上）。
+ *
+ * 这是**冷启动**用的表：同步记录（`pets/.synced.json`）建立之后，判定就只看记录，
+ * 这个表只在"目标没有记录"时才参与 —— 也就是所有老装机，以及第一次装新版本的人。
+ * 因此每改一次随包宠物，都要把**改动之前那一版**的哈希补进来（改动之后那一版是目标，
+ * 不需要进表）。
+ */
+const BUNDLED_PET_HASHES = {
+  'ds-whale-girl': [
+    // ef7fb1a：模型第一次随包分发（1.0.x，17 个槽位、5 个相位）
+    '5421dee9d13ee60b91c341ab515bbef3fb8702a9791279c9a2f61124d4478b34',
+    // 3f18b195：面板跟随宿主主题 + 自拍可配置
+    '707049e3b8a05f3de5ddd49299bcb47fdd2ac1494209b7c710c1371be718bb27',
+    // 9b62d727：自拍独立成槽、氛围拆三个、摸鱼不再擦掉手选
+    '071a7bfe18b4882703a43f8a14dc7eded8d5aa08671dc3ecc4db220258e5be23',
+    // 6c6b61e1（2.0.0）：把作者调好的值烘成宠物默认
+    'e931e44a6589932688d7507b0d5e62ba4c0f9618492ec7fe644885117e61f12a',
+    // 4b594ed3（2.2.0）：多接三个会话状态
+    '88b86f32833882893e8ec10a9320bb4d9899a0211811d5a96544e4b97b804234',
+    // 25c4d285（2.3.0 前）：台词 / 反应候选 / 摸鱼槽位
+    '18840cd90fe70aa68632c45f77b4af1254595b5f963d261d2cbf34f6fbcaf579',
+    // 1.0.1（2.3.0 ~ 2.3.2 随包的那份）：内容与上面那条相同，只是换了插件版本号
+    '7c6cdb9c9f3d92636c388bffb3229c439cf01a65fe6a8a88499a8e4071f7884a',
+  ],
+}
+
+/** 同步记录：哪个宠物是我们装的、装的是哪一版、装下去那份长什么样。 */
+const SYNC_RECORD = '.synced.json'
+
+/** 文件和 buffer 的 SHA-256（判定"这是不是我们发出去的原样"）。 */
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/** 读同步记录；读不出来就当"没有"（老装机本来就没有）。 */
+function readSyncRecord() {
+  const parsed = readJson(join(petsRoot(), SYNC_RECORD))
+  return parsed !== null && typeof parsed === 'object' ? parsed : {}
+}
+
+function writeSyncRecord(record) {
+  mkdirSync(petsRoot(), { recursive: true })
+  writeFileSync(join(petsRoot(), SYNC_RECORD), JSON.stringify(record, null, 2) + '\n')
+}
+
+/** 点分数字比较：'1.1.0' > '1.0.1'。非数字段（rc / beta）只取数字部分。 */
+export function compareVersions(a, b) {
+  const parts = (raw) => String(raw ?? '').split('.').map((piece) => {
+    const n = Number.parseInt(piece, 10)
+    return Number.isFinite(n) ? n : 0
+  })
+  const left = parts(a)
+  const right = parts(b)
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const one = left[i] ?? 0
+    const two = right[i] ?? 0
+    if (one !== two) return one > two ? 1 : -1
+  }
+  return 0
+}
+
+/** 这份宠物目录里的 pet.json 是不是"某一次随包发出去的原样"。 */
+function isPristineBundledManifest(petId, manifestPath, fingerprints) {
+  let hash
+  try {
+    hash = sha256(readFileSync(manifestPath))
+  } catch {
+    return false
+  }
+  return (fingerprints[petId] ?? []).includes(hash)
+}
+
+/**
+ * 把随包宠物装进用户的宠物目录，并在**确实是我们装的那份**过期时更新它。
  *
  * 以前宠物是仓库里单独一份，装插件的人还得自己再拷一次 —— 从插件市场装完
  * 「看不见宠物」就是这么来的（插件包里有代码，没有模型）。
@@ -551,31 +659,99 @@ export function scanPet(dir, id) {
  * 已明确授权本项目转载与开源（见 pets/ds-whale-girl/LICENSE）；Core 是 Live2D Inc.
  * 的专有软件，只允许从官方渠道取，所以它走 CDN 兜底那条路。
  *
- * 只在目标**不存在**时复制：用户自己改过的宠物永远优先，绝不覆盖。
+ * **升级这一半是补上的**（原来只有"目标不存在才拷"）：插件目录会随
+ * `dsh plugin add` / npm 更新，用户的宠物目录不会 —— 于是宠物**自己的默认值
+ * 永远停在装它的那一天**。25c4d285 往 pet.json 里加的那批（台词 / 互动反应候选 /
+ * 摸鱼槽位 / 新增的三个相位）就这么一直没到过老用户的桌面，症状是"互动只有台词
+ * 不演反应、相位不弹台词、装扮少三个槽位"，而且**看起来完全像插件的 bug**。
+ *
+ * 三条判定，缺一条都会变成"静默覆盖用户数据"：
+ *   1. 目标不存在 → 装一份（并把版本与内容指纹记进 `pets/.synced.json`）；
+ *   2. 目标就是我们上次装下去的那一份（**内容指纹**对得上）→ 整份更新；
+ *   3. 用户动过（指纹对不上）→ **一个字都不碰**。
+ *
+ * 第 2 条在冷启动时（记录出现之前装的副本）靠 `BUNDLED_PET_HASHES` 认人：
+ * 内容与历史上任何一次随包分发**逐字节相同**才升级。改过名字/槽位/任何东西的副本
+ * 哈希必然不同，所以"用户自己改过的宠物永远优先，绝不覆盖"这条没有被削弱。
  */
-export function installBundledPets() {
+export function installBundledPets(options = {}) {
   const bundled = join(pluginRoot(), 'pets')
   if (!existsSync(bundled)) return
+  // 冷启动指纹表可以被注入：测试要造一份"我们以前发过的旧副本"，但测试**不能**
+  // 依赖生产表里的具体哈希（那样改一次表就得改测试，而且改错了也没人发现）。
+  const fingerprints = options.fingerprints ?? BUNDLED_PET_HASHES
   let names = []
   try {
     names = readdirSync(bundled).filter((entry) => !entry.startsWith('.'))
   } catch {
     return
   }
+  const record = readSyncRecord()
+  const notes = []
+  let dirty = false
   for (const name of names) {
     const source = join(bundled, name)
     const target = join(petsRoot(), name)
     try {
       if (!statSync(source).isDirectory()) continue
-      if (existsSync(target)) continue
-      mkdirSync(dirname(target), { recursive: true })
+      const manifestPath = join(source, 'pet.json')
+      if (!existsSync(manifestPath)) continue
+      const version = String(readJson(manifestPath)?.version ?? '')
+      const targetManifest = join(target, 'pet.json')
+
+      if (!existsSync(target)) {
+        mkdirSync(dirname(target), { recursive: true })
+        cpSync(source, target, { recursive: true })
+        record[name] = { version, hash: sha256(readFileSync(targetManifest)) }
+        dirty = true
+        continue
+      }
+
+      const synced = record[name]
+      const same = existsSync(targetManifest) ? sha256(readFileSync(targetManifest)) : undefined
+      const ours = (synced !== undefined && synced.hash === same)
+        || isPristineBundledManifest(name, targetManifest, fingerprints)
+      if (!ours) {
+        // 用户自己改过：不动它。**要说出来** —— 沉默地不升级，用户看到的是
+        // "插件更新了但没有任何变化"，比报错更难查。
+        if (compareVersions(version, readJson(targetManifest)?.version) > 0) {
+          notes.push(name + '：宠物目录里这份被改过，跳过更新（随包版本 ' + version
+            + '，本地 ' + String(readJson(targetManifest)?.version ?? '?') + '）')
+        }
+        continue
+      }
+      // **升级与否只看内容**，不看版本号：版本号是宠物自己声明的，随包那份在同一个
+      // 版本号下改过（补默认值就是这么发生的），只比版本号会让这次修订永远发不出去。
+      // 反过来，"版本相同 + 内容相同"在这里就短路了，不会做无谓的整份重写。
+      const bundledHash = sha256(readFileSync(manifestPath))
+      if (same === bundledHash) continue
+
+      // cpSync 是逐文件覆盖 —— 用户额外放进去的文件（自己的贴图、备注）不在随包
+      // 那份里，所以留得住。
+      // 「原先」那个版本号要**在覆盖之前**读：覆盖之后再读只会读到新的，日志就成了
+      // "更新到 1.1.0（原先 1.1.0）"（第一次跑就写成了这样）。
+      const was = String(readJson(targetManifest)?.version ?? '?')
       cpSync(source, target, { recursive: true })
+      record[name] = { version, hash: bundledHash }
+      dirty = true
+      notes.push(name + '：宠物默认值更新到 ' + version + '（原先 ' + was + '）')
     } catch {
       /* 只读文件系统之类：让用户自己拷，别让整个目录扫描失败 */
     }
   }
+  if (dirty) {
+    try {
+      writeSyncRecord(record)
+    } catch {
+      /* 记录写不进去只影响"下次少一次判定"，不影响这次已经装好的宠物 */
+    }
+  }
+  if (notes.length > 0 && options.quiet !== true) {
+    for (const note of notes) console.log('[live2d-pet] ' + note)
+  }
 }
 
+/** Build the live catalog from disk (fresh per request, so installs are picked up). */
 export function buildCatalog() {
   installBundledPets()
   const root = petsRoot()
@@ -719,6 +895,7 @@ function catalogRoute() {
           motionGuards: pet.motionGuards,
           headParts: pet.headParts,
           tailParts: pet.tailParts,
+          partNames: pet.partNames,
           lines: pet.lines,
           patReactions: pet.patReactions,
           tailReactions: pet.tailReactions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pet-live2d",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Live2D 桌宠插件：为 DSH Web GUI 挂一只可拖动、会跟随鼠标、能换动作与表情的 Live2D 宠物。",
   "type": "module",
   "main": "lib/index.js",

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

@@ -3,7 +3,7 @@
   "id": "ds-whale-girl",
   "displayName": "DS鲸鱼娘",
   "description": "氵六青的 DS 鲸鱼娘 Live2D 桌宠：8 组动作 + 44 个表情/道具，点她会有反应。",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "author": "模型：上善无形 / ZipZipPipe / 氵六青 · 插件：A8Chann",
   "license": "CC BY-NC-SA 4.0 (attribution, NON-COMMERCIAL, share-alike). Character: original OC by 上善无形 (https://www.pixiv.net/users/62155430); DeepSeek maid redesign by ZipZipPipe (https://www.pixiv.net/users/18604994); this Live2D model by 氵六青 (https://space.bilibili.com/11272072), who authorised redistribution here — which does NOT lift the base NC/SA terms. Commercial use requires permission from each rights holder. See NOTICE.md.",
   "homepage": "https://space.bilibili.com/11272072",