dsh-pet-live2d 2.3.2 → 2.3.4

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # 更新日志
 
+## 2.3.4
+
+### 修：摸尾巴"很难点到" —— 尾巴的判定区域和可点区域都收紧了
+
+用户的原话："尾巴一直在摆动，摸尾巴的事件现在很难点到。"查下来是**两件事叠在一起**，
+而且第二件才是主因。
+
+**① 尾巴判定把 11 个"可换配件"也算成了尾巴。**
+
+`hitsTail` 原来按名字挑部件（名字里带 `尾|鳍|翅|翼`），这只模型里有 **15 个部件 / 16 块**
+drawable 命中 —— 但其中 11 块是**可选配件**（狐狸尾 / 猫尾 / 狼尾 / 天使翅膀 / 恶魔翅膀…），
+几何**一直留在原地**、横跨从头顶到腰腹的整个角色。实测（24×24 网格）：
+
+| | 修之前 | 修之后 |
+|---|---|---|
+| "算尾巴"的格子占角色 | 22.0% | 5.2% |
+| 其中同时算头（会被摸头优先吃掉） | 86.6% | ~55% |
+| **只算尾巴、真正可点的格子** | ~17 | ~59 |
+
+于是你点在**看得见的尾鳍**上，拿到的是摸头反应（重锤出击）。
+
+现在按**贴图**收窄：`texture_00.png` 上鲸鱼尾鳍只占 `x 3..444, y 953..1397` 那一块，
+落在那里的正好是 `ArtMesh38/56/58/59/60` 五块（全属于部件 `尾巴(蒙皮)`）。UV 读不到时
+**不做收窄**，退回旧行为 —— "更精确"不能变成"整个失效"。
+
+**② 可点区域（轮廓快照）跟不上摆动。**
+
+摸头/摸尾巴的判定每次点击都现读几何，所以"点的是不是尾巴"是准的；但**决定事件归谁**
+的那层 `clip-path` 轮廓是**开机从画布抓一次**的静态快照。尾鳍一直在摆，摆出快照的那
+一瞬间，点击**直接穿透到页面**（实测 `elementFromPoint` 返回 `HTML`，而判定说她是）。
+
+现在尾巴有一块**跟着摆动实时更新**的可点矩形（每 ~120ms，模型空间 → 舞台按 y 轴方向
+换算），并进 `[data-hit]` 的 `clip-path`；JS 侧的 `hitsMask` 用**同一套**（当前尾巴盒子
+或静态快照，取或）—— 两边必须一致，否则就是"事件进得来、判定说不在她身上"这种点了没反应。
+顺序也踩过坑：`hitsMask` 一度改成纯几何，结果"只有几何、没有像素"的点被算成在她身上，
+而 DOM 并不覆盖它 —— `cdp-passthrough` 立刻红。
+
+**顺带**：`onModel`（"算不算落在她身上"）以前只认静态快照，现在也认尾巴当前盒子。
+
+### 诊断：一批新读口
+
+- `lastPress()` —— **按住那一刻**路由用的三个答案（`onModel` / `onHead` / `onTail`）+ 时间戳。
+  "点了没反应"要先分清是事件没进来、还是判定说不是她；从"她说了什么"倒推是分不出来的。
+- `tailDebug()` —— 尾巴判定的收窄结果（收窄前后各是哪些、贴在哪块贴图上）与尾巴实时盒子。
+- `hitsMaskStatic()` —— **只按静态快照**判定。要证明"这一点在快照外、却在宽限之内"，
+  就得能把两层分开读。
+- `uvRaw()` / `uvTables()` —— 贴图坐标表本身（哪块 drawable 画在贴图的哪一块）。
+- `modelToStage()` —— 模型空间 → 舞台坐标，尾巴那块实时矩形靠它换算。
+
+## 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
 
 ### 修：摸尾巴又摸不到了（这次是真的）

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)
 
@@ -124,13 +129,23 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 
 - 摸头/摸尾巴按**三角面**判定：圆顶带耳朵尖的头部轮廓、尾巴的边缘都对得上，不是方框。
   顶点是**当前帧变形后**的，所以头歪着、身体摆着也准。
-- **摸头优先于摸尾巴**：这两个区域可能有重叠（尾巴/翅膀挂件在身后，几何上会伸到头部
-  附近），重叠处算摸头。
+- **尾巴只认"鲸鱼尾鳍"那一块**：这只模型有 16 块 drawable 的名字里带"尾/翅/翼"，但其中
+  11 块是**可选配件**（狐狸尾 / 猫尾 / 狼尾 / 天使翅膀…）的几何、一直留在原地、横跨全身。
+  全算成尾巴的话"点到哪儿都是尾巴"，而摸头又优先，可见的尾鳍反而摸不到。所以尾巴是按
+  **贴图**认的：`texture_00.png` 上鲸鱼尾鳍那一块对应的 5 块 drawable（都属部件 `尾巴(蒙皮)`）。
+- **可点区域跟着尾巴动**：决定事件归谁的那层轮廓是开机抓一次的，尾鳍摆动时会摆出去 ——
+  现在尾巴有一块实时跟随的可点矩形并进轮廓里，所以**摆到哪儿都点得到**。
+- **摸头优先于摸尾巴**：尾巴判定收紧之后两者基本不再重叠，重叠处仍然算摸头。
 - **尾巴/翅膀是可选配件**：没戴的时候它们的几何是退化的，"摸尾巴"就是没反应 ——
