dsh-plugin-wallpaper-engine-pet-link 1.4.0 → 1.4.1

package/README.md

@@ -1,36 +1,93 @@
-# 桌宠联动子包
+# 桌宠联动子包（pet-link）
 
-本包只包含官方 pet 桥接、四条演出排播、调参面板、九段定制动画及五张配图。不包含 pet 渲染器、Electron、完整基础素材或第三方补丁安装器。
+把壁纸吉祥物变成**可联动的桌宠**：安装 [dsh-pet-dshwe](https://github.com/Fish-under-sea/dsh-pet-dshwe)（上游 [dsh-pet](https://github.com/PC2005-cloud/dsh-pet) 的全量 fork）后，点壁纸吉祥物触发四条演出——侧栏后拉、跳抓吉祥物绳子、踢开侧栏原生弹飞、站立哈气开栏；没装或关闭时一切照旧（原生侧栏操作）。本包只做**编排 + 安装 + 面板**：九段联动动画、五张气泡配图在这里；宠物运行时（渲染、物理、动画池、Electron helper）全在 `dsh-pet-dshwe`，本包不含也不改它。
 
-## 使用
+## 快速开始
 
-1. 按仓库的完整源码部署步骤安装 Wallpaper 的主包和七个子包。
-2. 自行安装并启用官方 [dsh-pet](https://github.com/PC2005-cloud/dsh-pet)，将目标设为网页显示。官方需提供同页 `petApi7340.pose/progress` 和 `/dsh-pet-7340/` 下的 config、lock、anim、position、throw 接口。审计基线为官方提交 `7440b963ab7fb962cb7694e094aa0c9c7a438a7b`；同为 `0.3.7` 的旧构建不一定有这些接口。
-3. 将 Wallpaper 吉祥物设为官方侧栏模式，按 `Ctrl+Shift+D` 打开面板，刷新并选择目标 petId，再分别试跑四条逻辑。
+1. 安装本仓主包 `dsh-plugin-wallpaper-engine`（含 7 个子包）——见仓库根 [CONTRIBUTING.md](../../CONTRIBUTING.md) 的完整源码安装。
+2. 打开壁纸引擎设置页，第一张卡片就是「桌宠联动」：
+   - **未装运行时** → 点「下载并安装 dsh-pet-dshwe」（见下文安装事务）；
+   - 装完**重开 DSH** 生效；
+   - 把「联动开关」打开（默认开），点壁纸吉祥物或卡片上的「测试一次联动」。
+3. 也可以手动安装：`dsh plugin --profile <profile> add dsh-pet-dshwe`，与官方 `dsh-pet` 可同机共存（互不接管，同时启用各显示一只）。
 
-没有官方 pet、服务缺失、目标隐藏或联动关闭时，只停用联动，吉祥物原生侧栏操作继续可用。不会自动安装、启用或修改官方 pet。目标缺失不会自动改控另一只宠物。
+## 双 provider 状态机
 
-## 控制边界
+`petLinkMode()` 每次判定都重新回答一个问题：此刻走 **linked**（页内 `petApiDshwe.link` 直控）还是 **native**（主包原生吉祥物）。四条判据**全真**才 linked，任一为假立即降级 native 并给出可读原因：
 
-- 宿主按 petId 协调页面，保管官方锁凭证并顺序下发白名单指令；短租约、失锁和旧响应清理不会强占新运行。
-- 官方同一 pet 的动作会同步到其他显示端。`surface` 不是单页定向，本包不承诺跨端隔离。
-- 发起页面自绘气泡并读取官方 pose 跟随。动作结束释放官方唯一锁后，气泡可以继续存在；不调用官方 broadcast 或 bubble/clear，也不注入桌面透明窗。
-- 侧栏、抓绳、踢腿弹飞、哈气四条排播使用同页 playbackId 与实际视频进度触发节点。位置和抛掷交给官方 `position/throw`；不查询宠物 DOM、不改 React 私有字段、不逐帧发 HTTP。
-- 官方直线位移按墙钟推进，不能保证视频缓冲时的逐帧贴边同步。旧私有运动面的精度不作为当前接口已实现的能力。
+| 判据 | 降级原因（reason） |
+|---|---|
+| 联动开关开启 | `toggled-off`（关闭时点击吉祥物 = 原生侧栏开关，不空转） |
+| 页内探测到 `petApiDshwe` 服务 | `runtime-not-installed`（未装 / 未加载） |
+| `link.*` 14 项方法齐全且协议版本 ≥ 4 | `runtime-too-old`（需升级 dsh-pet-dshwe） |
+| 目标 petId 有效且根节点可见 | `unknown-target` / `unknown-pet` / `pet-not-displayed` |
 
-## 参数与验证
+降级是**彻底的**：不下发任何动作、不上租约、不画气泡，原生侧栏行为一字不差。判定失败绝不留半死状态（探测通过但控制面缺方法、点了没反应）。
 
-面板提供目标选择、四逻辑参数、运行、停止、重置和 JSON 导出。五张气泡各有出现与隐藏的动作、开始/结束锚点及毫秒偏移；重置当前逻辑同时清除该逻辑的气泡节点。参数是当前页运行时覆盖，刷新前请导出。
+> **排播进行中切换开关是有意的语义选择**：当轮演出演完、结尾归还租约并清掉气泡后才降级——不做动作中途硬打断；之后的新交互立即走 native。卸载运行时同理：服务下页后本轮收尾干净、无残留（租约 / 气泡 DOM / 定时器全部释放），后续点击回落原生。
+
+## 四条排播与联动细节
+
+| 逻辑 | 演出 |
+|---|---|
+| 侧栏拉动（默认） | 螃蟹步走到屏幕边缘 → 蓄力后拉 → 侧栏展开 → 贴边等待 → 气泡「累死本鲸了…」→ 走回原位 |
+| 抓绳互动（吉祥物在近侧） | 走向吉祥物 → 跳抓眩晕 → 绳子下拉 → 侧栏展开 → 落地起身 |
+| 彩蛋一（侧栏逻辑第 3 次） | 气泡「偶鲸鲸！！！」→ 踢侧栏 → 宠物被原生抛掷物理弹飞 → 落地「哇啊啊啊啊啊！！！」 |
+| 彩蛋二（吉祥物逻辑第 3 次） | 气泡「？！欺负一只肥鱼！？」→ 站立哈气 → 侧栏按进度展开 |
+
+技术口径：
+
+- 每只宠物一份控制器，全部经 `petApiDshwe.link` 的 14 项正式方法（`getRoot` 逐帧贴边 / `adoptPosition` 承接位置续物理 / `getPlayback` 真实播放进度 / `throwNative` 原生物理弹飞 / `lock-unlock` 独占租约等）——不再依赖任何 `window` 私有字段。
+- 发动作 = 每段一次 HTTP（`POST /dsh-pet-dshwe-7340/anim?pet=`），之后进度/位置/抛掷读数全走页内 `link.*`，**无逐帧请求**。
+- 睡觉竞争：取锁后发现宠物在睡 → 先释放租约 → `POST /wake` → 等醒来且「起来」演完 → 重新取锁 → 才下发点播；`throwNative` 是纯物理，睡着时照常起飞不唤醒。
+- 气泡由本包**自绘**覆盖层（逐帧跟随宠物根节点），不占用、不清理宠物自己的气泡。
+- 官方 `dsh-pet` 在场时只**探测并提示**（卡片显示「两者会各显示一只，互不接管」），不阻断、不互斥、不改官方任何文件。
+
+## 运行时安装（设置页卡片 → 宿主半路由）
+
+自研下载器已于 2026-11-01 拆除：下载解包会绕过 DSH 依赖管理、与 `link:` 布局冲突，实测造成重复注册 / 误判未安装 / 启动崩溃。现在安装走 **DSH 官方入口**（插件 → 添加插件，包名 `dshpet-dshwe`），pet-link 只保留只读探测与图文引导。
+
+宿主半只剩一条只读路由（同源校验：带 Origin 时必须 http + 本机回环 + 同端口，`sec-fetch-site: cross-site` 一律 403；只接受 GET）：
+
+- `GET /pet-link/pet/state` → `{ ok, installed, name, version, path, runtimePresent, running, installUrl, installCommand }`
+  - `installed` / `version` / `path`：每次请求**现扫** profile 的 `node_modules/{dshpet-dshwe,dsh-pet-dshwe}/package.json`（不缓存）；
+  - `runtimePresent`：数据根 `$DSH_HOME/dsh-pet-dshwe/` 是否存在；
+  - `running`：页内 `petApiDshwe` 服务是否已注册（决定联动是否真的可用）；
+  - `installUrl` / `installCommand`：给卡片展示的官方入口与命令，纯展示、不可执行。
+
+卡片按钮「如何下载安装联动桌宠」展开的是图文引导（三步 + 仓库链接），点了**不会**替用户装包：安装动作由 DSH 的插件管理完成，装完 `petApiDshwe` 注册上来，卡片在 5s 内自动从 native 翻到 linked。
+
+## 浮层操控面板（`Ctrl+Shift+D`）
+
+约 50 个参数、13 个分组、缓动三选一，按四条逻辑各存一份覆盖；按钮：▶ 运行 / ■ 停止 / 重置当前逻辑 / 导出 JSON / 导入 JSON；可拖动、`Esc` 关闭；气泡时间节点可按动作开始/结束锚点 + 毫秒偏移编辑。参数清单唯一真源见 [`src/pet-link/panel-params.js`](src/pet-link/panel-params.js)，逐组参数说明见 [`docs/2026-10-30-M6-panel-params.md`](../../../docs/2026-10-30-M6-panel-params.md)。
+
+**持久化口径（相对初始计划 §3.6 的一处降级，明确如实说明）**：参数覆盖层持久化在 WE 侧 `localStorage` 命名空间键 `dsh-we-pet-link-panel-v1`（记录 `{version, logic, target, tuning, bubbleTiming}`），刷新 / 重开页面可回读。
+
+- **为什么不是「写入 WE 设置」**：WE 的宿主端 `/settings` 是固定 7 簇白名单（`core / appearance / mascot / fx / parallax / typeColor / media`）按键合并，簇外键会被判据驳回忽略——塞面板参数进去根本落不了盘，改白名单则要动主包的设置契约。
+- **真实边界**：换浏览器 / 清站点数据 / 换机器即丢；跨环境迁移用面板的「导出 JSON → 导入 JSON」。
+- **若要落宿主文件**：替换 `src/pet-link/panel.js` 里 `createPetLinkPanelSettings` 适配器的默认实现（`load/save/clear` 三方法，面向任意 `storage` 注入），面板本体与其余逻辑零改动。
+
+## 验证
 
 ```sh
-npm run build
-npm run verify:pet-link
+# 前置（干净环境首跑必做，否则以下全部 ERR_MODULE_NOT_FOUND 红）：
+#   1) npm install --ignore-scripts --no-audit --no-fund   # 装工具链（npm cache 可指工作区 .npm-cache：npm_config_cache=<目录>）
+#   2) npm run build                                        # 生成 5 份浏览器半产物（lib/client.js + 4 子包 client.*.js）
+# 预期产物：built lib/client.js (约 4.5 MB) + fonts/fx/parallax/pet-link 四份 client.*.js
+
+npm run verify:pet-link               # 定点回归总链：包面 → 热插拔 → 排播引擎 → 四排播 → 回落 → 面板 → 卡片 → 侧栏/玻璃
+npm run verify:pet-install           # 安装事务 16 场景（含真实 64 MB 产物解包 819 文件、连解 20 次、三种篡改必败、并发两条）
+npm run verify:pet-link:integration   # 真实 Cordis：配置更新、旧处理器失效、十次启停零路由残留
+npm run verify:pet-link:browser       # 独立浏览器：自有气泡、配图加载与调参面板（需本机 Edge/Chrome 可起无头实例）
+npm run verify                        # 全仓守卫链（92 步到尾，任何一步红都会短路）
 ```
 
-回归覆盖协议协调、真实本地 HTTP、素材 Range、独立气泡生命周期、四条排播、缺席回退和卸载竞态。`npm run verify:pet-link:integration` 检查真实 Cordis 配置更新与启停；`npm run verify:pet-link:browser` 检查独立浏览器中的自有气泡、配图加载及调参面板。浏览器夹具不等于官方完整 React 宠物或桌面窗口的视觉验收；不能把接口单测当成所有动画均已真机验收。
+另在 fork 仓（`repo-dsh-pet-dshwe/`）：`npm run verify:rename`——改名判据（扫描全仓文本文件的旧身份串，0 残留才通过；扫描条数以命令输出为准，不写死数字）。
+
+浏览器夹具不等于官方完整 React 宠物或桌面窗口的视觉验收；不能把接口单测当成所有动画均已真机验收。沙箱类环境（禁止子进程 spawn）下 `verify:pet-link:browser` 与 `verify-deployment` 会红，属环境限制而非缺陷——本地依赖齐全的正常环境可全绿。
 
 ## 从旧版本迁移
 
-内置 pet 和修改第三方文件的安装器已退役。旧 profile 里的派生依赖、bundle 选择、数据及曾经安装的外部补丁不会自动清除。关闭宿主后先停用旧内置 bundle，再更新 Wallpaper；外部补丁应通过其原备份恢复或重装官方包，不对活动安装做故障注入。
+内置 pet 与修改第三方文件的安装器已退役。旧 profile 里的派生依赖、bundle 选择、数据及曾经安装的外部补丁不会自动清除。关闭宿主后先停用旧内置行，再按部署说明更新；外部补丁应通过其原备份恢复或重装官方包，不对活动安装做故障注入。旧版调参面板的「本页运行时覆盖、刷新即丢」已被持久化取代。
 
-本包保留联动定制素材，不包含官方完整资源、字体及个人数据。代码许可证不替代素材授权；素材分发与商用范围须分别确认。本轮不发布 npm。
+本包保留联动定制素材，不包含宠物完整资源、字体及个人数据。代码许可证不替代素材授权；素材分发与商用范围须分别确认。本轮不发布 npm。