dsh-desktop-pet

一句话定位

DSH 鲸鱼娘宠物的 Linux / Windows 桌面伴侣：一个透明置顶、无边框的悬浮宠物窗口，通过本地 HTTP 反向连接运行中的 DSH Web 服务，自动反映会话活动（思考 / 工具调用 / 等待批准 / 任务完成），并与网页端宠物互斥（在线时自动隐藏网页端）。

注意：dsh plugin ... add 这条命令仅在 DSH CLI 的 bundle 列表里登记这个插件，不会自动启动桌面应用；真正的桌面二进制需要去 GitHub Releases 手动下载。

语言: JavaScript / CommonJS（Electron 版与共享层）+ Rust（Tauri 版）+ 原生 HTML/CSS/JS（渲染端，无框架）
关键依赖: tauri 2（含 tray-icon 特性）、reqwest（纯 HTTP，无 TLS，回环请求）、tokio（异步运行时）、tauri-plugin-opener（从托盘打开网页端）
架构模式: 双实现——Electron（src/main.cjs）与 Tauri（src-tauri/src/lib.rs）共用 src/shared.cjs 的 DSH URL 校验与状态选择逻辑；DSH bundle 端只注册一个 inert 占位符（apply() 为空函数），真实应用通过 HTTP 反向连接运行中的 DSH Web 服务
入口文件: src/main.cjs（Electron 启动入口）/ src-tauri/src/lib.rs::run（Tauri 启动入口）；渲染端 src/renderer/renderer.js

Linux 或 Windows 用户希望把 DSH 的鲸鱼娘宠物从浏览器里「拿出来」，不切窗口也能看到会话进度（思考 / 使用工具 / 等待批准）。特别适合同时开多个会话的用户——桌面伴侣顶部的多会话气泡能一眼看到哪些会话在等你批准。你已经在浏览器里看鲸鱼娘了，那这个插件不是为你准备的。

依赖	最低版本	说明
DSH	未声明	DSH bundle 端无依赖，运行时强依赖 DSH Web 服务运行在 `http://127.0.0.1:3080`（本机 loopback）
whale-girl 插件	未声明	运行时强依赖上游 `vlln/whale-girl` 暴露的 `/whale-girl/*` HTTP API 与资源清单（README 注明）
Node	>=22	CI release.yml 使用 Node 22；package.json 未声明 engines 字段
平台	Linux + Windows	`package.json#build` 仅配置 linux 与 win；CI 仅产 Linux（AppImage / deb）与 Windows（NSIS）包
原生模块	无 npm 原生模块	Tauri 编译需 Rust 工具链；Linux 还需 webkit2gtk-4.1-dev / libayatana-appindicator3-dev / librsvg2-dev / patchelf / libxdo-dev

dsh plugin --profile web add github:xiaoshihou514/dsh-desktop-pet

安装后需前往 GitHub Releases 下载桌面二进制并手动启动。本命令仅登记 bundle，不会自动启动桌面应用。

本插件无需额外配置——DSH bundle 端 dsh-plugin.mjs 的 apply() 为空函数，cordis.patch.yml 仅注册一个空插件槽位，不向 DSH 暴露任何 Schema 配置项。

桌面应用运行时的体验参数（宠物尺寸、不透明度、气泡时长、散步开关与速度等）由上游 whale-girl 插件的 /whale-girl/config 端点统一管理，请到 whale-girl 插件的设置页调整。

Q: 执行安装命令后会立刻在桌面上看到宠物吗？

A: 不会。这条命令只在 DSH CLI 的 bundle 列表里登记这个插件，真正的桌面应用需要去仓库 GitHub Releases 下载 AppImage / deb / RPM / NSIS / portable 二进制并手动启动。

Q: 必须在 DSH 运行时才能使用吗？

A: 是。桌面端通过本地 HTTP 连接到运行中的 DSH Web 服务（默认 http://127.0.0.1:3080），DSH 没启动时窗口会显示「请启动 DSH Web 服务」。

Q: 能连远程 DSH 吗？

A: 可以通过 --dsh-url 启动参数或 DSH_URL 环境变量指定地址，但地址必须指向本机（127.0.0.1 / localhost / ::1），非 loopback 主机会被 shared.cjs 的 normalizeDshUrl 拒绝。

Q: 同时打开网页端宠物会冲突吗？

A: 不会。桌面端每 15 秒发一次 presence 心跳，桌面端在线时网页端鲸鱼娘自动隐藏；桌面端退出或崩溃后 45 秒 TTL 过期，网页端自动恢复。

Q: Wayland 下能拖动宠物或让它散步吗？

A: 不能。Wayland 下窗口移动由合成器接管，程序化 set_position 不可用，桌面端会自动禁用拖拽和散步功能，仅 X11 / XWayland 下可用。

Q: 为什么 Alt+F4 / 关闭按钮关不掉窗口？

A: 设计如此。Ctrl+W、Alt+F4、窗口管理器关闭请求一律被拦截，只能从系统托盘菜单「退出」或窗口内 × 按钮退出，避免误关。

Q: macOS 能用吗？

A: 源码里 macOS 分支存在但未启用。package.json 没有 macOS 构建配置，CI release.yml 也没有 macOS 任务，README 未声明提供 macOS 包。

进阶 — 安装命令本身一行就够，但真正能用的桌面应用需要去 GitHub Releases 手动下载二进制、确保上游 whale-girl 插件已安装、DSH Web 服务运行在 3080 端口；所有交互（投喂、散步、切换会话气泡）都是 UI 上点击，无需编程。

macOS 未配置构建目标：源码里 darwin 分支（ozone 选择、setAlwaysOnTop）都存在，但 package.json 没有 macOS 构建配置，CI release.yml 也没有 macOS job，README 未声明提供 macOS 包
Wayland 下拖拽 / 散步被禁用：canProgrammaticallyMove 在 Wayland 会话下返回 false，拖拽（pet:drag-move）与散步（pet:walk-move）直接 short-circuit 返回 moved: false，仅 X11 / XWayland 下可用
强制 loopback：DSH_URL 必须指向本机（normalizeDshUrl 拒绝非 127.0.0.1 / localhost / ::1 的主机），远程 DSH 不可直连
Linux 强制软件合成：app.disableHardwareAcceleration 在 Linux 上无条件启用，规避 Mesa/NVIDIA + 某些合成器组合下透明窗口不稳定问题；GUI 性能依赖 CPU
macOS 关闭拦截是硬编码：on_window_event 一律拦截 CloseRequested（除非显式置 quitting 标志），托盘菜单是唯一正常退出通道，习惯 Alt+F4 的用户可能觉得别扭
跨平台编译 Windows 工具链门槛高：CI 在 Linux 主机上交叉编译 Windows 需要 cargo-xwin + windres + mingw gcc + nsis + libayatana-appindicator，release.yml 用了约 80 行专门配置