-  这是对的，不是坏了。戴上翅膀/尾巴（装扮槽）之后才摸得到。
+  这是对的，不是坏了。戴上尾巴（装扮槽）之后才摸得到。
 - 转圈看的是**累计转角**（不是位置绕了几圈），所以贴着角色转小圈、远远转大圈都算。
 - 三个互动各自可开关，反应也能改（见下）。共用的三句台词在「气泡」设置里。
 
+> 上表那三组是**默认反应**，来源分两层：宠物 `pet.json` 里声明了就用它的；**没声明就用
+> 插件内置的这几个**（重锤出击 / 问号 / 星星眼、吐魂 / 问号、晕晕）—— 自己做的宠物不写
+> 这三个键也有反应。设置页「互动」卡的行尾会标明当前用的是哪一层（宠物默认 / 内置默认 /
+> 已改过），候选勾选本来就是最高优先级。
+
 ### 气泡：说什么、在哪、要不要
 
 她说话时会弹一个小气泡（问候、点击、摸头、摸尾巴、转晕、归位，以及**每个会话相位一句**：
@@ -237,6 +252,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 },
@@ -309,6 +329,11 @@ cd ../../tools/browser-test && npm install && npm run suite
 `fidgetTally()`（摸鱼抽签统计）、`effectiveRelations()` / `settingsOverrides()`（有效关系与
 存档覆盖）、`ambientDebug()` / `keptPoseDebug()`（氛围回放与姿势保持的内部状态）。
 
