dsh-whale-pet

Readme

# dsh-whale-pet

[简体中文](./README.zh-CN.md)

A whale-girl desktop pet plugin for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI.

| Idle | Hover wave | Working | Complete |
|:---:|:---:|:---:|:---:|
| ![Idle animation](https://raw.githubusercontent.com/Er1c0v0/dsh-whale-pet/main/docs/idle-preview.gif) | ![Hover wave](https://raw.githubusercontent.com/Er1c0v0/dsh-whale-pet/main/docs/hover-preview.gif) | ![Working animation](https://raw.githubusercontent.com/Er1c0v0/dsh-whale-pet/main/docs/working-preview.gif) | ![Ready animation](https://raw.githubusercontent.com/Er1c0v0/dsh-whale-pet/main/docs/ready-preview.gif) |

## Highlights

- Mirrors five Harness states: idle, working, needs input, complete, and blocked.
- Hugs a DeepSeek-whale-inspired pillow while idle, falls asleep after 40 seconds, startles awake, and plays one friendly three-pose wave when hovered or focused.
- Shows privacy-safe activity summaries from Harness presentation metadata in bubbles that choose an on-screen position around the pet without covering the character.
- Supports dragging, keyboard movement, position reset, collapse/restore, reduced motion, English, and Simplified Chinese.
- Uses the official `shell.overlay` slot without patching Harness or scraping UI text.

## Install

Requires Node.js 22.19+ or 24+ and DeepSeek Harness 0.1.0-rc.6.

```bash
dsh plugin --profile web add dsh-whale-pet@0.1.0
dsh --profile web --dump-config
dsh --profile web
```

The dump should contain exactly one `dsh-whale-pet` entry. The pet appears at the bottom-right of the Web UI.

To uninstall:

```bash
dsh plugin --profile web remove dsh-whale-pet
dsh --profile web --dump-config
```

## State mapping

| Priority | Session condition | Pet state |
|---:|---|---|
| 1 | Removed | Blocked |
| 2 | Approval, plan review, or question pending | Needs input |
| 3 | Running | Working |
| 4 | Explicit open, agent, or prompt error | Blocked |
| 5 | A running session stops successfully | Complete for 1600 ms |
| 6 | No session, cold/loading, or settled | Idle |

## Development

```bash
pnpm install --frozen-lockfile
pnpm check
pnpm test:visual
npm pack
node scripts/smoke-harness.mjs --package ./dsh-whale-pet-*.tgz
```

Idle assets, frame order, and interaction timing have one source of truth in `src/client/idle-animation.json`. `pnpm assets:check` enforces the 700,000-byte runtime WebP budget; the current set uses 679,044 bytes, so review asset size before adding more artwork.

See [CONTRIBUTING.md](./CONTRIBUTING.md) for artwork and verification rules.

## Privacy and licenses

The plugin reads only current-session status and provider-declared presentation metadata. It does not read tool arguments, prompts, model reasoning, or conversation text, and it makes no analytics requests. Preferences stay in browser-local storage.

Code is licensed under [MIT](./LICENSE). Artwork is licensed under [CC BY 4.0](./LICENSES/CC-BY-4.0.txt); provenance and hashes are recorded in [ASSET_ATTRIBUTION.md](./ASSET_ATTRIBUTION.md).