whale-girl-plus

Readme

# whale-girl-plus · 鲸鱼娘桌宠增强版

> DeepSeek Harness（dsh）Web GUI 的桌面宠物插件 —— 在原版 `whale-girl` 基础上的增强分支：
> 多套服饰、休闲随机动作、工作节奏动画、完成庆祝变体，以及全部可配置的休闲行为系统。

**上游项目**：本仓库是 [vlln/whale-girl](https://github.com/vlln/whale-girl)（MIT License）的修改增强版（fork & enhance），
所有改动站在原项目的框架之上完成。署名链见 [NOTICE.md](NOTICE.md)。

---

## ✨ 相比原版新增了什么

| 模块 | 内容 |
| --- | --- |
| 👗 服饰系统 | 菜单「更换服饰」在 4 套服装间循环：经典女仆装、樱花粉、城市白领装、运动装（黄运动衣 + 白短裤 + 黑运动鞋 + 白遮阳帽） |
| 🎾 休闲动作 | 空闲站立时每 15-25 秒随机出现一个娱乐动作，持续 6-7 秒后回到站立：歪头杀、思考、看书、坐着喝茶、打网球、深夜抱枕头犯困（23:00-05:00 限定）、清晨起床（06:00-10:00 限定） |
| 🤖 自动换装 | 抽到「打网球」时自动换上运动装，动作结束后换回原服饰（不覆盖你的偏好选择） |
| 💻 工作节奏 | AI 工作时严格按 1:3 时间比交替：思考 3 秒 → 伏案打字 9 秒 → 循环；任务结束立即回到站立 |
| 🎉 完成庆祝 | 每次任务输出完毕随机播放两种庆祝之一（各 1/2）：举手欢呼 / 吹卷哨（彩带派对喇叭） |
| ⚙️ 配置系统 | 休闲行为的总开关、间隔区间、动作时长、7 个动作独立开关，全部可在设置面板调整，即时生效 |
| 🩹 稳定性修复 | 修复「回合结束事件丢失导致宠物永久卡在思考态」的服务端泄漏问题；修复「轮询重置计时器导致打字相位永远不触发」的调度 bug |

原版已有的能力全部保留：喂食/玩耍互动、拖拽（带惊讶表情）、游走、睡眠与睡醒、等级与回忆账本、欢迎/失落/惊吓事件、气泡回话、第三方插件事件缝（`whale-girl:say` 等）。

## 📦 安装

前提：已安装 [DeepSeek Harness](https://github.com/deepseek-ai) 的 `dsh` CLI 并有 web profile。

```bash
# 直接从 GitHub 安装
dsh plugin --profile web add github:Henryang777/whale-girl-plus

# 或者先克隆再本地安装
git clone https://github.com/Henryang777/whale-girl-plus
dsh plugin --profile web add ./whale-girl-plus
```

> ⚠️ 如果之前装过原版 `whale-girl`，请先卸载再装增强版（两者内部路由相同，不能共存）：
>
> ```bash
> dsh plugin --profile web remove whale-girl
> ```

安装后重启 dsh web 服务（或重开页面），右下角即可看到鲸鱼娘。

## ⚙️ 配置

打开 dsh Web GUI → 设置 → `whale-girl-plus` 插件配置区：

| 配置项 | 默认 | 说明 |
| --- | --- | --- |
| `leisure.enabled` | `true` | 休闲动作总开关 |
| `leisure.minWaitMs / maxWaitMs` | `15000 / 25000` | 两次休闲动作的随机间隔区间（毫秒） |
| `leisure.minMs / maxMs` | `6000 / 7000` | 单个休闲动作的持续时长区间（毫秒） |
| `leisure.actions.*` | 全开 | 7 个动作各自的开关：`headtilt` 歪头杀、`think` 思考、`reading` 看书、`tea` 喝茶、`tennis` 打网球、`pillow` 深夜抱枕困、`wakeup` 清晨起床 |
| `size / opacity / walk / sleepAfterMs …` | 同原版 | 尺寸、透明度、游走、入睡阈值等原版配置项全部保留 |

## 🗂 目录结构

```
whale-girl-plus/
├── .dsh-plugin/            # 插件本体（dsh 加载的就是这里）
│   ├── index.mjs           # Node 端：路由、状态聚合、会话事件、配置注册
│   ├── client.js           # 浏览器端打包产物（由 client/ 构建）
│   ├── client/             # 浏览器端源码：index.mjs 主循环 + logic.mjs 纯逻辑
│   ├── src/                # Node 端模块：config / routes / assets / activity …
│   └── assets/
│       ├── manifest.json   # 服饰（角色）清单：每套服饰的状态→精灵图参数
│       └── characters/     # 4 套服饰的精灵图（每套若干 256px 帧 sheet）
├── scripts/                # 构建与门禁脚本（build-client.mjs 等）
├── tests/                  # 单元测试（node --test）
├── docs/                   # 架构/状态机/精灵图规范等设计文档（上游）
├── decisions/              # 设计决策记录（上游）
├── originals/              # 角色形象原作参考图
├── cordis.patch.yml        # dsh bundle 补丁声明
├── package.json            # 包定义（dsh 插件入口声明）
├── LICENSE                 # MIT（含上游版权声明）
├── NOTICE.md               # 署名链与素材来源说明
└── CHANGELOG.md            # 相对上游的改动清单
```

## 🔨 开发

```bash
pnpm install          # 只需 esbuild（devDependencies）
pnpm run build:client # 修改 client/ 源码后重新打包出 .dsh-plugin/client.js
pnpm test             # 运行单元测试
pnpm run gates        # 仓库门禁检查
```

精灵图规范（帧尺寸、playback 模式、状态总表）见 [docs/sprites-spec.md](docs/sprites-spec.md)；
新增服饰/角色的步骤见 [docs/adding-a-character.md](docs/adding-a-character.md)。

## 🙏 署名与许可

- 代码：**MIT License**（沿用上游许可，见 [LICENSE](LICENSE)）
- 本仓库是 [vlln/whale-girl](https://github.com/vlln/whale-girl) 的修改版，原作者 **Sam Gao (vlln)**
- 鲸鱼娘角色形象原作：**上善**；女仆装二次设计：**ZipZipPipe**
- 增强版新增的精灵图（看书/喝茶/打网球/白领装/运动装等）为 AI 辅助生成并人工后期，按相同角色设定绘制
- 详细署名链与素材声明见 [NOTICE.md](NOTICE.md)

角色形象素材的使用范围以原作者要求为准；请勿将本仓库用于商业用途。