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

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