Skip to content
Back to search

whale-girl

DSH Web GUI 桌面宠物插件(QQ 宠物形态):右下角悬浮、可拖拽/投喂/玩耍的积累型伙伴。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vlln--whale-girl/badge.svg)](/listings/vlln--whale-girl)

HTML

<a href="/listings/vlln--whale-girl"><img src="/api/listings/vlln--whale-girl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 (npm 上的版本可能落后于 main,以 git 源为准): dsh plugin --profile web add whale-girl@0.2.0
# 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 136 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center"><a href="README.zh.md">中文</a> | English</p>
  2. <h1 align="center">whale-girl</h1>
  3. <p align="center">
  4. <strong>A desktop pet in the DSH Web GUI (QQ-pet style)</strong><br/>
  5. A persistent companion floating bottom-right: draggable, feedable, playable —
  6. completed tasks, sessions, and companionship time accrue into seniority levels,
  7. titles, and memories.
  8. </p>
  9. <p align="center">
  10. <img src="https://badgen.net/badge/license/MIT/green" alt="license" />
  11. <img src="https://badgen.net/badge/format/official%20bundle/8257D0" alt="official bundle" />
  12. <a href="https://dshfind.com/en/plugins/vlln/whale-girl?ref=badge"><img src="https://dshfind.com/api/badge/vlln/whale-girl" alt="dshfind" /></a>
  13. <a href="https://www.dsh.so/artifact/whale-girl"><img src="https://www.dsh.so/badge/whale-girl.svg" alt="dsh.so security" /></a>
  14. </p>
  15. ---
  16. ## Installation
  17. Official **bundle plugin** (`dsh.bundle` + `dsh.client` in root `package.json`), managed via the official profile:
  18. ```sh
  19. dsh plugin --profile web add whale-girl # npm source (build artifacts ship in the package)
  20. # to track the latest commit instead: dsh plugin --profile web add "github:vlln/whale-girl#main"
  21. # or local directory: dsh plugin --profile web add <path-to-whale-girl>
  22. ```
  23. **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.
  24. Update via `dsh plugin --profile web update whale-girl` (or switch the git ref), then restart.
  25. ## Usage
  26. | You / event | Pet behavior |
  27. |---|---|
  28. | Drag the pet | Stretched diagonally (`drag`) |
  29. | Menu 🍗 feed / 🎾 play | Chomping / ball toss (`eat`/`play`) → joy (`joy`) |
  30. | Idle ≥60s | Naps (`sleep`); wakes on interaction (`wake`) |
  31. | Task done / level-up / title / round done | Cheers (`celebrate`) |
  32. | Task failed / request error | Startled (`error`) → disappointed (`disappointed`) |
  33. | New session | Waves welcome (`welcome`) |
  34. | Session running / thinking | Pensive company (`think`, occasional `working`) |
  35. | Awaiting approval | Expectant waiting (`wait`) |
  36. | Periodic wandering | Walking (`walk`) |
  37. | Default | Idle standby (`idle`, random blinks / turns) |
  38. Full state machine (priorities / transitions / triggers): [docs/state-machine.md](docs/state-machine.md).
  39. ## Desktop Companion (Optional)
  40. `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:
  41. ```sh
  42. # Prereqs: Node ≥18; the rendering shell needs Rust (cargo)
  43. npm install -g whale-girl-desktop # npm install (engine + Tauri shell source included)
  44. whale-girl-desktop --headless # headless: presence heartbeat + state polling + SSE
  45. cd "$(npm root -g)/whale-girl-desktop/src-tauri" && cargo build --release # first build ~5-15 min; artifact target/release/whale-girl-desktop (~12MB)
  46. ./target/release/whale-girl-desktop # transparent always-on-top desktop pet (defaults to local DSH on 3080)
  47. # WHALE_GIRL_BASE_URL=http://IP:PORT points at a non-local DSH
  48. # or from source: cd desktop && npm install && cd src-tauri && cargo build --release
  49. ```
  50. - 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).
  51. - Shell: Tauri v2 (recommended, ~12MB); legacy Electron shell kept (`npm i -D electron`).
  52. - Design & contracts: `desktop/DESIGN.md`, `desktop/BUILD-RUN.md`.
  53. ## State Preview
  54. | State | Trigger | Preview |
  55. |---|---|---|
  56. | `idle` | Default standby | ![idle](docs/preview/idle.gif) |
  57. | `working` | Random work spell while session thinks | ![working](docs/preview/working.gif) |
  58. | `celebrate` | Task done / level-up / title / round done | ![celebrate](docs/preview/celebrate.gif) |
  59. | `error` | Task failed / request error | ![error](docs/preview/error.gif) |
  60. | `disappointed` | Brief dejection after failure | ![disappointed](docs/preview/disappointed.gif) |
  61. | `joy` | Happy after feeding / playing | ![joy](docs/preview/joy.gif) |
  62. | `eat` | Click to feed | ![eat](docs/preview/eat.gif) |
  63. | `play` | Click to play | ![play](docs/preview/play.gif) |
  64. | `drag` | While dragging | ![drag](docs/preview/drag.gif) |
  65. | `walk` | Periodic wandering | ![walk](docs/preview/walk.gif) |
  66. | `sleep` | Idle ≥60s | ![sleep](docs/preview/sleep.gif) |
  67. | `wake` | Wake-up transition | ![wake](docs/preview/wake.gif) |
  68. | `welcome` | New session | ![welcome](docs/preview/welcome.gif) |
  69. | `think` | Company while session thinks | ![think](docs/preview/think.gif) |
  70. | `wait` | Awaiting approval | ![wait](docs/preview/wait.gif) |
  71. ## Configuration
  72. **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).
  73. 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 <target>…", 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](docs/update-row.md).
  74. 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:
  75. ```yaml
  76. whale-girl:
  77. enabled: true # web render toggle (false disables the in-page pet while a desktop companion runs)
  78. sessionMemory: false # session memory (local file; see the config card)
  79. size: 110 # pet size px (64–160)
  80. opacity: 1 # default opacity (0.2–1)
  81. walk:
  82. enabled: true # wandering toggle
  83. sleepAfterMs: 60000
  84. ```
  85. 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).
  86. ## Characters
  87. 🎭 "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](docs/sprites-spec.md)); new characters: [docs/adding-a-character.md](docs/adding-a-character.md).
  88. ## Reference Implementation
  89. 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:
  90. - **Structure**: `lib/` (entry / logic / client / assets) separate from docs, decisions, scripts — root [AGENTS.md](AGENTS.md)
  91. - **Conventions**: gates (`scripts/gates/run.mjs`) + decision records + full asset contracts; guidance: plugin-registry's [make-dsh-plugin skill](https://github.com/vlln/plugin-registry/tree/main/skills/make-dsh-plugin), [cookbook](https://github.com/vlln/plugin-registry/blob/main/docs/cookbook/creating-a-plugin.md), [gotchas](https://github.com/vlln/plugin-registry/blob/main/skills/make-dsh-plugin/references/gotchas.md)
  92. ## Contributing
  93. **Issues and suggestions welcome** — your feedback shapes the pet's next steps:
  94. - 🐛 **Bug**: file an issue with repro steps, browser & dsh versions; console errors for client issues
  95. - 💡 **Feature ideas**: see [docs/state-machine.md](docs/state-machine.md) and [docs/growth-system.md](docs/growth-system.md), describe the expected effect
  96. - 🎨 **New characters**: [docs/adding-a-character.md](docs/adding-a-character.md) §quick guide — read-only contract, 15 sheets + manifest entries, validated by `verify-assets`
  97. - 🔧 **Code**: every non-trivial change needs a decision record (`decisions/`), gate self-checks, single-purpose commits ([docs/AGENTS.md](docs/AGENTS.md), root [AGENTS.md](AGENTS.md))
  98. ## Acknowledgements
  99. Character by [ZipZipPipe](https://space.bilibili.com/4168597) (the "Whale Girl" sticker character); sprites generated from their design.
  100. ## License
  101. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.