+## 交流群
+
+**大肥鱼 pet-live2d 交流群** —— QQ 群号 **974641848**：装不上、模型不对劲、想投稿自己的宠物，
+都欢迎进群说。群二维码在[仓库 README 的「交流群」一节](../README.md#交流群)。
+
 ## 许可
 
 - 插件代码：MIT

package/docs/README.md

@@ -10,5 +10,7 @@
 
 - `preview.png` — 桌宠与面板的整体截图（300px 宽，建议跑 `tools/browser-test/cdp-final.mjs` 生成）
 - `downscale-fix.png` — 缩小时线条清晰度的前后对比
+- `qq-group.png` — 交流群二维码（群号 974641848），被仓库根 `README.md` 的「交流群」一节引用。
+  它不是美术资产，不受 CC BY-NC-SA 约束，但仍然随包分发（`files` 里有 `docs`）。
 
 当前这些图片保存在仓库之外的 `local-assets/screenshots/`，已在 `.gitignore` 中排除。

package/lib/client.js

@@ -287,6 +287,8 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     /** 由 parts 解出来的 drawable 下标（换模型要重算，缓存起来）。 */
     let headIndices = null;
     let tailIndices = null;
+    /** 尾巴类里**贴图落在尾鳍区域**的那几块（收窄结果，换模型要重算）。 */
+    let tailFinIndices = null;
 
     /**
      * 部件 id → drawable 下标（带所属部件下标）：cdi3 的部件名 → 引擎原始表。
@@ -434,6 +436,170 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       return read ? false : null;
     };
 
+    /**
+     * 一块 drawable 的**纹理坐标**包围盒（归一化 0..1），读不到返回 null。
+     *
+     * 为什么需要它：这只宠物有十几个"尾巴/翅膀"配件，几何同时留在原地 —— 光看几何
+     * 分不出谁是谁。而**贴图是作者自己画的**：鲸鱼尾鳍那块贴图区域只属于尾巴。
+     * 有了 UV 就能回答"这块 drawable 画的是贴图上哪一块"，那是权威依据。
+     *
+     * 字段名各版本不一（`vertexUvs` / `uvs`），所以按候选顺序试。
+     */
+    const readUvs = (index) => {
+      const raw = model?.internalModel?.coreModel?._model;
+      const drawables = raw?.drawables;
+      if (drawables === undefined || drawables === null) return null;
+      let table;
+      for (const key of ["vertexUvs", "uvs", "drawableVertexUvs"]) {
+        const candidate = drawables[key];
+        if (candidate !== undefined && candidate !== null) { table = candidate; break }
+      }
+      if (table === undefined) return null;
+      const entry = table[index];
+      if (entry === undefined || entry === null) return null;
+      const values = Array.from(entry);
+      if (values.length < 2) return null;
+      let minU = Infinity;
+      let minV = Infinity;
+      let maxU = -Infinity;
+      let maxV = -Infinity;
+      for (let i = 0; i + 1 < values.length; i += 2) {
+        const u = values[i];
+        const v = values[i + 1];
+        if (u < minU) minU = u;
+        if (u > maxU) maxU = u;
+        if (v < minV) minV = v;
+        if (v > maxV) maxV = v;
+      }
+      return { minU, minV, maxU, maxV };
+    };
+
+    /**
+     * 尾巴判定**此刻**该用哪几块 drawable（带缓存）。
+     *
+     * 名字里带尾/翅的部件有 15 个 / 16 块，其中 11 块是可换配件的几何、**一直留在原地**、
+     * 横跨从头顶到腰腹的整个角色。全算上的话"算尾巴"的格子占角色 22%，其中 86.6% 同时
+     * 算头 —— 而路由是摸头优先，于是**可见的尾鳍永远轮不到**（用户报的"摸尾巴很难点到"）。
+     *
+     * 收窄依据是**贴图**（作者自己画的）：只留 UV 落在尾鳍区域的那几块（`TAIL_FIN_UV`）。
+     * 保守之处：UV 读不到、或者收完一块不剩，就退回原来那一整份 —— 宁愿判定偏松，
+     * 也不能让"摸尾巴"整个消失。
+     */
+    const tailIndicesNow = () => {
+      if (tailIndices === null) tailIndices = drawableIndicesForParts(tailParts);
+      if (tailFinIndices === null) {
+        const narrowed = (tailIndices ?? []).filter((entry) => uvInsideTailFin(readUvs(entry.index)) === true);
+        tailFinIndices = narrowed.length > 0 ? narrowed : (tailIndices ?? []);
+      }
+      return tailFinIndices;
+    };
+
+    /**
+     * 尾巴类 drawable 此刻的**并集包围盒**（模型空间），读不到返回 null。
+     *
+     * 两处用：① `hitsMask` 把它并进"算不算落在她身上"（尾鳍摆出静态轮廓网格之外时，
+     * 那一瞬间的点击不该落空）；② `[data-hit]` 的 `clip-path` 里拼进去的那块矩形
+     * （跟着摆动重建，见 hitPath）。
+     */
+    const measureTailBox = () => {
+      const list = tailIndicesNow();
+      const im = model?.internalModel;
+      if (list.length === 0 || im === null || im === undefined) return null;
+      const box = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
+      for (const entry of list) {
+        let index = entry.index;
+        if (typeof entry.id === "string" && typeof im.getDrawableIndex === "function") {
+          const fresh = im.getDrawableIndex(entry.id);
+          if (fresh >= 0) index = fresh;
+        }
+        let verts;
+        try {
+          verts = im.getDrawableVertices(index);
+        } catch {
+          continue;
+        }
+        if (verts === undefined || verts === null || verts.length < 2) continue;
+        for (let i = 0; i + 1 < verts.length; i += 2) {
+          const vx = verts[i];
+          const vy = verts[i + 1];
+          if (vx < box.minX) box.minX = vx;
+          if (vx > box.maxX) box.maxX = vx;
+          if (vy < box.minY) box.minY = vy;
+          if (vy > box.maxY) box.maxY = vy;
+        }
+      }
+      return box.maxX > box.minX && box.maxY > box.minY ? box : null;
+    };
+
+    /**
+     * 模型空间 → **舞台局部**坐标（CSS px），读不到返回 null。
+     *
+     * 为什么不用引擎的 `toStagePosition()`：这个包装层上没有它（实测直接抛异常，
+     * 外面只看到 null）。改用**两个盒子对齐**：`model.getBounds()` 给的是模型在舞台上的
+     * 轴对齐盒，而模型空间里"整只宠物的盒"由全部 drawable 的顶点算出来。两者一比就是
+     * 缩放 + 平移（模型的旋转是 0，锚点已经烘进 getBounds），所以这条映射在缩放、
+     * 拖动、窗口 resize 之后都成立，也不依赖任何私有字段。
+     */
+    const modelToStage = (x, y) => {
+      const im = model?.internalModel;
+      if (model === null || im === null || im === undefined) return null;
+      if (typeof im.getDrawableIDs !== "function" || typeof im.getDrawableVertices !== "function") return null;
+      let bounds;
+      try {
+        bounds = model.getBounds();
+      } catch {
+        return null;
+      }
+      if (bounds === undefined || bounds === null || !(bounds.width > 0) || !(bounds.height > 0)) return null;
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      try {
+        for (const id of im.getDrawableIDs()) {
+          const index = im.getDrawableIndex(String(id));
+          if (index < 0) continue;
+          const verts = im.getDrawableVertices(index);
+          if (verts === undefined || verts === null) continue;
+          for (let i = 0; i + 1 < verts.length; i += 2) {
+            if (verts[i] < minX) minX = verts[i];
+            if (verts[i] > maxX) maxX = verts[i];
+            if (verts[i + 1] < minY) minY = verts[i + 1];
+            if (verts[i + 1] > maxY) maxY = verts[i + 1];
+          }
+        }
+      } catch {
+        return null;
+      }
+      if (!(maxX > minX) || !(maxY > minY)) return null;
+      return {
+        x: bounds.x + (x - minX) / (maxX - minX) * bounds.width,
+        y: bounds.y + (y - minY) / (maxY - minY) * bounds.height,
+      };
+    };
+
+    /** 静态快照网格的判定（`hitsMask` 与诊断读口共用一份实现，避免两处走岔）。 */
+    const hitsMaskGrid = (x, y, width, height) => {
+      if (hitMask === null) return true;
+      if (width <= 0 || height <= 0) return true;
+      // The grid covers the model's own bounding box, so normalise against
+      // that box rather than the whole stage.
+      const box = hitBox ?? { x: 0, y: 0, width, height };
+      const gx = Math.floor(((x - box.x) / box.width) * hitMask.width);
+      const gy = Math.floor(((y - box.y) / box.height) * hitMask.height);
+      // One cell of tolerance: the model breathes and sways, so requiring an
+      // exact opaque cell would make edge clicks feel unreliable.
+      for (let dy = -1; dy <= 1; dy += 1) {
+        for (let dx = -1; dx <= 1; dx += 1) {
+          const cx = gx + dx;
+          const cy = gy + dy;
+          if (cx < 0 || cy < 0 || cx >= hitMask.width || cy >= hitMask.height) continue;
+          if (hitMask.data[cy * hitMask.width + cx] === 1) return true;
+        }
+      }
+      return false;
+    };
+
     /** 点 (x,y) 在 verts 的第 i0/i1/i2 号顶点组成的三角形里吗（同向叉积法）。 */
     const pointInTriangle = (x, y, verts, i0, i1, i2) => {
       const ax = verts[i0 * 2];
@@ -582,6 +748,18 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     const expressionFade = new Map();
     /** 上一帧的时间戳（算 dt 用）；0 表示还没有基准。 */
     let expressionFadeAt = 0;
+    /**
+     * 尾巴类 drawable 的**实时并集包围盒**（模型空间）与它的采样时刻。
+     *
+     * 尾鳍一直在摆，而可点击的轮廓遮罩是开机抓一次的静态网格 —— 摆到网格之外的那一瞬，
+     * "点在尾巴上"会被判成"没落在她身上"。所以每帧（节流 100ms）采一次这个盒子，
+     * `hitsMask` 把它一起算进去：**尾巴摆到哪儿都算她**。
+     *
+     * 采样放在 saveParameters 缝里（`update()` 之前）—— 那是这一帧真正要画的姿势，
+     * 帧外读到的是引擎基线，会慢半拍。
+     */
+    let tailBoxLive = null;
+    let tailBoxSampledAt = 0;
     /** The core model whose saveParameters hook is installed. */
     let hookedCore = null;
     /**
@@ -1026,6 +1204,16 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
           const probeAt = probeId === null || values === null ? -1 : parameterIndex(core, probeId);
           const pre = probeAt >= 0 ? values[probeAt] : null;
           applyExpressionLayers(core);
+          // 尾巴的实时盒子（节流）：可点区域要跟着摆动的尾鳍走，见 tailBoxLive 的注释。
+          const nowMs = typeof performance !== "undefined" && typeof performance.now === "function"
+            ? performance.now()
+            : Date.now();
+          if (nowMs - tailBoxSampledAt >= TAIL_BOX_SAMPLE_MS) {
+            tailBoxSampledAt = nowMs;
+            // 私有函数，不是公开读口 `tailBoxNow()` —— 后者挂在 api 对象上，
+            // 控制器内部看不到它（这个错误每帧抛一次，外面只表现为"盒子一直是 null"）。
+            tailBoxLive = measureTailBox();
+          }
           // The layers are now in place and update() is next, so this is the
           // pose the frame is about to draw.
           if (values !== null) {
@@ -1525,6 +1713,11 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         headBox = null;
         hitMask = null;
         hitBox = null;
+        tailBoxLive = null;
+        tailBoxSampledAt = 0;
+        tailIndices = null;
+        tailFinIndices = null;
+        headIndices = null;
       },
       playIdle,
       playOnce,
@@ -1849,23 +2042,35 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       hitsMask(x, y, width, height) {
         if (hitMask === null) return true;
         if (width <= 0 || height <= 0) return true;
-        // The grid covers the model's own bounding box, so normalise against
-        // that box rather than the whole stage.
-        const box = hitBox ?? { x: 0, y: 0, width, height };
-        const gx = Math.floor(((x - box.x) / box.width) * hitMask.width);
-        const gy = Math.floor(((y - box.y) / box.height) * hitMask.height);
-        // One cell of tolerance: the model breathes and sways, so requiring an
-        // exact opaque cell would make edge clicks feel unreliable.
-        for (let dy = -1; dy <= 1; dy += 1) {
-          for (let dx = -1; dx <= 1; dx += 1) {
-            const cx = gx + dx;
-            const cy = gy + dy;
-            if (cx < 0 || cy < 0 || cx >= hitMask.width || cy >= hitMask.height) continue;
-            if (hitMask.data[cy * hitMask.width + cx] === 1) return true;
+        // "落点算不算落在她身上"必须与 **DOM 那一层完全一致**，否则两种坏法都会出现：
+        // 事件能进来而判定说不在她身上（点了没反应），或者判定说有而事件进不来（穿透错）。
+        // DOM 的 `clip-path` = 静态快照 + **尾巴当前那块矩形**，所以这里也就这两样：
+        //   ① 尾巴当前盒子（`measureTailBox`，当前姿势）—— 尾鳍摆出快照时靠它接住；
+        //   ② 开机抓的静态轮廓快照（下面那张网格 + 一格容差）。
+        //
+        // **不能**把头/尾的"几何"算进来：几何比像素宽，"只有几何、没有像素"的点会被判定
+        // 说成在她身上，而 DOM 那层并不覆盖它 —— cdp-passthrough 立刻红（character click
+        // 落到 page，实测）。头/尾几何是给**路由**用的（决定演什么），不是给"在不在她身上"。
+        if (model !== null && vendor !== null) {
+          try {
+            const point = model.toModelPosition(new vendor.Point(x, y));
+            const tailNow = measureTailBox();
+            if (tailNow !== null
+              && point.x >= tailNow.minX && point.x <= tailNow.maxX
+              && point.y >= tailNow.minY && point.y <= tailNow.maxY) return true;
+          } catch {
+            /* 换算失败就只按网格 */
           }
         }
