dsh-pet-live2d 3.1.3 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 更新日志
 
+## 3.3.0（2026-10-09）
+
+### 新：官方「插件」页里有自己的图标和常用设置
+
+侧栏「插件」页上这张卡片以前是默认插画加包名，现在有自己的图标、中文与英文标题/描述
+（「设置 → 内置插件」那份列表同样受益）。点进详情页多了一节配置区：常用开关（气泡 /
+提示音 / 摸头 / 摸尾巴 / 转圈 / 记住装扮）、四根手感滑杆（注视满偏、收回倍数、摸鱼静置、
+提示音音量）和「显示位置」。它写的是与 **设置 → 桌宠** 同一份配置，改哪边都一样；
+相位台词、池子编辑器、装扮与文案仍在设置页里改。
+
+## 3.2.0（2026-10-09）
+
+### 新：会话状态提示音
+
+「桌宠 → 会话提示音」单独控制总开关和音量；「会话相位」改为两列概览、按需展开编辑，不再把八个动作池同时铺满页面。每个相位可上传 MP3 / WAV / OGG 提示音并随宠物分别保存；移除上传即恢复宠物默认音符，静音和总开关仍独立生效。
+
+### 新：提示音可以「试听」
+
+设置页每个相位多了「试听」：点一下直接听这个相位**会响的那段声音**（有上传听上传，否则听宠物/内置音符），不用等会话真的跑到那个相位。它**故意不受**总开关与单相位静音影响 —— 默认总开关就是关的，跟着它走等于"点了没反应"；音量用当前提示音音量，音量为 0 时按 0.35 试听。**拖音量滑杆也会即时试听**（停手才响一次，用最终音量；音量 0 就是没声，不给兜底）。
+
+### 改：上传音频的判据两端统一（并放行"长度未知"的 WAV）
+
+以前网页端只认开头几个字节、桌面端会完整解析容器，于是同一个文件可能"网页端传得进、桌面端读不出来"——相位的「已上传」在桌面端凭空消失，而且两边都不报错。现在两份宿主共用一套判据，由 `tools/sound-vectors.json` 的合同向量在两边测试里钉住；顺带放行长度字段写 `0` / `0xFFFFFFFF` 的流式 WAV（这类文件浏览器本来就能播，以前会被桌面端错杀）。
+
 ## 3.1.3（2026-10-01）
 
 ### 修：设置里选「桌面」后，桌面上什么都没有（手动双击同一个 exe 却正常）

package/README.md

