whale-girl
DSH Web GUI 内的桌面宠物（QQ 宠物形态）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:vlln/whale-girl#4f30e24ca68ff02ef5429c61aa053c89be3468ce
Whale Girl 以 whale-girl 发布，当前版本为 0.2.4。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
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.
Official bundle plugin (dsh.bundle + dsh.client in root package.json), managed via the official profile:
dsh plugin --profile web add "github:vlln/whale-girl#main" # single-line git source (build artifacts committed)
# or npm source: dsh plugin --profile web add whale-girl@0.2.4
# or local directory: dsh plugin --profile web add <path-to-whale-girl>
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.
| You / event | Pet behavior |
|---|---|
| Drag the pet | Stretched diagonally (drag) |
| Menu 🍗 feed / 🎾 play | Chomping / ball toss (eat/play) → joy (joy) |
| Idle ≥60s | Naps (sleep); wakes on interaction (wake) |
| Task done / level-up / title / round done | Cheers (celebrate) |
| Task failed / request error | Startled (error) → disappointed (disappointed) |
| New session | Waves welcome (welcome) |
| Session running / thinking | Pensive company (think, occasional working) |
| Awaiting approval | Expectant waiting (wait) |
| Periodic wandering | Walking (walk) |
| Default | Idle standby (idle, random blinks / turns) |
Full state machine (priorities / transitions / triggers): docs/state-machine.md.
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:
# Prereqs: Node ≥18; the rendering shell needs Rust (cargo)
npm install -g whale-girl-desktop # npm install (engine + Tauri shell source included)
whale-girl-desktop --headless # headless: presence heartbeat + state polling + SSE
cd "$(npm root -g)/whale-girl-desktop/src-tauri" && cargo build --release # first build ~5-15 min; artifact target/release/whale-girl-desktop (~12MB)
./target/release/whale-girl-desktop # transparent always-on-top desktop pet (defaults to local DSH on 3080)
# WHALE_GIRL_BASE_URL=http://IP:PORT points at a non-local DSH
# or from source: cd desktop && npm install && cd src-tauri && cargo build --release
/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).npm i -D electron).desktop/DESIGN.md, desktop/BUILD-RUN.md.| State | Trigger | Preview |
|---|---|---|
idle | Default standby | idle |
working | Random work spell while session thinks | working |
celebrate | Task done / level-up / title / round done | celebrate |
error | Task failed / request error | error |
disappointed | Brief dejection after failure | disappointed |
joy | Happy after feeding / playing | joy |
eat | Click to feed | eat |
play | Click to play | play |
drag | While dragging | drag |
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 (<dshHome>/profiles/<profile>/cordis.patch.yml); a whale-girl: section in <dshHome>/settings.yaml is imported into that entry once:
whale-girl:
enabled: true # web render toggle (false disables the in-page pet while a desktop companion runs)
sessionMemory: false # session memory (local file; see the config card)
size: 110 # pet size px (64–160)
opacity: 1 # default opacity (0.2–1)
walk:
enabled: true # wandering toggle
sleepAfterMs: 60000
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).
🎭 "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.
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:
lib/ (entry / logic / client / assets) separate from docs, decisions, scripts — root AGENTS.mdscripts/gates/run.mjs) + decision records + full asset contracts; guidance: plugin-registry's make-dsh-plugin skill, cookbook, gotchasIssues and suggestions welcome — your feedback shapes the pet's next steps:
verify-assetsdecisions/), gate self-checks, single-purpose commits (docs/AGENTS.md, root AGENTS.md)Character by ZipZipPipe (the "Whale Girl" sticker character); sprites generated from their design.
MIT License
walk | Periodic wandering | walk |
sleep | Idle ≥60s | sleep |
wake | Wake-up transition | wake |
welcome | New session | welcome |
think | Company while session thinks | think |
wait | Awaiting approval | wait |