Henryang777/whale-girl-plus

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

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

上游项目：本仓库是 vlln/whale-girl（MIT License）的修改增强版（fork & enhance），
所有改动站在原项目的框架之上完成。署名链见 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 的 dsh CLI 并有 web profile。

直接从 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，请先卸载再装增强版（两者内部路由相同，不能共存）：

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            # 相对上游的改动清单

🔨 开发

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

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

🙏 署名与许可

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

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