whale-girl-plus · 鲸鱼娘桌宠增强版
> DeepSeek Harness（dsh）Web GUI 的桌面宠物插件 —— 在原版 whale-girl 基础上的增强分支： > 多套服饰、休闲随机动作、工作节奏动画、完成庆祝变体，以及全部可配置的休闲行为系统。
上游项目：本仓库是 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 的 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，请先卸载再装增强版（两者内部路由相同，不能共存）： > > ``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 # 相对上游的改动清单🔨 开发
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 的修改版，原作者 Sam Gao (vlln)
- 鲸鱼娘角色形象原作：上善；女仆装二次设计：ZipZipPipe
- 增强版新增的精灵图（看书/喝茶/打网球/白领装/运动装等）为 AI 辅助生成并人工后期，按相同角色设定绘制
- 详细署名链与素材声明见 [NOTICE.md](NOTICE.md)
角色形象素材的使用范围以原作者要求为准；请勿将本仓库用于商业用途。