@@ -62,16 +62,28 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 
 插件包里就带着一只可用的宠物（`pets/ds-whale-girl/`，CC BY-NC-SA 4.0）。**第一次运行时
 宿主半区会把它复制进 `%DSH_HOME%\pets\`**，所以装完插件、重启 `dsh web` 就能看见。
-只在目标**不存在**时复制 —— 你自己改过或换过的宠物目录永远优先，不会被覆盖。
+升级时原封不动的随包宠物会同步新版默认值（包括提示音）；你自己改过的宠物目录优先，不会被覆盖。
 
 ## 怎么用
 
 - **右键点宠物** 呼出面板：「动作」「装扮」两个页签，底部是大小滑杆和「归位」。
   平时画面上没有常驻 UI。
-- **改配置** 去 **DSH 设置页 → 桌宠**（面板只负责"点一下换个样子"）。
+- **改配置** 两个入口：**DSH 设置页 → 桌宠**（完整设置），或**侧栏「插件」→ 本插件**（常用开关）。
 
 ## 设置说明
 
+### 官方「插件」页上的那一节
+
+侧栏点「插件」，「已安装」里那张带图标的卡片就是本插件。点进详情，描述与插件行之间是它
+自己的配置区：
+
+- **常用开关**：气泡、会话提示音、摸头 / 摸尾巴 / 转圈、跨启动记住装扮；
+- **四根滑杆**：注视满偏、收回倍数、静置多久开始摸鱼、提示音音量；
+- **显示位置**：自动 / 页面内 / 桌面。
+
+改的是与设置页**同一份**配置（`%DSH_HOME%\pet-settings.json`），两边随时一致。相位台词、
+池子编辑器、装扮与台词文案仍在 **设置 → 桌宠** 里改 —— 那里才是完整设置。
+
 ### 摸鱼：每个槽位一张条目表
 
 摸鱼 = 静置一会儿之后，宠物自己换个样子。**每个槽位各掷一次骰子**（不是"这次只动一两个"），
@@ -85,9 +97,9 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 - **「默认」＝回到默认**（把这个槽位清空）。`默认 10 : 脸红 1` = 大约每 11 次摸鱼脸红一次、
   其余时间回到没有。想让某个槽位**完全不动**，把它的条目删光或权重归 0。
 
-### 会话相位：同一套池子
+### 会话相位：动作、气泡与提示音放在一起
 
-每个会话相位下面是"槽位 → 条目表"，机制和摸鱼一样。**宠物跟着 DSH 的真实事件换相位**：
+设置页「会话提示音」卡统一控制开关和音量；紧邻的「会话相位」卡将八个相位排成宽屏两列、窄屏单列的概览，默认收起，点开一个相位后才显示它的「气泡与提示音」「动作槽位」编辑区。行头「重置动作」只恢复动作槽位；台词用自己的「恢复默认」按钮，提示音可单独静音、**试听**或上传文件。动作池子仍是"槽位 → 条目表"，机制和摸鱼一样。**宠物跟着 DSH 的真实事件换相位**：
 
 | 相位 | 什么时候 | 这只宠物演什么 |
 |---|---|---|
@@ -106,10 +118,11 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 
 相位表**一开始就列出全部相位**，显示的是**有效池子**：
 
-| 行头标记 | 含义 | 那一行有什么 |
+| 行头概览 | 含义 | 恢复方式 |
 |---|---|---|
-| 默认 | 你没改过，用的是宠物默认 | 没有 `×` |
-| 已改过 | 你改过，用的是你的 | 有 `×` = 恢复默认 |
+| 动作默认 / 已改 | 动作槽位沿用宠物默认 / 用你的池子 | 动作改过才显示「重置动作」，只重置动作池 |
+| 台词默认 / 已改 | 该相位台词是否被你修改 | 展开后点「恢复默认」 |
+| 音频宠物默认 / 已上传 / 已静音 / 未配置 | 宠物音符、当前宠物的上传文件、单独静音或未声明 | 展开后上传、移除上传或勾选提示音 |
 
 改动**只在真的编辑时才落盘**，所以"看一眼"不会留下覆盖 —— 以后宠物更新了默认值，
 没改过的相位照样吃得到。
@@ -125,6 +138,18 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 
 右键面板的「装扮」页签跟着相位走 —— 会话中它显示的是**相位抽到的**，不是你上次手选的。
 
+### 提示音：完成 / 失败 / 需要你处理
+
+在 **DSH 设置页 → 桌宠 → 会话提示音** 打开总开关并调节音量（默认关闭）；到紧邻的「会话相位」卡点开相位，在「提示音」处选 **上传音频**。支持 MP3 / WAV / OGG，单文件最多 1 MB；每只宠物、每个相位分别保存到 `$DSH_HOME/pet-sounds/`，换宠物不会沿用另一只的上传音频。「移除上传」恢复宠物默认音符，静音勾选框也能关闭已上传音频；上传成功会解除该相位先前的静音，但不会替你打开总开关。上传音频比宠物音符优先，两个窗口最多 3 秒同步一次。
+
+上传的文件是按**容器结构**校验的（不是看扩展名，也不是只看开头几个字节）：MP3 要有合法的帧头、Ogg 要过页校验、WAV 的 fmt/data 块要自洽 —— **网页端与桌面端用的是同一套判据**（同一份合同向量在两边测试里跑）。长度字段写成 `0` 或 `0xFFFFFFFF` 的"流式" WAV 也收；明显不是音频、或被截断的文件会在上传时就报错，不会写进 `$DSH_HOME/pet-sounds/`。
+
+旁边的 **「试听」** 让你不必等会话真的跑到那个相位：点一下直接听这一相位**会响的那段声音**（有上传听上传，否则听宠物/内置音符）。它**故意不受**总开关与单相位静音影响 —— 默认总开关就是关的，跟着它走等于"点了没反应"；音量用当前提示音音量，音量为 0 时按 0.35 试听。没有任何音源（未配置、也没上传）的相位，按钮是灰的。
+
+**拖动「会话提示音」卡里的音量滑杆也会即时试听**一小段（防抖：停手才响，响的是最终音量；这只宠物一个音源都没有时只给数字反馈）。音量滑杆这条**按真实音量**响 —— 拖到 0 就是静音，不会像「试听」按钮那样兜底发声，否则你听到的就不是"0 有多大声"了。
+
+未上传时，内置宠物的 `done`、`failed`、`waiting`（待批准）、`asking`（待回答）各有一段合成短音；别的宠物可在 `pet.json` 的 `live2d.sounds` 声明自己的音符，空数组表示该相位不响，未声明整个字段的旧宠物沿用内置四声。音量拉到 0 会静音；首次播放前浏览器需要你点击一次页面解锁音频。初次连接的状态快照和重复状态不会响；若两个窗口同时接收相位，两边都开启时可能各响一次。
+
 ### 互动：摸头 / 摸尾巴 / 转圈
 
 点她身上会有反应，判定用的是**模型自己的几何**，不是画出来的区域：
@@ -159,9 +184,7 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 她说话时会弹一个小气泡（问候、点击、摸头、摸尾巴、转晕、归位，以及**每个会话相位一句**：
 思考中 / 用工具 / 等你批准 / 等你回答 / 叫了帮手 / 消息排队 / 完成 / 出错）。
 
-- **所有文本都能改**：设置页「气泡」卡里逐条编辑。一组台词**用 `|` 分隔多个变体**
-  （随机挑一句）；**留空 = 用宠物默认**（`pet.json` 的 `live2d.lines`），所以"看一眼"不会
-  把默认改掉。
+- **所有文本都能改**：会话台词在「会话相位」卡的对应相位里，其他台词在「气泡」卡。非相位的一组台词**用 `|` 分隔多个变体**（随机挑一句），留空使用宠物默认；相位台词是一句，留空表示该相位不弹，点「恢复默认」可回到宠物台词。看一眼设置不会留下覆盖。
 - **位置可调**：左右 / 上下偏移两个滑杆（相对她头顶的默认位置），另有"一句话停留多久"。
 - **总开关**：关掉之后任何台词都不弹。
 
@@ -258,6 +281,8 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
     ],
     // 会话相位 -> 槽位 -> 选项（读成"每个槽位一条、权重 1"的池子）
     "looksByPhase": { "done": { "whale": "头顶鲸", "mood": "开心兴奋" } },
+    // 可选：每个相位一组 [频率 Hz, 从开始播放起的秒数]；空数组表示该相位静音
+    "sounds": { "done": [[660, 0], [880, 0.13]], "failed": [] },
     // 摸鱼默认盯哪些槽位（用户还能再加；不写就是"手/情绪/脸红/嘴/眼"那五个兜底）
     "fidgetSlots": ["rhand", "lhand", "mood", "cheek", "mouth", "eyes", "selfie"],
     // 互动反应候选（标签 = 动作的中文名或表情名）。**三个键都可以不写** ——
@@ -278,6 +303,7 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 
 - **动作和表情列表以 `.model3.json` 里声明的为准**，插件启动时从模型读出 —— 换模型 / 改模型
   文件立刻生效，不用改插件代码。
+- `sounds`：宠物声明后只有列出的相位会响；每相位最多 8 个正弦音符，频率 80–4000 Hz、起始时间 0–2 秒。没写整个字段的旧宠物沿用内置四声；无效音符不会播放。声音由页面合成，音量和静音可在设置页调整。
 - `motionOptions`：`hold`（停在最后一帧）/ `persist`（定格且不自动放手）/ `prepend`（先播前置
   动作）/ `preset`（开播前把某些参数写死）。不写就是"播一次然后回待机"。
 - `motionGuards`：动作的前提，形如"槽位 = 标签白名单"。**白名单形式没法自动满足，只能拦**
@@ -295,6 +321,9 @@ dsh plugin --profile web add "link:./dsh-pet-live2d/dsh-live2d-pet"
 | GET | `/api/live2d-pet/asset/<id>/<path>` | 只服务 `model3.json` **引用闭包**内的文件（白名单 Set 比对 + realpath 包含，`..` 永远匹配不上） |
 | GET | `/api/live2d-pet/runtime/live2dcubismcore.min.js` | Cubism Core：本地有就发本地的，没有就去 Live2D 官方 CDN 取一份并缓存（`x-live2d-core-source: cdn`）；两边都拿不到才 502 |
 | GET | `/api/live2d-pet/runtime/live2d-vendor.js` | 插件内置的 MIT vendor 分包（pixi.js + 引擎），按需懒加载 |
+| GET | `/api/live2d-pet/sound/<id>` | 查询这只宠物已上传音频的相位、URL、格式和版本 |
+| GET | `/api/live2d-pet/sound/<id>/<phase>` | 读取已上传的相位音频 |
+| POST | `/api/live2d-pet/sound/<id>/<phase>` | JSON `{ "base64": "..." }` 上传，或 `{ "action": "reset" }` 移除；限 MP3 / WAV / OGG、1 MB |
 
 API 与资产路由默认只答本机回环请求。
 

package/icon.svg

@@ -0,0 +1,45 @@
+<!--
+  dsh-pet-live2d 的插件图标（原创几何图形，不含模型的任何美术素材 ——
+  模型是 B站@氵六青 的 DS鲸鱼娘，授权与这个图标无关）。
+
+  用途：DSH 侧栏「插件」页、设置 → 内置插件列表里这张卡片的图标。
+  宿主的读法（`dsh-app-boot` 的 `readPluginMeta` → `iconOf`）：
+  package.json 的 `"icon": "./icon.svg"`，或导出的 `./icon` 子路径；
+  必须是**包目录内的相对路径**，SVG / PNG / JPEG / WebP，≤256 KiB。
+  它以 `data:image/svg+xml;base64,…` 塞进 `<img width=36 height=36>`，
+  `object-fit:contain` —— 所以画布按 36×36 画、图形留一点边距，
+  且**不能依赖 currentColor**（img 里没有继承），颜色一律写死。
+
+  几何约定：所有图形都在 0…36 的 viewBox 内；尾鳍画在身体**之前**，
+  它靠左下那只角（10,20.4）藏在身体里，看起来才是连着的。
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 36 36" width="36" height="36" role="img" aria-label="Live2D pet">
+  <title>Live2D 桌宠</title>
+  <defs>
+    <linearGradient id="pet-tile" x1="0" y1="0" x2="0.45" y2="1">
+      <stop offset="0" stop-color="#7FB0FF"/>
+      <stop offset="1" stop-color="#3B5DD4"/>
+    </linearGradient>
+  </defs>
+
+  <!-- 底：一块圆角砖。浅色与深色主题下都要能看见，所以自带底色而不是只描线。 -->
+  <rect x="0.6" y="0.6" width="34.8" height="34.8" rx="9.4" fill="url(#pet-tile)"/>
+
+  <!-- 头顶冒出来的那颗心（对应她的「冒爱心」表情） -->
+  <g fill="#FFB4D2">
+    <circle cx="12.7" cy="7.7" r="2"/>
+    <circle cx="16.5" cy="7.7" r="2"/>
+    <path d="M10.6 8.4h8l-4 4.3z"/>
+  </g>
+
+  <!-- 尾鳍（左下角压在身体下面） -->
+  <path d="M10 20.4 2.2 12.4l8.6.8z" fill="#D8E6FF"/>
+
+  <!-- 身体 -->
+  <ellipse cx="17.6" cy="21" rx="13" ry="7.4" fill="#FFFFFF"/>
+
+  <!-- 眼睛 / 嘴 / 腮红 -->
+  <circle cx="23.6" cy="19.9" r="1.7" fill="#1E2A4C"/>
+  <path d="M21.7 23.6c1 1 2.3 1 3.3 0" fill="none" stroke="#1E2A4C" stroke-width="1" stroke-linecap="round" opacity=".9"/>
+  <ellipse cx="18.9" cy="24" rx="1.9" ry="1.1" fill="#FFA6C8"/>
+</svg>