-        return false;
+        return hitsMaskGrid(x, y, width, height);
       },
+      /**
+       * Diagnostic: 只按**开机抓的静态快照**那张网格判定（不含几何、不含尾巴实时盒子）。
+       *
+       * "尾鳍摆出快照"这件事没法凭空断言 —— 要证明"这一点在快照外、却在宽限之内"，
+       * 就得能把两层分开读。它只用于测试与排查，不参与行为。
+       */
+      hitsMaskStatic: (x, y, width, height) => hitsMaskGrid(x, y, width, height),
       /** Head-part ids, pushed in by the component once the catalog is ready. */
       setHeadParts(ids) {
         headParts = Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
@@ -1876,7 +2081,24 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       setTailParts(ids) {
         tailParts = Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
         tailIndices = null;
+        tailFinIndices = null;
       },
+      /**
+       * 尾巴类 drawable 此刻的**并集包围盒**（模型空间），读不到返回 null。
+       *
+       * 用途：`hitsMask` 把它并进"算不算落在她身上"。轮廓遮罩是开机抓一次的静态网格，
+       * 而尾鳍一直在摆 —— 摆动幅度大的时候，尾鳍会摆到网格之外，那一瞬间"点在尾巴上"
+       * 会被判成"没落在她身上"，事件落空。并把集盒之后，尾巴摆到哪儿都算她。
+       */
+      tailBoxNow: () => measureTailBox(),
+      /**
+       * 模型空间 → **舞台局部**坐标（CSS px），读不到返回 null。
+       *
+       * 就是 `hitsHead / hitsTail / hitsMask` 里那条映射的逆向（它们用
+       * `model.toModelPosition()`）：用来把"尾巴此刻的包围盒"画到 DOM 上，
+       * 做成那一层跟着摆动走的可点区域。
+       */
+      modelToStage: (x, y) => modelToStage(x, y),
       idleName: () => idleName,
       groups: () => groups,
       /** Declared playback policy for one motion group (diagnostics). */
@@ -1913,22 +2135,119 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
           return true;
         }
       },
