whale-girl

中文 | English

whale-girl

A desktop pet in the DSH Web GUI (QQ-pet style) A persistent companion floating bottom-right: draggable, feedable, playable — completed tasks, sessions, and companionship time accrue into seniority levels, titles, and memories. Installation

Official bundle plugin (dsh.bundle + dsh.client in root package.json), managed via the official profile:

Restart web after installing (bundle layers compose at startup); the pet appears bottom-right: click for its menu (🍗 feed / 🎾 play), drag to move, hover for the status bar (seniority level / task count / recent shared memories). Hidden on onboarding pages.

Update via dsh plugin --profile web update whale-girl (or switch the git ref), then restart. Usage Full state machine (priorities / transitions / triggers): docs/state-machine.md. Desktop Companion (Optional)

desktop/ is a standalone companion app (Node engine + Tauri shell, zero runtime deps) that keeps the whale girl resident on your OS desktop. Not installed via dsh plugin — enable it yourself: Uses whale-girl's public endpoints (/state, /events, /presence, /interact, /config, /assets) without touching the plugin; the in-page pet hides while it runs (presence contract) and returns after exit/crash (TTL 45s). Shell: Tauri v2 (recommended, ~12MB); legacy Electron shell kept (npm i -D electron). Design & contracts: desktop/DESIGN.md, desktop/BUILD-RUN.md. State Preview Configuration

Plugins → Installed → whale-girl bundle page (config card): the high-frequency subset — show on page, session memory, size, opacity, wandering, sleep delay, and the feed/play reply pools (one per line). Session memory (off by default) records completed-task milestones to a local file and greets you with last time's progress on resume/fork — local only, never model context, never uploaded; off stops all reads/writes (file kept). Changes apply immediately, no restart (a switch writes on click; numbers and reply pools write on blur or Enter). The card's first row is an update row: it checks the source once on mount (git installs by commit, registry installs by version) and shows the verdict plus the installed short commit; a newer revision turns the button into "Update to …", and updating reinstalls through DSH's profile package manager without touching your settings. Full contract (endpoints, payloads, two-step reinstall, failure reasons, host version requirement): docs/update-row.md.

The full option list lives in the plugin entry's config in the profile patch ( /profiles/ /cordis.patch.yml); a whale-girl: section in /settings.yaml is imported into that entry once:

Full option list and why the semantic layer (XP / titles) is sealed: lib/src/config.mjs. Not configurable (changing XP / title thresholds would break the accumulation ledger). Characters

🎭 "Switch Character" cycles characters (or set whale-girl:character in localStorage); the button is greyed out when the manifest has a single character ("No other characters available"). Every character ships all 15 states (full contract: docs/sprites-spec.md); new characters: docs/adding-a-character.md. Reference Implementation

whale-girl is a complete bundle plugin format exemplar (dsh.bundle + cordis.patch.yml + lib/, evolving with the official mechanism) — model new plugins on it: Structure: lib/ (entry / logic / client / assets) separate from docs, decisions, scripts — root AGENTS.md Conventions: gates (scripts/gates/run.mjs) + decision records + full asset contracts; guidance: plugin-registry's make-dsh-plugin skill, cookbook, gotchas Contributing