# dsh-desktop-pet

> DSH 鲸鱼娘宠物的 Linux/Windows 桌面伴侣，通过本地 HTTP 反向连接运行中的 DSH Web 服务，显示会话活动并支持喂食互动。

## Metadata

- Author: [@xiaoshihou514](https://github.com/xiaoshihou514)
- Repo: <https://github.com/xiaoshihou514/dsh-desktop-pet.git>
- GitHub: [xiaoshihou514/dsh-desktop-pet](https://github.com/xiaoshihou514/dsh-desktop-pet)
- Stars: 19
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `dsh`, `dsh-plugin`
- Forks: 1
- Open Issues: 0
- Last push: 2026-08-21T08:33:03.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

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

## Wiki

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

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

## 核心能力
- 在桌面右下角放置一个透明置顶的无边框悬浮宠物窗口，无任务栏图标，可被其他窗口遮挡但不消失
- 跟随 DSH 会话活动自动切换动画：思考、使用工具、等待批准、任务完成、回合庆祝、报错、休息
- 单击宠物投喂、右键玩耍，与 DSH `/whale-girl/interact` 接口联动，触发后会播短气泡反馈
- 闲置时沿屏幕底部水平散步（窗口真的在动），顶到工作区边缘自动反弹转向，速度与间隔可调
- 窗口顶部气泡区同时展示多个会话的状态（思考中 / 等待批准 / 已完成），有会话等待批准时整体变红提醒
- 拖动后窗口位置自动保存到本地，重启后仍在原处；同时通过心跳通知网页端鲸鱼娘自动隐藏

## 技术实现
- **语言**: 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`](https://github.com/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 |

## 安装方式
```bash
dsh plugin --profile web add github:xiaoshihou514/dsh-desktop-pet
```

> 安装后需前往 [GitHub Releases](https://github.com/xiaoshihou514/dsh-desktop-pet/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 行专门配置

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-desktop-pet](https://deepseek-plugin.org/plugins/xiaoshihou514/dsh-desktop-pet)
Wiki generated by AI (model: `MiniMax-M3`)