miku00039-01/dsh-whale-pet

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

中文说明 · Changelog

✨ 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)

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 (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

# 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:

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. Please make sure it meets the license terms before distributing.

📄 License

Code: MIT — see LICENSE. Artwork: see the attribution note above.