dolphin-pet-plugin

Readme

# 🐬 Dolphin Pet Plugin for DeepSeek Harness

A cute desktop pet plugin for DeepSeek Harness (DSH) web interface.

> 中文文档请见 [README.zh.md](README.zh.md)

## Features

- 🐬 **Built-in Dolphin** — A cute SVG dolphin named "波波" (Bobō) with animations, expressions, and idle swimming
- ✏️ **Custom Name** — Give your pet any name you like (up to 20 characters)
- 🖼️ **Custom Image** — Upload your own PNG/JPG/GIF image as the pet
- 🤖 **AI Generated** — Generate a pet image with AI using your DSH-configured models
- ❤️ **Mood System** — Pet it, feed it, watch its mood change over time
- 💾 **Persistent** — State persists across sessions (both locally and server-side)
- ⌨️ **Shortcuts** — Press `P` to pet, `F` to feed
- 🖱️ **Draggable** — Drag the pet anywhere on the screen

## Installation

### Via DSH Plugin Market

If you have `dshmarket` installed:
1. Open **Settings → Plugin Market**
2. Search for "dolphin-pet-plugin"
3. Click **Install**

### Via CLI

```bash
dsh plugin --profile web add dolphin-pet-plugin
```

### Local Development

```bash
# Clone or copy this plugin directory
cd dolphin-pet-plugin

# Install into your DSH web profile
dsh plugin --profile web add .
```

Then restart `dsh web` and refresh the page. The pet will appear in the bottom-right area of your screen.

## Usage

| Action | Effect |
|--------|--------|
| Drag the pet | Move it anywhere on screen |
| Click the pet (no drag) | Pet it — hearts + mood increase |
| 🫳 摸摸 button / `P` key | Pet the pet |
| 🐟 喂食 button / `F` key | Feed the pet |
| ⚙️ Settings button | Open settings panel |

### Settings

Click the ⚙️ button to open the settings panel where you can:

- **Change name** — Type any name for your pet
- **Choose pet image**:
  - 🐬 Dolphin (default built-in SVG)
  - 🖼️ Custom — upload your own image or generate one with AI

## How It Works

The plugin has two halves:

1. **Host (Node.js)** — Registers HTTP API routes and injects the client script into every served `index.html`
2. **Client (Browser JS)** — Renders the pet, handles interactions, and provides the settings panel

Configuration is saved server-side when available, with localStorage as a fallback.

## Development

The project structure:

```
dolphin-pet-plugin/
├── package.json          # Plugin manifest with dsh.bundle config
├── cordis.patch.yml      # Cordis bundle patch (how plugin mounts)
├── README.md             # English documentation
├── README.zh.md          # Chinese documentation
├── lib/
│   ├── index.js          # Host entry — inject routes + script
│   └── routes.js         # HTTP API routes
└── client/
    └── client.js         # Client-side: pet rendering + settings
```

### API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/plugins/dolphin-pet/client.js` | Serve client script |
| GET | `/plugins/dolphin-pet/config` | Get current pet config |
| POST | `/plugins/dolphin-pet/config` | Update pet config |
| POST | `/plugins/dolphin-pet/upload` | Upload custom pet image |
| POST | `/plugins/dolphin-pet/ai-generate` | Generate pet image with AI |

## Publishing to DSH Market

To publish this plugin to the DSH plugin marketplace (see [PUBLISH.md](PUBLISH.md) for the full guide):

1. **Publish to npm** (optional but recommended - enables prebuilt installs):
   ```bash
   npm publish
   ```

2. **Submit to awesome-dsh-plugin** - the market's data source:
   - Fork https://github.com/awesome-dsh-plugin/awesome-dsh-plugin
   - Add `data/plugins/bo961386926__dolphin-pet-plugin.yml`:
     ```yaml
     url: https://github.com/bo961386926/dolphin-pet-plugin
     name: bo961386926/dolphin-pet-plugin
     category: fun
     description:
       en: A desktop pet that swims in the web GUI - rename it, upload your own pet image, or generate one with AI.
       zh: 在网页界面里游来游去的桌面宠物--可以改名字、上传自定义图片，或用 AI 生成形象。
     ```
   - Run `npm ci && node scripts/generate-readme.mjs` and commit both READMEs
   - Open a PR (repo must be at least 1 day old with 10+ commits)
   
   The marketplace syncs from this registry daily; your plugin typically appears within a day after merge.

## License

MIT