dsh-pet — Whale-girl pet plugin

English | 中文

A soft, healing whale-girl who works alongside you in DeepSeek Harness.

While the model thinks, you wait — she swims. She follows official session activity and switches animations while waiting, thinking, using tools, composing a reply, celebrating completion, or reporting failure; you can also pat her head, feed her dried fish, and watch her grow from a baby whale into your deep-sea bond.

Re-implemented from the pet feature of the Codex desktop app, as an official DSH plugin shape (cordis bundle: host half + client half in one package).

Features

Feature	Description
State animation	Official session activity → whale-girl animation: thinking → running, tool → running-right, review → review, waiting → waiting, done → jumping, failed → failed
Head-pat interaction	Click the whale-girl → bubble feedback + affinity +1 (10s cooldown)
Feeding	Hover panel "喂食" (Feed) → consumes 1 dried fish + affinity +5 (30s cooldown)
Treat economy	Dried-fish stock (cap 20): +1 every 3 rounds of work, +1 every 30 minutes; when low it prompts "多陪鲸鱼娘工作一会儿" (Work with the whale-girl a bit more)
Affinity	+1 per round completed; 4 levels: 幼鲸 (baby whale) → 伙伴 (companion) → 挚友 (close friend) → 深海羁绊 (deep-sea bond, capped at 100)
Custom naming	Hover panel "改名" (Rename) → 1–20 characters, persisted, echoed in the summon button/panel
Dragging	Hold and drag the whale-girl to reposition; position persisted
Hide/Summon	Hover panel "隐藏" (Hide); after hiding, a "召唤{name}" (Summon {name}) button appears in the input selector row
Status bubble	Shows the current session stage or tool name; transient interaction feedback temporarily takes priority
Multi-session activity	The pet is host-global: the most recent meaningful event controls its display, while completed turns from every session contribute affinity and treats

Animation preview

The sprites are an 8-column × 9-row atlas (192×208 cells) generated by the hatch-pet pipeline; below are previews of each state:

idle	waiting	running	jumping

waving	review	failed	move left/right

Architecture

dsh-pet/
|-- src/
|   |-- index.ts        # host half: plugin entry (cordis apply, route registration)
|   |-- service.ts      # PetService: pet state machine + affinity + config (HTTP API service face)
|   |-- state.ts        # pet state machine: projected session activity → 9 state animations
|   |-- affinity.ts     # affinity ledger (pure functions + cooldowns)
|   |-- treats.ts       # dried-fish stock ledger
|   |-- persist.ts      # persistence ($DSH_HOME/pet.json, atomic write)
|   |-- routes.ts       # /api/pet/* JSON API + /pet/whale/* static asset routes
|   `-- client/         # browser half
|       |-- index.ts    # global mount (createRoot → body) + polling (2s) + interaction wiring (fetch)
|       |-- PetDockEntry.tsx  # global floating entry (document.body, always shown: no session / new session / mid-session)
|       |-- WhalePet.tsx      # floating component (portal + rAF frame animation + dragging)
|       |-- spritesheet.ts    # atlas geometry + per-state animation tracks (frames/duration)
|       `-- pet.module.css
|-- assets/whale/       # whale-girl assets (pet.json + spritesheet.webp + animation previews)
`-- cordis.patch.yml    # bundle patch: inserts the pet plugin row

Data flow

official session events (turn/step/chunk/tool) ----\
                                                    > PetService (host)
optional legacy activity/status ------------------/
                                                              | /api/pet/* JSON
global React root (createRoot → document.body) `.

## Sprites and animation-track calibration

The whale-girl atlas is generated by the hatch-pet pipeline as 9 states × 8 columns: `assets/whale/spritesheet.webp` (1536×1872, 8 columns × 9 rows of 192×208 cells) + `assets/whale/pet.json`. The actual frame count and rhythm of each row are defined in `TRACKS` in `src/client/spritesheet.ts`. If the artwork is redone and the frame count changes, only that table needs updating (row-order contract: 0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review).

## License

[BSD-3-Clause](https://github.com/ningbainb/deepseek-harness-desktop/blob/f30137e7d72942d2cd851a0fa0713f596ed06ad6/packages/dsh-pet/LICENSE)