+      /**
+       * 诊断：把**尾巴类** drawable 的**当前三角面**吐出来（模型空间）。
+       *
+       * 用来看"收窄前那一整份"里每块的几何落在哪儿（收窄结果见 `tailDebug()`）——
+       * 正是靠它量出"16 块里 11 块是配件、横跨整个角色"，才决定按贴图收窄。
+       *
+       * 单位是模型空间（`toModelPosition` 的坐标系）；配合 `fitBox()` 能换算回屏幕。
+       */
+      tailDrawables: () => {
+        const list = drawableIndicesForParts(tailParts);
+        if (list === null) return [];
+        const out = [];
+        for (const entry of list) {
+          let index = entry.index;
+          if (typeof entry.id === "string" && typeof model?.internalModel?.getDrawableIndex === "function") {
+            const fresh = model.internalModel.getDrawableIndex(entry.id);
+            if (fresh >= 0) index = fresh;
+          }
+          const row = { id: entry.id, index };
+          try {
+            const verts = model.internalModel.getDrawableVertices(index);
+            let minX = Infinity;
+            let minY = Infinity;
+            let maxX = -Infinity;
+            let maxY = -Infinity;
+            const triangles = [];
+            for (let i = 0; i + 1 < verts.length; i += 2) {
+              const vx = verts[i];
+              const vy = verts[i + 1];
+              if (vx < minX) minX = vx;
+              if (vx > maxX) maxX = vx;
+              if (vy < minY) minY = vy;
+              if (vy > maxY) maxY = vy;
+            }
+            const idx = model.internalModel.coreModel.getDrawableVertexIndices(index);
+            for (let i = 0; i + 2 < idx.length && triangles.length < 400; i += 3) {
+              triangles.push([
+                verts[idx[i] * 2], verts[idx[i] * 2 + 1],
+                verts[idx[i + 1] * 2], verts[idx[i + 1] * 2 + 1],
+                verts[idx[i + 2] * 2], verts[idx[i + 2] * 2 + 1],
+              ]);
+            }
+            const uvs = readUvs(index);
+            Object.assign(row, {
+              vertices: verts.length / 2,
+              triangles: triangles.length,
+              box: { minX, minY, maxX, maxY },
+              tris: triangles,
+              // 纹理坐标（归一化）：用来回答"这块在贴图的哪一块上" —— 贴图才是
+              // "哪些部件真的是尾巴"的权威（作者自己画的图）。
+              uvBox: uvs === null ? null : uvs,
+            });
+          } catch (error) {
+            row.error = String(error?.message ?? error);
+          }
+          out.push(row);
+        }
+        return out;
+      },
+      /** 诊断：某块 drawable 的**原始 UV 数字**（不做任何换算，看表本身的形状）。 */
+      uvRaw: (index = 0) => {
+        const raw = model?.internalModel?.coreModel?._model;
+        const table = raw?.drawables?.vertexUvs;
+        if (table === undefined) return null;
+        const entry = table[index];
+        return entry === undefined ? null : Array.from(entry).slice(0, 16);
+      },
+      /** 诊断：core 里所有和 UV 有关的表名（不同版本字段名不一样，先看有什么）。 */
+      uvTables: () => {
+        const raw = model?.internalModel?.coreModel?._model;
+        if (raw === undefined) return null;
+        const out = {};
+        for (const scope of ["drawables", "parts"]) {
+          const table = raw[scope];
+          if (table === undefined || table === null) continue;
+          out[scope] = Object.keys(table);
+        }
+        out.drawableKeys = raw.drawables === undefined ? [] : Object.keys(raw.drawables);
+        return out;
+      },
+      /** 诊断：模型自绘包围盒（模型空间）与舞台尺寸，供"模型空间 → 屏幕"换算。 */
+      fitBox: () => {
+        try {
+          const b = model.getBounds();
+          return {
+            model: { x: b.x, y: b.y, width: b.width, height: b.height },
+            scale: typeof model.scale?.x === "number" ? model.scale.x : null,
+            position: { x: model.position?.x ?? null, y: model.position?.y ?? null },
+            anchor: { x: model.anchor?.x ?? null, y: model.anchor?.y ?? null },
+          };
+        } catch {
+          return null;
+        }
+      },
       /** Diagnostic: the measured head box in model space, or null. */
       headBox: () => headBox,
       /**
        * 这一下点在尾巴上吗？
        *
-       * 和摸头同一套判定（模型自己的三角面），只是部件集合换成 cdi3 里命名为
-       * 尾/鳍/翅/翼 的那些。**没有尾巴部件时返回 false**（不是 true）：摸尾巴是个
-       * 新增的互动，测不出来就不该乱触发（摸头那边相反，它要兼容旧模型）。
+       * 和摸头同一套判定（模型自己的三角面），但部件集合不是"名字里带尾/翅的那些"，
+       * 而是**再收窄一次**：只留贴图落在尾鳍区域的那几块（见 `tailIndices()`）。
+       * 原因见那段注释 —— 16 块里 11 块是配件几何、横跨全身，全算上的话"处处是尾巴"，
+       * 而路由摸头优先，可见的尾鳍反而永远轮不到。
+       *
+       * **没有尾巴部件时返回 false**（不是 true）：摸尾巴是个新增互动，测不出来就不该
+       * 乱触发（摸头那边相反，它要兼容没有 cdi3 的旧模型）。
        */
       hitsTail(x, y) {
         if (model === null || vendor === null) return false;
         if (tailParts.length === 0) return false;
         try {
           const point = model.toModelPosition(new vendor.Point(x, y));
-          if (tailIndices === null) tailIndices = drawableIndicesForParts(tailParts);
-          const hit = hitsPartsGeometry(tailIndices, point.x, point.y);
+          const hit = hitsPartsGeometry(tailIndicesNow(), point.x, point.y);
           return hit === true;
         } catch {
           return false;
@@ -1956,6 +2275,35 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         const im = model?.internalModel;
         return typeof im?.getDrawableIDs === "function" ? Array.from(im.getDrawableIDs()).map(String) : [];
       },
+      /**
+       * 尾巴判定**实际用的**那几块 drawable（收窄的结果，见 `tailIndicesNow`）。
+       */
+      tailIndices: () => tailIndicesNow(),
+      /** Diagnostic: 尾巴判定的收窄结果（收窄前 / 收窄后各是哪些、各自贴在哪块贴图上）。 */
+      tailDebug: () => {
+        if (tailIndices === null) tailIndices = drawableIndicesForParts(tailParts);
+        const kept = tailIndicesNow();
+        const rows = (tailIndices ?? []).map((entry) => {
+          const uv = readUvs(entry.index);
+          return {
+            id: entry.id,
+            part: entry.part,
+            uv,
+            inFin: uvInsideTailFin(uv) === true,
+            kept: kept.some((row) => row.id === entry.id),
+          };
+        });
+        return {
+          parts: tailParts.length,
+          before: (tailIndices ?? []).length,
+          after: kept.length,
+          region: TAIL_FIN_UV,
+          // 实时盒子（hitsMask 会并进"算不算落在她身上"）与它的采样间隔。
+          liveBox: tailBoxLive,
+          sampleMs: TAIL_BOX_SAMPLE_MS,
+          rows,
+        };
+      },
       /**
        * Diagnostic: 引擎原始表里 drawable → 父部件 的对应关系。
        *
@@ -2422,6 +2770,7 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     ROOT_SEL + " [data-hit]{position:absolute;inset:0;cursor:grab;pointer-events:auto}",
     ROOT_SEL + " [data-stage][data-dragging] [data-hit]{cursor:grabbing}",
     ROOT_SEL + " [data-hit][data-off]{display:none}",
+    // 尾巴那一块（那一截矩形由 JS 每 ~120ms 跟着摆动重建，见 hitPath）。
     // Until the silhouette is known the whole box stays live, so the pet is
     // never inert; it degrades to the pre-mask behaviour instead of nothing.
     ROOT_SEL + " [data-stage][data-nomask]{pointer-events:auto;cursor:grab}",
@@ -2841,8 +3190,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 };
@@ -2857,7 +3209,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) =>
@@ -3575,28 +3930,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";
   };
 
   /** 跑一条反应（由点击/转圈触发）。 */
@@ -3765,6 +4152,50 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
   /** Alpha above which a sampled pixel counts as part of the character. */
   const HIT_MASK_ALPHA = 24;
 
+  /**
+   * 贴图上**真正属于尾巴**的那一块（归一化 UV）。
+   *
+   * 为什么这是一个常量而不是"名字里带尾/翅的部件"：这只宠物有 **16 块** drawable 命中
+   * `尾|鳍|翅|翼`，但其中 **11 块是可换配件**（狐狸尾 / 猫尾 / 狼尾 / 天使翅膀 /
+   * 恶魔翅膀…），几何**一直留在原地**、横跨从头顶到腰腹的整个角色。把它们全算成尾巴，
+   * 结果是"算尾巴"的格子占角色 **22%**，其中 **86.6% 同时算头** —— 而路由是摸头优先，
+   * 于是用户点在**可见的尾鳍**上拿到的是摸头反应（用户报的"摸尾巴很难点到"）。
+   *
+   * 依据是**贴图**（作者自己画的）：`texture_00.png` 2048² 上，鲸鱼尾鳍只占
+   * `x 3..444, y 953..1397` 这一块，对应下面这个归一化区域。实测落在这里的正好是
+   * `ArtMesh38 / 56 / 58 / 59 / 60` 五块，全部属于部件 `尾巴(蒙皮)`；其余 11 块各自
+   * 落在贴图别处（`ArtMesh75` 落在 600,1592 → 1069,2045 那片大翅膀上）。
+   *
+   * UV 读不到时（别的引擎版本、没有 `vertexUvs` 表）**不做任何收窄** —— 退回旧行为，
+   * 不能让"判定变得精确"变成"判定整个失效"。
+   */
+  const TAIL_FIN_UV = { minU: 0, minV: 0.45, maxU: 0.23, maxV: 0.72 };
+
+  /** 一块 drawable 的 UV 包围盒整体落在这个区域里吗（留一点边距）。 */
+  function uvInsideTailFin(uv) {
+    if (uv === null) return null;
+    const pad = 0.02;
+    return uv.minU >= TAIL_FIN_UV.minU - pad && uv.maxU <= TAIL_FIN_UV.maxU + pad
+      && uv.minV >= TAIL_FIN_UV.minV - pad && uv.maxV <= TAIL_FIN_UV.maxV + pad;
+  }
+
+  /**
+   * 尾鳍实时包围盒的采样间隔（ms）。
+   *
+   * 100ms ≈ 6 帧一次：摆动一个来回大约 30 帧，所以盒子永远落后不超过摆动幅度的几分之一，
+   * 而每帧读几十个顶点是白烧 CPU。采样点在 `saveParameters` 缝里（这一帧真正要画的姿势）。
+   */
+  const TAIL_BOX_SAMPLE_MS = 100;
+
+  /**
+   * 尾巴那一块矩形在包围盒外**再放宽的比例**。
+   *
+   * 它每 120ms 跟着实时盒子重建，而尾鳍一直在摆 —— 采样时刻的位置和用户抬手那一刻
+   * 会差一点。实测（探针 `probe-tail-precise.mjs`）不留余量时会有落点掉在矩形之外、
+   * 事件穿透到页面。放宽按这一块自己的尺寸取比例，所以缩小/放大宠物都合适。
+   */
+  const TAIL_LAYER_PAD = 0.08;
+
   /**
    * Build a coarse opacity grid of the character as actually rendered.
    *
@@ -3988,6 +4419,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),
@@ -4000,6 +4442,14 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         windowMs: TUNING.spinWindowMs,
         threshold: TUNING.spinTurns * Math.PI * 2,
       });
+      /**
+       * 诊断：**上一下按住的三个答案**（onModel / onHead / onTail，以及事件被哪一层接住）。
+       *
+       * "点了没反应"要先分清卡在哪一段：事件没进宠物（截不住 / 穿透到页面）、
+       * 路由判成"身体"（只有台词）、还是判定本身说不在她身上。从"她说了什么"倒推
+       * 这三件事是分不出来的 —— 尾巴那一串问题就是这么绕了好几轮的。
+       */
+      api.lastPress = () => lastPressRef.current;
     }, []);
     /**
      * The pins the USER owns (slot choices, flashes) and the pins the SESSION
@@ -4474,6 +4924,70 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       return () => observer.disconnect();
     }, []);
 
+    /**
+     * 尾巴那一层可点区域的**动态更新**。
+     *
+     * 尾鳍一直摆，而 `[data-hit]` 的轮廓是开机快照 —— 摆出去就点不到（事件穿透到页面）。
+     * 这里按固定间隔把尾巴此刻的包围盒（模型空间）换算成舞台上的百分比矩形：
+     *
+     *   模型空间 → 舞台：`model.getBounds()` 给的是舞台局部盒，
+     *   尾巴各 drawable 的并集盒 → 按比例映射进那个盒子里（同一套映射，
+     *   不猜 anchor / scale，换缩放、换宠物都成立）。
+     *
+     * 间隔 120ms 是刻意的：尾鳍一个摆动来回约 0.5 秒，取 1/4 个周期足够跟上，
+     * 而每帧 setState 会让整个宠物重渲染 —— 那是白烧。**只在格子真的变了才 setState**，
+     * 静止时一个渲染都不产生。
+     */
+    useEffect(() => {
+      if (!ready) return undefined;
+      let last = "";
+      const tick = () => {
+        const api = motion.current;
+        const stage = stageRef.current;
+        if (api === null || stage === null) return;
+        const box = typeof api.tailBoxNow === "function" ? api.tailBoxNow() : null;
+        if (box === null || typeof api.modelToStage !== "function") {
+          if (last !== "") { last = ""; setTailPath(""); }
+          return;
+        }
+        const rect = stage.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) return;
+        // 模型空间 → 舞台：`modelToStage()` 用"模型空间包络盒 ↔ 引擎自绘盒"对齐，
+        // 缩放、拖动、resize 之后都成立（比 `toStagePosition` 稳 —— 那个 API
+        // 在这层包装上直接抛异常）。
+        //
+        // 注意**模型空间 y 向上、舞台 y 向下**：小 y 的顶点画在舞台下方。所以要把
+        // 两个对角都映射完再取 min/max —— 直接拿 minX/minY 当左上角会把这一层画到
+        // 屏幕外（第一版就是这么错的：尾巴层跑到左边去了）。
+        //
+        // 再加一圈**摆动的余量**：这一层每 120ms 更新一次，而尾鳍一直在摆，所以
+        // 采样时刻的位置和用户抬手那一刻的位置差着一个余量；不留的话就会出现
+        // "实测点在这层外面"（第一版 5 轮里有 2 轮是这样）。余量按这一块自己的
+        // 尺寸取比例，缩放之后依然合适。
+        const padX = (box.maxX - box.minX) * TAIL_LAYER_PAD;
+        const padY = (box.maxY - box.minY) * TAIL_LAYER_PAD;
+        const a = api.modelToStage(box.minX - padX, box.minY - padY);
+        const b = api.modelToStage(box.maxX + padX, box.maxY + padY);
+        if (a === null || b === null) return;
+        const left = Math.max(0, Math.min(a.x, b.x));
+        const top = Math.max(0, Math.min(a.y, b.y));
+        const right = Math.min(rect.width, Math.max(a.x, b.x));
+        const bottom = Math.min(rect.height, Math.max(a.y, b.y));
+        const width = right - left;
+        const height = bottom - top;
+        if (!(width > 0) || !(height > 0)) return;
+        // 一条矩形 = 一段 subpath，直接拼在轮廓路径后面（同一个 `clip-path`）。
+        const next = "M" + left.toFixed(1) + " " + top.toFixed(1)
+          + "h" + width.toFixed(1) + "v" + height.toFixed(1) + "h-" + width.toFixed(1) + "Z";
+        if (next === last) return;
+        last = next;
+        setTailPath(next);
+      };
+      tick();
+      const timer = window.setInterval(tick, 120);
+      return () => window.clearInterval(timer);
+    }, [ready]);
+
     // ---- greeting -----------------------------------------------------
     useEffect(() => {
       if (!ready || greeted.current) return;
@@ -5504,6 +6018,10 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     // Interaction bookkeeping lives above the effects that read it, so the
     // idle-fidget scheduler can tell "left alone" from "being handled".
     const dragState = useRef(null);
+    // 诊断读口：按住那一刻路由用的三个答案（尾鳍点不到这类问题要能直接看见它们，
+    // 而不是从"她说了什么"倒推）。
+    const lastPressRef = useRef(null);
+
     // Last time the user touched the pet; the idle-fidget timer (#6) measures
     // quiet time from here so a fidget never fires under the user's cursor.
     const lastInteraction = useRef(Date.now());
@@ -5567,6 +6085,17 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      * hidden and the stage keeps its old full-box behaviour.
      */
     const [maskPath, setMaskPath] = useState("");
+    /**
+     * `[data-hit]` 真正用的路径 = 轮廓快照 + **尾巴那一块矩形**（跟着摆动更新）。
+     *
+     * 为什么要并：轮廓是开机从渲染画布抓一次的静态网格，而尾鳍一直在摆 —— 摆出去的那一
+     * 瞬间，点击落在 `clip-path` 之外、事件直接穿透到页面（实测 `elementFromPoint=HTML`，
+     * 而 `hitsMask` / `hitsTail` 都说是她）。这正是用户报的"尾巴一直在摆动，摸尾巴很难
+     * 点到"。并一条矩形只多 20 来个字符，而且**只有一层 DOM**：再叠一层会和主层抢事件，
+     * 落哪一层取决于 z 序与更新时间，那种不确定性极难查。
+     */
+    const [tailPath, setTailPath] = useState("");
+    const hitPath = tailPath === "" ? maskPath : (maskPath === "" ? tailPath : maskPath + tailPath);
     const pendingPhase = useRef(null);
     // Published by the stream effect so the (earlier-declared) subscription can
     // flush a deferred phase; a ref avoids a declaration-order dependency.
@@ -5668,6 +6197,7 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         onHead: hitsHead(event.clientX, event.clientY),
         onTail: hitsTail(event.clientX, event.clientY),
       };
+      lastPressRef.current = Object.assign({ at: Date.now(), layer: event.currentTarget?.getAttribute?.("data-tail") !== null ? "tail" : "hit" }, dragState.current);
       setDragging(true);
       try { event.currentTarget.setPointerCapture(event.pointerId); } catch { /* not capturable */ }
     }, [hitsModel, hitsHead, hitsTail]);
