本地物理兼容修订

当前为 0.5.2。碰撞需要 dsh-pet 0.3.8 适配器，安装、互斥和恢复方式见 COMPATIBILITY.md。

dsh-pet-lan · 桌宠联机

给已安装的 dsh-pet 0.3.8 加一个局域网联机层：同一 Wi-Fi / 局域网里，装了本插件的 DSH 会互相广播桌宠，远端桌宠显示在桌面透明小窗或 DSH 浏览器浮层里，可以打招呼、点击挤压、拖拽抛掷，位置自动保存。

需要 dsh-pet 0.3.8（带 /dsh-pet-7340 路由的版本），并且桌宠已经可见。
本插件不修改 DSH 本体；可选的实时状态补丁会修改 dsh-pet 的运行时文件，详见下文。
点击/拖拽/抛掷只作用于插件显示的远端桌宠；本机 dsh-pet 只参与碰撞反应，不接受本插件的点击/拖拽控制。

功能

• 局域网发现：UDP 广播，同一房间名 + 端口的 DSH 互相可见，不经过任何外部服务器。
• 远端桌宠：桌面透明小窗（默认）或 DSH 窗口内浮层；可拖拽、抛掷，桌面窗口位置按 peer 保存。
• 点击挤压 + 小黄鸭音效：按下时播放 Ya1 按下音效并开始挤压/长按，松开时播放 Ya2 松开音效。点击还会给对方发送通知「XX 捏了你一下」（XX 是你的桌宠名）。
• 拖拽 / 抛掷 / 反弹：按住拖动，松手按拖动速度抛出；桌宠受重力下落，碰到屏幕边缘/地面会反弹并逐渐停下。桌面窗口使用 0.3.8 共享物理核心；浏览器浮层保留原有基础抛掷；桌面窗口位置会持久化，浏览器浮层位置在本次会话内保留。
• 桌宠碰撞（可开关，纯本地）：桌面模式下，远端桌宠之间、以及远端桌宠与本机 dsh-pet 之间会互相弹开。弹性/摩擦/重力读取本机 dsh-pet 的 physics，和本地手感一致。碰撞只在本机表现，不会同步给远端宠物。设置页「桌宠碰撞」可关闭。
• 名字标签 / 打招呼：点击名字标签上的 👋 按钮，对方桌宠会说一句短问候并播放动作；点击宠物本体只做挤压/音效，不会误发打招呼。
• 实时动作 / 气泡 / 表情包（可选）：运行附带的补丁后，对方的动画、折叠气泡和表情包会同步过来；不跑补丁也能联机，只是远端宠物本地随机动作、没有实时气泡。
• 设置页「桌宠联机」：显示方式（桌面 / 浏览器 / 两者）、房间名、端口、气泡共享、是否接受打招呼、桌宠碰撞、在线列表、桌面窗口状态与收发诊断。
• 浏览器回退：没有 Electron 或桌面 helper 启动失败时，自动在 DSH 窗口内显示远端桌宠。

碰撞针对桌面窗口，使用 0.3.8 物理桥接补丁的实时状态；浏览器浮层不参与。接管期间自动暂停原生碰撞，关闭、断线或退出后恢复。

小黄鸭音频来自 dsh-whale-widget（MIT，Ya1/Ya2）；碰撞参数来自本机 dsh-pet physics（默认 gravity 1400 / restitution 0.78 / groundFriction 2.5 / ceilingBounce true）。

安装

1. 先装 dsh-pet

在 DSH 插件市场安装并启用 dsh-pet 0.3.8，确认桌宠正常显示。

2. 安装本插件

在插件市场搜索 dsh-pet-lan 安装，或者：

dsh plugin --profile web add dsh-pet-lan

桌面应用把 web 换成 desktop。

3. 配置

打开 设置 → 桌宠联机：

• 房间名 / 端口：同一局域网的设备必须填相同值（默认 dsh-pet / 41234，可自行修改）。
• 显示方式：桌面窗口（默认，需要 Electron）、浏览器浮层，或两者。
• 广播气泡文字：关闭后只同步动作和位置，不广播气泡文本。
• 接受打招呼：关闭后忽略别人发来的挥手。

4. 可选：实时状态补丁

实时动作 / 气泡 / 表情包同步需要给 dsh-pet 打一个小补丁（不是自动执行的）：

node <插件目录>\scripts\patch-dsh-pet.mjs

补丁会修改 dsh-pet 的 4 个运行时文件：

• lib/client.js
• runtime/electron-helper/preload.js
• runtime/electron-helper/main.js
• runtime/electron-helper/sprite.js

原文件会备份为 *.dsh-pet-lan.bak。补丁是幂等的，dsh-pet 升级后需要重新运行一次。

安全提示：这是对另一个 npm 包的原地修改。运行前请确认你信任本插件，并保留备份；如果不想修改 dsh-pet，跳过这一步，联机功能仍然可用。恢复时把对应的 .dsh-pet-lan.bak 改回原名即可。

安全 / 隐私

• 联机数据走局域网 UDP 明文广播，没有加密，也没有身份认证；房间名不是密码，同一局域网内知道房间名的人可以伪造桌宠或发送打招呼。
• 广播内容：桌宠名称、主机名、视口、桌宠位置；开启“广播气泡文字”时还包括气泡文本（可能包含对话内容）和表情包名。
• 只建议在可信的专用局域网使用；不要在公共 Wi-Fi 上开启。
• 不接受来自非回环地址的 HTTP 控制请求；UDP 侧有 peer 数量、每 IP 包速率和全局限流。
• 不访问外部网络、不上传遥测；所有状态文件都在 $DSH_HOME 下。
• 可选的 dsh-pet 补丁会修改另一个包的运行时文件；这是本插件唯一的“包外写入”，已在上面单独说明。

更完整的威胁模型见 SECURITY.md。

显示方式

• 桌面窗口：每个远端桌宠一个透明、置顶、可拖拽的小窗；鼠标不在桌宠上时点击穿透。需要 Electron（dsh-pet 桌面模式安装时通常已下载到 $DSH_HOME/electron）。
• 浏览器浮层：远端桌宠显示在 DSH 窗口内，适合没有 Electron 的环境。
• 两者：同时显示。

Electron 缺失或桌面 helper 启动失败时自动退回浏览器浮层；设置页会显示错误原因。

Windows 防火墙

首次运行可能弹出防火墙提示：允许专用网络的 UDP 入站（默认端口 41234）。如果点了取消，用管理员 PowerShell 补一条：

New-NetFirewallRule -DisplayName "dsh-pet-lan" -Direction Inbound -Protocol UDP -LocalPort 41234 -Action Allow -Profile Private

协议

• UDP 广播，默认端口 41234，约每 1500 ms 一次 presence，6.5 秒无消息即下线。
• 房间名过滤；presence 里带桌宠列表、主机名、视口和可选实时状态。
• 挥手是单播 wave 消息；收到后在本地调用 dsh-pet 的 /broadcast 和 /anim。
• 挤压通知是单播 poke 消息；收到后在本地桌宠气泡显示「XX 捏了你一下」，不回传碰撞状态。
• 协议版本 v: 1；实现见 lib/index.js。

卸载 / 回退

1. 在插件市场或 profile 里移除 dsh-pet-lan。
2. 如果运行过实时状态补丁，把 dsh-pet 下的 *.dsh-pet-lan.bak 恢复为原文件名。
3. 配置文件在 $DSH_HOME/dsh-pet-lan.json，可删除。

兼容性

• DSH 0.2.1-rc.2（已测试）
• dsh-pet 0.3.8
• Node.js 22+

License

MIT