# 🐋 DSH Whale Pet

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

A Windows desktop pet that bundles **DeepSeek Harness** service management — start, stop, monitor — and GUI launching into a single zero-dependency `.exe`.

[中文说明](README.md) · [Changelog](CHANGELOG.md)

![whale](assets/whale.png)

## ✨ Features

| Feature | Description |
|---|---|
| **One-click launch** | Double-click the exe: detect the DSH service → start it in the background if not running → open the GUI when ready → the whale appears |
| **Character-shaped pet** | Per-pixel transparent always-on-top window shaped exactly like the image; draggable, remembers its position |
| **Double-click to summon** | Double-click the whale to open the GUI (reuses the same PWA window, no tab stacking) |
| **Right-click menu** | Open / Close / Status / Exit |
| **Close program** | Stops the DSH service **and** closes the GUI app window (matched by window title — **does not touch your other browser windows**) |
| **Exit** | Confirmation dialog, then exits together with the service |
| **Tray icon** | Left-click to summon, right-click for the menu (fallback entry) |
| **Status monitor** | Only green/red states (no yellow intermediate); adaptive interval — 5s online / 2s offline |
| **Status card** | Floating card with service state/address/PID/uptime + pet memory/GDI handles (leak self-check) |
| **Single instance** | Second launch just summons the existing instance |
| **Crash log** | Unhandled exceptions are written to `dsh-whale-pet-crash.log` |

## 📦 Dependencies

| Dependency | Required? | Notes |
|---|---|---|
| **Windows 10 / 11** | ✅ Yes | Uses WinForms / layered windows / netstat |
| **.NET Framework 4.x** | ✅ Yes | **Preinstalled on Windows — nothing to install**; the exe is compiled by the built-in csc.exe targeting 4.x |
| **DeepSeek Harness** | ✅ Yes | Must be properly installed: ① Node.js ② dsh CLI installed globally (`npm i -g @deepseek-ai/dsh`) ③ API credentials configured (`DEEPSEEK_API_KEY` in `~/.dsh/.credentials.yaml`). The pet starts the service via `node <dsh lib/bin.js> web`, listening on `127.0.0.1:3080` |
| **Chrome** | ⚪ Optional | Used for the PWA standalone-window mode (via the `DeepSeek Harness.lnk` shortcut generated by the DSH GUI). Falls back to the default browser when absent |

> In short: **a working DeepSeek Harness install is all you need**; Chrome only improves the window experience.

## 🚀 Quick Start

### Option A: install as a DSH plugin (recommended)

```sh
dsh plugin --profile web add github:miku00039-01/dsh-whale-pet
```

Then type `/whalepet` in DSH to launch the whale pet.

### Option B: download the exe directly

1. Download `DSH桌宠.exe` from [Releases](https://github.com/miku00039-01/dsh-whale-pet/releases) (or build it — see below)
2. Double-click to run — the whale appears at the bottom-right of your screen
3. First run generates `dsh-whale-pet.conf` next to the exe (auto-detected paths); edit it if needed

## ⚙️ Configuration (`dsh-whale-pet.conf`, INI format)

| Key | Default | Description |
|---|---|---|
| `workspace` | (exe directory) | DSH workspace root (which workspace your sessions attach to) |
| `nodePath` | auto-detect | Path to node.exe |
| `dshBin` | auto-detect | Path to `@deepseek-ai/dsh/lib/bin.js` |
| `pwaShortcut` | auto-search | Path to the Chrome PWA shortcut; empty + not found → falls back to the browser |
| `pwaWindowTitle` | `DeepSeek Harness` | GUI window title prefix (used to close exactly that window) |
| `port` | `3080` | DSH service port |
| `lastX` / `lastY` | -1 | Last whale position (auto-recorded) |

## 🖥️ Open behavior & switches

- **How the pet opens the GUI**: prefers a Chrome PWA **standalone window** (via the shortcut in `pwaShortcut`); falls back to a default-browser tab when the shortcut is missing.
- **Service start switch**: the pet starts the service with `dsh web --no-open` — newer dsh (0.1.1+) auto-opens the browser by default, and `--no-open` lets the pet control window opening so you don't get "a web page first, then the app window".
- **Want a different behavior?**
  - Point `pwaShortcut` at another PWA shortcut, or **leave it empty** to always open in the default browser.
  - Running `dsh web` manually (without `--no-open`) will auto-open the browser — that is dsh's own behavior, unrelated to the pet.

All keys left empty = auto-detection. Restart the pet after editing. See `dsh-whale-pet.conf.example`.

## 🔨 Building from Source

```powershell
# Requires: Windows 10/11 (ships csc.exe and .NET Framework), PowerShell 7 or 5.1
pwsh -File build.ps1
```

The script: ① generates the multi-size `assets/pet.ico` from `assets/whale.png`; ② compiles `src/DSHPet.cs` → `DSH桌宠.exe` using the built-in csc.exe (zero third-party dependencies).

## 📁 Project Layout

```
dsh-whale-pet/
├── src/DSHPet.cs              # All source (single file, WinForms + P/Invoke)
├── assets/whale.png           # Pet artwork (see attribution)
├── assets/pet.ico             # exe icon (generated by build)
├── assets/WHALE_ATTRIBUTION.md# Artwork attribution & license
├── build.ps1                  # One-click build script
├── .github/workflows/ci.yml   # CI: build on push, release on tag
├── dsh-whale-pet.conf.example # Sample config
├── CHANGELOG.md               # Version history
└── README.md
```

## 🚀 Publishing a Release

Push a version tag — CI builds on Windows and attaches the exe to a GitHub Release automatically:

```bash
git tag v1.0.0
git push origin v1.0.0
```

## 🖼️ Artwork Attribution

The whale artwork source and license are documented in [`assets/WHALE_ATTRIBUTION.md`](assets/WHALE_ATTRIBUTION.md). Please make sure it meets the license terms before distributing.

## 📄 License

Code: MIT — see [LICENSE](LICENSE). Artwork: see the attribution note above.