dsh-pet-desktop
中文 README
A desktop-pet plugin for DeepSeek Harness — the Codex pet experience, fully ported to your desktop.
A self-contained DSH harness plugin: when the harness starts, a frame-animated pet lives on your desktop. No web-pet dependency — it ships its own state machine, chatter engine and pet registry, and subscribes directly to harness session events.
Features
- 🖥️ Desktop overlay: frameless, always-on-top, transparent smart click-through — when on, she's inert to dragging/clicking/scroll and only a right-click still reaches her control menu (so you can never trap yourself); the info card (name/rank/feed/rename) appears only on a tap, not on hover
- 📌 Edge-aware dragging: 1:1 pointer tracking with snap — the instant she hits a screen edge she sticks there (recycling the mouse can't drag her back off; a fresh grab moves her again). Bubbles and the settings card auto-flip near edges — grow inward at left/right, drop below her feet at the top — nothing ever clips off-screen
- 🎬 Native Codex pet format: drop Codex pet folders straight into
~/.codex/pets — also auto-discovers ~/.dsh/pets and bundled assets/pets (pet.json + spritesheet.webp); the 9 standard tracks (idle / running-right / running-left / waving / jumping / failed / waiting / running / review) with per-pet tracks / sequences overrides
- 💬 Live activity bubbles: harness session events project onto six phases (waiting / thinking / tool / review / done / failed); 389 built-in zh chatter lines rotating every 4 s; tool "whispers" («…」) with 9 s / 5 s cooldowns and 8 s on-screen TTL; multi-session bubble stack with
+N badge
- 💕 Affinity: pet +1 (10 s cooldown), feed +5 (costs 1 treat, 30 s cooldown), completed turn +1 (idempotent per session turn); treats accrue +1 per 30 turns and +1 per 5 h, capped at 20; affinity never decays
- 🐋 Decoration: bundled whale status ornament, phase-driven frame segments, switchable/off in settings
- 📈 Daily token meter: the tap card and the settings page show today's tokens (input / output / cache buckets plus call count, zeroed at local midnight, survives restarts); with dsh-usage installed it automatically mirrors that plugin's same-day ledger — same source and convention as the usage panel
- 📊 Usage mirror: with the web dsh-pet / dsh-usage installed, balance and plan-window announcements echo onto the desktop pet (pure mirror, no dependency)
- ⚙️ Settings integration: a “桌面宠物” section — auto-start, status + start/stop, window controls (always-on-top, click-through, hide/summon, size slider), pet picker with sprite thumbnails, decoration picker, electron path. Click-through can always be undone here — no way to trap yourself
Install
Requires DSH Desktop (or any harness host with the web server).
dsh plugin --profile web add @qiqibabyy/dsh-pet-desktop
# local development:
dsh plugin --profile web add link:../dsh-pet-desktop
Electron runtime lookup order (first hit wins):
- the
electronPath setting
DSH_PET_ELECTRON env var- this package's
node_modules/electron/dist/electron.exe
- global npm:
%APPDATA%/npm/node_modules/electron (Windows)
If nothing is found the settings card says so in red; npm i -g electron fixes it everywhere.
Pets & decorations
Format details: assets/pets/README.md. Sources scanned in order (later overrides same pet ids):
- bundled
assets/pets/
${CODEX_HOME:-~/.codex}/pets/ — native Codex directory${DSH_HOME:-~/.dsh}/pets/ — user directory (decorations/ subfolders scanned too)- extra directories from the
petDirs plugin config
Pets declaring renderer: live2d / frames2d are skipped by design — this plugin renders sprite2d atlases.
Porting pets from Codex
Drop them in as-is, zero conversion: copy a Codex pet folder (pet.json + atlas) into ~/.codex/pets/<id>/ and it is discovered automatically (CODEX_HOME is honored). Both Codex manifest generations are understood — the legacy flat hatch-pet shape and v2 sprite2d blocks. No CLI needed to swap pets: harness settings → "Desktop Pet" → the appearance picker; click a thumbnail and the companion re-skins live.
Ranks (affinity points)
| points ≥ | rank | star trail |
|---|
| 0 | Baby Whale 幼鲸 | * |
| 25 | Companion 伙伴 | ** |
| 50 | Close Friend 挚友 | *** |
| 80 | Deep Sea Bond 深海羁绊 | **** |
| 200 | Kindred Spirit 心有灵犀 | ***** |
| 500 | Legendary Bond 传说羁绊 | ****** |
| 2000 | Mythic Bond 神话羁绊 | ******* |
| 10000 | Eternal Covenant 永恒之契 | ******** |
| 100000 | Lifelong Companion 鲸生共渡 | ********* |
Loopback API
Served by the plugin on the harness web port, loopback-only:
| Route | Purpose |
|---|
GET /api/desktop-pet/state?current=<sid> | full view for the companion renderer |
GET /api/desktop-pet/pets / decorations | registries |
POST /api/desktop-pet/interact {kind} | pet / feed (+reaction) |
POST /api/desktop-pet/set-pet / set-decoration / set-name / set-display / announce | verbs |
GET /api/desktop-pet/status · POST start / stop | companion supervisor |
GET /desktop-pet-assets/** | atlases & decoration frames (allow-listed, containment-checked) |
Development
npm install # one runtime dep: schemastery
node scripts/smoke.mjs # host-free smoke test: registry / ledger / chatter / projection
| Path | Role |
|---|
index.js | plugin assembly (cordis host half) |
src/service.js | state machine + affinity ledger + event projection |
src/chatter.js | chatter engine (ported line-by-line from dsh-pet) |
src/registry.js | pet/decoration discovery (Codex v1 + v2 manifests) |
src/routes.js | loopback routes + asset serving |
src/supervisor.js | Electron companion process discovery/spawn/keepalive |
client.js | settings card (build-free CJS module-loader factory) |
companion/ | Electron overlay app (zero npm deps; any electron.exe runs it) |
License
- Code: Apache-2.0 (LICENSE)
src/chatter.js text pools and assets/decorations/whale are derived from
dsh-web @linxin666/dsh-pet
(code Apache-2.0; the whale decoration declares MIT in its own manifest)- Pet interaction concepts and the sprite format salute Codex Desktop Pet