@@ -5930,10 +6460,16 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       },
         // Only the silhouette is interactive; everything else in the square
         // canvas stays click-through to the page behind (requirement #5).
+        //
+        // **尾巴那一块要并进这条路径**：轮廓是开机抓一次的静态快照，而尾鳍一直在摆，
+        // 摆出快照的那一瞬间点击会穿透到页面（实测：`elementFromPoint=HTML`，而判定说
+        // 是她）。并一条矩形只多 20 来个字符，比"再叠一层 DOM"更不容易和主层抢事件
+        // —— 两层叠着的时候，落哪一层取决于 z 序与更新时机，那种不确定性正是这一串
+        // 问题里最难查的部分。
         h("div", {
           "data-hit": "",
-          ...(maskPath === "" ? { "data-off": "" } : { style: { clipPath: "path('" + maskPath + "')", WebkitClipPath: "path('" + maskPath + "')" } }),
-          ...(maskPath === "" ? {} : { onPointerDown, onContextMenu }),
+          ...(hitPath === "" ? { "data-off": "" } : { style: { clipPath: "path('" + hitPath + "')", WebkitClipPath: "path('" + hitPath + "')" } }),
+          ...(hitPath === "" ? {} : { onPointerDown, onContextMenu }),
         }),
       ),
       // 气泡的偏移量走 CSS 变量（值，不是布局）：位置规则仍然只写在样式表里。
@@ -6418,12 +6954,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);
@@ -6446,8 +6979,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) => {
@@ -6466,9 +7007,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'
@@ -567,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)
+}
+
+/**
+ * 把随包宠物装进用户的宠物目录，并在**确实是我们装的那份**过期时更新它。
  *
  * 以前宠物是仓库里单独一份，装插件的人还得自己再拷一次 —— 从插件市场装完
  * 「看不见宠物」就是这么来的（插件包里有代码，没有模型）。
@@ -578,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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pet-live2d",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "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",